Hugging Face 模型下载失败：分层定位与镜像
Hugging Face 下载失败可从认证、网络和本地缓存排查。按 huggingface_hub 版本核对下载配置，并验证实际涉及的 Hub 与文件存储链路。
Hugging Face 的下载报错长得都很像"网络问题"，实际分属三层：认证、网络、本地。层找错了，换镜像、挂代理全是白费。本文给一个三层判定法，每层配一条命令，再给一份环境变量与报错对照。
先判断下载失败来自认证、网络还是本机
先问一个问题：报错里有没有 HTTP 状态码？
- 有 401 或 403，是认证层
- 没有状态码，只有 timeout、ConnectionReset、Read timed out，是网络层
- 报错提到磁盘、权限、路径，是本地层
这些类别可能交叠，状态码和错误文本只是定位线索。按发生阶段检查认证响应、网络日志和本地磁盘/权限；连通性检查可用智能检测助手。
401 与 403 分别检查令牌和访问权限
401 是没带 token 或 token 无效；403 最常见的是 gated 模型还没在模型页接受协议，也可能来自组织权限、地区限制或触发速率限制，先看响应体里的说明再动手。
处理顺序：先在模型页面点接受协议（用你要下载的那个账号），再让命令行带上同一个账号的 token：
```bash
export HF_TOKEN=hf_xxxxxxxx
hf auth whoami # 旧版 CLI：huggingface-cli whoami
```
whoami 返回你的用户名，说明 token 已生效。此时仍报 403，检查是不是用了另一个账号的 token——协议是账号级授权，不跨账号。模型 token 和代理的账号密码不是一回事：前者是 Hugging Face 的凭据，后者是代理出口的鉴权；代理这边只写主机、端口、账号密码，两种写法的区别见代理白名单和账号密码怎么选。
网络不通或下载中断时，检查镜像、代理和续传
何时切换镜像或启用下载加速
优先使用 Hugging Face 官方端点。只有确认镜像运营方、传输协议、版本同步方式和凭据处理后，才考虑配置镜像。下载加速方法取决于 huggingface_hub 版本；当前版本应按官方环境变量文档核对 hf_xet 支持，旧版 hf_transfer 配置不要当作通用现行方法。安装前先确认版本与官方说明：
```bash
python -c "import huggingface_hub; print(huggingface_hub.version)"
hf download --help
```
下载中断后如何恢复未完成的文件
下载中断后可按所用 CLI 和客户端版本的文档恢复任务；先查看缓存和下载日志，不要假定所有客户端、存储端点都能以相同方式续传。命令名以当前 CLI 版本为准：新版是 hf download，旧版是 huggingface-cli download，参数用 --help 核对（见 hf CLI 文档）。
如何让模型文件请求通过代理
客户端是否读取 HTTPS_PROXY / HTTP_PROXY 取决于具体库和版本。对 huggingface.co 的 HEAD 请求只验证该请求的网络路径，不能证明模型文件存储或 Xet 请求也经过代理。代理的主机和端口见帮助中心获取代理。
| 环境变量 | 作用 | 什么时候设 |
|---|---|---|
HF_ENDPOINT | 指定 Hub API 端点 | 仅在确认端点可信、受支持且版本匹配后 |
HF_TOKEN | 认证凭据 | 私有库或 gated 模型 |
HF_HOME | 缓存根目录 | 系统盘空间不足时 |
HF_XET_HIGH_PERFORMANCE | 按当前版本文档启用 Xet 高性能模式 | 仅在版本支持且确认适合当前负载时 |
HTTPS_PROXY | 配置客户端代理 | 先核对所用客户端/版本支持情况 |
镜像和代理都配好了仍报 timeout 或 connection reset，先分清是超时、连接被拒还是证书错误，三者的改法不在同一层。
磁盘空间和文件权限如何导致下载失败
三类报错：
OSError: No space left on device：模型缓存默认在~/.cache/huggingface，用HF_HOME指到大盘PermissionError：缓存目录属主不对，多见于用 root 装过一次之后- 下载后加载报错：先检查具体文件、仓库和修订；按当前 CLI 支持情况用
hf cache verify校验指定仓库/修订的文件校验和。缓存存在或扫描到元数据不等于内容完整。确认版本支持后再执行该命令。
分辨是出口慢还是本地带宽慢，可以按代理 IP 可用率、延迟和稳定性怎么测试里的口径先测一轮。
根据报错信息定位认证、连接或本地问题
| 报错或现象 | 所属层 | 处理动作 |
|---|---|---|
| 401 Unauthorized | 认证 | 设置 HF_TOKEN 后 whoami 验证 |
| 403 Forbidden / gated repo | 认证 | 模型页接受协议，用同账号 token |
| Read timed out / ConnectionReset | 网络或中间层 | 记录失败阶段、目标主机和客户端代理配置，再按该路径排查 |
| 卡在 99% 或中途断开 | 网络 | 重跑原命令续传，不加 --force-download |
No space left on device | 本地 | 改 HF_HOME 或清理缓存 |
PermissionError | 本地 | 修正缓存目录属主 |
拿不准卡在哪一层时，先用帮助中心的智能检测助手跑一次连通性检测，再回头对照上表。
FAQ
使用第三方镜像前要核实什么
核实运营方、同步修订、协议和凭据处理。hf cache verify（仅在支持该命令的版本中）可校验指定仓库和修订的文件；它不能证明镜像运营方可信。私有或 gated 仓库的令牌不要交给未核实的第三方端点；使用最小权限令牌并避免将其写入日志或共享命令记录。
下载到一半断了怎么续
按客户端和 CLI 版本文档恢复下载并检查缓存状态；不要假定所有文件存储端点都支持相同续传方式。只有确认缓存损坏且了解重下影响后，再清理缓存。
公司代理下 443 不通先查什么
HEAD 请求只覆盖该请求的主机和路径。还应检查模型下载实际访问的 Hub、文件存储/Xet 域名，以及所用客户端是否读取代理设置；结合 DNS、TLS 和代理日志定位。公司网络的域名策略按管理员提供的规则核实。
大型模型文件下载可按所需带宽、地区、会话和套餐计费口径比较机房代理 IP 与其他方案。续传、缓存命中及重试产生的流量和费用取决于客户端、存储端点和套餐规则，使用前向服务商核实，不假定已下载部分不会再次计费。