Hugging Face模型下载加速：镜像站+官方CLI一条命令搞定断点续传

不看不知道，很多人在常规网络环境下从 Hugging Face 下载模型，第一反应都是去折腾各种复杂的网络辅助工具。我折腾过一轮之后发现，真没必要。用镜像站加官方命令行工具，一条命令就能把几百 MB 甚至几十 GB 的模型稳定拉下来，还自带断点续传，比手动点网页下载省心太多。

这篇文章是我这段时间反复实操之后整理的完整记录，从核心原理到具体命令再到踩坑排查都有。适合刚接触 Hugging Face、还没摸清下载流程的新手，也适合被大模型断传折腾过的老手。看完你可以直接照着抄作业。

1. 先看整体思路：为什么“镜像站 + 命令行”是首选

1.1 下载模型慢的根源

Hugging Face 上很多模型动辄几个 GB，大一点的几十 GB 也很常见。直接在浏览器里点单个文件下载，体验其实非常糟糕：一是浏览器下载默认不走任何并行分片，单线程拉几百 MB 文件，速度很难上去；二是连接链路长、网络波动大，下载到一半直接报错，浏览器又不会自动断点续传，只能从头再来。

我见过不少朋友下某个 7B 模型，在网页上点了两天都没拉下来，最后放弃。原因不复杂：单个大文件 + 不稳定的传输链路 + 没有续传机制，三个问题叠在一起，谁用谁知道。

1.2 绕开复杂网络设置的三个可行性方案

要解决这个问题，通常有三条路可以走：

1. 在 Hugging Face 网页上手动下载。 适合小文件、临时看一眼。对 GB 级模型不友好，慢且容易断。
2. 使用官方 Python SDK / 命令行工具直接拉取。 支持断点续传、可脚本化、可筛选文件，是目前最主流的做法。但因为仍走默认的国际链路，速度可能不尽如人意。
3. 使用镜像站 + 官方 CLI。 本质上是把下载请求指向离你更近、连接更稳定的镜像服务，传输更快，配合官方命令行工具的续传和并发能力，体验最好。

我最后还是选了第三种方案。它的核心思路可以类比成：以前你要去仓库提货，仓库很远、路上还堵车；现在你换到一个直接合作的分仓，路很短、货架也已经备好货，提货效率自然就上去了。

1.3 为什么不是随便找个第三方下载器

网上确实有很多第三方下载器或脚本，号称能一键拉取模型。但我的建议是优先用官方 CLI，原因很现实：官方工具维护及时、语法稳定、不会因为 Hugging Face 接口变动而废掉；第三方脚本往往只针对某个特定模型或某个时期有效，一旦对方不维护，报错都没地方问。

所以在这篇文章里，我的主线思路始终是：用交易量最大的官方命令行工具，配合一个可靠的镜像中转，解决传输链路过长和断传问题。

2. 动手前准备：工具安装与关键环境变量

2.1 安装 huggingface_hub 并验证命令行

官方 CLI 集成在 huggingface_hub 这个 Python 包里，安装很简单：

bash复制pip install -U huggingface_hub

如果你用的是 Windows，或者当前 Python 环境有权限限制，可以加 --user 或使用虚拟环境：

bash复制python -m venv hf-venv
source hf-venv/bin/activate      # Windows 下运行 hf-venv\Scripts\activate
pip install -U huggingface_hub

装完之后验证一下：

bash复制huggingface-cli version

能正常输出版本号，就说明环境没问题。有些人可能会遇到 huggingface-cli 不是内部命令、无法识别之类的情况，多半是 Python 的 Scripts 目录没有加入 PATH，直接运行 python -m huggingface_hub.cli.cli version 也可以检查。

2.2 设置 HF_ENDPOINT 指向镜像站

这是整个方案里最关键的一步。huggingface_hub 会自动读取一个叫 HF_ENDPOINT 的环境变量，只要把它指向镜像站地址，所有官方 API 的请求就都会自动走这个地址。

Linux / macOS 临时生效：

bash复制export HF_ENDPOINT=https://hf-mirror.com

Windows PowerShell 临时生效：

powershell复制$env:HF_ENDPOINT="https://hf-mirror.com"

Windows CMD 临时生效：

cmd复制set HF_ENDPOINT=https://hf-mirror.com

如果你希望长期生效，可以把这行写进 shell 的配置文件，比如 ~/.bashrc 或 ~/.zshrc；Windows 可以用 setx HF_ENDPOINT https://hf-mirror.com。

