Hugging Face Transformers

Hugging Face Transformers は現在最も人気のあるオープンソースの NLP / AI ライブラリであり、数千の事前学習モデルを提供し、テキスト、画像、音声、マルチモーダルなど、ほぼすべての AI タスクをカバーしています。

その核心的価値: 複雑なモデルのロード、推論、トレーニングのプロセスを数行のコードにカプセル化することです。

Hugging Face エコシステム全体像 Hub 40万以上のモデル 10万以上のデータセット Transformers 事前学習モデルの推論 とファインチューニングフレームワーク Datasets 大量のデータセット 効率的なロードと処理 PEFT パラメータ効率的なファインチューニング LoRA / QLoRA Accelerate 複数GPU/TPUトレーニング 分散高速化 Tokenizers 高性能トークナイザー（Rust実装） Evaluate モデル評価指標（BLEU/F1など）

対応しているタスクタイプ

Transformers が対応するタスク分類 NLP 自然言語処理 テキスト分類（感情分析） 固有表現認識（NER） 質問応答システム（QA） テキスト要約生成 機械翻訳 テキスト生成（対話） 穴埋め/言語モデル CV コンピュータビジョン 画像分類 物体検出 画像セグメンテーション 深度推定 画像生成 ビデオ分類 キーポイント検出 音声 & マルチモーダル 音声認識（ASR） 音声分類 テキスト音声合成（TTS） 画像テキストマッチング（VQA） 画像キャプション生成 ドキュメントQA（DOC QA） ゼロショット分類

Transformer アーキテクチャの核心原理

ライブラリを使用する前に、基盤となるアーキテクチャを理解しておくと、なぜそのようにパラメータ調整するのかが分かるようになります。

全体アーキテクチャ: Encoder-Decoder

三大モデルファミリー

三大モデルファミリー: アーキテクチャ × 適用シーン × 代表モデル Encoder のみのモデル 双方向アテンションで、全体の文脈を理解 適している: 分類、NER、QA（理解系） 代表: BERT、RoBERTa、ALBERT 中国語: BERT-wwm、MacBERT 特徴: 入力全体を同時に見られる 入力 -> [CLS] が全体を表し、[MASK] で事前学習 Decoder のみのモデル 因果的アテンション（左側のみ参照）、自己回帰生成 適している: テキスト生成、対話、コード生成 代表: GPT シリーズ、LLaMA、Qwen 中国語: ChatGLM、Baichuan 特徴: 単語ごとに次の単語を予測 入力 -> 次の単語を予測 -> 結合してもう一度予測 -> 繰り返し Encoder-Decoder モデル シーケンス間（Seq2Seq）タスク 適している: 翻訳、要約、QA生成 代表: T5、BART、mT5 中国語: mT5、PEGASUS-Chinese 特徴: 入力をエンコードし、出力をデコードして生成 ソースシーケンス -> Encoder -> Decoder -> ターゲットシーケンス

インストールと環境設定

インストール

# 基础安装
pip install transformers

# 完整安装（包含训练依赖）
pip install transformers[torch]       # PyTorch 后端（推荐）
pip install transformers[tf-cpu]      # TensorFlow 后端
pip install transformers[flax]        # JAX/Flax 后端

# 常用配套库
pip install datasets          # HuggingFace 数据集库
pip install evaluate          # 模型评估指标
pip install accelerate        # 多GPU/混合精度训练
pip install peft              # 参数高效微调（LoRA等）
pip install tokenizers        # 高性能分词器
pip install sentencepiece     # 部分模型（T5/LLaMA）需要

# 验证安装
python -c "import transformers; print(transformers.__version__)"

環境変数の設定

# 设置模型缓存目录（模型下载后缓存到此路径，默认 ~/.cache/huggingface）
export HF_HOME=/data/huggingface_cache

# 国内用户：使用镜像站加速下载（推荐 hf-mirror.com）
export HF_ENDPOINT=https://hf-mirror.com

# 离线模式（网络不可用时，只使用已缓存的模型）
export TRANSFORMERS_OFFLINE=1

