换个宇宙过去一年多，我一直在跟大模型打交道，工作里几乎每天都要从 Hugging Face 拉模型权重、数据集。下载这事看起来简单，但真到实操的时候，尤其是对国内开发者来说，坑真不少：某个模型文件几个 G 甚至几十个 G，浏览器点开半天不动；下载到一半连接断开，又要从头开始；明明调通了代码，换台机器、换个网络环境又卡在模型文件拉取上。这篇文章把我自己这段时间用下来的方法、踩过的坑、还有稳定的下载思路整理出来，希望能帮你省下一些时间。
里面会覆盖几个比较典型的场景：纯命令行下载、Python 代码里直接下载、镜像源切换、断点续传与并发加速、模型缓存目录迁移、内网离线传输，以及不同框架下（ollama、vllm、transformers）的模型下载区别。不管你是刚接触 Hugging Face 的小白，还是要在服务器上批量拉模型的老手，应该都能从里面找到对应的操作。
1. 为什么在 Hugging Face 下载大模型又慢又容易失败
1.1 慢的根源不只是服务器带宽
Hugging Face 的模型仓库本质上是一个 Git 仓库加一个文件存储系统。模型权重文件不像普通代码那样只有几 KB，而是动辄几 GB。以 Llama-3-8B 为例，光权重的 safetensors 文件就有约 4.5GB，如果下载速度只有几百 KB/s，那确实要等很长时间。很多人以为 Hugging Face 下载慢，是因为它的服务器在国外、跨境链路拥塞，这话只说对了一半。
真实情况是，Hugging Face 下载文件的请求会走多个重定向流程。当你通过 huggingface-cli 或者 transformers 的 snapshot_download 请求一个模型时，客户端先要访问主站读取仓库元数据（有哪些文件、文件大小、commit 版本），然后再通过 CDN 地址逐个拉取实际文件。整个链路的瓶颈不只是服务器物理距离，还包括 DNS 解析质量、TLS 握手时延、CDN 节点调度策略。更现实的问题是，一个普通家用宽带的国际出口带宽本身就有限，再叠加高峰时段的跨境流量拥塞，表现就是下载速度极不稳定，甚至连仓库元数据都拉不下来。
1.2 失败往往不是网络导致的，而是你的下载姿势不对
我见过很多刚接触大模型的朋友，安装完 huggingface_hub 之后，直接在代码里让 transformers 的 from_pretrained 去拉模型，结果跑到一半卡住不动。其实这不仅仅是网络问题，有几个细节经常被忽略：
- 没有设置超时和重试机制：Hugging Face 的下载请求默认超时时间在弱网环境下不够用，一旦 TCP 连接被重置，整个流程直接抛异常退出。
- 没有做断点续传：很多下载工具不支持断点续传，或者因为文件名、临时文件结构变动导致续传失败。
- 一次下载全部历史版本文件：Hugging Face 仓库里默认会带 .git 历史记录，如果用 git clone 方式拉取整个仓库，会把历史提交里的旧版本文件也一并拉下来，文件数量翻好几倍，经常拉到一半就失败。
- 内存占用问题：某些下载方式会把文件先读进内存再落盘，大文件很容易把内存吃满。
所以，想要稳定下载 Hugging Face 的大模型，不能只是换一个工具，而是要理解它的下载机制，然后用合适的工具、加合适的参数来操作。
1.3 先搞清楚常见的下载链路
这里先梳理一下访问 Hugging Face 资源的完整链路。你输入 huggingface.co 域名后，请求先经过 DNS 解析拿到服务器 IP，然后建立 TLS 加密连接，再访问模型仓库的 API 接口获取文件清单，最后从实际存储 URL 中下载每个文件。下载大模型时，绕开哪个环节都可能出问题。
正因为这样，比较有效的解决方法通常分为四类：
- 替换域名访问入口，使用地区内可稳定访问的镜像服务。
- 使用支持并发分片、断点续传的专业下载工具（如 hf_transfer、aria2）。
- 提前在本地准备好模型文件，通过离线方式拷入目标机器，避免在生产环境反复下载。
- 用缓存目录恢复机制，让代码不再重复下载已存在文件。
后面每一节都会落到具体的操作上面。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 最省事的方案：配置镜像源用 huggingface-cli 下载
2.1 镜像源是什么，为什么值得用
镜像源就是原站的复制品。Hugging Face 本身提供了部分资源的 CDN，但这些 CDN 节点在不同地区的调度效果差别巨大。我们这边常用的方式是使用国内可访问的 Hugging Face 镜像站，例如 hf-mirror.com。它的基本原理是定时同步 Hugging Face 上的主流模型仓库，让用户通过一个国内访问更稳定的域名来下载文件。
你不需要注册 Hugging Face 账号也可以下载绝大部分开源模型（除非原仓是 gated model，需要申请权限），镜像站通常也能同步处理这种授权模型，前提是你拿到过原站的访问令牌并在请求时带上。
2.2 设置环境变量，改一行配置
使用镜像站的最简操作是在你的 shell 环境中设置一个环境变量：
bash复制export HF_ENDPOINT=https://hf-mirror.com
这样设置之后，Hugging Face 官方工具链（比如 huggingface-cli、transformers、datasets）会自动把默认的 https://huggingface.co 替换为镜像地址。对于只跑一次的场景，直接在命令行前面加就行：
bash复制HF_ENDPOINT=https://hf-mirror.com huggingface-cli download meta-llama/Llama-3-8B --local-dir ./models/Llama-3-8B
如果你希望永久生效，可以写入 shell 配置文件：
bash复制echo "export HF_ENDPOINT=https://hf-mirror.com" >> ~/.bashrc
source ~/.bashrc
设置生效后，可以先快速验证是否正常：
bash复制huggingface-cli download sshleifer/tiny-gpt2 --local-dir ./test_hf
如果这个几十 MB 的小模型能顺利下载，说明链路是通的。
提示：不要把 HF_ENDPOINT 理解成只能设置成 hf-mirror.com，它只是告诉服务端“替代原域名”，完全兼容官方工具链，这也是它比手动改代码更方便的原因所在。
2.3 用 huggingface-cli 正确拉取模型文件
新版本的 huggingface_hub 把下载命令重构成了 huggingface-cli download，它替代了老版本的 transformers-cli。具体操作：
bash复制pip install -U "huggingface_hub[cli]"
huggingface-cli download gpt2 --local-dir ./gpt2
--local-dir 参数会把模型文件直接存到你指定的目录，而不是放进默认的缓存目录。这对我们部署模型很友好，下载完成后目录结构一目了然。
下载指定文件，而不是整个仓库时，可以使用 --include 和 --exclude：
bash复制huggingface-cli download Qwen/Qwen2.5-7B-Instruct --include "*.safetensors" --exclude "*.msgpack" --local-dir ./qwen2_5_7b
这样可以有效避免拉取一些辅助格式文件。*.safetensors 是 PyTorch 权重主文件，*.bin 相对少见，但有些老模型还在用。如果你只想下载一个 checkpoint 文件，可以精确到文件名：
bash复制huggingface-cli downl