Hugging Face Gated 模型下载全攻略：解决 401/403 和访问受限问题
在使用 Hugging Face Hub 下载大型受限（Gated）模型 google/gemma-2-9b-it 时，我踩了很多坑。本文总结整个流程、常见报错及最终解决方案，供大家参考。
一、问题背景
Hugging Face 上有些模型是 Gated 模型，即只能由官方授权账号访问。比如：
google/gemma-2-9b-it
如果直接使用普通命令下载，会出现：
huggingface_hub.utils._errors.GatedRepoError: 401 Client Error
Cannot access gated repo ...
You must have access to it and be authenticated to access it. Please log in.
即便已经登录 Hugging Face CLI，也可能遇到 not access / 401 / 403 错误。
二、踩过的坑
1️⃣ 仅登录账号仍报 not access
-
直接运行：
huggingface-cli download --resume-download google/gemma-2-9b-it --local-dir /home/hhucs/hhucs/models
-
会报：
Cannot access gated repo
-
原因：登录账号不等于拥有访问权限，Gated 模型需要官方批准。
2️⃣ token 未使用或错误
-
即使你登录了 CLI，如果 Python 脚本或命令行使用的 token 不是被授权账号的 token，下载仍会报 401。
3️⃣ 镜像或缓存问题
-
国内镜像或旧缓存可能导致 gated 模型访问失败。
-
Hugging Face Hub 的缓存目录如果存在旧 token，会干扰下载。
三、解决方案
1️⃣ 申请模型访问权限
-
打开模型页面：https://huggingface.co/google/gemma-2-9b-it
-
点击 Request access，填写用途和团队信息。
-
等待官方批准。
只有授权账号才能访问 gated 模型，即便登录也不能代替授权。
2️⃣ 获取并使用 token
-
生成 token：
-
Hugging Face → Settings → Access Tokens → New Token → Read 权限
-
-
下载时指定 token：
huggingface-cli download \--token hf_你的授权token \--resume-download \google/gemma-2-9b-it \--local-dir /home/hhucs/hhucs/models
✅ 这是我最终能成功下载的命令，这里一定要指定--token才可以
-
--resume-download支持断点续传，大模型下载中断后可以继续。 -
--local-dir指定模型保存路径。
3️⃣ Python API 下载（可选）
from huggingface_hub import snapshot_downloadsnapshot_download(repo_id="google/gemma-2-9b-it",cache_dir="/home/hhucs/hhucs/models",resume_download=True,use_auth_token="hf_你的授权token"
)
执行效果示意（终端截图风格）：
Downloading: 100%|████████████████████████████| 4.04G/4.04G [00:16<00:00, 250MB/s]
Model snapshot saved to /home/hhucs/hhucs/models/google/gemma-2-9b-it
4️⃣ 验证模型文件
$ ls /home/hhucs/hhucs/models/google/gemma-2-9b-it
config.json
pytorch_model.bin
tokenizer.json
README.md
✅ 下载成功，可以直接用于后续模型加载。
四、总结经验
| 阶段 | 常见问题 | 解决方法 |
|---|---|---|
| 登录 | 仅 huggingface-cli login，仍报 not access | 使用被授权账号的 token |
| 授权 | 账号未申请 gated 模型访问 | 在模型页面 Request access |
| 下载 | 大模型下载中断 / 缓存干扰 | --resume-download + 清理缓存 + 官方 Hub |
💡 小提示：
-
gated 模型必须 官方授权，登录不能代替授权
-
国内镜像可能不支持 gated 模型，建议直连官方 Hub
-
token 安全，不要泄露在公共场合，必要时立即重置