Hugging Face下载慢或中断怎么办

直接答案

Hugging Face 下载慢或中断时，不要先删除缓存，也不要立即改用来源不明的镜像。先记录原命令和报错，确认仓库权限、固定版本、剩余磁盘与文件总量；然后升级官方客户端，在同一缓存或 local-dir 下重跑同一版本。缓存会避免重复获取未变化的内容。超时确实过短时再提高 HF_HUB_DOWNLOAD_TIMEOUT。

一、先按错误类型定位

401 或 403 多数与登录、访问申请或令牌权限有关；RepositoryNotFound、RevisionNotFound 和文件不存在应核对仓库 ID、repo type、标签或提交 SHA；TimeoutError、连接重置和长时间无进度更像网络或超时问题；No space left on device、只读目录或写入失败则是本地磁盘问题。不同错误不能靠同一个“加速参数”解决。

二、固定命令并做 dry-run

先执行：

hf download 发布方/仓库名 --revision 完整提交SHA --dry-run

确认计划文件、总量和缓存命中，再保留完全相同的 repo ID、revision、include/exclude 与 local-dir 重试。更换 main 上的版本或同时改多个筛选条件，会让前后两次任务不再是同一份资源，也难以判断是否真正续接。

三、升级官方客户端并复用缓存

Hugging Face 当前文档建议安装最新版 huggingface_hub；从 0.32.0 起会一并安装 hf_xet。可执行：

pip install -U "huggingface_hub"

hf_xet 采用分块方式传输。旧文章中的 HF_HUB_ENABLE_HF_TRANSFER 已被官方标记为弃用，不应继续当作当前首选。使用官方缓存或 local-dir 的元数据重复执行下载，可以跳过已经存在且未变化的文件；不要为了“重来一次”随意删除完整缓存。

四、只在确认超时时调整等待时间

macOS 或 Linux 可在启动命令前设置：

HF_HUB_DOWNLOAD_TIMEOUT=60 hf download 发布方/仓库名 --revision 完整提交SHA

Windows PowerShell 可先执行：

$env:HF_HUB_DOWNLOAD_TIMEOUT="60"

这个值只是延长单次下载等待时间，不会修复权限错误、断网、磁盘写满或错误版本。环境变量应在 huggingface_hub 进程启动或导入前设置。

五、优先使用默认自适应并发

hf_xet 默认会根据实时网络状况自适应调整并发，官方说明默认设置通常无需调参，能够覆盖大多数网络路径。只有在高带宽、CPU 和 SSD/NVMe 都有充足余量，并且至少配备 64GB 内存的专用下载设备上，才考虑 HF_XET_HIGH_PERFORMANCE=1。该模式会提高并发和缓冲区；低内存设备可能反而降速，也可能占用大量 CPU 和网络资源，因此不适合共享生产机。写入机械硬盘时，可参考官方的 HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY=1 顺序写入选项。调整后应观察网络、内存、CPU、磁盘和错误日志，不应只看瞬时速度。

六、不要用不明镜像替代来源核对

非官方镜像可能版本滞后、缺少分片、改变目录或无法证明权利来源。若确需其他合法渠道，仍应以官方仓库 ID、完整提交 SHA、文件清单和校验值作为基准。Gated 或私有资源不能通过更换下载地址来规避授权。

七、仍不稳定时如何寻求协助

保留官方链接、固定版本、dry-run 结果、完整错误文本、失败时间、系统与磁盘信息，不要提供访问令牌。橙子AI科技可在合法访问权限、许可证及平台规则允许的前提下，评估版本范围、下载协助、完整性校验和国内交付方式。本站不代理 Hugging Face，也不在网页中直接提供模型文件。

国内下载 Hugging Face 模型很慢或经常中断怎么办