Hugging Face 模型下载提示 401 或 403？检查账号、Token 与访问申请

Hugging Face 模型下载出现 401 或 403，先核对完整错误、仓库地址、当前身份和目标模型访问状态。Token 有效、Token 能读目标资源、账号已获模型批准是三项不同条件；不能把“登录成功”当成所有受限模型都能下载。

本文依据 2026 年 10 月 1 日读取的官方授权与异常说明，核对了 huggingface_hub 1.26.1 的 CLI 帮助，并实际下载公开仓库配置作为访问基线。没有使用私人 Token，也没有申请或实测任何受限模型账号；以下申请和批准后的流程属于官方操作指引。

先保留哪些信息，才能定位原因

记录报错中的异常类、HTTP 状态、Request ID、repo_id、revision 和文件名；复制日志前删除 Token、Authorization 请求头和个人信息。浏览器能看到模型简介，不足以证明能下载其文件。

官方错误说明区分仓库不存在或无权访问、受限仓库未获授权、revision 不存在、文件不存在等情况。401、403 是排查入口，必须结合异常类及服务端文字判断。

第一步：浏览器申请账号与命令行身份一致

官方 gated 模型说明指出，访问申请由个人用户发起，申请需要在浏览器中完成。进入目标模型页面，登录你准备用来下载的账号，阅读条款并按页面要求提交信息。自动审批与人工审批不同；pending 表示仍待决定，不能写成下载权限已获准。

用同一安装环境的 CLI 检查身份。以下在 Windows PowerShell 的独立环境执行，登录时按交互提示操作，不把 Token 硬编码进脚本：

py -3.11 -m venv .venv-access
.\.venv-access\Scripts\python.exe -m pip install "huggingface_hub==1.26.1"
.\.venv-access\Scripts\hf.exe auth login
.\.venv-access\Scripts\hf.exe auth whoami

官方 CLI 指南提供登录和当前身份检查。whoami 返回的账号应与提交模型申请的浏览器账号一致。某个组织成员身份不能替代模型对个人用户的访问批准；拒绝、撤销或额外限制应按页面和作者条款处理。

第二步：检查 Token 能做什么

官方用户 Token 文档区分 read、write 和 fine-grained。仅下载模型通常应使用必要的读取权限；write 权限不能绕过模型作者的访问决定。fine-grained Token 还需要覆盖本次目标资源及相应读取范围。

1. 在账号 Token 设置中确认 Token 未被撤销、属于刚才获批的账号。
2. 核对读取权限和指定资源，按自己的下载需要设置最小范围。
3. 重新使用交互登录后再执行 whoami，确认实际身份与预期一致。
4. 若脚本显式传入 token 参数或进程设置了 HF_TOKEN，核对它是否使运行时使用另一个账号。

官方环境变量说明指出 HF_TOKEN 会覆盖机器上保存的 Token。可只检查当前进程是否设置了它，不输出值：

if (Test-Path Env:HF_TOKEN) {
    Write-Output "当前进程设置了 HF_TOKEN，请核对其所属账号"
}

第三步：用明确文件发起一次真正的下载检查

在目标模型 Files 页面选择一个较小、确实存在且你有权取得的文件。保存下方代码为 access_check.py，再执行 .\.venv-access\Scripts\python.exe -X utf8 access_check.py；按提示输入仓库 ID、revision 和文件路径。token=True 要求使用当前登录凭证，force_download=True 避免仅命中旧本地文件就误判这次远端权限已经恢复。

from huggingface_hub import hf_hub_download
repo = input("目标 repo_id: ").strip()
revision = input("已核对的 revision: ").strip()
filename = input("Files 中实际存在的小文件路径: ").strip()
if not all([repo, revision, filename]):
    raise ValueError("三个字段都要明确填写")
path = hf_hub_download(
    repo_id=repo, revision=revision, filename=filename,
    local_dir="access-check", token=True, force_download=True,
)
print("下载完成:", path)

验收需要当前身份正确、申请已获批准、目标文件远端请求成功且本地文件可读取。若仍失败，保留新的异常类、Request ID 和目标路径，分别回查账号、权限、申请状态与文件，不把“公开仓库能下载”当成“受限模型已授权”。

公开仓库基线能证明什么

本次在不携带 Token 的情况下，取得 tiny-random-bert 固定提交的 config.json，输出 public_config_download: OK。这仅证明当时网络与公开文件下载路径可用；它没有验证你的 Token、人工审批状态或任何受限模型的许可。

已经获批，为什么以后仍可能失败？

模型作者可以改变访问决定，Token 也可能撤销或调整范围。新的错误需要重新核对当前状态；不能依赖曾经成功的缓存结果。若模型条款或地区要求不满足，应遵循其说明，不把切换账号或增加权限当成绕过授权的方法。