HuggingFace 下载开源大模型中途断连后 --resume 无法续传的 hf_transfer 配置

文章导读
针对“HuggingFace 下载开源大模型中途断连后 `--resume` 无法续传”的情况,最可能的原因不是 `--resume` 参数本身失效,而是当前下载后端不是 huggingface_hub 默认的分片续传逻辑,而是 hf_transfer(或相似传输加速器)。hf_transfer 启用的多线程分块写入方式,中断后重新拉起命令时,可能找不到可续传的 .incomplete 文件,或者
📋 目录
  1. 一 先确认这次下载是不是真的用了 hf_transfer
  2. 二 `--resume` 不生效的三个检查点
  3. 三 处理动作:关掉 hf_transfer,让默认续传机制接管
  4. 四 验证信号:确认续传真的发生了
A A

针对“HuggingFace 下载开源大模型中途断连后 `--resume` 无法续传”的情况,最可能的原因不是 `--resume` 参数本身失效,而是当前下载后端不是 huggingface_hub 默认的分片续传逻辑,而是 hf_transfer(或相似传输加速器)。hf_transfer 启用的多线程分块写入方式,中断后重新拉起命令时,可能找不到可续传的 .incomplete 文件,或者临时文件路径不一致,于是从头下载。需要先确认实际传输后端,再决定是调整 hf_transfer 配置,还是暂时关掉它让 huggingface_hub 自身的断点续传接管。

先确认这次下载是不是真的用了 hf_transfer

`--resume` 不能续传,第一步是确认传输链路:是否通过环境变量或 snapshot_download 参数启用了 hf_transfer。没有启用时,它只是普通 huggingface_hub 下载,问题另查。启用后,下载日志中关键词会有 hf_transfer、xet、或分片并发请求痕迹。可用以下命令复现一次并观察输出:

# 显式启用 hf_transfer,重新运行下载
HF_HUB_ENABLE_HF_TRANSFER=1 huggingface-cli download meta-llama/Llama-3.1-8B `--local-dir` ./models

# 重新运行前,先看当前目录下有哪些未完成文件
find ./models -name "*.incomplete" -exec ls -lh {} \;

如果复现后看到的日志是重新开始下载,而 .incomplete 文件大小没有在上次中断位置继续增长,问题就基本落在 hf_transfer 的断点续传上。此时建议优先关掉 hf_transfer,用默认下载后端完成剩余文件。

`--resume` 不生效的三个检查点

重启下载前,按下列顺序检查。每个检查点都对应一种独立失败原因,不一定与 hf_transfer 直接相关。

HuggingFace 下载开源大模型中途断连后 --resume 无法续传的 hf_transfer 配置
  1. 检查 local-dir 是否一致。 续传依赖特定临时文件和路径状态。第一次下载用 `--local-dir` ./models,第二次换成了绝对路径或其他目录名,huggingface_hub 不当作同一任务,会重新下载。确定两次命令使用同一个目录。
  2. 检查是否存在 .incomplete 文件。 如果目录下没有遗留 .incomplete 文件,说明断连后临时文件被清理或从未写到最终目录,即使 `--resume` 也无可续内容。此时下载会从头开始,需要做的是缩短下载周期或改用支持继续传输的工具。
  3. 检查连接掉线时是否卡在下载最后阶段的“落盘”动作。 hf_transfer 下载完成后会移动临时文件到最终路径。断连可能发生在临时文件移入最终路径之前。这种场景下重新运行会重新拉取该文件,尽管日志看起来是“下载失败”。可先用 find ./models -name "*.incomplete" 查看是否有残留临时文件,确认后再执行续传。

还有一个容易被忽略的外部因素:部分模型仓库的下载 URL 带签名时效,断连后如果 URL 已过期,服务器返回 401 或 403,续传会被判定为不可用。遇到这种情况,重新运行命令通常会重新获取有效 URL,不需要手工改文件。

处理动作:关掉 hf_transfer,让默认续传机制接管

如果确认自定义传输器是断点续传不可靠的根因,最直接的动作是关闭 HF_HUB_ENABLE_HF_TRANSFER,改用 huggingface_hub 默认下载链路。默认链路按文件维护 .incomplete 分片,`--resume` 的续传行为更连续。

# 关闭 hf_transfer,使用默认下载后端
HF_HUB_ENABLE_HF_TRANSFER=0 huggingface-cli download meta-llama/Llama-3.1-8B `--local-dir` ./models

# Python 调用中同样关闭该环境变量
HF_HUB_ENABLE_HF_TRANSFER=0 python -c "from huggingface_hub import snapshot_download; snapshot_download('meta-llama/Llama-3.1-8B', local_dir='./models')"

有些环境还会默认启用 hf_xet 传输后端。如果日志里出现 xet 相关字样,但你又没有显式配置过,可以开启调试日志确认当前实际生效的传输后端:

HuggingFace 下载开源大模型中途断连后 --resume 无法续传的 hf_transfer 配置
HF_HUB_VERBOSITY=debug huggingface-cli download meta-llama/Llama-3.1-8B `--local-dir` ./models 2>&1 | grep -iE "xet|hf_transfer|incomplete"

不建议同时开启多进程或多次并发执行同一个 local-dir 的下载命令,否则多个进程会争抢同一个 .incomplete 文件,导致续传状态被互相覆盖。这里给出的处理动作是止血方式,不是性能提升方案;在稳定完成下载后,再根据实际网络环境评估是否重新启用 hf_transfer。

验证信号:确认续传真的发生了

续传是否生效,不应只看客户端输出。建议按以下信号组合判断:

  • 重新运行命令前记录 ./models 目录总大小和 *.incomplete 文件大小。
  • 重新运行后,同一 .incomplete 文件大小应从之前位置继续增长,而不是从 0 开始。
  • 控制台出现“Resuming download”“continue from existing file”之类日志,而不是重新打印完整的“Downloading”文件列表。
  • 下载完成后比对模型文件内容,常见方式是读取 sha256 校验值或确认模型载入成功。

如果关闭 hf_transfer 后 .incomplete 文件依然从 0 开始,则问题已经不在 hf_transfer 配置,而是命令行参数或网络中间层导致的会话失效。此时可以抓取 HTTP 响应状态码确认服务器是否拒绝分段请求,并检查本地目录是否有权限写入。