国内下载 HuggingFace 模型的三种姿势，别再等超时了

王王老师307 阅读
#HuggingFace#下载#踩坑

在国内下载 HuggingFace 模型，不折腾一下就是"下载 10 分钟、失败 10 次"。我试了各种方案，最后稳定用下来的三种，分享给大家。

方案一：HF 镜像站（最省事）。

设置环境变量用 hf-mirror：

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

之后 huggingface_hub 的下载请求都会走镜像。大部分模型都能下，速度还行。

如果用的是 transformers 的 from_pretrained，设了环境变量也会生效。注意：有些库不读 HF_ENDPOINT（比如某些自定义 loader），需要手动传。

方案二：huggingface-cli 断点续传。

Bash
huggingface-cli download BAAI/bge-m3 --local-dir ./models/bge-m3

断点续传 + 多线程。配合 hf_transfer：

Bash
pip install hf_transfer export HF_HUB_ENABLE_HF_TRANSFER=1

大文件能快很多。但 hf_transfer 有时会报错（进度条消失、校验失败），不行就关掉。

方案三：ModelScope（国内模型首选）。

国内模型（Qwen、bge 等）在 ModelScope 上都有，下载走国内 CDN，速度飞快：

Python
from modelscope import snapshot_download snapshot_download("Qwen/Qwen2.5-14B-Instruct", local_dir="./models/qwen14b")

方案四（补充）：离线迁移。

如果目标机器不能上外网：在一台能下的机器上下好，tar 打包传到目标机器解压。注意保持目录结构，from_pretrained 能直接加载本地路径。

坑：

  1. 下载一半失败。HF 的缓存机制会在 .cache/huggingface 下留临时文件，重试会自动续传。别手动删缓存目录，除非确认没用了。

  2. 磁盘空间。模型 + 缓存 + 临时文件可能占几倍空间，下之前 df -h 看下。

  3. 验证 sha256 慢。大文件下载完要校验哈希，很慢但别跳过，下载损坏的模型跑起来报错更难受。

总结：国内下模型，中文模型走 ModelScope，其他走 HF 镜像，命令走 huggingface-cli。

评论0

还没有评论，来抢沙发～