设置完之后，建议先 echo $HF_ENDPOINT 确认值已经写入，以免后面命令跑起来发现没生效，白折腾。

注意：环境变量是区分大小写的，不要写成 hf_endpoint 或 Hf_Endpoint，否则不会被识别。

2.3 搞懂 --local-dir 和断点续传

很多新手下载完模型之后发现文件不知去向，或者路径乱七八糟，这通常是因为没有用 --local-dir 参数。默认情况下，命令行工具会按缓存结构保存文件，目录层级很深，对人不友好。

我的建议是下载时直接指定一个可读的本地目录：

bash复制huggingface-cli download <模型ID> --local-dir ./models/<模型名>

这样文件就会原样保存在目标目录下，你打开就能看到 config.json、model.safetensors、tokenizer.json 这类文件，非常直观。

关于断点续传，旧版本需要手动加 --resume-download，新版已经默认启用续传机制。中途断网或 Ctrl+C 中断，重新执行同一条命令，它会把没下完的部分续上，不用从头开始，这个功能相当实用。

3. 实操：四种高频下载场景的完整命令

3.1 场景一：下载完整模型仓库到指定目录

创建一个干净的目录，进入后执行：

bash复制huggingface-cli download <模型ID> --local-dir ./models/<模型名>

比如你打算下载一个英文文本生成模型（这里用占位符举例），可以写成：

bash复制huggingface-cli download my-org/my-model --local-dir ./models/my-model

执行之后，终端会打印出当前正在下载的文件列表，以及实时进度条。模型里的 config.json、tokenizer.json、safetensors 权重等都会陆续落盘。整个过程全自动，不需要你手动一个个点。

如果你在服务器上跑，建议加上 --local-dir 之后再把终端挂到后台或 tmux 里，避免 SSH 断开导致任务中断。

3.2 场景二：只下载需要的权重文件

有时候你只需要权重，不需要模型仓库里的 onnx 目录、tf_model.h5 这类额外格式文件。这种情况用 --include 参数做筛选更省时：

bash复制huggingface-cli download my-org/my-model \
  --local-dir ./models/my-model \
  --include "*.safetensors" \
  --include "config.json" \
  --include "tokenizer*"

如果是反向思路，想排除某些文件，则用 --exclude：

bash复制huggingface-cli download my-org/my-model \
  --local-dir ./models/my-model \
  --exclude "*.h5" \
  --exclude "onnx/*"

--include 和 --exclude 可以组合使用。命令行工具会先按 include 规则保留匹配文件，再用 exclude 规则剔除。实测下来，用筛选参数可以省下好几 GB 的无效流量。

3.3 场景三：下载数据集

下载数据集和下载模型的命令很相似，只需要加上 --repo-type dataset：

bash复制huggingface-cli download my-org/my-dataset \
  --repo-type dataset \
  --local-dir ./datasets/my-dataset

数据集仓库有时候会很大，推荐像场景二那样，用 --include "*.parquet" 之类的参数只拉你需要的格式。默认的 repo-type 是 model，下载数据集时忘记加参数，终端会直接报仓库不存在，所以这个点要记住。

3.4 场景四：需要鉴权的受限模型

有些模型是受限访问，页面上会显示 “Gated Model”，需要你登录并同意协议才能下载。直接从命令行下载会遇到 403 或仓库不存在之类的报错。

解决办法是先去 Hugging Face 网站登录，在个人设置里生成一个 Access Token，然后带着 token 下载：

bash复制huggingface-cli download my-org/gated-model \
  --token hf_xxxxxxxxxxxxxxxxxxxx \
  --local-dir ./models/gated-model

也可以用环境变量 HF_TOKEN 替代写在命令里：

bash复制export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx
huggingface-cli download my-org/gated-model --local-dir ./models/gated-model

提示：Token 相当于你的账号凭证，不要把它写进公开的脚本、笔记或 GitHub 仓库。如果发现在公共地方泄露了就立即去后台重置。

4. 继续提速：并发传输工具与自动化脚本

4.1 hf_transfer 一键加速

如果你想进一步压榨带宽，可以开启 Hugging Face 官方出品的并发传输模块 hf_transfer。安装和开启都很简单：

bash复制pip install hf_transfer
export HF_HUB_ENABLE_HF_TRANSFER=1

