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次

四、断点续传生效条件

  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

相关推荐
无奈笑天下1 小时前
银河麒麟桌面上USB打印机无法打印问题标准处理流程
linux·运维·网络协议
15Moonlight2 小时前
Linux 网络(11):IO 多路转接(select /poll/epoll)
linux·网络
wno7043 小时前
CentOS下FTP服务搭建
linux·运维·centos
15Moonlight3 小时前
Linux网络(12):Reactor 模式
linux·网络
思想觉悟4 小时前
Android启动流程之点rc文件
android·linux·面试
kyle~16 小时前
嵌入式 SoC 系统
linux·c++·嵌入式·计算系统
人生!?18 小时前
Linux 从入门到进阶 | 基础语法
linux·笔记·教程
心之王者71619 小时前
Linux 进程信号:从产生、阻塞到捕捉与子进程回收
linux·服务器·网络
AndreaYYmm19 小时前
日志里 grep 到 Fail 就判失败?这六个假阳性我全踩过
linux·shell
爱吃香菜的初学者20 小时前
二十五.Linux——epoll
linux·运维·服务器