【Bug已解决】OSError: You are trying to access a gated repo. 解决方案一、现象长什么样加载一个需要授权的模型如 Llama-2/3、Gemma、某些医疗/金融垂类模型时直接报from transformers import AutoModelForCausalLM model AutoModelForCausalLM.from_pretrained(meta-llama/Llama-2-7b-hf)报错OSError: You are trying to access a gated repo. Make sure to have access to it. Your request should be authenticated and have the necessary permissions. ... 401 Client Error. (Request-ID: ...) Repository Not Found or Gated.或者更隐蔽在 CI / 服务器上跑得好好的换到一台新机器立刻报这个错——因为那台机器没登录过 HuggingFace。也可能你明明在网页上点了「Accept license」本地还是报 gated。因为网页授权和本地 CLI 登录是两件事必须本地也登录拿到 tokentoken 里才带「已授权该 gated repo」的声明。最迷惑的是报错说「Repository Not Found」让人误以为是 repo 名字拼错或模型下架其实是「没权限」的意思。二、背景HuggingFace Hub 上的「gated repo」是需要主动申请授权的仓库用户在模型页面点 Accept作者通过后该用户才被允许下载。下载时Hub 要求请求带一个已登录的 token且这个 token 对应的用户必须在该 repo 的授权名单里。transformers的from_pretrained内部调用hf_hub下载文件默认会从以下位置找 token环境变量HF_TOKEN/HUGGING_FACE_HUB_TOKEN缓存的登录态huggingface-cli login写入的~/.cache/huggingface/token显式传入的token/use_auth_token参数。如果三者都没有或 token 对应的用户没被授权Hub 返回 401transformers 包成上面的OSError: gated repo。常见踩坑只在网页点了 Accept没在本地huggingface-cli login→ 本地无 token → 401。服务器上用 CI secret 注入HF_TOKEN但 secret 名字拼错写成HUGGINGFACE_TOKEN→ 变量没被读到 → 401。用了use_auth_tokenTrue但本机从未登录 → 没 token 可拿 → 401。模型作者后来把 repo 改成 gated你之前能下现在不能下 → 401。三、根因根因一句话访问 gated repo 时本地没有有效的、已授权该 repo 的 HuggingFace token或 token 未被from_pretrained读到Hub 返回 401被包装成OSError: gated repo。三点展开未登录/无 token本地没huggingface-cli login也没设HF_TOKEN请求匿名 → 401。token 未被读取环境变量名错、参数名错use_auth_tokenvstoken、或 token 文件权限问题导致from_pretrained拿不到 token。授权未同步网页点了 Accept 但用户在 Hub 的授权名单里还没生效或换了个没授权的账号登录。不是 repo 不存在是「授权 token 缺失/未生效」。四、最小可运行复现不依赖真实 gated 模型模拟「无 token 访问 gated repo 触发 OSError」import os class FakeHub: GATED {meta-llama/Llama-2-7b-hf} AUTHORIZED_USERS {valid-token: alice} def get(self, repo, tokenNone): if repo in self.GATED: if not token: raise OSError(You are trying to access a gated repo. (no token)) if self.AUTHORIZED_USERS.get(token) is None: raise OSError(You are trying to access a gated repo. (401 unauthorized)) return fweights of {repo} def resolve_token(explicitNone): # 模拟 from_pretrained 找 token 的优先级 return explicit or os.environ.get(HF_TOKEN) or None hub FakeHub() repo meta-llama/Llama-2-7b-hf # 场景1完全没 token tok resolve_token(None) try: hub.get(repo, tok) except OSError as e: print(场景1无token:, e) # 场景2有 token 但未授权 tok resolve_token(someone-else) try: hub.get(repo, tok) except OSError as e: print(场景2未授权:, e) # 场景3有效 token tok resolve_token(valid-token) print(场景3有效token:, hub.get(repo, tok))跑出来场景1/2 触发 gated OSError场景3 成功。这就是「无有效 token → 401 → gated OSError」的精确复现。五、解决方案第一层最小直接修复最小修复登录拿到 token并确保from_pretrained能读到它。三种等价做法from transformers import AutoModelForCausalLM # 做法 A先命令行登录推荐一劳永逸 # huggingface-cli login # 然后代码里什么都不用传自动读缓存 token model AutoModelForCausalLM.from_pretrained(meta-llama/Llama-2-7b-hf) # 做法 B环境变量CI / 服务器常用 # export HF_TOKENhf_xxx # 代码里同样不用传 model AutoModelForCausalLM.from_pretrained(meta-llama/Llama-2-7b-hf) # 做法 C显式传 token注意参数名是 token不是 use_auth_token 已废弃 model AutoModelForCausalLM.from_pretrained( meta-llama/Llama-2-7b-hf, tokenhf_你的token, )关键检查清单先在模型页面点Accept拿到网页授权再在本机huggingface-cli login或设HF_TOKEN确认登录的账号就是被授权的那个账号多账号时容易登错若仍 401跑huggingface-cli whoami确认当前 token 对应的用户以及该用户是否在 repo 授权名单。这一步单独就让 gated repo 正常下载。六、解决方案第二层结构性改进第一层是「手动登录/传 token」。但在多模型、多环境本地/CI/容器里token 来源分散、容易漏。更稳的做法把「token 如何解析、是否授权、报错如何提示」收敛成单一解析器。from dataclasses import dataclass, field from typing import Optional import os dataclass class HfAuthResolver: HuggingFace token 解析与校验的单一入口。 # 显式 token优先级最高 explicit_token: Optional[str] None # 允许的环境变量名按优先级 env_keys: list field(default_factorylambda: [HF_TOKEN, HUGGING_FACE_HUB_TOKEN]) def resolve(self) - Optional[str]: if self.explicit_token: return self.explicit_token for k in self.env_keys: v os.environ.get(k) if v: return v # 回退到 huggingface-cli 登录缓存 try: from huggingface_hub import HfApi return HfApi().token except Exception: return None def diagnose(self, repo: str) - str: tok self.resolve() if not tok: return (f访问 {repo} 失败未找到 token。请 huggingface-cli login f或设置 HF_TOKEN。并确认已在模型页 Accept 授权。) # 校验 token 能拿到用户信息说明已登录且有效 try: from huggingface_hub import whoami user whoami(tokentok) return ftoken 有效当前用户: {user.get(name)}。若仍 401请确认该用户已被 {repo} 授权。 except Exception as e: return ftoken 无效或网络异常: {e} # 用法 resolver HfAuthResolver(explicit_tokenos.environ.get(HF_TOKEN)) print(resolver.diagnose(meta-llama/Llama-2-7b-hf)) # 解析出的 token 传给 from_pretrained(..., tokenresolver.resolve())结构收益单一解析token 来源显式/环境变量/CLI 缓存按优先级统一解析不散落。可诊断diagnose把「无 token / token 无效 / 未授权」区分开排错不再猜。可复用本地、CI、容器都过同一个HfAuthResolver环境差异被吸收。七、解决方案第三层断言 / CI 守护写 pytest 守三条(1) token 解析优先级正确(2) 无 token 时给出清晰诊断而非裸 OSError(3) 显式 token 优先生效。import os import pytest from your_lib import HfAuthResolver def test_explicit_token_wins(monkeypatch): monkeypatch.setenv(HF_TOKEN, from_env) r HfAuthResolver(explicit_tokenfrom_arg) assert r.resolve() from_arg def test_env_token_used_when_no_explicit(monkeypatch): monkeypatch.delenv(HF_TOKEN, raisingFalse) monkeypatch.setenv(HUGGING_FACE_HUB_TOKEN, from_alt) r HfAuthResolver() assert r.resolve() from_alt def test_no_token_diagnosis_clear(monkeypatch): monkeypatch.delenv(HF_TOKEN, raisingFalse) monkeypatch.delenv(HUGGING_FACE_HUB_TOKEN, raisingFalse) r HfAuthResolver() msg r.diagnose(meta-llama/Llama-2-7b-hf) assert 未找到 token in msg assert huggingface-cli login in msg or HF_TOKEN in msg def test_diagnose_mentions_authorization(monkeypatch): monkeypatch.setenv(HF_TOKEN, fake) r HfAuthResolver() msg r.diagnose(some/gated) # 即使是假 token诊断也应提示「确认授权」方向 assert 授权 in msg or token in msgCI 常驻跑这四条后任何「token 解析优先级错」「无 token 时裸崩」的回归都会立刻爆红。八、排查清单报OSError: gated repo时按顺序查先确认是不是 401 类错误gated不是「repo 真的 404」——gated 本质是权限问题。确认已在模型页面Acceptlicense且授权的账号就是你本地要登录的账号。本机跑huggingface-cli login或设HF_TOKEN再huggingface-cli whoami看当前用户。确认from_pretrained能读到 token传token最稳或确保环境变量名是HF_TOKEN。use_auth_token已废弃别再用改用token。CI/容器里确认 secret 名与代码读取的环境变量名一致常见坑HUGGINGFACE_TOKENvsHF_TOKEN。仍 401 时用HfAuthResolver.diagnose(repo)区分「无 token / token 无效 / 未授权」对症处理。九、小结OSError: You are trying to access a gated repo根子是本地没有有效的、已授权该 repo 的 HuggingFace token或 token 没被from_pretrained读到Hub 返回 401 被包成该错。修复三层次第一层huggingface-cli login或设HF_TOKEN、或显式token并确保登录账号已被网页授权第二层用HfAuthResolverdataclass 统一解析 token 来源优先级并给出可诊断的错误提示第三层用 pytest 守「token 解析优先级」「无 token 时清晰诊断」「显式 token 优先」。工程启示凡是加载可能 gated 的模型token 管理要集中、可诊断别让from_pretrained在缺 token 时裸崩。把「无 token / 无效 / 未授权」三种情况用诊断信息区分开排错效率能高一个数量级。切记网页 Accept 和本地登录是两道独立门槛缺一不可。