Windows PowerShell 下同样设置环境变量即可。设置完成后再执行下载命令，底层传输层会切到 Rust 实现的并发下载，多分片同时拉取，大文件速度提升非常明显。

不过它也有个特点：比较激进，网络抖动时可能会直接报错退出。如果你发现开启后反而更容易失败，关掉这个环境变量就好，不用勉强。

4.2 用 Python 脚本做批量下载和增量更新

命令行适合手动操作，如果要批量下载多个模型，或者定期更新，建议直接写脚本调用 snapshot_download：

python复制# download_model.py
from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="my-org/my-model",          # 替换成真实模型ID
    repo_type="model",
    local_dir="./models/my-model",
    allow_patterns=["*.safetensors", "config.json", "tokenizer*"],
    ignore_patterns=["*.msgpack", "*.h5", "onnx/*"],
)

联盟参数里，allow_patterns 对应命令行的 --include，ignore_patterns 对应 --exclude。每次运行这个脚本，它都会校验本地已有文件，只补下载缺失或变更的部分，天然支持增量更新。

我自己的习惯是把模型 ID、保存路径都放进一个配置文件，脚本循环读取，批量拉取一整个模型列表，非常省事。

4.3 大文件断传的兜底方案

镜像站和官方 CLI 已经能解决大部分问题。但如果你是超大文件重度用户，比如上百 GB 的模型，我建议在高并发模式下再备一个多线程下载器作为兜底。

思路并不复杂：先用命令行工具把文件清单拉出来，把每个大文件对应的 URL 提取出来，再交给多线程下载器分片下载。不过这个过程需要手动解析仓库文件列表，相对繁琐，不是必要情况我不推荐优先尝试。

实测下来，对绝大多数人来说，“镜像站 + 官方 CLI + hf_transfer”的组合已经足够顺畅，兜底方案只作为极端网络场景的备用手段。

5. 常见问题与排查技巧实录

5.1 问题速查表

5.2 我踩过的几个坑

第一个坑是旧版命令习惯。早期版本需要 transformers-cli download 或者 python -m huggingface_hub.cli.download，现在统一用 huggingface-cli download 就对了。如果你在网上找到的教程还在说 transformers-cli，大概率是过时信息，直接别理。

第二个坑是 --resume-download。新版换了默认行为，手动加这个参数反而可能报错，因为该参数已经不再被支持。如果你在某个脚本里看到它，删掉就行，新版默认就会续传。

第三个坑是镜像站偶尔也会慢。毕竟它承担了大量并发请求，高峰时段速度波动很正常。我碰到这种情况会换个时间段再下，或者临时切回官方直连试试，不要死磕一个方案。

第四个坑是下载到默认缓存目录找不到文件。如果你第一次下载时没加 --local-dir，文件会散落在 ~/.cache/huggingface/hub 里，而且目录结构是按缓存块组织的，不方便直接拷走。后来我每次下载都固定加 --local-dir，文件一目了然。

5.3 如何验证下载是否完整

下载完成后不要急着立刻删源文件，建议先做一次基本验证。最直接的办法是用 Python 把模型加载起来：

python复制from transformers import AutoModel, AutoTokenizer

model = AutoModel.from_pretrained("./models/my-model")
tokenizer = AutoTokenizer.from_pretrained("./models/my-model")
print("加载成功，模型结构如下：", model.config.model_type)

能正常加载就说明权重文件基本完整。如果你只下载了部分权重文件，加载时可能会因为缺少分片报错，这时候再回到仓库里看缺了哪些分片，按文件名筛出来重新拉取即可。

6. 最后再分享一点我的下载习惯

说到习惯，我在实际使用中比较依赖“先小后大”的策略。第一次下载某个模型时，我会先只拉 config.json 和 tokenizer 这类小文件，快速确认路径、协议、环境变量都没有问题，再放开下载完整权重。这样可以把最常见的问题在最早期暴露掉，免得等权重快下完了才发现路径错了。

另外，如果你和我一样需要在多台机器上反复复现同一个环境，强烈建议把下载命令写成一个脚本，固定好镜像地址和 --local-dir 路径。换机器时直接跑一次脚本，比手输命令要可靠得多。数据、脚本、环境配置都按同一套目录规则摆好，后面排查问题会省下很多时间。

整个流程跑顺之后你会觉得，下载 Hugging Face 模型本来就不需要多么复杂的网络改造。一条环境变量、一条命令，剩下的都交给镜像站和官方工具自己处理就可以了。