Hugging Face Transformers のエラー対処ガイド — 原因の見分け方と解決手順

# 現在アクティブな Python 環境を確認
which python
python --version
 
# transformers がインストールされているか確認
pip show transformers

# 仮想環境を新規作成（既存を使い回さない）
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
 
# transformers と依存ライブラリをセットでインストール
pip install transformers[torch] accelerate sentencepiece

import transformers
print(transformers.__version__)  # 例: 4.40.0
 
import torch
print(torch.__version__)         # 例: 2.3.0+cu118
print(torch.cuda.is_available()) # True なら GPU 利用可

# 現在のバージョン確認
pip show transformers | grep Version
# → Version: 4.28.0（古い場合がある）
 
# モデルカードで推奨バージョンを確認してからアップグレード
pip install "transformers>=4.40.0"
 
# または最新版にアップグレード
pip install --upgrade transformers

transformers==4.40.0
torch==2.3.0
accelerate==0.30.0
tokenizers==0.19.1

pip install -r requirements.txt

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch
 
model_id = "meta-llama/Meta-Llama-3-8B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_id)
 
# torch_dtype を指定することで VRAM 使用量を約半分に削減
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.float16,   # または torch.bfloat16
    device_map="auto"            # 利用可能なデバイスに自動配置
)
 
# 推論
inputs = tokenizer("こんにちは", return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=100)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

import torch
 
# bf16 対応 GPU なら bfloat16、非対応なら float16 に自動で切り替える
dtype = torch.bfloat16 if torch.cuda.is_bf16_supported() else torch.float16
 
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=dtype,
    device_map="auto"
)

pip install bitsandbytes

from transformers import BitsAndBytesConfig
 
quantization_config = BitsAndBytesConfig(load_in_4bit=True)
 
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    quantization_config=quantization_config,
    device_map="auto"
)

# バッチサイズを 8 → 1 に削減
for i in range(0, len(dataset), 1):  # batch_size=1
    batch = dataset[i:i+1]
    # 推論処理

import torch
import gc
 
# 不要になったモデルを解放
del model
gc.collect()
torch.cuda.empty_cache()
 
# 現在の VRAM 使用量を確認
print(f"VRAM 使用中: {torch.cuda.memory_allocated() / 1024**3:.1f} GB")
print(f"VRAM 予約済み: {torch.cuda.memory_reserved() / 1024**3:.1f} GB")

# ① モデルIDのスペルミスを確認（大文字・小文字・スラッシュ）
# 正しい例: "openai-community/gpt2" ではなく "gpt2"（公式で変更された場合がある）
 
# ② ネットワーク接続を確認
curl -I https://huggingface.co
 
# ③ HF_TOKEN を設定（プライベートモデルの場合）
huggingface-cli login
# または環境変数で指定
export HF_TOKEN="YOUR_HF_TOKEN_HERE"

from transformers import AutoTokenizer
from huggingface_hub import login
 
# プログラムから認証
login(token="YOUR_HF_TOKEN_HERE")
 
# オフライン環境の場合はローカルパスを指定
tokenizer = AutoTokenizer.from_pretrained("/path/to/local/model")

# キャッシュを削除してから再ダウンロード
rm -rf ~/.cache/huggingface/hub/models--gpt2
 
# またはキャッシュディレクトリ全体をクリア（慎重に）
# rm -rf ~/.cache/huggingface/

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
 
model = AutoModelForCausalLM.from_pretrained("gpt2", device_map="cuda")
tokenizer = AutoTokenizer.from_pretrained("gpt2")
 
# ❌ 悪い例：入力が CPU のまま
inputs = tokenizer("Hello", return_tensors="pt")
# → RuntimeError が発生する
 
# ✅ 正しい例：モデルと同じデバイスに移動
device = next(model.parameters()).device
inputs = tokenizer("Hello", return_tensors="pt").to(device)
 
outputs = model.generate(**inputs, max_new_tokens=50)
print(tokenizer.decode(outputs[0]))

import torch
 
# Mac での GPU 利用可否は cuda ではなく mps で確認する
print(torch.backends.mps.is_available())  # True なら Apple GPU が使える
 
device = "mps" if torch.backends.mps.is_available() else "cpu"
model = model.to(device)

PYTORCH_ENABLE_MPS_FALLBACK=1 python your_script.py

from transformers import pipeline
import torch
 
# デバイスを明示
device = 0 if torch.cuda.is_available() else -1
 
# テキスト生成パイプライン（最も基本的なテスト）
generator = pipeline(
    "text-generation",
    model="gpt2",
    device=device
)
 
result = generator("Hugging Face is", max_new_tokens=30, num_return_sequences=1)
print(result[0]["generated_text"])
# → "Hugging Face is a company that..." のように続きが出力されれば成功

import torch
from transformers import AutoModel
 
model = AutoModel.from_pretrained("bert-base-uncased").to("cuda")
print(f"モデルのデバイス: {next(model.parameters()).device}")
# → モデルのデバイス: cuda:0

# キャッシュの内訳を確認（モデルごとのサイズと最終利用日時が一覧になる）
huggingface-cli scan-cache
 
# 対話的に不要なモデルを選んで削除
huggingface-cli delete-cache

# 例: 外付けSSDへ移す（シェルの設定ファイルに追記して永続化）
export HF_HOME="/Volumes/ExternalSSD/huggingface"

# pyenv + venv の組み合わせが安定しています
pyenv install 3.11.8
pyenv local 3.11.8
python -m venv .venv
source .venv/bin/activate

pip freeze > requirements.txt

huggingface-cli download meta-llama/Meta-Llama-3-8B-Instruct

# 別ターミナルで実行（1秒おきに更新）
watch -n 1 nvidia-smi