HuggingFace 模型权重加速下载实战

一个 70B 模型 140GB，从 huggingface.co 直连要 4 小时，从 hf-mirror 跑满千兆只要 22 分钟——给一份当下能用的方案集合。

现状

huggingface.co 在国内访问极其不稳，gated 模型还需要先 huggingface-cli login 才能下，下载中断后断点续传也常常 broke pipe。下面是我们在客户现场实际跑过的几条路径，按推荐顺序排列。

方案 1：hf-mirror.com（首选）

社区维护的反向代理，2024 年起一直能用。核心就一个环境变量：

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

设置完，所有 huggingface_hub / transformers / datasets / peft 调用都自动走镜像，代码不用改：

from transformers import AutoModelForCausalLM
m = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-72B-Instruct")  # 自动从 hf-mirror 拉

CLI 下载也一样：

HF_ENDPOINT=https://hf-mirror.com \
huggingface-cli download Qwen/Qwen3-72B-Instruct \
  --local-dir ./qwen3-72b --local-dir-use-symlinks False

写到 ~/.bashrc 一劳永逸。

方案 2：ModelScope（阿里）

模型自带国内 CDN，速度比 hf-mirror 还稳，但 不是所有 HF 模型都同步——主流开源模型（Qwen、Llama、DeepSeek、Mistral、Gemma）基本都有，长尾模型未必。

pip install modelscope
modelscope download --model Qwen/Qwen3-72B-Instruct \
  --local_dir ./qwen3-72b

代码层面也支持自动 fallback：

from modelscope import AutoModelForCausalLM
m = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-72B-Instruct")

方案 3：hfd 脚本 + aria2 多线程

社区脚本 hfd.sh 做了多线程并发，对千兆带宽特别合适：

wget https://hf-mirror.com/hfd/hfd.sh && chmod +x hfd.sh
./hfd.sh Qwen/Qwen3-72B-Instruct --tool aria2c -x 16 \
  --local-dir ./qwen3-72b

-x 16 是 aria2c 的并发连接数，千兆机器开 16 基本能跑满；万兆机房可以开到 32–64。

方案 4：gated 模型怎么办

部分模型（Llama 系列、Gemma）需要在 HF 网页同意 license 后才能下。流程：

浏览器开 https://huggingface.co/<model>，点 "Agree and access repository"
在 HF 设置里建一个 read 权限 token
节点上：

export HF_TOKEN=hf_xxxxxxxxxxxxxxxxx
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download meta-llama/Llama-3.3-70B-Instruct \
  --token $HF_TOKEN --local-dir ./llama3.3-70b

hf-mirror 透传 token，所以 license 检查在源站完成。

方案 5：内部缓存（推荐给团队 / 公司用）

每次都从公网拉浪费时间。在公司内网起一个 Cloudflare R2 / MinIO / 阿里云 OSS bucket 当 model registry，第一次有人下完后直接 aws s3 cp 一份过来：

# 第一次：上行
aws s3 sync ./qwen3-72b/ s3://my-models/qwen3-72b/ \
  --endpoint https://my-r2.account.r2.cloudflarestorage.com

# 之后所有人：千兆/万兆内网下行，几分钟搞定
aws s3 sync s3://my-models/qwen3-72b/ ./qwen3-72b/ \
  --endpoint https://my-r2.account.r2.cloudflarestorage.com

九章智算云客户可以直接用我们的对象存储 OSS，CCI/CCS 节点到 OSS 是内网千兆，70B 模型 ~3 分钟。

实测对比

70B 模型（140GB），杭州办公网千兆 + 节点千兆内网：

方法	耗时	成功率
`huggingface.co` 直连	4h+，多次断	< 30%
`hf-mirror.com`（单连接）	38 min	100%
`hfd.sh` + aria2c -x 16	22 min	100%
ModelScope	26 min	100%（模型存在前提下）
内网 OSS（首次已缓存）	3 min	100%

一些小坑

transformers 的旧版本（< 4.40）有时不读 HF_ENDPOINT，要用 HUGGINGFACE_HUB_ENDPOINT 再设一次保险。
local-dir-use-symlinks=False 一定加，否则缓存目录是软链，删除原模型时会断链。
一边下一边 du -sh 看进度比看 CLI 进度条靠谱——某些版本进度条卡死但实际还在下。

HuggingFace 模型权重加速下载实战

目录