先说结论：解决 HuggingFace 下载慢，只有三条路线，按场景选即可。镜像路线（hf-mirror.com）免费、速度快，覆盖绝大多数公开模型和数据集，日常开发首选；加速库路线（hf_transfer）在链路本身不差的前提下用多线程榨干带宽，适合和镜像叠加使用；代理路线是 gated 模型（需要登录 token）、私有仓库、上传模型、访问 Spaces 等完整 Hub 生态的唯一解——这些场景镜像救不了。三条路线互不冲突，可以共存。下文每条路线都给出可直接复制粘贴的命令。
为什么 HuggingFace 在中国下载这么慢？
git clone 一个 7B 模型，速度显示 3KB/s，预计完成时间 47 天——这大概是每个在中国做 AI 开发的人都经历过的场景。三个核心原因：
-
跨国链路瓶颈：HuggingFace 的服务器和 CDN 节点主要部署在欧美，数据要穿过拥挤的国际出口。TCP 在高丢包环境下会自动降速，文件越大问题越严重。
-
CDN 帮不上忙：HuggingFace 的模型文件走 Cloudflare 等 CDN 分发，而这些 CDN 在中国大陆没有可用节点，请求可能被路由到遥远的 POP 点，延迟反而更高。
-
“大象流”被降优先级：下载几十 GB 的模型属于典型的长时间大流量连接（Elephant Flow），国际出口带宽有限，运营商的 QoS 策略会对这类连接降低优先级——所以经常是开头几分钟挺快，随后一路掉到 KB 级。
这套跨境链路问题不是 HuggingFace 独有，Docker 镜像拉取、GitHub clone 都是同一个病根，解法思路也高度相似：能用国内镜像就用镜像，镜像覆盖不到的场景走代理。
路线一：hf-mirror.com 镜像站（免费方案首选）
hf-mirror.com 是社区维护的 HuggingFace 国内镜像，与官方工具链完全兼容——你不需要改任何代码，只需要设置一个环境变量 HF_ENDPOINT，所有 huggingface_hub 系的工具（huggingface-cli、transformers、datasets）就会自动从镜像拉取。实测下载速度通常能到 10-50MB/s。
Linux / macOS（bash / zsh）
# 1. 安装/升级官方下载工具
pip install -U huggingface_hub
# 2. 设置镜像端点（当前终端会话生效）
export HF_ENDPOINT=https://hf-mirror.com
# 3. 下载模型（--local-dir 指定落盘目录）
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./Qwen2.5-7B-Instruct
# 4. 下载数据集
huggingface-cli download --repo-type dataset squad --local-dir ./squad设置后可以先验证一下是否生效，再开始动辄几十 GB 的下载：
echo $HF_ENDPOINT # 应输出 https://hf-mirror.com关于落盘位置：不加 --local-dir 时，文件会进默认缓存目录 ~/.cache/huggingface/hub，由 transformers 等库自动复用；加了 --local-dir 则把文件放到你指定的目录，适合部署、拷贝到其他机器等需要”拿到实体文件”的场景。缓存盘不够大时，可以用 export HF_HOME=/data/huggingface 把整个缓存挪到大盘上。
想让镜像配置长期生效，把环境变量写进 shell 配置文件：
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc # zsh 用户写 ~/.zshrc
source ~/.bashrcWindows PowerShell
PowerShell 设置环境变量的语法不同，不要照抄 bash 的 export：
# 当前会话生效
$env:HF_ENDPOINT = "https://hf-mirror.com"
# 写入用户级环境变量，永久生效（新开终端后可用）
[Environment]::SetEnvironmentVariable("HF_ENDPOINT", "https://hf-mirror.com", "User")
# 之后正常使用
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir .\Qwen2.5-7B-Instruct断点续传：大文件下载的保命符
下载几十 GB 的权重文件，中途断线是常态。huggingface-cli 的断点续传能从上次中断的位置继续，而不是从头再来：
huggingface-cli download --resume-download Qwen/Qwen2.5-7B-Instruct --local-dir ./Qwen2.5-7B-Instruct说明：较新版本的 huggingface_hub 已经默认开启断点续传，--resume-download 会提示”已废弃”但不影响使用；旧版本则需要显式加上这个参数。无论哪个版本，中断后重新执行同一条命令即可续传。
在 Python 代码里指定镜像
如果你不方便改机器的环境变量（比如共享服务器、CI 环境），可以在代码内解决。两种写法：
方式一：代码内设置环境变量（注意必须在 import transformers / huggingface_hub 之前设置）：
import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
from transformers import AutoModel, AutoTokenizer
model = AutoModel.from_pretrained("bert-base-chinese")方式二：snapshot_download 显式传入 endpoint 参数（较新版本 huggingface_hub 支持）：
from huggingface_hub import snapshot_download
snapshot_download(
repo_id="Qwen/Qwen2.5-7B-Instruct",
local_dir="./Qwen2.5-7B-Instruct",
endpoint="https://hf-mirror.com",
)容器 / K8s 环境
在 Dockerfile 或 Pod 配置中注入环境变量即可：
ENV HF_ENDPOINT=https://hf-mirror.com优点：免费、速度快、支持断点续传、与官方工具零成本兼容。
局限：公益项目带宽有上限，高峰期可能拥堵；镜像与官方有几小时到一天的同步延迟；需要登录授权的 gated 模型和私有仓库覆盖不到（见路线三）。
顺带一提，这种”换国内源”的思路和 npm / pip 换镜像源是同一套方法论——把开发环境的所有包管理器一次配齐，收益更大。
路线二：hf_transfer 高速传输库
hf_transfer 是 HuggingFace 官方用 Rust 编写的高性能传输模块，替代默认的 Python 下载逻辑，通过多线程分块把带宽打满。在链路本身不差（比如已经走了镜像或代理）的情况下，它能把单文件下载速度再抬一截：
# 1. 安装
pip install hf_transfer
# 2. 启用加速（可与镜像叠加）
export HF_HUB_ENABLE_HF_TRANSFER=1
export HF_ENDPOINT=https://hf-mirror.com
# 3. 正常下载，底层自动切换为 hf_transfer
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./Qwen2.5-7B-Instruct用之前想清楚它的取舍——hf_transfer 是一个”性能优先”的底层工具：
- 出错信息少：传输失败时报错非常简略，排查网络问题会比较痛苦；
- 不支持断点续传：一旦中断需要重新下载该文件，几十 GB 的单个权重分片断在 95% 会很想哭；
- 它加速的是带宽利用率，不是链路质量：如果你的瓶颈是国际出口丢包（直连 HuggingFace 的典型情况），hf_transfer 帮不了你，先解决链路（镜像或代理），再谈榨干带宽。
建议：网络稳定的内网/镜像场景开着它；跨境不稳定链路上下载超大文件时，宁可关掉它换取断点续传。
路线三：多线程下载器 hfd + aria2
对特别大的模型（70B、100B+），单线程即使走镜像也不够快。hf-mirror 官方提供的 hfd 脚本封装了 aria2c 的多线程能力：
# 1. 安装 aria2
sudo apt-get install aria2 # Ubuntu/Debian
brew install aria2 # macOS
# 2. 下载 hfd 脚本
wget https://hf-mirror.com/hfd/hfd.sh
chmod a+x hfd.sh
# 3. 设置镜像
export HF_ENDPOINT=https://hf-mirror.com
# 4. 多线程下载模型（-x 为并行连接数）
./hfd.sh Qwen/Qwen2.5-7B-Instruct --tool aria2c -x 4
# 5. 下载数据集
./hfd.sh squad --dataset --tool aria2c -x 4-x 4 表示 4 个并行连接，带宽富余可以调到 -x 8。它自动处理大文件分片和断点续传，是”镜像 + 多线程 + 可续传”三者兼得的组合，大模型下载场景比 hf_transfer 更稳妥。
git clone 大模型仓库的陷阱（以及正确替代）
很多人习惯性地 git clone 模型仓库，这在大模型场景下是个坑：
- git lfs 全量拉取慢：
git clone会通过 git-lfs 逐个拉取所有大文件，没有多线程分块，也不能像huggingface-cli那样只挑需要的文件； - 双倍磁盘占用：git-lfs 会在
.git/lfs/objects里保留一份对象缓存，工作区再放一份实体文件——clone 一个 15GB 的模型，磁盘实际要吃掉约 30GB； - 中断即重来：clone 过程断掉，大概率只能删掉重clone。
正确姿势：需要模型文件就用 huggingface-cli download（见路线一）；确实需要 git 仓库结构（比如要提交代码、看历史）时，先跳过大文件再按需补：
# 只克隆仓库结构和小文件，跳过 LFS 大文件
GIT_LFS_SKIP_SMUDGE=1 git clone https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct
# 大文件用 huggingface-cli 按需下载到同一目录
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./Qwen2.5-7B-Instruct路线四：ModelScope（魔搭）国内替代源
如果你要的模型在阿里的 ModelScope 上也有，直接从 ModelScope 下载往往更省事——服务器在国内，走阿里云带宽，不需要任何镜像配置：
pip install modelscopefrom modelscope import snapshot_download
model_dir = snapshot_download('Qwen/Qwen2.5-7B-Instruct')也可以直接用命令行下载：
modelscope download --model Qwen/Qwen2.5-7B-Instruct适用范围要拎清：
- 国产模型基本全覆盖且是第一发布源：Qwen、GLM、DeepSeek、Yi 等国产系模型在 ModelScope 上通常与 HuggingFace 同步发布甚至更早，下载体验远好于跨境拉取；
- 国外新模型有同步延迟：欧美实验室的新模型（以及冷门模型、数据集）要等社区搬运，可能滞后数天甚至没有；
- 生态绑定在 HuggingFace 的场景替代不了：依赖
transformers自动拉取、datasets库、HF Spaces 的工作流，换源成本不低。
结论：下国产模型优先 ModelScope，下国外模型走 hf-mirror，两者是互补关系而非二选一。
路线五：代理直连——镜像救不了的场景
前面的免费方案能覆盖”下载公开模型”这个主场景，但以下场景只能直连 huggingface.co，必须走代理：
- Gated 模型：Llama、Gemma 等需要在官网申请授权、下载时携带登录 token 验证身份的模型，授权校验发生在 HuggingFace 官方服务端；
- 私有仓库：你自己或组织的 private repo，镜像站无法访问；
- 上传模型 / 数据集：
huggingface-cli upload、git push只能推到官方源，镜像是只读的； - 完整 Hub 生态：Spaces、Inference API、Discussions、模型评估页，这些交互功能没有镜像可言；
- CI/CD 与训练流水线：生产链路依赖第三方公益镜像存在稳定性风险，需要可控的直连通道。
终端走代理的标准写法（HTTP 代理为例，端口以你代理客户端实际监听端口为准，7890 只是常见默认值）：
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
# 之后正常使用官方端点，不要再设 HF_ENDPOINT
huggingface-cli download meta-llama/Llama-3.1-8B-Instruct \
--token $HF_TOKEN --local-dir ./Llama-3.1-8B-InstructPowerShell 对应写法：
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"注意两点：一是 HF_ENDPOINT 与代理二选一——设了镜像端点，流量就不会去官方源，gated 校验会失败，走代理前记得 unset HF_ENDPOINT；二是 Python 的 requests/huggingface_hub 会自动读取这两个环境变量，代码不用改。
如果你还要对 HuggingFace 仓库做 git push（上传模型权重、改 README），git 同样默认读取 HTTPS_PROXY 环境变量；也可以只对 huggingface.co 域名单独配代理，不影响访问国内 git 源：
git config --global http.https://huggingface.co.proxy http://127.0.0.1:7890如果你的日常工作除了下模型还要访问 Claude / OpenAI API、跑 Google Colab、连 W&B——整个 ML 工具链不可能每个都找镜像，一条稳定的代理链路是更省心的整体解。JetStream 的 IEPL 专线走独立国际以太网链路，不挤公共出口，实测直连 huggingface.co 下载可以稳定在 20-50MB/s。
推荐策略：日常下公开模型用 hf-mirror（免费够快），碰到 gated 模型、私有仓库、上传需求时切代理直连。两套配置可以共存，按需切换。
各方案对比总结
| 方案 | 成本 | 速度 | 覆盖范围 | 适用场景 |
|---|---|---|---|---|
| hf-mirror 镜像 | 免费 | 10-50MB/s | 公开模型/数据集 | 日常开发首选 |
| hf_transfer | 免费 | 带宽利用率高 | 同所走链路 | 稳定链路上叠加提速 |
| hfd + aria2 | 免费 | 多线程叠加 | 公开模型/数据集 | 70B+ 大模型 |
| ModelScope | 免费 | 国内直连稳定 | 国产模型全、国外有延迟 | 下国产模型 |
| 代理直连 | 付费 | 稳定 20-50MB/s | 全覆盖含 gated/私有/上传 | 完整 HF 生态 |
常见问题
hf-mirror 镜像和 HuggingFace 官方数据完全一致吗？
镜像有几小时到一天的同步延迟。要第一时间拉刚发布的模型，直连官方源更保险。
git clone 和 huggingface-cli download 哪个好？
下载模型文件一律用 huggingface-cli download：支持断点续传、可只下载需要的文件、不产生 git-lfs 的双倍磁盘占用。git clone 只在你确实需要仓库的 git 结构时使用，并配合 GIT_LFS_SKIP_SMUDGE=1。
为什么设了镜像还是很慢？
依次排查：1）高峰期镜像站拥堵，换时段重试；2）单线程瓶颈，换 hfd + aria2 多线程；3）内网限速或公司出口策略；4）你要的是 gated/私有模型，镜像本来就覆盖不到，走代理。
模型下载到哪了？磁盘快满了怎么办？
不指定 --local-dir 时，所有文件都在 ~/.cache/huggingface/hub 缓存目录里，同一个模型不会重复下载。磁盘吃紧时先用 huggingface-cli scan-cache 查看缓存占用，再用 huggingface-cli delete-cache 交互式清理不用的旧模型；长期方案是设置 HF_HOME 把缓存整体迁到数据盘。
hf_transfer 开了反而报错？
hf_transfer 错误信息简略且不支持断点续传，跨境不稳定链路上建议 unset HF_HUB_ENABLE_HF_TRANSFER 关掉它，用默认下载逻辑保住续传能力。
让分流自动化：JetStream 的做法
上面所有方案落地后，你的真实工作流大概率是”混合态”：hf-mirror 和 ModelScope 要直连国内、huggingface.co 和 Colab 要走代理，手动切换很快就会烦不胜烦。
JetStream App 内置规则分流，正好解决这个问题：huggingface.co、GitHub、Colab 等国外开发资源自动走代理，hf-mirror、ModelScope、pip 国内源自动直连，无需手动切换模式，也不用维护分流规则。macOS / Windows / iOS（iOS 通过 TestFlight 分发）全平台可用，配置几分钟搞定：
相关阅读（同系列跨境开发加速）：