huggingface-cli download 断点续传

在使用 huggingface-cli download 时，断点续传的核心是 --resume-download 参数，该参数能检测本地未完成的下载文件，从断点处继续传输（而非重新下载）。以下是完整的使用方法、生效条件和问题排查：

一、核心原理

--resume-download 会在下载时生成临时文件（后缀通常为 .tmp），记录已下载的字节数；当下载中断（网络断开、进程终止等），重新执行带该参数的命令时，工具会读取临时文件，从断点处续传，避免重复下载已完成部分。

二、前提准备

确保 huggingface-hub 版本足够新（v0.10+ 支持该参数，v0.16+ 对大文件/LFS 文件支持更完善）：

bash 复制代码

pip install --upgrade huggingface-hub

三、断点续传的具体用法

1. 基础用法（以下载 LiveCodeBench 为例）

在原有下载命令后直接添加 --resume-download 即可：

bash 复制代码

huggingface-cli download LiveCodeBench/LiveCodeBench \
  --local-dir LiveCodeBench \          # 本地保存目录
  --local-dir-use-symlinks False \     # 强制下载文件（非符号链接）
  --resume-download                    # 核心：断点续传参数

2. 结合筛选规则（include/exclude）

若仅下载指定文件/排除部分文件，续传参数仍兼容：

bash 复制代码

huggingface-cli download LiveCodeBench/LiveCodeBench \
  --include "data/**,evaluation/*.py" \  # 只下载指定目录/文件
  --exclude "docs/**" \                  # 排除无需下载的内容
  --local-dir LiveCodeBench \
  --local-dir-use-symlinks False \
  --resume-download

3. 下载指定版本 + 断点续传

若需下载特定分支/commit/tag，续传参数同样生效：

bash 复制代码

huggingface-cli download LiveCodeBench/LiveCodeBench \
  --revision v1.0 \  # 指定版本（分支/标签/commit hash）
  --local-dir LiveCodeBench \
  --local-dir-use-symlinks False \
  --resume-download

4. 自动重试 + 断点续传（网络不稳定时）

搭配 --retries N（N 为重试次数），实现中断后自动重试 + 续传：

bash 复制代码

huggingface-cli download LiveCodeBench/LiveCodeBench \
  --local-dir LiveCodeBench \
  --local-dir-use-symlinks False \
  --resume-download \
  --retries 5  # 最多自动重试5次

四、断点续传生效条件

本地保留了中断后的临时文件：--local-dir 目录下会生成 .tmp 后缀的临时文件，不要删除/移动；
重新执行的命令与中断前完全一致 ：包括 --local-dir、--include/--exclude、--revision 等所有参数，否则会视为新下载；
目标文件在 Hugging Face Hub 上未被修改：若文件更新，工具会判定为新文件，重新下载。

五、常见问题排查

1. 断点续传未生效（重新从头下载）

原因1：huggingface-hub 版本过旧 → 执行 pip install --upgrade huggingface-hub 升级；
原因2：临时文件被删除 → 中断后不要清理 --local-dir 目录，保留 .tmp 文件；
原因3：命令参数不一致 → 确保重新执行的命令和中断前的参数完全相同（比如 --local-dir 路径不能改）；
原因4：文件在 Hub 上已更新 → 可删除本地旧文件后重新下载。

2. 报错 "Resume download not supported for this file"

原因：旧版本对 LFS 大文件的断点续传支持不足 → 升级到 huggingface-hub>=0.16.0 即可解决。

3. 续传时提示文件校验失败

原因：中断导致临时文件损坏 → 删除该文件的 .tmp 临时文件，重新执行命令（会从头下载该文件，但其他文件仍可续传）。

六、补充说明

--resume-download 是幂等的：即使文件已完全下载，执行带该参数的命令也不会重复下载，只会校验文件完整性；
若需强制重新下载（忽略断点）：移除 --resume-download 参数，或删除 --local-dir 目录后重新执行。

参考

livecodebench/code_generation_lite