Hugging Face模型下载太慢？中国用户完整加速指南

git lfs clone 一个7B模型，速度显示3KB/s，预计完成时间：47天。这大概是每个在中国做AI开发的人都经历过的场景。

Hugging Face是全球最大的AI模型和数据集共享平台，但它的服务器和CDN节点主要部署在欧美。在中国大陆直连下载，速度慢、频繁中断、git lfs报错是常态——尤其是下载几十GB的大模型时，中途断掉基本等于重来。

这篇文章整理了6种经过验证的加速方案，涵盖从免费镜像到专线VPN的完整解决路径，帮你根据实际情况选择最合适的方式。

---

为什么Hugging Face在中国下载这么慢？

三个核心原因：

1. 跨国链路瓶颈：数据从美国/欧洲的服务器传到中国，需要经过拥挤的国际出口。TCP协议在高丢包环境下会自动降速，文件越大问题越严重。

2. CDN反而帮倒忙：Hugging Face使用的CDN（如Cloudflare）在中国大陆没有节点或节点受限。请求可能被路由到遥远的POP点，延迟反而更高。

3. 运营商限速"大象流"：下载一个几十GB的模型属于典型的"大象流"（Elephant Flow）。国际出口带宽有限，运营商的QoS策略会对这类长时间大流量连接降低优先级。

---

方案一：hf-mirror.com 镜像站（最推荐的免费方案）

hf-mirror.com 是社区维护的Hugging Face国内镜像，服务器在国内，下载速度通常能达到10-50MB/s。

命令行使用（推荐）：

# 1. 安装必要工具
pip install -U huggingface_hub hf_transfer

# 2. 设置镜像环境变量
export HF_ENDPOINT=https://hf-mirror.com

# 3. 下载模型
huggingface-cli download --resume-download meta-llama/Llama-2-7b --local-dir ./Llama-2-7b

# 4. 下载数据集
huggingface-cli download --repo-type dataset squad --local-dir ./squad

在Python代码中使用：

import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

# 之后正常使用 transformers / huggingface_hub
from transformers import AutoModel, AutoTokenizer
model = AutoModel.from_pretrained("bert-base-chinese")

长期配置（写入bashrc，一劳永逸）：

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc

优点： 免费、速度快、支持断点续传、与官方工具完全兼容。

局限： 公益项目带宽有上限，高峰期可能拥堵；少数私有模型可能不可用。

---

方案二：hfd脚本 + aria2多线程下载

对于特别大的模型（如70B、100B+），单线程下载即使用了镜像也不够快。hfd 脚本结合 aria2 的多线程能力，可以将下载速度再拉高一个量级。

# 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. 用4线程下载模型
./hfd.sh meta-llama/Llama-2-7b --tool aria2c -x 4

# 5. 下载数据集
./hfd.sh squad --dataset --tool aria2c -x 4

-x 4 表示4个并行连接，可以根据你的带宽调到 -x 8 或更高。

优点： 多线程显著提速；自动处理git lfs大文件；断点续传可靠。

局限： 需要安装额外工具；脚本需要手动更新。

---

方案三：ModelScope（魔搭社区）替代

如果你需要的模型在阿里的 ModelScope 上也有，直接从ModelScope下载会更快——服务器在国内，且阿里云的带宽更稳定。

# 安装ModelScope
pip install modelscope

# 下载模型
from modelscope import snapshot_download
model_dir = snapshot_download('ZhipuAI/chatglm3-6b')

很多主流模型（ChatGLM、Qwen、Llama系列、Stable Diffusion等）都能在ModelScope找到。

优点： 国内原生平台，速度稳定；社区活跃，中文文档完善。

局限： 模型覆盖不如Hugging Face全面；部分模型版本可能有延迟。

---

方案四：AI快站（aifasthub.com）

AI快站 是另一个免费的模型加速下载平台，提供了简洁的一键下载脚本：

# 下载专用工具
wget https://dl01.aifasthub.com/shell/hf-fast.sh
chmod a+x hf-fast.sh

# 下载模型（自动多线程+断点续传）
./hf-fast.sh meta-llama/Llama-2-7b

# 增加并发线程
./hf-fast.sh -j 8 meta-llama/Llama-2-7b

优点： 操作极简；自带多线程和断点续传。

局限： 作为公益项目，长期稳定性有待观察。

---

方案五：hf_transfer加速模块

Hugging Face官方提供了 hf_transfer 这个Rust编写的高性能传输模块，替代默认的Python下载逻辑，即使走镜像也能再提速。

# 安装
pip install hf_transfer

# 启用加速
export HF_HUB_ENABLE_HF_TRANSFER=1
export HF_ENDPOINT=https://hf-mirror.com

# 正常下载，底层自动使用hf_transfer
huggingface-cli download --resume-download gpt2 --local-dir ./gpt2

优点： 官方维护，与huggingface-cli无缝集成。

局限： 对网络环境本身质量仍有依赖；不支持所有文件类型的加速。

---

方案六：VPN专线——当你需要完整的HF生态

以上方案能覆盖大部分模型下载场景。但如果你遇到以下需求，镜像方案就不够了：

• 下载私有模型或组织内部模型——镜像站无法访问需要认证的私有repo
• 使用Hugging Face Hub的完整功能——Spaces、Discussions、Inference API、模型评估等都需要直连
• 在CI/CD或自动化训练流水线中拉取模型——需要稳定的直连通道，不能依赖第三方镜像
• 同时访问GitHub、Weights & Biases、Colab等整个ML工具链——不可能对每个平台都找镜像

Jetstream的IEPL专线通过独立的国际以太网链路连接，不走拥堵的公共出口。实测 git lfs clone 7B模型的速度可以稳定在20-50MB/s：

# 连接Jetstream IEPL节点后
# 直接使用原始Hugging Face地址，无需设置任何镜像
git lfs clone https://huggingface.co/meta-llama/Llama-2-7b

# 或者在服务器上设置代理
export ALL_PROXY=socks5://127.0.0.1:7890
huggingface-cli download --resume-download meta-llama/Llama-2-7b --local-dir ./Llama-2-7b

推荐策略： 日常开发用hf-mirror镜像（免费快速），需要访问私有模型或完整HF生态时切换VPN。两种方案可以共存，不冲突。

---

各方案对比总结

---

常见问题

hf-mirror镜像和Hugging Face官方数据完全一致吗？

镜像会有几小时到一天的同步延迟。如果你需要最新发布的模型版本，可能需要等待同步或直连原站。

git lfs clone和huggingface-cli download哪个好？

推荐 huggingface-cli download。它支持断点续传、进度显示更友好，且与hf_transfer加速模块兼容。git lfs clone 一旦中断就要从头开始。

在Docker容器/Kubernetes Pod中怎么用镜像？

在容器启动脚本或Dockerfile中设置环境变量即可：

ENV HF_ENDPOINT=https://hf-mirror.com

为什么设了镜像还是很慢？

可能原因：1）高峰期镜像站拥堵，换个时间或换AI快站试试；2）你的内网有流量限制；3）模型文件特别大但只用了单线程，试试hfd+aria2多线程。

---

相关阅读：

• 《arXiv在中国访问慢？5种实测方案加速论文下载》
• 《Kaggle数据集在中国下载慢？4种加速方案实测》