在使用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-download3. 下载指定版本 + 断点续传
若需下载特定分支/commit/tag，续传参数同样生效：
huggingface-cli download LiveCodeBench/LiveCodeBench\--revision v1.0\# 指定版本（分支/标签/commit hash）--local-dir LiveCodeBench\--local-dir-use-symlinks False\--resume-download4. 自动重试 + 断点续传（网络不稳定时）
搭配--retries N（N 为重试次数），实现中断后自动重试 + 续传：
huggingface-cli download LiveCodeBench/LiveCodeBench\--local-dir LiveCodeBench\--local-dir-use-symlinks False\--resume-download\--retries5# 最多自动重试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
