记录一下那天晚上的排查过程。内网机器设了 HF_HUB_ENABLE_HF_TRANSFER=1 拉 Qwen2.5-14B,hf_transfer 1.2.0 跑到 40% 报 403,原文是 error sending request for url,把变量关掉用普通下载又能继续,换 token 重试三次都断在同一个百分比。

刚开始盯着「跳转到 CDN 时没有带上鉴权信息」,折腾了半个多小时,排掉了。

排查方向其实有限,先把可能性排一排。镜像站不支持多段 Range 请求。还有一种是代理只允许单连接并发被拒。

少数情况下是hf_transfer 与 hf_hub 版本不匹配。

临时关掉变量验证是否限流

$env:HF_HUB_ENABLE_HF_TRANSFER='0'; huggingface-cli download Qwen/Qwen2.5-14B-Instruct --local-dir .\qwen14b

随后用 curl 测服务端是否支持 Range

curl -I -H "Range: bytes=0-1023" https://hf-mirror.com/Qwen/Qwen2.5-14B-Instruct/resolve/main/model-00001-of-00008.safetensors

再往下换成支持分片的镜像端点再试

$env:HF_ENDPOINT='https://hf-mirror.com'; $env:HF_HUB_ENABLE_HF_TRANSFER='1'; huggingface-cli download Qwen/Qwen2.5-14B-Instruct

等前面都确认过,再对齐 hf_hub 与 hf_transfer 版本

pip install -U "huggingface_hub>=0.26" "hf_transfer>=0.1.8"

当时还开着另一个排查窗口,两边日志对照着看才定位到。

怎么算真的好了,看的是同一批现象。下载完整结束,文件 sha256 与仓库清单一致,日志里不再出现 403。

这里还有个坑。hf_transfer 出错不会自动回退到普通下载,脚本里要显式捕获异常再切回去。改动前把原配置备份一份,出问题能马上回滚,这比任何技巧都实用。

作者 9823189