# 禁用进度条（CI/CD 环境）
export DISABLE_TQDM=1

実例

# コード内で設定することもできます
import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

# 現在のキャッシュディレクトリを確認
from transformers.utils import TRANSFORMERS_CACHE
print(TRANSFORMERS_CACHE)

Pipeline: 5行コードでAIを実行

Pipeline は Transformers の最も高レベルな抽象化であり、モデルのロード、前処理、推論、後処理をすべてカプセル化しているため、3〜5行のコードで推論を完了できます。

Pipeline 内部の処理フロー 元の入力 テキスト / 画像 音声 / などのデータ 前処理 Tokenizer によるトークナイズ token ID に変換 Padding/Truncation モデル推論 順伝播 logits の出力 または隠れ層ベクトル 後処理 Softmax/Argmax デコード token->テキスト 出力を整形 結果 ラベル/スコア 生成テキスト Pipeline はすべてのステップを自動的に実行し、ユーザーは元の入力を渡すだけで整形された結果を得られます

Pipeline クイックサンプル大全

実例

from transformers import pipeline

# 1. 感情分析（テキスト分類）
classifier = pipeline("sentiment-analysis")
result = classifier("I love using Hugging Face Transformers!")
# -> [{'label': 'POSITIVE', 'score': 0.9998}]

# 2. テキスト生成
generator = pipeline("text-generation", model="gpt2")
result = generator("Once upon a time in a land far away,",
    max_new_tokens=50, num_return_sequences=1, temperature=0.8)

# 3. 穴埋め（マスク言語モデル）
unmasker = pipeline("fill-mask", model="bert-base-uncased")
result = unmasker("The capital of France is [MASK].")
# -> [{'token_str': 'paris', 'score': 0.9823}, ...]

# 4. 固有表現認識（NER）
ner = pipeline("ner", aggregation_strategy="simple")
result = ner("My name is John and I work at Google in New York.")
# -> [{'entity_group': 'PER', 'word': 'John', 'score': 0.998}, ...]

# 5. 抽出型QA
qa = pipeline("question-answering")
result = qa(question="Who invented Python?",
    context="Python was created by Guido van Rossum in 1991.")
# -> {'answer': 'Guido van Rossum', 'score': 0.9887}

# 6. テキスト要約
summarizer = pipeline("summarization", model="facebook/bart-large-cnn")
result = summarizer(article, max_length=60, min_length=20)

# 7. 機械翻訳
translator = pipeline("translation", model="Helsinki-NLP/opus-mt-en-zh")
result = translator("Hello, how are you today?")
# -> [{'translation_text': 'こんにちは、今日はどうですか？'}]

# 8. ゼロショット分類（特別なトレーニング不要）
zero_shot = pipeline("zero-shot-classification")
result = zero_shot("I love playing football",
    candidate_labels=["sports", "politics", "technology"])
# -> {'labels': ['sports', ...], 'scores': [0.972, ...]}

Pipeline 発展的な設定

実例

import torch
from transformers import pipeline

# GPUを指定
pipe = pipeline("text-generation", model="gpt2", device=0)

# 精度を指定（VRAM節約）
pipe = pipeline("text-generation", model="meta-llama/Llama-2-7b-hf",
    torch_dtype=torch.float16, device_map="auto")

# バッチ処理（スループット向上）
pipe = pipeline("sentiment-analysis", batch_size=32)
results = pipe(large_text_list)    # 自動バッチ推論

# 大きなテキストをチャンクに分割して処理
asr = pipeline("automatic-speech-recognition",
    model="openai/whisper-large-v2",
    chunk_length_s=30, stride_length_s=5)
result = asr("long_audio.wav", return_timestamps=True)

Tokenizer 徹底解説

Tokenizer は NLP の最初のステップ: 生のテキストをモデルが理解できる数値シーケンスに変換します。

Tokenization の完全な流れ

