‍♂️ 个人主页小李同学_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 多线程(终极方案) 原理:多线程 断点续传 安装与使用 四大方案终极对比 不同场景怎么选?一张图搞定️ 组合拳:终极速度配方❓ 常见问题 FAQQ1:设置了 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:2398:21:47, 38.2KB/s]38 KB/s,13.5 GB 的模型,下载要98 小时。等你终于下完了,老师都换下一个研究方向了。别急,这篇文章给你四个亲测有效的方案,总有一个能把你的下载速度提升 100 倍以上。本文适合: 正在学 AI 的学生党‍ 在国内做大模型开发的工程师 折腾过但效果一般的老玩家(文末有组合拳) 一张表,看懂四种方案该选哪个方案速度评级难度稳定性适用场景① HF-Mirror 镜像站⭐⭐⭐⭐ 极简⭐⭐⭐⭐绝大多数情况首选② 官方 hf_transfer⭐⭐⭐⭐⭐ 中等⭐⭐⭐带宽足、追求极速③ ModelScope 魔搭⭐⭐⭐⭐ 极简⭐⭐⭐⭐⭐下载国产模型④ hfd aria2 多线程⭐⭐⭐⭐⭐ 较高⭐⭐⭐⭐超大模型 / 不稳网络 下面逐个拆解,每种方案都给出完整可复制代码。 为什么 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_ENDPOINThttps://hf-mirror.com # 永久生效(写入配置文件) echo export HF_ENDPOINThttps://hf-mirror.com ~/.bashrc source ~/.bashrcWindows 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):方案平均速度总耗时直连 huggingface.co50 KB/s ~ 2 MB/s几乎不可能HF-Mirror30 ~ 80 MB/s约 5~8 分钟 下载需授权的模型(Gated Model)像meta-llama/Llama-2-7b-hf这种需要申请的模型,镜像站不支持登录,流程是:去官网huggingface.co登录并申请许可在 Settings → Access Tokens 创建 Token回到镜像站,用--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_TRANSFER1 export HF_ENDPOINThttps://hf-mirror.com # 搭配镜像站效果更佳 # 3. 正常下载即可 huggingface-cli download Qwen/Qwen2-7B-Instruct --local-dir ./Qwen2-7B⚠️ 使用前必看特性说明✅ 优点速度极快,能跑满千兆带宽❌ 缺点 1不支持进度条(版本低时)❌ 缺点 2错误处理较差,网络抖动容易整个失败❌ 缺点 3需要带宽足够,低带宽下反而可能慢建议:家庭宽带 100M 以下的同学,hf_transfer提升不明显,用方案一就够了。 方案三:ModelScope 魔搭社区(国产之光)官网:https://modelscope.cn/studios?fromgoogle_semgad_source1gad_campaignid23130013561gbraid0AAAAA-G-q9s5NCUm7NS8eQfnJG3HaOgW8gclidCj0KCQjw-pHPBhCdARIsAHXYWP84ieuh2wZ3ALVDGbgz7jscSzs1ufX3CGYWYE0tAVjn-xgsoTv_BXgaAtvFEALw_wcBhttps://modelscope.cn/studios?fromgoogle_semgad_source1gad_campaignid23130013561gbraid0AAAAA-G-q9s5NCUm7NS8eQfnJG3HaOgW8gclidCj0KCQjw-pHPBhCdARIsAHXYWP84ieuh2wZ3ALVDGbgz7jscSzs1ufX3CGYWYE0tAVjn-xgsoTv_BXgaAtvFEALw_wcBModelScope 是阿里达摩院出品的模型社区,带宽堆料堆得很猛,国内 CDN 节点遍布,下载速度稳定飞快。 什么时候用 ModelScope?情况推荐度下载国产模型(Qwen、ChatGLM、Baichuan、DeepSeek、Yi)⭐⭐⭐⭐⭐ 必用下载国外冷门模型⭐⭐ 可能没有追求稳定(镜像站挂了)⭐⭐⭐⭐⭐ 最佳备胎 使用方法# 1. 安装 pip install modelscope # 2. Python 下载from modelscope import snapshot_download # 直接下载整个模型仓库 model_dir snapshot_download( qwen/Qwen2-7B-Instruct, cache_dir./models, revisionmaster ) 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_ENDPOINThttps://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 四大方案终极对比维度HF-Mirrorhf_transferModelScopehfdaria2 速度30-80 MB/s100 MB/s50-100 MB/s100 MB/s 学习成本⭐⭐⭐⭐⭐⭐⭐ 配置步骤1 步3 步2 步4 步 稳定性好一般极好好 断点续传✅⚠️ 有坑✅✅ 模型覆盖全量镜像全量(走官方或镜像)国产为主全量镜像 Gated Repo✅ 支持✅ 支持-✅ 支持 费用免费免费免费免费 不同场景怎么选?一张图搞定️ 组合拳:终极速度配方实战中,我通常这样组合:# 一劳永逸的 .bashrc 配置 export HF_ENDPOINThttps://hf-mirror.com # 方案一:走国内镜像 export HF_HUB_ENABLE_HF_TRANSFER1 # 方案二:开启 Rust 加速 export HF_HOME~/.cache/huggingface # 统一缓存路径 # 然后正常用 huggingface-cli 或 transformers 即可这套组合下来,单文件 80 MB/s,千兆网下 120 MB/s 稳稳的。❓ 常见问题 FAQQ1:设置了 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_PROXYQ3:hf_transfer 没有进度条咋办?A:升级到最新版pip install -U hf_transfer,0.1.4 版本已支持进度条。Q4:公司内网能用吗?A:要看内网是否允许访问hf-mirror.com。如果不允许,只能申请白名单或用内部镜像。 总结TL;DR新手直接抄这两行export HF_ENDPOINThttps://hf-mirror.combr/pip install -U huggingface_hub千兆网加这一行export HF_HUB_ENABLE_HF_TRANSFER1下 Qwen/ChatGLM直接用 ModelScope下 100GB 大模型hfd.sh aria2c -x 16再也不用看着 38 KB/s 的进度条发呆了