HuggingFace OSError: Can't Load Tokenizer for Model の修正方法

エラーの内容

AutoTokenizer.from_pretrained() を呼び出すと、次のエラーが表示されます：

OSError: Can't load tokenizer for 'bert-base-uncased'. If you were trying to load it from 'https://huggingface.co/models', make sure you don't have a local directory with the same name. Otherwise, make sure 'bert-base-uncased' is the correct identifier of a pretrained model listed on 'https://huggingface.co/models'.

または短縮版：

OSError: Can't load tokenizer for 'your-model-name'.

怖そうに見えますが、たいていは大したことありません。原因はほぼ必ず次の3つのうちのどれかです：モデル名の間違い、ネットワークの遮断、またはローカルキャッシュの破損。

発生する原因

タイポまたはモデル名の誤り — 指定した識別子がHub上に存在しない。
インターネット接続なし — ファイアウォール、企業プロキシ、またはエアギャップ環境。
キャッシュの破損 — ダウンロードが途中で中断され、~/.cache/huggingface/ に壊れたファイルが残っている。
transformers のバージョンが古い — 一部のトークナイザークラスは4.20以降に追加されており、古いインストールでは認識されない。
プライベートまたはゲートモデル — Llama 2、Mistralなどのリポジトリはライセンスへの同意と有効なHFトークンが必要。
ローカルパスの混乱 — ディレクトリパスを指定したが、必要なファイルがその中に存在しない。

手順ごとの修正方法

ステップ1 — モデル名を確認する

モデル名は大文字・小文字を区別します。Bert-Base-Uncased は失敗し、bert-base-uncased は成功します。

# 間違い
tokenizer = AutoTokenizer.from_pretrained("Bert-Base-Uncased")

# 正しい
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

コミュニティモデルにはユーザー名のプレフィックスも必要です — モデルカードのURLから直接IDをコピーしてください：

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

ステップ2 — ネットワークと認証を確認する

他の操作を行う前に、Hubに実際にアクセスできるか確認してください：

python -c "from huggingface_hub import HfApi; print(HfApi().model_info('bert-base-uncased'))"

ここで接続エラーが出た場合、問題はコードではなくネットワークにあります。

Llama 2などのゲートモデルは、モデルページでのライセンス同意と有効なトークンが必要です：

# 方法A: CLIログイン（セッションをまたいで持続）
huggingface-cli login

# 方法B: トークンをインラインで渡す
tokenizer = AutoTokenizer.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    token="hf_your_token_here"
)

トークンは huggingface.co/settings/tokens で生成できます。ダウンロードには読み取りアクセスで十分です。

ステップ3 — 破損したキャッシュを削除する

中断されたダウンロードは、将来の読み込みを妨げる不完全なファイルを残します。特定のモデルフォルダーを削除して、新たにダウンロードし直してください：

# まずキャッシュの場所を確認する
python -c "from huggingface_hub import constants; print(constants.HF_HUB_CACHE)"

# 壊れたモデルだけを削除する（Linux/macOS）
rm -rf ~/.cache/huggingface/hub/models--bert-base-uncased

# 最終手段：すべて削除する
rm -rf ~/.cache/huggingface/hub/

注意：bert-base-uncased のような一般的なモデルは約440MBあります。大きなモデル（Llama 2 7B）は13GB以上になります。再ダウンロード前にディスク容量を確認してください。

ステップ4 — Transformersをアップグレードする

高速トークナイザーのバックエンドや新しいモデルタイプには、最新リリースが必要なことが多いです。スタック全体を一度にアップグレードしてください：

pip install --upgrade transformers tokenizers huggingface_hub

現在のバージョンを確認してください：

python -c "import transformers; print(transformers.__version__)"

4.30未満のバージョンでは、2023年以降にリリースされたモデルで問題が発生します。最新のモデル（Mistral、Phi、Gemma）には4.35以上が必要です。

ステップ5 — ローカルディレクトリから読み込む

すでにモデルをダウンロード済みの場合は、ローカルパスを直接指定してネットワークを完全にスキップできます：

from transformers import AutoTokenizer

# 一度保存する
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
tokenizer.save_pretrained("./local_tokenizer/")

# 以降はオフラインで読み込む
tokenizer = AutoTokenizer.from_pretrained("./local_tokenizer/")

ディレクトリには tokenizer_config.json が必要です。トークナイザーの種類によっては、vocab.txt（BERTスタイル）、vocab.json（GPT-2スタイル）、または tokenizer.json（高速トークナイザー）も必要です。何か不足していると感じたら ls ./local_tokenizer/ で確認してください。

ステップ6 — オフラインモードを明示的に有効にする

エアギャップ環境では、実行前に TRANSFORMERS_OFFLINE=1 を設定してください：

# シェルで設定
export TRANSFORMERS_OFFLINE=1
python your_script.py

# またはPython内で設定
import os
os.environ["TRANSFORMERS_OFFLINE"] = "1"

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

このフラグを設定すると、Transformersはすべてのネットワーク呼び出しをスキップし、キャッシュからのみ読み込みます。キャッシュが存在しない場合は、huggingface.co への接続待ちでハングすることなく、すぐに明確なエラーが表示されます。

ステップ7 — 低速トークナイザーにフォールバックする

高速（Rustベース）トークナイザーが tokenizers ライブラリとバージョン競合を起こすことがあります。診断のステップとして、純粋なPython実装に切り替えてください：

tokenizer = AutoTokenizer.from_pretrained(
    "bert-base-uncased",
    use_fast=False
)

大きなバッチでは遅くなりますが、Rustライブラリのあらゆるレイヤー問題を完全に回避できます。

修正の確認

修正を適用した後、この簡単な動作確認を実行してください：

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
output = tokenizer("Hello, HuggingFace!", return_tensors="pt")
print(output)
# 期待される出力: {'input_ids': tensor([[101, 7592, 1010, ...]]), 'attention_mask': tensor([[1, 1, ...]])}

テンソルが出力されればトークナイザーは正常に読み込まれています。エラーが出た場合は、モデルIDまたはファイルに依然として問題があります。

簡易診断チェックリスト

Hub URLからモデル名を直接コピーする — 手動で入力し直さない。
huggingface-cli whoami を実行して認証済みであることを確認する。
モデルページに「Access restricted」または「Gated model」の表示がないか確認する。
ディスク空き容量を確認する — トークナイザーのキャッシュは500MBから13GB以上になる。
ローカルから読み込む場合、対象フォルダーに tokenizer_config.json が存在するか確認する。
企業ネットワークでは HTTPS_PROXY を設定する — HFダウンロードの失敗はサイレントなプロキシブロックであることが多い。

プロキシとファイアウォールの修正

企業のプロキシは、明確なエラーを表示せずにHuggingFaceのダウンロードをブロックすることがよくあります。スクリプトを実行する前にプロキシを設定してください：

export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080
python your_script.py

シェル環境を変更できない場合は、Python内で設定してください：

import os
os.environ["HTTPS_PROXY"] = "http://proxy.company.com:8080"

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")