Tokenization の完全なプロセス: テキスト -> モデル入力 Step 1 生のテキスト: "Hello, I'm learning Transformers! It's great." Step 2 トークナイズ（Tokenize）: ["Hello", ",", "I", "'m", "learning", "Transform", "##ers", "!", ...] WordPiece/BPE サブワードトークナイズ: 珍しい単語は分割されます（Transformers -> Transform + ##ers） Step 3 特別なトークンを追加: ["[CLS]", "Hello", ",", "I", "'m", "learning", "Transform", "##ers", ... "[SEP]"] [CLS]分類トークン [SEP]区切りトークン [PAD]パディング; モデルによって特別なトークンは異なります Step 4 token ID に変換: [101, 7592, 1010, 1045, 1005, 1049, 4083, 19081, 2121, ... 102] 各トークンは語彙テーブルの整数インデックスにマッピングされ、モデルのEmbedding層に入力されます。

Tokenizer の核心的な使い方

実例

from transformers import AutoTokenizer

# Tokenizer をロード
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

# ワンステップでエンコード完了
encoding = tokenizer(
    "Hello, I'm learning Transformers!",
    return_tensors="pt",        # PyTorch tensor を返す
    padding=True,               # 最長シーケンスにパディング
    truncation=True,            # 長さ超過時はトランケーション
    max_length=128,             # 最大長
)

print(encoding.keys())
# -> dict_keys(['input_ids', 'token_type_ids', 'attention_mask'])

print(encoding["input_ids"][0][:8])
# -> tensor([101, 7592, 1010, 1045, 1005, 1049, 4083, 19081])

print(encoding["attention_mask"][0][:8])
# -> tensor([1, 1, 1, 1, 1, 1, 1, 1]) # 1=実トークン, 0=パディング

# デコード（ID -> テキスト）
decoded = tokenizer.decode(encoding["input_ids"][0], skip_special_tokens=True)
print(decoded)   # -> "hello, i'm learning transformers!"

# バッチエンコード（自動パディングで整列）
texts = ["Short.", "This is a much longer sentence for testing."]
batch = tokenizer(texts, padding=True, truncation=True, return_tensors="pt")
print(batch["input_ids"].shape)   # -> torch.Size([2, 10])

# 語彙情報
print(f"語彙サイズ: {tokenizer.vocab_size}")      # -> 30522
print(f"[CLS] ID: {tokenizer.cls_token_id}")     # -> 101
print(f"[SEP] ID: {tokenizer.sep_token_id}")     # -> 102
print(f"最大長: {tokenizer.model_max_length}")  # -> 512

一般的な Tokenizer タイプの比較

主流のトークン化アルゴリズム3種の比較 アルゴリズム 原理 トークン化の例 代表的なモデル BPE Byte Pair Encoding 高頻度の文字ペアを統計してマージ 最適なサブワード語彙を学習 "transformers" -> ["transform", "ers"] GPT / RoBERTa WordPiece 言語モデルの確率を最大化 ## プレフィックスでサブワードを表記 "transformers" -> ["transform", "##ers"] BERT / DistilBERT SentencePiece Unigram / BPE 変種 言語非依存で直接処理 生バイト、先頭で語頭をマーク "transformers" -> ["_transform", "ers"] T5 / LLaMA / Qwen

モデルのロードと推論

AutoClass: 自動で適切なモデルクラスを選択

AutoClass の仕組み：正しいモデルアーキテクチャに自動マッチング モデル名 "bert-base-uncased" またはローカルパス AutoClass config.json を読み取る アーキテクチャタイプと照合 AutoModel / AutoTokenizer / ... 正しいクラスを自動返却 BertForSequenceClassification GPT2LMHeadModel T5ForConditionalGeneration ... よく使う AutoClass 早見表： AutoTokenizer 自動トークナイザー AutoModel ベースモデル（隠れ層を出力） AutoModelForSeqClass テキスト分類タスク AutoModelForCausalLM テキスト生成タスク

実例

import torch
from transformers import AutoTokenizer, AutoModelForSequenceClassification

model_name = "bert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(
    model_name, num_labels=2, torch_dtype=torch.float16, device_map="auto"
)

