Hugging Face 模型下载太慢?2026 最全 4 种加速方案对比(建议收藏)

🤵‍♂️ 个人主页：小李同学_LSH的主页

✍🏻 作者简介：LLM学习者
🐋 希望大家多多支持，我们一起进步！😄
如果文章对你有帮助的话，
欢迎评论 💬点赞👍🏻 收藏 📂加关注+

从龟速 100KB/s 到飙到 100MB/s+,国内下载大模型,这篇就够了。

目录

📖 前言:一个让所有 AI 学习者崩溃的场景

🎯 一张表,看懂四种方案该选哪个

🤔 为什么 Hugging Face 在国内这么慢?(原理篇)

延迟与带宽的数学关系

丢包带来的雪上加霜

架构示意

🌟 方案一:HF-Mirror 镜像站(99% 的人首选)

✨ 核心原理:一行环境变量搞定

🔧 三种使用姿势

姿势 1️⃣:环境变量(推荐,一劳永逸)

姿势 2️⃣:Python 代码内设置(临时用)

姿势 3️⃣:命令行直接下载

📊 实测速度

🔐 下载需授权的模型(Gated Model)

⚡ 方案二:官方 hf_transfer(速度王者)

🧪 什么是 hf_transfer?

🔧 使用方法(三行代码)

⚠️ 使用前必看

🎨 方案三:ModelScope 魔搭社区(国产之光)

🎯 什么时候用 ModelScope?

🔧 使用方法

💡 与 transformers 的无缝对接

🏆 方案四:hfd + aria2c 多线程(终极方案)

🧠 原理:多线程 + 断点续传

🔧 安装与使用

🎯 四大方案终极对比

💡 不同场景怎么选?一张图搞定

🛠️ 组合拳:终极速度配方

❓ 常见问题 FAQ

Q1:设置了 HF_ENDPOINT 还是走官方地址?

Q2:下载到一半报错 Connection refused?

Q3:hf_transfer 没有进度条咋办?

Q4:公司内网能用吗?

🎁 总结

📖 前言:一个让所有 AI 学习者崩溃的场景

做过 AI 的同学都懂这种痛:

$ from transformers import AutoModel $ model = AutoModel.from_pretrained("meta-llama/Llama-2-7b-hf") Downloading model.safetensors: 0%| | 12.5M/13.5G [05:23<98:21:47, 38.2KB/s]

🥲38 KB/s,13.5 GB 的模型,下载要98 小时。

等你终于下完了,老师都换下一个研究方向了。

别急,这篇文章给你四个亲测有效的方案,总有一个能把你的下载速度提升 100 倍以上。

本文适合:

• 🎓 正在学 AI 的学生党
• 🧑‍💻 在国内做大模型开发的工程师
• 🔧 折腾过但效果一般的老玩家(文末有组合拳)

🎯 一张表,看懂四种方案该选哪个

👇 下面逐个拆解,每种方案都给出完整可复制代码。

🤔 为什么 Hugging Face 在国内这么慢?(原理篇)

先讲清楚原理,你才能对症下药。

延迟与带宽的数学关系

TCP 协议下,单连接下载的理论最大速度由下式决定:

其中:

• Window Size:TCP 窗口大小(通常 64 KB ~ 几 MB)
• RTT(Round-Trip Time):往返时延

国内访问huggingface.co的 RTT 通常在250~400 ms,而访问国内镜像只有5~30 ms。

代入公式:

速度差距 30 倍以上。这就是为什么"换个镜像"就能起飞。

丢包带来的雪上加霜

考虑丢包率 p 和传输次数 k,有效吞吐率为:

跨境链路丢包率常年在 5%~20%,,单是丢包就把速度砍掉 65%。

架构示意

🌟 方案一:HF-Mirror 镜像站(99% 的人首选)

官网:https://hf-mirror.com/https://hf-mirror.com/

这是国内 AI 社区自发维护的公益镜像站,完整镜像了 HuggingFace 的模型和数据集,速度飞快,不需要任何账号。

✨ 核心原理:一行环境变量搞定

