Hugging Face大模型下载提速与镜像配置实战指南-代码聚汇网

Hugging Face大模型下载提速与镜像配置实战指南

换个宇宙·2026-09-04·阅读 22 GEO检测（免费）

Hugging Face大模型下载hf-mirror镜像

|难度：普通|阅读约 53 分钟

过去一年多，我一直在跟大模型打交道，工作里几乎每天都要从 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 download Qwen/Qwen2.5-7B-Instruct model-00001-of-00004.safetensors --local-dir ./qwen_part

这个功能在模型文件非常大、你只需要其中某几个分片重新合并的时候特别有用。我自己经常只要某个中间层权重做微调实验，就只拉对应分片，节省大量等待时间。

2.4 加参数实现断点续传和并发加速

实测下来，huggingface-cli 默认情况下下载单文件并不快。想提速，一个很实用的参数是 HF_HUB_ENABLE_HF_TRANSFER=1，它底层调用了 hf_transfer 库，实现了类似分片并发下载的机制。

先安装依赖：

bash复制pip install hf_transfer

然后设置环境变量再执行下载：

bash复制export HF_ENDPOINT=https://hf-mirror.com
export HF_HUB_ENABLE_HF_TRANSFER=1
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./qwen2_5_7b

注意，hf_transfer 模式为了追求速度，不会做本地文件进度校验，遇到网络抖动时失败概率会高一点。如果你的网络本身不太稳定，建议关闭这个开关，使用官方默认下载器。

那断点续传怎么办？官方默认下载器会把临时文件放在模型目录附近的 .cache 文件夹里，如果下载中断，重新执行同一条下载命令时，它会自动检测已下载的分块并继续传输。但这有个前提：你的下载目录、环境变量不能变，否则重新跑到另一个临时目录就前功尽弃了。

2.5 官方下载器和 hf_transfer 的取舍

这里我给一个比较直接的建议表：

场景	推荐方式	原因
内网服务器拉取海量模型	镜像源 + huggingface-cli	稳定、支持断点续传，适合长期挂机
需要快速下载超大单个文件	镜像源 + hf_transfer	分片并发，吞吐量明显提升
带宽有限且不稳定	官方默认下载器	hf_transfer 有时候直接失败，反而更慢
只需要模型中的个别文件	huggingface-cli download 加 include	避免全套下载

我个人的习惯是优先用默认下载器，如果多次出现“下载到 60% 就停住”的情况，再临时开 hf_transfer 或者换 aria2c 辅助。

3. 了解模型仓库结构与缓存目录，避免“重复下载”

3.1 Hugging Face 模型仓库里到底有什么

一个有代表性的模型仓库（比如 NousResearch/Hermes-3-Llama-3.1-8B）通常包含以下几类文件：

权重文件：model-00001-of-00004.safetensors，大模型的核心。
配置文件：config.json，包含模型结构超参数、模型类型等。
分词器文件：tokenizer.json、tokenizer_config.json、vocab.json、merges.txt。
生成配置：generation_config.json，控制采样参数。
README 文件：.md 后缀，有人用它做演示脚本入口。
附带文件：model.safetensors.index.json，这是 safetensors 分片的索引文件。

如果你的模型是 gguf 格式（量化后的通用格式），通常只有一个或者几个 .gguf 文件，外加简洁的 README。搞清楚这些文件的作用能够帮助你判断：到底哪些文件才是运行模型必需的。

3.2 为什么重复断网后重新下载，磁盘空间却越来越多

Hugging Face 的默认缓存设计是基于内容的，也就是说每个文件都会按它的内容哈希放到类似 ~/.cache/huggingface/hub/models--xxx 的目录下。第一次下载模型失败时，已经下载完的部分分片都躺在缓存里。重新下的时候，如果走的是同一套缓存目录，它会复用已有分片。

但问题往往出现在“缓存目录”不是你想的那个位置。很多教程里都会让你在代码里写：

python复制from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-7B-Instruct")