# 手動推論の完全な流れ
text = "Transformers is an amazing library!"

# 1. エンコード
inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=512)
inputs = {k: v.to(model.device) for k, v in inputs.items()}

# 2. フォワード伝播
with torch.no_grad():
    outputs = model(**inputs)

# 3. 出力の解析
logits = outputs.logits                       # shape: [1, 2]
probs  = torch.softmax(logits, dim=-1)
pred   = torch.argmax(probs, dim=-1).item()

id2label = model.config.id2label              # {0: 'LABEL_0', 1: 'LABEL_1'}
print(f"予測クラス: {id2label[pred]}, 信頼度: {probs)

文ベクトルの抽出

実例

from transformers import AutoModel, AutoTokenizer
import torch

model = AutoModel.from_pretrained("bert-base-uncased")
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

def get_sentence_embedding(text: str) -> torch.Tensor:
    inputs = tokenizer(text, return_tensors="pt", max_length=512, truncation=True)
    with torch.no_grad():
        outputs = model(**inputs)
    # 全トークンに平均プーリング（Mean Pooling）を適用
    token_embeddings = outputs.last_hidden_state          # [1, seq_len, 768]
    attention_mask = inputs["attention_mask"].unsqueeze(-1)
    mean_embedding = (token_embeddings * attention_mask).sum(1) / attention_mask.sum(1)
    return mean_embedding  # [1, 768]

vec = get_sentence_embedding("Hello world")
print(vec.shape)  # -> torch.Size([1, 768])

十大よくあるタスク実践

テキスト分類（感情分析）

実例

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch

model_name = "cardiffnlp/twitter-roberta-base-sentiment-latest"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)

def predict_sentiment(texts):
    inputs = tokenizer(texts, return_tensors="pt", padding=True,
                       truncation=True, max_length=512)
    with torch.no_grad():
        logits = model(**inputs).logits
    probs = torch.softmax(logits, dim=-1)
    results = []
    for i, t in enumerate(texts):
        pid = probs[i].argmax().item()
        results.append({"text": t, "label": model.config.id2label[pid],
                         "score": round(probs[i][pid].item(), 4)})
    return results

print(predict_sentiment(["I love this!", "This is terrible."]))
# -> [{'text': 'I love this!', 'label': 'positive', 'score': 0.9756}, ...]

テキスト生成（対話/続き書き）

実例

from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "Qwen/Qwen2-1.5B-Instruct"     # 阿里通义千问（中国語対応）
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name, torch_dtype=torch.float16, device_map="auto"
)

messages = [
    {"role": "system", "content": "あなたは役立つ AI アシスタントです。"},
    {"role": "user", "content": "Transformer とは何かを3文で説明してください。"},
]
text = tokenizer.apply_chat_template(messages, tokenize=False,
                                      add_generation_prompt=True)
inputs = tokenizer(text, return_tensors="pt").to(model.device)

with torch.no_grad():
    output_ids = model.generate(
        **inputs, max_new_tokens=300, temperature=0.7, top_p=0.9,
        do_sample=True, repetition_penalty=1.1,
        pad_token_id=tokenizer.eos_token_id,
    )

new_tokens = output_ids[0][inputs["input_ids"].shape[1]:]
response = tokenizer.decode(new_tokens, skip_special_tokens=True)
print(response)

固有表現認識（NER）

実例

from transformers import pipeline

ner = pipeline("ner", model="dslim/bert-base-NER", aggregation_strategy="simple")
result = ner("Elon Musk founded SpaceX in 2002 and Tesla Motors in 2003.")
for entity in result:
    print(f"{entity['word']:<20} -> {entity['entity_group']} ({entity['score']:.3f})")

# 中国語 NER
ner_cn = pipeline("ner", model="hfl/chinese-bert-wwm-ext-ner-msra",
                   aggregation_strategy="simple")
result = ner_cn("小明は北京大学で学び、その後アリババで働きました。")

機械翻訳

実例

from transformers import pipeline