HuggingFace 的工具链会读取HF_ENDPOINT环境变量来决定从哪里下载。我们把它指向镜像站即可。

🔧 三种使用姿势

姿势 1️⃣:环境变量(推荐,一劳永逸)

Linux / macOS:

# 临时生效(当前终端) export HF_ENDPOINT=https://hf-mirror.com # 永久生效(写入配置文件) echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc source ~/.bashrc

Windows PowerShell:

# 临时生效 $env:HF_ENDPOINT = "https://hf-mirror.com" # 永久生效 [Environment]::SetEnvironmentVariable("HF_ENDPOINT", "https://hf-mirror.com", "User")

姿势 2️⃣:Python 代码内设置(临时用)

import os os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com' # 注意:必须在 import transformers 之前设置! from transformers import AutoModel model = AutoModel.from_pretrained("bert-base-uncased")

⚠️血泪坑:如果你先import transformers再设置环境变量,是不会生效的,因为库已经读取过变量了。

姿势 3️⃣:命令行直接下载

# 先安装官方 CLI pip install -U huggingface_hub # 下载模型 huggingface-cli download --resume-download Qwen/Qwen2-7B-Instruct \ --local-dir ./Qwen2-7B-Instruct \ --local-dir-use-symlinks False

📊 实测速度

📸配图建议:在这里插入一张下载进度条截图,显示速度从几十 KB/s 跳到 50+ MB/s 的瞬间。 截图命令:huggingface-cli download ...跑起来之后直接截屏就行。

实测下载 Qwen2-7B-Instruct(约 15 GB):

🔐 下载需授权的模型(Gated Model)

像meta-llama/Llama-2-7b-hf这种需要申请的模型,镜像站不支持登录,流程是:

1. 去官网huggingface.co登录并申请许可
2. 在 Settings → Access Tokens 创建 Token
3. 回到镜像站,用--token参数下载:

huggingface-cli download --token hf_xxxxxxxxxxxxxx \ --resume-download meta-llama/Llama-2-7b-hf \ --local-dir ./Llama-2-7b-hf

⚡ 方案二:官方 hf_transfer(速度王者)

HF-Mirror 已经很快了,但如果你的机器带宽是千兆/万兆(比如实验室服务器、云主机),想榨干带宽,上hf_transfer。

https://github.com/huggingface/hf_transferhttps://github.com/huggingface/hf_transfer

🧪 什么是 hf_transfer?

hf_transfer是 HuggingFace 官方用Rust 编写的底层加速库,专为高带宽环境设计,使用多连接并行 + 大块分片技术。

并行下载的时间复杂度:

其中 N 是并行连接数,是启动开销。实测在千兆网下可以轻松跑满带宽。

🔧 使用方法(三行代码)

# 1. 安装 pip install -U huggingface_hub hf_transfer # 2. 开启加速(环境变量) export HF_HUB_ENABLE_HF_TRANSFER=1 export HF_ENDPOINT=https://hf-mirror.com # 搭配镜像站效果更佳 # 3. 正常下载即可 huggingface-cli download Qwen/Qwen2-7B-Instruct --local-dir ./Qwen2-7B

⚠️ 使用前必看

💡建议:家庭宽带 100M 以下的同学,hf_transfer提升不明显,用方案一就够了。

🎨 方案三:ModelScope 魔搭社区(国产之光)

官网:https://modelscope.cn/studios?from=google_sem&gad_source=1&gad_campaignid=23130013561&gbraid=0AAAAA-G-q9s5NCUm7NS8eQfnJG3HaOgW8&gclid=Cj0KCQjw-pHPBhCdARIsAHXYWP84ieuh2wZ3ALVDGbgz7jscSzs1ufX3CGYWYE0tAVjn-xgsoTv_BXgaAtvFEALw_wcBhttps://modelscope.cn/studios?from=google_sem&gad_source=1&gad_campaignid=23130013561&gbraid=0AAAAA-G-q9s5NCUm7NS8eQfnJG3HaOgW8&gclid=Cj0KCQjw-pHPBhCdARIsAHXYWP84ieuh2wZ3ALVDGbgz7jscSzs1ufX3CGYWYE0tAVjn-xgsoTv_BXgaAtvFEALw_wcB

