HuggingFace 模型下载速度慢 hf_transfer 2.0 怎么开启加速

现象

在云服务器上拉 7B 模型,三个小时只下了 4G,速度长期在 400KB/s,最后报 Read timed out,重跑又从零开始。用浏览器能打开模型页,但下载大文件始终很慢。

原因

huggingface-CLI 默认走单连接下载,跨境链路上单流很容易被限速。没开 hf_transfer 时,分片和重试都由 Python 层处理,断线后已下载的部分利用不充分。另一个常见问题是缓存目录在系统盘,空间不足时写入变慢,看起来像网络卡住。

解决步骤

第一步,装带 hf_transfer 的客户端并打开开关。用官方推荐的安装方式,设置环境变量后再下载,分片并发会明显提升吞吐。

pip install -U "huggingface_hub[hf_transfer]"
export HF_HUB_ENABLE_HF_TRANSFER=1
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download Qwen/Qwen2.5-7B-Instruct \
  --local-dir ./qwen7b

第二步,确认缓存和磁盘位置。用 df -h 看目标盘剩余空间,至少留出模型体积两倍;把 HF_HOME 指到大盘,避免下载到一半因空间不足失败。已经下载过的仓库会走断点续传,不要删缓存重来。

第三步,限制并发避免被限速。带宽小的时候把 HF_HUB_DOWNLOAD_TIMEOUT 调大,并适当降低并发,单连接跑满比多连接互相抢占更稳。下载完成后校验文件大小和 sha256。

验证

用 du -sh 看目录增长,速度应稳定在带宽上限的七成以上;下载结束后 transformers 能正常加载并完成一次推理,说明文件完整。

小结

下载慢先分清是链路限速还是磁盘瓶颈。开启 hf_transfer、换可达镜像、把缓存放到大盘,再配合断点续传,基本能解决大部分超时。

您可以还会对下面的文章感兴趣: