huggingface-cli下载中断后如何续传？

Question

使用 `huggingface-cli download` 下载大模型时，若因网络中断导致下载中止，再次运行相同命令是否会续传已下载的部分？当前版本的 Hugging Face CLI 默认基于 HTTP Range 请求支持断点续传，前提是缓存目录中保留了未完成的临时文件（如 `.incomplete` 文件）。若临时文件被删除或缓存清理，则会重新下载整个文件。如何确保中断后能正确续传？是否需手动指定缓存路径或使用特定参数？这是用户在下载大型模型权重时常遇到的关键问题。

Answer 1

一、Hugging Face CLI 下载大模型的断点续传机制深度解析

在大规模预训练模型日益普及的今天，使用 huggingface-cli download 命令下载模型权重已成为AI工程师和研究人员的标准操作。然而，在实际应用中，由于网络波动或系统中断导致下载中止的情况屡见不鲜。本文将从浅入深探讨该命令是否支持断点续传，并提供确保续传成功的最佳实践。

1. 断点续传的基本原理与实现方式

Hugging Face 的 CLI 工具底层依赖于 requests 库和 HTTP 协议中的 Range 请求头 来实现部分下载功能。当文件传输中断时，若临时文件未被清除，后续请求会检测到已存在的不完整文件，并通过发送带有 Range: bytes=x- 的请求继续获取剩余数据。

关键机制如下：

• 下载过程中生成临时文件（如 model.bin.incomplete）
• 记录已接收字节数并校验文件大小一致性
• 重启下载时检查本地是否存在对应的 .incomplete 文件
• 若存在，则发起 Range 请求跳过已下载部分

2. 缓存路径管理对续传的影响

默认情况下，Hugging Face 使用环境变量 HF_HOME 或用户主目录下的 ~/.cache/huggingface/ 路径作为缓存根目录。模型文件在此路径下按命名空间组织存储。

配置项	说明	示例值
HF_HOME	全局缓存根路径	/data/cache/hf
HF_HUB_CACHE	仅用于模型缓存	/data/models
TRANSFORMERS_CACHE	旧版兼容变量	~/.cache/huggingface/transformers

建议显式设置 HF_HUB_CACHE 以集中管理模型缓存位置，避免因系统清理脚本误删临时文件而导致无法续传。

3. 确保续传成功的最佳实践

为最大化保障断点续传的成功率，应采取以下策略：

1. 始终指定稳定的缓存路径：
   export HF_HUB_CACHE=/your/stable/path
2. 禁用自动清理机制：
   避免运行 huggingface-cli scan-cache 或手动删除 .incomplete 文件
3. 使用重试脚本封装下载命令：

#!/bin/bash
MAX_RETRIES=5
for i in $(seq 1 $MAX_RETRIES); do
    huggingface-cli download bert-base-uncased && break
    echo "Download attempt $i failed, retrying..."
    sleep 10
done

4. 内部流程分析：从 CLI 到 HTTP 层的数据流

以下是 huggingface-cli download 执行过程中的核心逻辑流程图：

graph TD A[用户执行 huggingface-cli download] --> B{检查本地缓存} B -->|存在 .incomplete 文件| C[读取当前文件大小] B -->|无临时文件| D[发起完整 GET 请求] C --> E[构造 Range: bytes={size}- 请求头] E --> F[发送 HTTP Range 请求] F --> G[追加写入 .incomplete 文件] G --> H{下载完成？} H -->|否| F H -->|是| I[重命名为正式文件名] I --> J[更新缓存元数据]

该流程表明，只要 .incomplete 文件未被破坏或删除，系统天然具备续传能力。

5. 常见问题排查清单

当预期续传未发生时，可参考以下诊断步骤：

现象	可能原因	解决方案
每次中断后重新开始	.incomplete 文件被删除	检查是否有定时清理任务
报错 No such file or directory	缓存路径权限不足	chmod 755 缓存目录
下载速度极慢	服务器不支持 Range 请求	联系 Hugging Face 支持团队
文件损坏	网络丢包严重	使用 rsync 或 aria2 多线程替代

6. 高级技巧：结合外部工具提升稳定性

虽然原生命令支持续传，但在弱网环境下仍推荐结合专业下载器增强鲁棒性。例如使用 aria2c 并行下载分片：

# 获取模型文件 URL 后使用 aria2 断点续传
aria2c -x 8 -s 8 --continue=true \
  "https://huggingface.co/bert-base-uncased/resolve/main/pytorch_model.bin" \
  -d /data/models/bert-base-uncased \
  -o pytorch_model.bin

此方法不仅支持断点续传，还能利用多连接加速下载，特别适合千兆以上大模型。