エラーの内容
Hugging Face から Llama 3 モデルを読み込もうとした際に — transformers、huggingface_hub、vLLM、またはHF APIをラップするその他のライブラリを使って — 即座に以下のエラーが発生します：
huggingface_hub.utils._errors.GatedRepoError: 401 Client Error. Cannot access gated repo for url https://huggingface.co/meta-llama/Llama-3-8B/resolve/main/config.json
Linux、macOS、Windows を問わず発生します。ライブラリがモデルリポジトリから最初のファイルを取得しようとした瞬間にエラーが発生します。
何が起きているのか
MetaのLlamaモデル — Mistral、Gemma、Falcon、その他数十のモデルも同様 — はHuggingFace上のゲート付きリポジトリに置かれています。ゲートを通過するには、以下の3つの条件をすべて同時に満たす必要があります：
- 有効なHugging Faceアカウントを持っていること
- モデルページにアクセスしてライセンスに同意していること
- そのアカウントの有効なHFトークンでローカル環境が認証されていること
401エラーは、HuggingFaceのサーバーがあなたを確認できなかったことを意味します。トークンが送信されていないか、トークンが無効か、あるいは最も多い原因として — アカウントがゲーティングの利用規約に同意していない場合です。
ステップ1：モデルのライセンスに同意する（スキップ禁止）
多くの人はトークンを持っていれば十分だと思い込んでいます。しかしそれだけでは不十分です。HuggingFaceのウェブサイトからモデルのアクセス条件に明示的に同意する必要があります — この手順にCLIのショートカットはありません。
- https://huggingface.co/meta-llama/Llama-3-8B にアクセスする
- **「Request access」または「Acknowledge license」**をクリックする（ラベルはモデルによって異なります）
- 必要な項目を入力して送信する
- 承認メールを待つ — Metaは通常数分から数時間以内に返答します
承認されると確認メールが届きます。それ以降、初めてトークンでこの特定のリポジトリにアクセスできるようになります。
ステップ2：読み取りトークンを取得する
https://huggingface.co/settings/tokens にアクセスし、少なくとも**Read（読み取り）**権限を持つトークンを作成します。トークンは hf_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567 のような形式で、hf_ で始まる約37文字です。ページを離れると再表示されないため、今すぐコピーしておいてください。
簡単な解決策：CLIで認証する
最も手早くブロックを解除する方法：
pip install -U huggingface_hub
huggingface-cli login
プロンプトが表示されたらトークンを貼り付けます。トークンは ~/.cache/huggingface/token に保存され、以降のすべてのHF呼び出しで自動的に使用されます。スクリプトを再実行すると、ダウンロードが開始されるはずです。
恒久的な解決策：コード内でトークンを渡す
CLIログインはDockerコンテナ、CIパイプライン、新規VMでは維持されません。自動化された環境では、トークンを明示的に渡してください：
from transformers import AutoModelForCausalLM, AutoTokenizer
import os
hf_token = os.environ.get("HF_TOKEN")
model = AutoModelForCausalLM.from_pretrained(
"meta-llama/Llama-3-8B",
token=hf_token
)
tokenizer = AutoTokenizer.from_pretrained(
"meta-llama/Llama-3-8B",
token=hf_token
)
または huggingface_hub を直接使用する場合：
from huggingface_hub import snapshot_download
import os
snapshot_download(
repo_id="meta-llama/Llama-3-8B",
token=os.environ.get("HF_TOKEN")
)
実行前に環境変数を設定します：
# Linux / macOS
export HF_TOKEN="hf_your_token_here"
python your_script.py
# Windows (PowerShell)
$env:HF_TOKEN = "hf_your_token_here"
python your_script.py
# Docker
docker run -e HF_TOKEN="hf_your_token_here" your-image python your_script.py
ノートブックで作業している場合は login() を直接呼び出してください — ただしトークンをバージョン管理にコミットしないよう注意してください：
from huggingface_hub import login
login(token="hf_your_token_here")
修正の確認
スクリプトを再試行する前に、HuggingFaceが実際にあなたの認証情報を認識しているか確認してください：
huggingface-cli whoami
ユーザー名が表示されるはずです。「Not logged in」と表示された場合、トークンが登録されていません。
次に、アカウントがゲート付きモデルに実際にアクセスできるか確認します：
from huggingface_hub import model_info
info = model_info("meta-llama/Llama-3-8B", token="hf_your_token_here")
print(info.id) # 表示されるべき内容: meta-llama/Llama-3-8B
401ではなく403が返ってくる場合は、ライセンスの承認が保留中か、まだ反映されていないことを意味します。数分待ってから再試行してください。
よくある間違い
- トークンの種類が違う：スコープが限定されたきめ細かいトークンでは、リポジトリの読み取りができない場合があります。これを避けるために、標準のReadトークンを使用してください。
- アカウントの不一致：ライセンスに同意したアカウントと、トークンが属するアカウントが一致している必要があります。複数のHFアカウントを持っている場合は、どのアカウントを使用したか確認してください。
- キャッシュに古いトークンが残っている：トークンを更新しましたか？古いトークンがまだキャッシュに残っているかもしれません。
rm ~/.cache/huggingface/tokenでクリアしてから再度ログインしてください。 - 承認がまだ審査中：Metaの返答は通常早いですが、即時ではありません。フォームを送信したばかりの場合は、問題があると判断する前に15〜30分ほど待ってみてください。
補足情報
ダウンロードが成功すると、モデルは ~/.cache/huggingface/hub/ に保存されます — Llama 3 8BはFloat16でおよそ16 GBを占めるため、ダウンロードを開始する前に十分なディスク容量があることを確認してください。モデルの config.json を確認したい場合は？
ToolCraftのJSON Formatterは構造上の問題を発見するのに便利です — ブラウザ上で完全に動作し、何もアップロードされません。YAMLベースのモデル設定を扱う場合は、同サイトのYAML ↔ JSON Converterを使えば、単一の設定値を確認するためだけにPythonスクリプトを書く手間が省けます。