这个写法会默认从 ~/.cache/huggingface 找缓存，在你的用户名下的隐藏目录。如果是 root 用户，则路径是 /root/.cache/huggingface。如果磁盘空间不足，或者你在不同用户下反复下载了几次，每个用户各自建立了一份缓存，磁盘自然就不够用。

想查看当前缓存占用，可以用一个简单命令：

bash复制du -sh ~/.cache/huggingface/hub/*

想自定义缓存目录：

bash复制export HF_HOME=/data/hf_cache

或者更细粒度：

bash复制export HUGGINGFACE_HUB_CACHE=/data/hf_cache/hub

设置完后，不管是代码加载还是 huggingface-cli 下载，都统一走这个目录。这样模型文件在多个项目间可以复用，也方便我们做离线迁移。

3.3 使用 snapshot_download 的完整姿势与断点恢复技巧

如果你希望在 Python 代码里下载模型，而不是使用命令行，我推荐用 snapshot_download，因为它能返回模型在本地的实际路径，方便后续用 transformers 加载：

python复制import os

os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

from huggingface_hub import snapshot_download

model_dir = snapshot_download(
    repo_id="Qwen/Qwen2.5-7B-Instruct",
    local_dir="./qwen2_5_7b",
    local_dir_use_symlinks=False,
    resume_download=True,
    max_workers=8,
)
print("模型目录：", model_dir)

这里几个参数解释一下：

local_dir：指定模型存放的最终目录。不指定时按缓存目录结构保存。
local_dir_use_symlinks=False：避免创建软链接，直接保留完整文件副本。对于本地部署或拷贝到其他机器会更方便，但也会占用更多磁盘。
resume_download=True：开启断点续传，虽然现在的 huggingface_hub 默认重启时会自动检测，但显式写出来更保险。
max_workers=8：并发下载线程数，在某些高速网络下能明显提速。

如果中途下载断了，重新执行这个 Python 脚本，它会在原来基础上继续下载。这个方法比什么“重新 clone 仓库”要靠谱得多。

3.4 把已下载的缓存目录作为离线源给另一台机器使用

很多生产环境的服务器是没有外网访问权限的，这时你不可能直接在服务器上执行上述命令。一个稳妥的办法是，在一台有网络的机器上下载完模型，打包拷贝到服务器。

我通常这样操作：

bash复制huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./qwen_offline
tar -czf qwen_offline.tar.gz qwen_offline

拷贝到目标服务器后解压：

bash复制mkdir -p /models
tar -xzf qwen_offline.tar.gz -C /models

然后在目标服务器上通过代码直接加载本地目录，不需要经过 Hugging Face 链路：

python复制from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("/models/qwen_offline")

如果你下载模型时使用的不是 --local-dir 而是缓存目录形态，也完全可以。把整个缓存目录传到服务器后，将服务器的 HF_HOME 环境变量指向缓存目录所在的位置即可。

4. 镜像站之外：多种下载提速与验证方式

4.1 Hugging Face Hub 官方 API 传递关键参数

在实际部署中，如果不太想依赖环境变量，可以在 API 层面就固定好 endpoint。比如在 Python 工具类里直接指定：

python复制from huggingface_hub import HfApi

api = HfApi(endpoint="https://hf-mirror.com")
model_info = api.model_info(repo_id="Qwen/Qwen2.5-7B-Instruct")
for sib in model_info.siblings:
    print(sib.rfilename)

这个方法适合构建你自己的工具脚本，把镜像源地址和应用代码绑定在一起，避免每台新机器都忘记设置环境变量。不过要注意，HfApi 的 endpoint 参数在部分旧版 huggingface_hub 中不支持，使用前先升级一下比较稳妥：

bash复制pip install -U huggingface_hub

4.2 用 aria2c 做多连接分片下载

有时候我在服务器上跑的一个模型文件非常大（比如 40GB 的全量权重），并且不是通过 transformers 去加载，而是直接拿到文件后做后续操作。这种情况下我会用 aria2c 来下载。它本身和 Hugging Face 没有直接关系，是一个通用下载器，但它支持多连接、断点续传，非常稳定。

使用方式如下。先从 Hugging Face 页面找到模型文件直链，例如：

bash复制wget https://hf-mirror.com/Qwen/Qwen2.5-7B-Instruct/resolve/main/model-00001-of-00004.safetensors?download=true -O model-00001-of-00004.safetensors

如果希望用 aria2c 下载多个文件，可以先把链接写入文本文件：

bash复制aria2c -x 16 -s 16 -k 1M -c -i urls.txt

参数含义：

-x 16：单服务器最大连接数。
-s 16：将文件拆分为 16 段下载。
-k 1M：每段大小为 1MB。
-c：支持断点续传。
-i urls.txt：从文件读取 URL 列表。

这个方法对于单个超大文件的效果最明显，尤其在你的带宽上限比较高的情况下，下载速度可以接近带宽上限。

4.3 下载文件后的完整性校验

模型下载完不代表万事大吉。无论用什么方式下载，文件都有可能损坏。Hugging Face 仓库的 README 或官方文档中经常会给出每个文件的 SHA256 校验值，比如 llama 系列、mistral 系列。你可以单独下载那个校验文件，也可以从仓库中抓取校验值。

如果仓库里没有自带校验文件，可以先去 Hugging Face 模型页查看文件列表，有些文件右侧直接显示 SHA256。更简单的做法是下载完直接看文件大小是否和远程列表中的一致，如果一致，大概率没问题。对于大文件，我会跑一遍本地校验：

bash复制sha256sum model-00001-of-00004.safetensors

将输出结果和仓库页面对比。如果出现校验不通过，即便耗时再长，也要重新下这个文件，否则后续加载模型可能出现莫名其妙的 tensor 维度错误或者加载到一半报错。

4.4 遇到加载时报错并不是下载问题：从文件类型反推

有一种情况经常让人误以为是下载不完整：模型下载好后，用 transformers 加载时提示某个 key 不存在或者 vocab_size 对不上。这往往不是文件损坏，而是你下载的模型文件名和代码里 config 指定的加载路径不一致，或者该模型本来就是 GGUF 量化格式，你需要用 llama.cpp、ollama 这类工具加载，而不是直接用 transformers。

比如你要用 TheBloke/Llama-2-7B-Chat-GGUF 里的文件，用 Python 的 transformers 直接加载是行不通的，会报不支持的文件类型。这类模型需要用 ollama 或 llama.cpp。下载侧其实没问题，大家要分清“下载工具”和“推理引擎”的职责边界。ollama 自己有统一的模型管理方式。

5. 不想敲命令行？用 Python 和 Transformers 无缝加载模型

5.1 保持“下载”和“加载”分离的思路

在实际项目中，我很少在模型加载过程中直接远程下载大型权重。因为 transformers 的 from_pretrained 虽然带有下载功能，但一旦网络不稳定，报错信息不够明确，排查问题也不方便。比较稳妥的思路是：

用命令行或者独立脚本把模型完整下载到本地磁盘。
用代码从本地路径加载模型，不经过网络请求。

下面是一个比较完整的加载示例：

python复制import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_path = "./qwen2_5_7b"

tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype=torch.float16,
    device_map="auto",
    trust_remote_code=True,
)

input_text = "用一句话解释什么是注意力机制"
inputs = tokenizer(input_text, return_tensors="pt").to(model.device)
outputs = model.generate(**inputs, max_new_tokens=128)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

如果模型代码中包含自定义网络结构（这种情况在国产开源模型上不少见），trust_remote_code=True 是必需的。但安全提醒一下：除非你信任该仓库来源，否则不要轻易开启这个参数，它会让代码在本地执行仓库内的 .py 文件，存在一定的安全风险。

5.2 把下载脚本整合成自动化工具，适配团队需求

如果你所在的团队经常需要拉取大模型，不要让每个人去记命令。我一般写一个简易的 Python 脚本，只暴露几个参数，脚本内部处理好镜像源和缓存路径：

python复制import argparse
import os

os.environ.setdefault("HF_ENDPOINT", "https://hf-mirror.com")
os.environ.setdefault("HF_HUB_ENABLE_HF_TRANSFER", "1")

from huggingface_hub import snapshot_download

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--repo", required=True, type=str)
    parser.add_argument("--local_dir", required=True, type=str)
    parser.add_argument("--include", type=str, default=None)
    args = parser.parse_args()
    snapshot_download(
        repo_id=args.repo,
        local_dir=args.local_dir,
        local_dir_use_symlinks=False,
        allow_patterns=[args.include] if args.include else None,
    )

if __name__ == "__main__":
    main()

用法：

bash复制python download_model.py --repo Qwen/Qwen2.5-7B-Instruct --local_dir ./qwen2_5_7b --include "*.safetensors"

这样团队成员只需要知道模型名和目标目录，不需要关心镜像、并发参数等一堆细节。

5.3 模型下载后在 GPU 上的显存检查

很多人在模型加载完成后发现显存不够用，就想是不是要去换小模型。但先别急着换，可以看几个关键词：模型精度、上下文长度、推理框架。比如一个 7B 模型用 FP16 精度加载，显存占用至少 14GB 左右；如果改成 8bit 量化或者 4bit 量化，占用会降一大截。

python复制model = AutoModelForCausalLM.from_pretrained(
    model_path,
    torch_dtype=torch.float16,
    device_map="auto",
    load_in_8bit=True,  # 或者 load_in_4bit=True，需要 bitsandbytes
)

这个和下载本身是不同维度的问题，但经常一起出现，这里提一句能让读者少走弯路。

6. 完整案例：从零下载并部署一个 7B 中文模型

6.1 案例背景

为了把这篇文章的理论落到实操，我以 Qwen2.5-7B-Instruct 为例，带你走一遍完整的下载、校验、加载流程。Qwen 系列应该是目前国内使用最广泛的开源中文模型之一，Hugging Face 仓库结构也比较典型。

假设我有一台 8 卡 V100 的服务器，外网速度一般，磁盘 /data 有足够空间。目标是把模型放到 /data/models/qwen2.5-7b-instruct。

6.2 操作步骤

第一步，准备环境：

bash复制pip install -U huggingface_hub transformers accelerate

第二步，设置镜像源与缓存目录：

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

第三步，开始下载：

bash复制huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir /data/models/qwen2.5-7b-instruct

下载耗时取决于文件总大小和网速。7B 模型通常 FP16 格式需要约 15GB 的空间，看到命令行打印“done”并且本地目录出现 config.json、权重文件、分词器文件后，说明下载成功。

bash复制ls -lh /data/models/qwen2.5-7b-instruct

第四步，用 transformers 加载测试：

python复制from transformers import AutoModelForCausalLM, AutoTokenizer

model_path = "/data/models/qwen2.5-7b-instruct"
tokenizer = AutoTokenizer.from_pretrained(model_path)
model = AutoModelForCausalLM.from_pretrained(model_path, device_map="auto")

text = "写一份简短的中文自我介绍"
inputs = tokenizer(text, return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

如果能正常输出文字，说明整套流程已经打通了。

6.3 用 vllm 部署：下载模型的另一个高相关场景

如果你的目标是做 OpenAI 兼容接口服务，而不是简单的命令行体验，建议直接用 vllm 部署。它加载模型的方式同样可以指定本地目录，所以你先要做的还是下载模型。示例：

bash复制pip install vllm

部署：

bash复制python -m vllm.entrypoints.openai.api_server \
  --model /data/models/qwen2.5-7b-instruct \
  --served-model-name qwen2.5-7b-instruct \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.9

vllm 在加载本地模型时不会访问外网，但如果你忽略了下载这一步，直接把 Hugging Face 的 repo_id 传给 --model 参数，它在无网络环境下会直接失败。

这里也顺带解释一下为什么很多人提到 vllm 就要从 Hugging Face 下载模型：vllm 本身不提供模型文件，它只是一个推理框架，模型权重必须由用户提前准备。你完全可以使用 ModelScope（魔搭）下载同一个模型，只要最终得到的本地文件格式有效，vllm 并不关心文件是从哪个源拿到的。

6.4 和 ModelScope（魔搭）下载做对比，应该怎么取舍

在国内环境，很多开发者也会用 ModelScope 来下载模型。ModelScope 的优势在于对国内网络更友好，而且有一个 App 形态的工具 modelscope 支持命令行下载：

bash复制pip install modelscope
modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./qwen2_5_7b

和 Hugging Face 相比，两者在模型仓库结构上高度类似，因为很多模型会同步发布到两边。如果一个模型在 ModelScope 上有完整文件，而你在 Hugging Face 上下载异常，完全可以在 ModelScope 上下载后在本地使用，不需要纠结文件来源。

我平时的选择逻辑是：

如果模型较新，只在 Hugging Face 发布，那我优先用 HF 镜像源。
如果模型两边都同步发布，ModelScope 偶尔也会快很多，那就看哪个稳定用哪个。
如果要做离线交付，通常两边都下载一份，校验文件数量一致后选一个主要源。

不过要注意，有些模型仓库的 README 中包含了下载脚本、推理代码，两边不一定是完全实时同步的。如果你是为了复现官方特定的实验配置，尽量从官方网站链接指向的源下载。

7. 分场景避坑指南：你可能也会遇到的几个问题

7.1 设置镜像源后仍访问原站，怎么办

明明设置了 HF_ENDPOINT=https://hf-mirror.com，运行代码却还在访问 huggingface.co，这种问题我遇到过不止一次。原因基本有这几类：

环境变量没有在当前 shell 会话中生效：检查一下 echo $HF_ENDPOINT，如果输出为空，说明还没设置成功。
Python 进程是从 systemd 或其他守护进程启动的，它继承的不是你交互 shell 的环境变量：此时需要把环境变量写入系统级配置文件，或者直接在服务启动单元里指定。
代码里显式写了 endpoint="https://huggingface.co"：这种情况环境变量会被代码里的显式赋值覆盖，注意查找相关代码。
huggingface_hub 版本太旧：部分老版本对 HF_ENDPOINT 的支持并不完整，升级后正常。

排查方法也比较直接：把日志级别调成 DEBUG 看实际请求 URL。

python复制import logging
logging.basicConfig(level=logging.DEBUG)
from huggingface_hub import snapshot_download

如果请求仍然打到 huggingface.co，那基本就是环境变量没有传入进程。

7.2 模型下载到一半显示磁盘空间不足

下载大模型最怕磁盘满。一个 70B 模型原始权重可能有 140GB 左右，下载前一定要先确认空间。可以使用：

bash复制df -h
du -sh /data/models

另外要留意，使用 hf_transfer 并发下载时，默认会把文件先写进隐藏的临时目录，再移动到目标位置，所以需要的临时空间可能比模型体积还要大 5% 左右。下载完成后如果空间紧张，可以清理 huggingface 缓存中的临时文件：

bash复制rm -rf ~/.cache/huggingface/hub/*.incomplete

或者直接用 hf-hub 的命令做缓存清理（需要较新版本）：

bash复制huggingface-cli scan-cache
huggingface-cli delete-cache

不过 scan-cache 的输出结果可能比较长，谨慎操作，不要误删正在使用的模型文件。

7.3 Gated Model 需要登录怎么办

有些模型仓库是受限的，比如 Llama 3、Mistral 等官方发布版本，需要在 Hugging Face 网页上点击申请权限，通过之后才能下载。镜像站通常会原样保留这种机制。具体操作：

登录 Hugging Face 官网，在模型页面点击“Agree and access repository”。
创建一个 Access Token，在用户设置页面选择“New token”。
下载时传入 token：

bash复制huggingface-cli login

或者用环境变量方式：

bash复制export HF_TOKEN=hf_xxxxxxxx
huggingface-cli download meta-llama/Meta-Llama-3-8B-Instruct --local-dir ./llama3

要注意，token 不要写进团队共享的脚本或者提交到 Git 仓库，泄漏后别人可以冒用你的身份下载受限模型。

7.4 GGUF 格式模型下载后怎么加载

很多量化模型以 GGUF 格式发布在 Hugging Face 上，比如各路基于 Llama、Qwen 的量化版本。这种格式不能直接用 transformers 加载，需要用 llama.cpp 系列工具或者 ollama。下载方法和普通模型类似：

bash复制huggingface-cli download QuantFactory/Qwen2.5-7B-Instruct-GGUF --include "*.gguf" --local-dir ./qwen_gguf

然后通过 llama.cpp 转换或者 ollama 创建模型。这里要特别提醒：不要因为 transformers 加载 GGUF 报错，就觉得是下载工具的问题。

ollama 的使用方式也值得顺带提一下。它自己维护了一个模型仓库，但有些模型是通过内部命令从 Hugging Face 拉取 GGUF 后导入的。如果你想完全离线使用，可以先用上述方法下载 GGUF 文件，再创建一个 Modelfile 指向本地文件：

bash复制FROM /data/models/qwen_gguf/qwen2.5-7b-instruct-q5_k_m.gguf

TEMPLATE """{{ .Prompt }}"""

SYSTEM """You are a helpful assistant."""

然后在 ollama 目录下执行：

bash复制ollama create myqwen -f Modelfile
ollama run myqwen

这样就把 Hugging Face 下载文件、GGUF 离线导入、ollama 部署三个环节串起来了。

7.5 下载速度波动大，需要监控实际速率

下载大模型时，如果你想知道实时速度，huggingface-cli 默认输出中已经带了百分比和平均速度。如果使用 hf_transfer，输出信息会比较少，甚至只在结束后显示总耗时。想要更细的观察，可以用 tqdm 或者在外面包一层 screen 命令，避免长时间任务因终端断开而中断。

bash复制screen -S hf_download
huggingface-cli download ...
# Ctrl+A D 退出会话，之后 screen -r hf_download 恢复

这个看起来不起眼的操作，在几百 GB 的模型下载过程中是真的能救命。

8. 换个角度：下载问题其实是模型工程化里的第一公里

把 Hugging Face 下载这层理清楚之后，你会发现后面无论是模型微调、量化、推理服务化，都踏实了很多。实际上，我在工作中看到很多部署事故都不是模型本身的问题，而是“权重文件没准备好”或者“目录引用错乱”导致的。如果从一开始就养成把下载和加载分离、把缓存目录规划好、把校验做起来的习惯，后续的容器化部署、多机分布式推理都能减少很多不必要的麻烦。

再分享一个自己的习惯：不论从哪种源下载，我都会在下载结束后记录模型的 commit 信息和文件大小。因为同一模型在不同时间点可能被作者更新过，带 .git 元数据的 repo 会动态变化。如果你想复现别人的实验，使用同一个 commit id 很重要。用 snapshot_download 的时候可以传入 revision 参数指定 commit hash：

python复制snapshot_download(
    repo_id="Qwen/Qwen2.5-7B-Instruct",
    revision="a9b0b1e...",
    local_dir="/data/models/qwen2.5-7b-instruct",
)

如果没有指定 commit hash，Hugging Face 默认拉取 main 分支最新版本，这样可能下来后和你之前的代码有兼容性问题。

下载模型从来不是一个高级技术，但它确实是决定模型能否顺利跑起来的第一公里。把每一步的原理和可能踩的坑都吃透，剩下的事情就水到渠成了。希望这篇内容能帮你用更稳定的方式拿到自己想要的模型，顺利跑通整个实验和应用链路。