本文目录
模型页面能打开，下载却在大文件开始后反复重试，继续加超时或清空缓存不一定有帮助。小文件和权重可能使用不同下载方式，账号许可、代理出口与磁盘空间也要分别确认。保留已完成的文件，再对照实际使用的工具排查，才能减少从头下载的次数。
Hub 小文件、Xet 分块与旧 Git LFS，下载方式有什么区别？
用模型卡或 config.json 确认普通 Hub 请求；大权重通常由 Xet 分块下载，分块即把大文件拆成较小内容分别传输。按下表确认正在用哪种工具，旧 Git LFS 有自己的兼容方式；排查时保留已完成缓存，再用小文件核对账号和网络。
当前下载方式
| 方式 | 实际大文件后端 | 适合场景 |
|---|---|---|
| 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 前设置
下面的示例会改用 HF_HOME。上一节登录后，先确认仍在使用同一 token 来源：HF_TOKEN 的值会优先用于认证，HF_TOKEN_PATH 可另定文件位置，默认 token 文件则随 HF_HOME 改变。
先确定代理和缓存目录，再做受限模型下载；更改目录后用 hf auth whoami 核对当前账号，必要时在该环境重新登录。公开模型示例不要求登录，成功也不能证明受限模型许可有效。
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 可达；分块开始后反复重试，应固定一个节点，查看失败域名、状态码与缓存写入错误。
先把相关 Hub/Xet 请求放在同一个固定节点上做对照，排除不同出口的可达性差异；下载结束后再恢复自动选择。换出口本身不能证明预签名 URL 已失效，仍应查看状态码与授权信息。不要把临时存储域名永久写成过宽的 DOMAIN-KEYWORD 规则。
401 / 403
检查仓库许可与 token，不增加超时。
httpx.TimeoutException / Read timed out
固定节点并确认失败请求命中；Hub 文件读取慢时可调整 HF_HUB_DOWNLOAD_TIMEOUT，Xet 分块错误则按 hf_xet 日志另查，不能假定同一变量控制全部下载。
No space left on device
移动 HF_HOME/HF_HUB_CACHE，保留已完成缓存，不换节点。
Permission denied 写缓存
修正目录所有者与挂载权限，不以 root 重下整份模型。
只得到几 KB 的指针文件
Git 流程缺少 git-xet/git-lfs 或大文件检出未完成。
复用已完成的 Hub 文件，分块缓存变量已失效
默认 Hub 缓存在 ~/.cache/huggingface/hub，Xet 相关目录为 ~/.cache/huggingface/xet。修改 HF_HOME 会改变后续使用的路径，不会自动搬走已有文件；先保留原目录中的已完成文件，再决定迁移或继续使用哪个缓存。
Hub 的 refs、blobs 与 snapshots 会复用已经完成的文件。下载中断后应使用相同的 repo_id、revision、用户和缓存目录重跑。
当前官方说明已将 HF_XET_CHUNK_CACHE_SIZE_BYTES 标为无效：hf_xet 不再使用本地下载分块缓存，设置这个变量也不会开启它。应复用已完成的 Hub 文件，检查实际请求和磁盘空间，不为“开启分块缓存”删除 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，断点续传和缓存更容易观察。
没有 git xet 命令时，先按官方平台说明安装 git-xet；macOS 可使用 Homebrew，Windows 官方文档提供 winget 安装方式。旧客户端仍可经 LFS bridge 下载，但遇到速度与大文件问题时，应优先升级 Hugging Face 的相关下载工具。
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 statusGit 自己使用 git config 与环境变量，和 Python SDK 不是同一配置。hf CLI 正常、git clone 卡住时，只检查 Git/Xet/LFS 与 Git 代理，不再改 HF_HOME。
启用离线模式，确认模型权重和 tokenizer 能从本地加载
检查下载结果与离线使用
再次运行同一下载命令
应快速命中相同 snapshot，而不是重新传输全部分块。
加载一次模型
使用实际 transformers 或项目代码读取权重与 tokenizer。
启用离线模式测试
已缓存内容可用时，设置 HF_HUB_OFFLINE=1 或使用 local_files_only，不应再访问 Hub。
检查凭据与空间
Notebook、日志和 Git 历史没有 token，缓存盘仍有升级余量。
记录 revision 与 snapshot 路径
下次更新模型时能区分新版本下载与旧缓存损坏。