alterlab-transformers

Transformers

概要

Hugging Face Transformers は、NLP、ビジョン、音声、マルチモーダルタスク向けの事前学習済みチェックポイントを Hub から読み込み、pipeline() または Auto* クラスで推論を実行し、Trainer でファインチューニングします。このスキルは transformers v5（≥ 5.0、2026-09 時点の最新バージョンは 5.17.0）を対象としています。v5 は PyTorch のみをサポートし、v4 の慣用的な書き方のいくつかを変更しているため、論文、ブログ、モデルカードの古いコード例を再利用する前に、以下の「v4 のコードを壊す v5 の変更点」を確認してください。

このスキルを使用する場面

ユーザーが次のことを希望する場合に使用してください。

• Hub のチェックポイントを使って pipeline() で手早く推論を実行する — テキスト分類、NER、ゼロショット分類、チャットモデルによるテキスト生成、音声認識、画像分類／物体検出、または VLM による画像とテキストの変換。
• dtype、device_map、アテンションバックエンド、4／8 ビット量子化を明示して、モデルとトークナイザー／プロセッサーを読み込む。
• model.generate() のデコードを制御する（貪欲法、サンプリング、ビームサーチ、ストリーミング、チャットテンプレート）。
• 必要に応じて peft による LoRA を使用し、Trainer でカスタムのラベル付きデータセットを使ってエンコーダーまたはデコーダーをファインチューニングする。
• v4 時代のコード（torch_dtype=、load_in_8bit=、削除されたパイプライン、TF／Flax モデル）を v5 に移行する。

対象外

シナリオ	代わりに使用
表形式の特徴量に対する古典的な ML（ランダムフォレスト、前処理パイプライン、CV グリッドサーチ）	alterlab-scikit-learn
カスタムの PyTorch アーキテクチャで、LightningModule を使った学習ループ、マルチ GPU 戦略、チェックポイント保存を構成する	alterlab-pytorch-lightning
社会科学の測定設計としてのトピックモデル、埋め込み、テキスト分類器（妥当性、BERTopic、辞書）	alterlab-text-as-data
タンパク質言語モデル（ESM3／ESM C 埋め込み、タンパク質設計）	alterlab-esm
事前学習済みの基盤モデルによるゼロショット時系列予測	alterlab-timesfm

インストール

uv pip install "transformers>=5" torch accelerate datasets

• ビジョン：pillow と torchvision（デフォルトの画像プロセッサーバックエンド。timm バックエンドを使用するモデルのみ timm を追加します）。
• 音声：librosa soundfile を追加します。
• LoRA／量子化：peft、bitsandbytes（CUDA）。メトリクス：evaluate または scikit-learn の標準メトリクス。

認証

ゲート付きモデルまたはプライベートモデルには Hub トークンが必要です。次のいずれかの方法で、一度ログインしてください。

from huggingface_hub import login
login()  # or run `hf auth login` in a shell (huggingface-cli is deprecated)

または、Hub クライアントが読み取る環境変数をエクスポートしてください。

export HF_TOKEN="your_token_here"

トークン：https://huggingface.co/settings/tokens。明示的に必要な場合は token=（削除された use_auth_token= ではなく）を渡してください。

クイックスタート

from transformers import pipeline

# Text generation with a small open chat model (CPU-friendly; add device_map="auto" on GPU)
generator = pipeline("text-generation", model="Qwen/Qwen3-0.6B")
messages = [{"role": "user", "content": "Explain p-hacking in two sentences."}]
out = generator(
    messages,
    max_new_tokens=128,
    tokenizer_encode_kwargs={"enable_thinking": False},  # Qwen3 chat-template switch; omit for other models
)
print(out[0]["generated_text"][-1]["content"])

# Text classification — pin the checkpoint; task defaults change between releases
classifier = pipeline("text-classification", model="distilbert/distilbert-base-uncased-finetuned-sst-2-english")
classifier(["This movie was excellent!", "Terrible pacing."])

# Zero-shot classification
zero_shot = pipeline("zero-shot-classification", model="facebook/bart-large-mnli")
zero_shot("The grant covers two postdoc salaries.", candidate_labels=["funding", "teaching", "ethics"])

生成するトークン数を指定する max_new_tokens を使用してください。max_length はプロンプトと出力の合計長を指定し、テキスト生成パイプラインではトークナイザーの切り詰めにも使用されます。v5 では要約、翻訳、質問応答専用のパイプラインはなくなりました。上記のように、チャットモデルにプロンプトを渡してください。

v4 のコードを破損させる v5 の変更点

