HuggingFace 模型下载的国内可行路径 (Downloading HuggingFace Models from Mainland China)

2026-09-17 暂无评论

一句话

「国内要用 hf-mirror.com」这条经验不是普遍成立的。在实测的这台机器上，hf-mirror.com 被 DNS 污染完全不通，而 huggingface.co 反而可以直连。不要凭经验选镜像，先做连通性实测。

实测数据

用 curl 对同一批目标做带/不带代理的对照（超时 15 秒）：

目标	直连	走 127.0.0.1:7890 代理
baidu.com	200 (0.23s)	—
modelscope.cn 模型 API	200 (0.37s)	—
hf-mirror.com	000 失败	000 失败
huggingface.co API	200 (0.36s)	200 (0.62s)
download.pytorch.org/whl/cpu	200 (0.69s)	—

大文件实测分块下载速度：huggingface.co 直连 5.2 MB/s，modelscope 直连 2.8 MB/s。

结论：这台机器上直连 huggingface.co 是最优路径，代理反而更慢（0.62s vs 0.36s 建连），hf-mirror 完全不可用。换机器要重测，不能照搬。

另一个更隐蔽的坑：huggingface_hub 卡死且不报错

用 huggingface_hub.snapshot_download 时遇到两种失败：

走代理下载大权重文件时抛 SSL EOF：SSLEOFError(8, 'UNEXPECTED_EOF_WHILE_READING')
换直连后卡在 "Fetching 7 files: 0%" 完全不动，既不报错也不超时

第 2 种特别耗时，因为没有任何反馈信号。原因与 xet 存储后端有关，设 HF_HUB_DISABLE_XET=1 可以规避其中一部分。

更稳的做法是绕过 huggingface_hub，直接用 curl 下文件，自己控制重试、续传与校验：

# 1. 从 API 拿文件清单和期望字节数（?blobs=true 会返回 size）
curl -s "https://huggingface.co/api/models/Qwen/Qwen3-0.6B?blobs=true"

# 2. 逐个文件下载，-C - 断点续传，--retry-all-errors 覆盖瞬时网络抖动
curl -L --retry 10 --retry-delay 3 --retry-all-errors -C - ^
     --connect-timeout 20 --max-time 10800 -o model.safetensors ^
     https://huggingface.co/Qwen/Qwen3-0.6B/resolve/main/model.safetensors

# 3. 下完校验字节数与 API 返回的 size 一致

必须做字节校验，不能用「文件大于某个大小」判断完成

第一版脚本用「文件大于 1KB 就跳过」判断是否已下载，结果把半截文件当成已完成：

if ((Test-Path $dest) -and ((Get-Item $dest).Length -gt 1024)) { continue }

中断的 562 MB 残缺权重满足这个条件，被直接跳过。这类错误的代价极高——模型加载时才报错，或者更糟，加载出一个损坏的模型给出无意义的结果，然后你会去怀疑数据和超参。

正确判据是拿 API 返回的期望字节数做等值比较：

$sizes = (Invoke-RestMethod "https://huggingface.co/api/models/$repo?blobs=true").siblings
# 期望大小 = 目标文件在 siblings 里的 size
if ($have -eq $expected) { 跳过 } else { 续传下载；下完再校验一次 }