# 英語から中国語へ
translator = pipeline("translation", model="Helsinki-NLP/opus-mt-en-zh")
result = translator("Artificial intelligence is transforming the world.")
print(result[0]["translation_text"])   # -> 人工知能は世界を変えつつある。

# 中国語から英語へ
translator_zh = pipeline("translation", model="Helsinki-NLP/opus-mt-zh-en")
result = translator_zh("人工知能が世界を変えている。")
print(result[0]["translation_text"])

テキスト要約

実例

from transformers import pipeline

summarizer = pipeline("summarization", model="facebook/bart-large-cnn")
result = summarizer(long_text, max_length=80, min_length=30,
                     do_sample=False, no_repeat_ngram_size=3)
print(result[0]["summary_text"])

ファインチューニング（Fine-tuning）

ファインチューニングは、事前学習済みモデルを特定のタスクとデータに適合させることであり、Transformers の最も重要な応用シナリオです。

ファインチューニングの流れ全体像

Transformers ファインチューニングの完全な流れ データの準備 データセットの読み込み HF datasets または カスタムCSV Tokenize エンコード Padding で整列 DataLoader 重要：データ品質 > データ量 モデルのロード AutoModelForTask num_labels を指定 下層パラメータを凍結 （オプション） 上層のみファインチューニング テクニック：小規模データセット まず下層を凍結 学習設定 TrainingArguments 学習率：2e-5 Batch：32 Epochs：3~5 Warmup ステップ数 重み減衰 テクニック：学習率 最も重要 学習 & 評価 Trainer.train() loss 曲線を監視 検証セットで評価 Early stopping 最良の ckpt を保存 注意：過学習 ベースラインと比較 保存 save_model() save_pretrained Hub にプッシュ 本番デプロイ 量子化推論 ONNX エクスポート HuggingFace Trainer を使うと学習プロセスを大幅に簡素化でき、勾配累積、混合精度、分散学習などを自動処理できます。

完全なファインチューニング例: テキスト分類

実例

from datasets import load_dataset
from transformers import (
    AutoTokenizer, AutoModelForSequenceClassification,
    TrainingArguments, Trainer, DataCollatorWithPadding,
    EarlyStoppingCallback,
)
import evaluate, numpy as np

# 1. データセットの読み込み
dataset = load_dataset("imdb")   # HF Hub の公開データセット

# 2. Tokenizer + 前処理
MODEL_NAME = "bert-base-uncased"
tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)

def tokenize_fn(examples):
    return tokenizer(examples["text"], truncation=True, max_length=512)

tokenized_ds = dataset.map(tokenize_fn, batched=True,
                           remove_columns=["text"])
tokenized_ds = tokenized_ds.rename_column("label", "labels")
tokenized_ds.set_format("torch")
data_collator = DataCollatorWithPadding(tokenizer=tokenizer)

# 3. モデルのロード
model = AutoModelForSequenceClassification.from_pretrained(
    MODEL_NAME, num_labels=2,
    id2label={0: "NEGATIVE", 1: "POSITIVE"},
    label2id={"NEGATIVE": 0, "POSITIVE": 1},
)

# 4. 評価指標
accuracy = evaluate.load("accuracy")
f1 = evaluate.load("f1")
def compute_metrics(eval_pred):
    logits, labels = eval_pred
    preds = np.argmax(logits, axis=-1)
    return {"accuracy": accuracy.compute(predictions=preds, references=labels)["accuracy"],
            "f1": f1.compute(predictions=preds, references=labels, average="binary")["f1"]}

# 5. 学習パラメータ
training_args = TrainingArguments(
    output_dir="./results", num_train_epochs=3,
    per_device_train_batch_size=16, per_device_eval_batch_size=32,
    gradient_accumulation_steps=2, learning_rate=2e-5,
    weight_decay=0.01, warmup_ratio=0.1,
    evaluation_strategy="steps", eval_steps=500,
    save_strategy="steps", save_steps=500,
    load_best_model_at_end=True, metric_for_best_model="f1",
    fp16=True, logging_steps=100, seed=42,
)