v4 の書き方	v5 での置き換え
torch_dtype=torch.float16	dtype=torch.float16（torch_dtype は警告のみ）。デフォルトは dtype="auto" になりました。これはチェックポイントの dtype（多くの場合 bf16）であり、float32 ではありません
TFAutoModel… / FlaxAutoModel…、framework="tf"、return_tensors="tf"	削除されました。PyTorch のみです（return_tensors は "pt"、"np"、"mlx" を受け付けます）
load_in_8bit=True / load_in_4bit=True	quantization_config=BitsAndBytesConfig(...)
pipeline("summarization" / "translation_xx_to_yy" / "text2text-generation" / "question-answering")	削除されました。チャットモデルと指示プロンプトを使った pipeline("text-generation") を使用します
pipeline("image-to-text" / "visual-question-answering")	VLM（例：Qwen/Qwen3-VL-2B-Instruct）を使った pipeline("image-text-to-text")
AutoModelForVision2Seq、AutoModelWithLMHead	AutoModelForImageTextToText、AutoModelForCausalLM / AutoModelForMaskedLM / AutoModelForSeq2SeqLM
apply_chat_template(..., tokenize=True) は ID のテンソルを返しました	BatchEncoding（input_ids、attention_mask）を返します → model.generate(**inputs)
低速トークナイザーと高速トークナイザー、use_fast=	🤗 tokenizers バックエンドではモデルごとに 1 つのトークナイザーを使用します。AutoTokenizer は use_fast を無視します
batch_decode、encode_plus、additional_special_tokens	decode はバッチを処理し、tokenizer(...)、extra_special_tokens を使用します（旧名称も後方互換性のため維持されています）
penalty_alpha（対照的検索）、force_words_ids / constraints、グループビームサーチ、DoLa	Hub の custom_generate リポジトリに移動しました。例：custom_generate="transformers-community/contrastive-search", trust_remote_code=True
TrainingArguments(logging_dir=..., warmup_ratio=...)	どちらも削除されました。TENSORBOARD_LOGGING_DIR 環境変数を設定します。warmup_steps=0.1（1 未満の浮動小数点数は比率として扱われます）
Trainer(tokenizer=...)	Trainer(processing_class=...)。report_to のデフォルトは "none" になりました
save_pretrained(safe_serialization=False)、use_auth_token=	常に safetensors を使用します。token=
TRANSFORMERS_CACHE、low_cpu_mem_usage=True	HF_HOME / HF_HUB_CACHE。低メモリ読み込みは常に有効です（フラグは無視されます）

出典：v5 移行ガイド（公式）。5.17.0 リリースと照合済みです。

主な機能

1. 手早く推論できるパイプライン

テキスト分類、NER、ゼロショット、フィルマスク、テキスト生成、ASR、音声分類、画像分類／セグメンテーション、物体検出、深度推定、画像テキスト変換について、1 回の呼び出しでトークナイズ、フォワードパス、後処理を行います。独自の前処理なしでプロトタイピングやバッチ推論を行う場合に使用します。references/pipelines.md を参照してください。

2. モデルの読み込みと管理

dtype、device_map、attn_implementation（デフォルトは SDPA）、quantization_config を指定した from_pretrained に対応し、保存、Hub へのアップロード、ONNX エクスポートのオプションもあります。references/models.md を参照してください。

3. テキスト生成

貪欲法、サンプリング（temperature/top-k/top-p）、ビームサーチに対応する generate()、チャットテンプレート、ストリーミング、静的キャッシュを利用できます。references/generation.md を参照してください。

4. トレーニングとファインチューニング

混合精度、勾配累積／チェックポイント、コールバック、ハイパーパラメーター検索に対応する Trainer と TrainingArguments、および peft による LoRA を利用できます。references/training.md を参照してください。

5. トークナイズ

パディング、切り詰め、特殊トークン、オフセット、チャットテンプレートに対応しています。references/tokenizers.md を参照してください。

よくあるパターン

パターン 1：シンプルな推論

pipe = pipeline("task-name", model="org/model-id")
output = pipe(input_data)

パターン 2：モデルとトークナイザーを明示的に指定（チャットモデル）

from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "Qwen/Qwen3-0.6B"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, dtype="auto", device_map="auto")

messages = [{"role": "user", "content": "State the central limit theorem in one sentence."}]
inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
    enable_thinking=False,  # Qwen3-specific template variable
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=128)
new_tokens = outputs[0, inputs["input_ids"].shape[1]:]
print(tokenizer.decode(new_tokens, skip_special_tokens=True))

パターン 3：分類器のファインチューニング

from datasets import load_dataset
from transformers import (AutoModelForSequenceClassification, AutoTokenizer,
                          DataCollatorWithPadding, Trainer, TrainingArguments)

model_id = "google-bert/bert-base-uncased"  # or answerdotai/ModernBERT-base
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForSequenceClassification.from_pretrained(model_id, num_labels=5)

ds = load_dataset("Yelp/yelp_review_full")
ds = ds.map(lambda b: tokenizer(b["text"], truncation=True), batched=True)

args = TrainingArguments(
    output_dir="./results",
    num_train_epochs=3,
    per_device_train_batch_size=16,
    eval_strategy="epoch",
    warmup_steps=0.1,          # ratio of total steps
    report_to="tensorboard",   # default is "none" in v5
)
trainer = Trainer(
    model=model,
    args=args,
    train_dataset=ds["train"],
    eval_dataset=ds["test"],
    processing_class=tokenizer,
    data_collator=DataCollatorWithPadding(tokenizer),
)
trainer.train()

実践的な注意点

• 研究コードではモデル ID（できれば revision= も）を固定してください。パイプラインのデフォルト設定や Hub リポジトリは変更されるため、結果が気付かないうちに変わる可能性があります。
• 論文で生成テキストやファインチューニング済みモデルの指標を示す場合は、正確なチェックポイント、transformers のバージョン、デコードパラメーター、シード（transformers.set_seed）を報告してください。
• 重みや出力を再配布する前に、モデルカードのライセンスと利用条件を確認してください。

リファレンスドキュメント

• references/pipelines.md — v5 でサポートされているタスク、パラメーター、バッチ処理、削除されたパイプライン
• references/models.md — 読み込み、dtype/device/attention/quantization、保存、エクスポート
• references/generation.md — デコード戦略、チャットテンプレート、ストリーミング、キャッシュ
• references/training.md — Trainer ワークフロー、TrainingArguments、PEFT、チューニング
• references/tokenizers.md — トークナイズ、特殊トークン、チャットテンプレート

AlterLab Academic Skills スイートの一部です。