ModelScope 是阿里达摩院出品的模型社区,带宽堆料堆得很猛,国内 CDN 节点遍布,下载速度稳定飞快。

🎯 什么时候用 ModelScope?

🔧 使用方法

# 1. 安装 pip install modelscope # 2. Python 下载

from modelscope import snapshot_download # 直接下载整个模型仓库 model_dir = snapshot_download( 'qwen/Qwen2-7B-Instruct', cache_dir='./models', revision='master' ) print(f"模型已下载到:{model_dir}")

命令行方式:

modelscope download --model qwen/Qwen2-7B-Instruct --local_dir ./Qwen2-7B

💡 与 transformers 的无缝对接

下载完后,可以直接用transformers加载:

from transformers import AutoModelForCausalLM, AutoTokenizer # 加载本地路径即可,不用重新下载 model = AutoModelForCausalLM.from_pretrained("./models/qwen/Qwen2-7B-Instruct") tokenizer = AutoTokenizer.from_pretrained("./models/qwen/Qwen2-7B-Instruct")

🏆 方案四:hfd + aria2c 多线程(终极方案)

如果你要下载几十 GB 甚至上百 GB 的大模型(比如 Llama-3-70B、DeepSeek-V3),并且网络不太稳定、经常中断,上这个组合拳。

🧠 原理:多线程 + 断点续传

hfd是 HF-Mirror 官方开发的 Shell 脚本,底层用aria2c实现:

• 🧵16 线程并发下载同一文件
• ♻️断点续传,网络断了不用重来
• 📦 自动处理 git-lfs 大文件

速度模型(理想情况):

其中 N 是线程数,是带宽上限。只要带宽没跑满,线程越多越快。

🔧 安装与使用

# 1. 安装 aria2 # Ubuntu/Debian sudo apt-get install aria2 git-lfs # macOS brew install aria2 git-lfs # 2. 下载 hfd 脚本 wget https://hf-mirror.com/hfd/hfd.sh chmod +x hfd.sh # 3. 设置环境变量 export HF_ENDPOINT=https://hf-mirror.com # 4. 开始下载(16 线程) ./hfd.sh meta-llama/Llama-2-7b-hf --tool aria2c -x 16 # 下载数据集 ./hfd.sh wikitext --dataset --tool aria2c -x 16 # 带 Token 下载 ./hfd.sh meta-llama/Llama-2-7b-hf --hf_username YOUR_USER --hf_token hf_xxxx --tool aria2c -x 16

🎯 四大方案终极对比

💡 不同场景怎么选?一张图搞定

🛠️ 组合拳:终极速度配方

实战中,我通常这样组合:

# 一劳永逸的 .bashrc 配置 export HF_ENDPOINT=https://hf-mirror.com # 方案一:走国内镜像 export HF_HUB_ENABLE_HF_TRANSFER=1 # 方案二:开启 Rust 加速 export HF_HOME=~/.cache/huggingface # 统一缓存路径 # 然后正常用 huggingface-cli 或 transformers 即可

这套组合下来,单文件 80 MB/s,千兆网下 120 MB/s 稳稳的。

❓ 常见问题 FAQ

Q1:设置了 HF_ENDPOINT 还是走官方地址?

A:99% 是先 import 再设置环境变量了,改成在代码最开头设置,或者写到~/.bashrc里。

# ❌ 错误示范 from transformers import AutoModel import os os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com' # 太晚了 # ✅ 正确示范 import os os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com' from transformers import AutoModel # 在这之后导入

Q2:下载到一半报错Connection refused?

A:检查是否有残留的代理变量:

env | grep -i proxy # 如果有输出,先清掉 unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY

Q3:hf_transfer 没有进度条咋办?

A:升级到最新版pip install -U hf_transfer,0.1.4+ 版本已支持进度条。

Q4:公司内网能用吗?

A:要看内网是否允许访问hf-mirror.com。如果不允许,只能申请白名单或用内部镜像。

🎁 总结

再也不用看着 38 KB/s 的进度条发呆了 🚀