# 6. Trainer を作成して学習
trainer = Trainer(
    model=model, args=training_args,
    train_dataset=tokenized_ds["train"],
    eval_dataset=tokenized_ds["test"],
    tokenizer=tokenizer, data_collator=data_collator,
    compute_metrics=compute_metrics,
    callbacks=[EarlyStoppingCallback(early_stopping_patience=3)],
)
trainer.train()

# 7. 評価して保存
eval_result = trainer.evaluate()
print(f"精度: {eval_result['eval_accuracy']:.4f}")
print(f"F1: {eval_result['eval_f1']:.4f}")

trainer.save_model("./my-sentiment-model")
tokenizer.save_pretrained("./my-sentiment-model")

LoRA パラメータ効率的ファインチューニング（推奨）

LoRA の原理：低ランク行列のみ学習し、元の重みは凍結 全量ファインチューニング（Full Fine-tuning） W + ΔW すべての重み行列を更新 パラメータ数：全部（例：7B パラメータを全学習） GPUメモリ要件：非常に高い（モデルサイズの4倍が必要） コスト：高額で、大量の GPU が必要 LoRA ファインチューニング W（凍結） 学習に参加しない + B x A r << d（低ランク行列） ここだけ学習 パラメータ数：元の 0.1%～1% GPUメモリ要件：低い（低ランク行列の勾配のみ保存） コスト：単一 GPU 24GB で 7B をファインチューニング可能 LoRA は ΔW を2つの低ランク行列に分解し、r は d よりはるかに小さく（通常 r=8〜64）、学習コストを大幅に削減します。

実例

from peft import LoraConfig, get_peft_model, TaskType
from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments
import torch

model_name = "meta-llama/Llama-2-7b-hf"
model = AutoModelForCausalLM.from_pretrained(
    model_name, torch_dtype=torch.float16, device_map="auto",
    load_in_4bit=True,        # 4-bit 量子化ロード（QLoRA）でメモリをさらに節約
)

# LoRA を設定
lora_config = LoraConfig(
    task_type=TaskType.CAUSAL_LM, r=16, lora_alpha=32,
    lora_dropout=0.05,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
)

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# -> trainable: 4,194,304 || all: 6,742,609,920 || 0.0622%

LoRA の利点：パラメータの1%未満のみを学習し、メモリ使用量を60〜70%削減、速度は2〜3倍高速、重みファイルはわずか数MB。同じベースモデルに複数の LoRA アダプタを保存して、異なるタスクに使用できます。

モデルの保存、ロード、公開

実例

# ローカルに保存
model.save_pretrained("./my-model")
tokenizer.save_pretrained("./my-model")

# ローカルからロード
model = AutoModelForSequenceClassification.from_pretrained("./my-model")
tokenizer = AutoTokenizer.from_pretrained("./my-model")

# HuggingFace Hub に公開
from huggingface_hub import login
login(token="your_hf_token")   # huggingface.co/settings/tokens
model.push_to_hub("your-username/my-sentiment-model")
tokenizer.push_to_hub("your-username/my-sentiment-model")

# Trainer 経由で直接公開
training_args = TrainingArguments(
    output_dir="your-username/my-model",
    push_to_hub=True, hub_strategy="every_save",
)

パフォーマンス最適化テクニック

推論高速化の全体像

推論高速化テクノロジースタック：シンプルから高度な最適化まで Level 1 - ゼロコスト最適化 torch.no_grad() 推論 | fp16/bf16 半精度 | batch 推論 | device_map="auto" で自動デバイス割り当て 高速化：1.5〜2倍 Level 2 - 量子化（モデル圧縮） bitsandbytes 4-bit/8-bit 量子化 | GPTQ（後学習量子化）| AWQ（アクティベーション認識量子化） 高速化：2〜4倍、メモリ半減 Level 3 - コンパイルとランタイム最適化 torch.compile()（PyTorch 2.0）| FlashAttention-2 | xFormers | Optimum（TensorRT/ONNX） 高速化：3〜10倍 Level 4 - 専用推論エンジン vLLM（LLM 高スループット推論）| TGI | TensorRT-LLM | llama.cpp（CPU） 本番グレード、最高性能

