本文目录
先确认慢的是 Hub 页面、Xet 分块，还是旧 Git LFS 下载
Hugging Face 模型下载慢或中断时，先别急着清缓存。模型卡和 config.json 是普通 Hub 请求，大权重通常由 Xet 分块下载，旧仓库也可能继续走 Git LFS；三条路径使用的工具、日志和恢复方式不同。先用小文件确认账号与网络，再设置 Clash 代理、超时和缓存目录。
当前下载方式
| 方式 | 实际大文件后端 | 适合场景 |
|---|---|---|
| huggingface_hub / hf CLI | huggingface_hub 0.32+ 自动安装 hf_xet，使用 Xet 分块下载 | 模型与数据集下载首选 |
| git clone + git-xet | Xet，仍保留 Git 工作流 | 需要完整仓库与提交历史 |
| 旧 Git LFS 客户端 | 通过兼容桥继续工作 | 遗留流程；不是当前性能首选 |
| 浏览器单文件 | Hub 生成的下载地址 | 查看小文件或临时下载 |
Hugging Face 官方文档说明，Hub 已采用 Xet；Git LFS 仍兼容，但 hf_transfer 已弃用，应改用 hf_xet。旧教程让用户只安装 Git LFS、开启 HF_HUB_ENABLE_HF_TRANSFER，已经不适合作为 2026 年默认方案。
先下载 config.json，把许可和网络分开
python -m pip install -U huggingface_hub
hf auth login
hf download gpt2 config.json
# 查看版本
python -c "import huggingface_hub; print(huggingface_hub.__version__)"公开模型的小文件成功，说明 Hub 元数据、基本 HTTPS 和本地缓存目录可用。受限模型返回 401/403 时，在浏览器用同一账号接受许可并检查 token 的 read 权限；换节点不会让账号自动获批。
token 由 hf auth login 保存，不写进 Clash YAML、Notebook 单元格或公共脚本。团队服务器使用自己的 secrets 管理，不复制个人 token。
环境变量必须在导入 huggingface_hub 前设置
CLASH_PORT=7890
export HTTPS_PROXY="http://127.0.0.1:$CLASH_PORT"
export HTTP_PROXY="http://127.0.0.1:$CLASH_PORT"
export HF_HOME="$HOME/hf-cache"
export HF_HUB_DOWNLOAD_TIMEOUT=30
mkdir -p "$HF_HOME"
hf download openai-community/gpt2 --include '*.json'
hf download openai-community/gpt2 --cache-dir "$HF_HOME/hub"官方文档注明 huggingface_hub 在 import 时读取环境变量。Notebook 已经导入库后再修改变量，当前内核可能继续使用旧值；应重启 kernel 或在启动前设置。HF_HUB_DOWNLOAD_TIMEOUT 默认 10 秒，只有连接已经建立但读取慢时才适合提高。
HF_HOME 同时影响 token 和缓存根目录；只想移动仓库缓存可以使用 HF_HUB_CACHE 或命令的 --cache-dir。目录必须由当前用户可写，并为临时分块、模型 revision 与解压留出空间。
网页能开、模型分块超时，要在连接页找 Xet 请求
模型卡和 README 是短请求，Xet 大文件下载还会访问内容寻址与预签名存储地址。网页正常只证明 huggingface.co 可达；分块开始后反复重试，应固定一个节点，查看失败域名、状态码与缓存写入错误。
自动策略在下载中途换出口，预签名 URL 与并发连接可能一起失效。把相关 Hub/Xet 请求放进一个固定策略组，完整下载结束后再恢复自动选择。不要把临时存储域名永久写成一条过宽的 DOMAIN-KEYWORD 规则。
401 / 403
检查仓库许可与 token，不增加超时。
httpx.TimeoutException / Read timed out
固定节点、检查 Xet 请求命中，再适度增加 HF_HUB_DOWNLOAD_TIMEOUT。
No space left on device
移动 HF_HOME/HF_HUB_CACHE，保留已完成缓存，不换节点。
Permission denied 写缓存
修正目录所有者与挂载权限，不以 root 重下整份模型。
只得到几 KB 的指针文件
Git 流程缺少 git-xet/git-lfs 或大文件检出未完成。
重跑同一 revision，先复用 Hub 缓存，再决定是否开启 Xet 分块缓存
默认 Hub 缓存在 ~/.cache/huggingface/hub，Xet 的相关文件位于 ~/.cache/huggingface/xet；设置 HF_HOME 后两者会一起移动。
Hub 的 refs、blobs 与 snapshots 会复用已经完成的文件。下载中断后应使用相同的 repo_id、revision、用户和缓存目录重跑。
当前官方文档说明 Xet chunk cache 默认大小为 0，也就是默认关闭。只有经常下载相同内容范围、并且磁盘空间足够时，才考虑设置 HF_XET_CHUNK_CACHE_SIZE_BYTES。单次下载慢时先固定节点和增加下载超时，不要为了试缓存先删除已经完成的 blobs。
from pathlib import Path
from huggingface_hub import snapshot_download
cache_dir = Path.home() / "hf-cache" / "hub"
path = snapshot_download(
repo_id="openai-community/gpt2",
revision="main",
cache_dir=cache_dir,
)
print(path)必须使用 Git 时，安装 git-xet 并保留 LFS 兼容
只有项目确实依赖 Git 历史或分支操作时，才需要走这条路径。普通模型下载优先使用 hf download，断点续传和缓存更容易观察。
HF_REPO='OWNER/MODEL'
# 例如 HF_REPO='openai-community/gpt2'
git lfs install
git xet install
git clone "https://huggingface.co/$HF_REPO"
cd "${HF_REPO##*/}"
git xet --version
git lfs version
git status没有 git xet 命令时，先按官方平台说明安装 git-xet；macOS 可使用 Homebrew，Windows 官方文档提供 winget 安装方式。旧客户端仍可经 LFS bridge 下载，但遇到速度与大文件问题时，应优先升级 Hugging Face 工具链。
Git 自己使用 git config 与环境变量，和 Python SDK 不是同一配置。hf CLI 正常、git clone 卡住时，只检查 Git/Xet/LFS 与 Git 代理，不再改 HF_HOME。
下载完成后断开网络，确认模型真的在本地
进度条走完后，项目仍可能在加载 tokenizer、配置或自定义代码时访问 Hub。最后要用实际项目做一次断网测试，确认所有必需文件都已进入本地缓存。
交付验证
再次运行同一下载命令
应快速命中相同 snapshot，而不是重新传输全部分块。
加载一次模型
使用实际 transformers 或项目代码读取权重与 tokenizer。
启用离线模式测试
已缓存内容可用时，设置 HF_HUB_OFFLINE=1 或使用 local_files_only，不应再访问 Hub。
检查凭据与空间
Notebook、日志和 Git 历史没有 token，缓存盘仍有升级余量。
记录 revision 与 snapshot 路径
下次更新模型时能区分新版本下载与旧缓存损坏。