huggingface-cli download 断点续传

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

一、核心原理

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

二、前提准备

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

pipinstall--upgrade huggingface-hub

三、断点续传的具体用法

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

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

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

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

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

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

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

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

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

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

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

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

四、断点续传生效条件

1. 本地保留了中断后的临时文件：--local-dir目录下会生成.tmp后缀的临时文件，不要删除/移动；
2. 重新执行的命令与中断前完全一致：包括--local-dir、--include/--exclude、--revision等所有参数，否则会视为新下载；
3. 目标文件在 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