実例

# 4-bit 量子化ロード（13B モデルは約7GB GPUメモリのみ）
from transformers import BitsAndBytesConfig, AutoModelForCausalLM
import torch

quant_config = BitsAndBytesConfig(
    load_in_4bit=True, bnb_4bit_compute_dtype=torch.float16,
    bnb_4bit_use_double_quant=True, bnb_4bit_quant_type="nf4",
)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-13b-hf",
    quantization_config=quant_config, device_map="auto",
)

# FlashAttention-2 高速化（要 pip install flash-attn）
model = AutoModelForCausalLM.from_pretrained(
    "mistralai/Mistral-7B-v0.1",
    attn_implementation="flash_attention_2",
    torch_dtype=torch.bfloat16, device_map="auto",
)

# torch.compile (PyTorch 2.0+)
model = torch.compile(model, mode="reduce-overhead")

よくある問題のトラブルシューティング

よくあるエラーと解決策の早見表 エラーメッセージ 原因と解決策 CUDA out of memory GPUメモリ不足 batch_size を小さくする；gradient_accumulation_steps を加える；fp16/4-bit を使う；より小さいモデルを使う OSError: model not found モデル名の誤りまたはネットワークの問題 スペルを確認する；HF_ENDPOINT ミラーを設定する；ダウンロード済みならローカルパスを使う ValueError: num_labels mismatch モデルをロードする際に num_labels=あなたのクラス数を明示的に指定する tensors on different devices inputs = {k: v.to(model.device) for k, v in inputs.items()} loss = NaN / loss が下がらない 学習率を確認する（大きすぎると NaN）；labels の値域を確認する（0~N-1）；gradient_clipping を追加する slow tokenizer / 速度が遅い pip install tokenizers で Rust の高速版をインストールする；use_fast=True（デフォルト）を使う

まとめと学習パス

Transformers 学習パスと中核知識ポイント 第一段階 入門（1週間） pip install で環境構築 Pipeline で5つのタスクを実行する Tokenizer の流れを理解する AutoModel で手動推論 Encoder/Decoder を理解する モデル出力構造を読み解く 第二段階 応用（2週間） Hub 上のモデルをロードする テキスト分類のファインチューニング実践 Trainer API を熟練して使う カスタムデータセットの処理 compute_metrics で評価 保存して Hub に公開する 第三段階 上級（3週間） LoRA / PEFT ファインチューニング 量子化（4-bit/8-bit） マルチモーダルモデルの使用 カスタム訓練ループ Accelerate で複数GPU FlashAttention で高速化 第四段階 エキスパート（継続） カスタムモデルアーキテクチャ スクラッチから事前学習 vLLM で本番デプロイ RLHF/DPO アライメント オープンソースモデルへの貢献 研究最先端の論文 各段階で実践すべきです：実際のデータセットを探し、訓練->評価->公開の完全なフローを実行する

主要API早見表

実例

# 1. トークナイザーをロード
tokenizer = AutoTokenizer.from_pretrained("model_name")

# 2. テキストをエンコード
inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=512)

# 3. モデルをロード
model = AutoModelForSequenceClassification.from_pretrained("model_name", num_labels=N)

# 4. 推論
with torch.no_grad():
    outputs = model(**inputs)

# 5. Pipeline
pipe = pipeline("task_name", model="model_name")

# 6. 訓練設定
args = TrainingArguments(output_dir="./out", num_train_epochs=3, learning_rate=2e-5)

# 7. 訓練
trainer = Trainer(model=model, args=args, train_dataset=ds, compute_metrics=fn)

# 8. 保存
model.save_pretrained("./my-model")
tokenizer.save_pretrained("./my-model")

# 9. データセット
dataset = load_dataset("dataset_name")
dataset = dataset.map(tokenize_fn, batched=True)

# 10. LoRA
config = LoraConfig(r=16, lora_alpha=32, target_modules=["q_proj","v_proj"])
model = get_peft_model(model, config)

参考リソース

その他の拡張