transformers

Transformers

概要

Hugging Face Transformers ライブラリを使用すると、NLP、コンピュータービジョン、音声、マルチモーダルの各分野のタスク向けに、数千もの事前学習済みモデルを利用できます。このスキルを使って、モデルの読み込み、推論の実行、カスタムデータでのファインチューニングを行えます。

インストール

transformers 5.12.0（PyPI の現行リリース、2026 年 6 月）でテスト済みです。Python 3.10 以降が必要です。現在、torch エクストラには PyTorch 2.4 以降が必要です。

uv pip install "transformers[torch]==5.12.0" huggingface_hub==1.19.0 datasets==5.0.0 evaluate==0.4.6 accelerate==1.14.0

ビジョンタスクでは、次を追加します。

uv pip install timm==1.0.27 pillow==12.2.0

音声タスクでは、次を追加します。

uv pip install librosa==0.11.0 soundfile==0.14.0

これらのバージョン指定は、再現可能な例を実現するためのものです。試行的に作業する場合は、Transformers と Hub のリリースノートで API の変更を確認してから、バージョン指定を緩めてください。

バージョンを確認します。

import transformers
print(transformers.__version__)

認証

Hugging Face Hub の多くのモデルは、アクセス制限付きまたは非公開です。これらを読み込む前に認証してください。

推奨： CLI でログインします（トークンは ~/.cache/huggingface/token に保存されます）。

hf auth login

Python：

from huggingface_hub import login
login()  # Interactive prompt; do not hardcode tokens in scripts

サーバー／CI： 環境変数に HF_TOKEN を設定します（トークンを git やシェルのプロファイルに絶対にコミットしないでください）。

export HF_TOKEN="..."  # Read token from a secret manager, not source code

トークンは https://huggingface.co/settings/tokens で取得できます。

セキュリティ： トークンをノートブック、リポジトリ、共有設定ファイルに貼り付けないでください。トークンを .bashrc や .zshrc でエクスポートするのではなく、hf auth login を使用してください。

必要な範囲に絞ったトークンスコープを使用してください。非公開モデルやアクセス制限付きモデルのダウンロードには read を、アップロードには write のみを使用します。長時間稼働する環境で、保存済みトークンを Hub へのリクエストごとに送信したくない場合は、HF_HUB_DISABLE_IMPLICIT_TOKEN=1 を設定し、認証が必要な箇所でのみトークンを渡してください。

Transformers v5

Transformers v5 は PyTorch 専用です（TensorFlow と JAX のバックエンドは削除されました）。v4 からのアップグレードについては、v5 移行ガイドを参照してください。新しいプロジェクトでは、transformers 5.x と huggingface_hub 1.x を組み合わせてください。

アクセス制限付きまたはカスタムアーキテクチャ： Hub でモデルのライセンスに同意してから、モデルカードで必要とされている場合に限り、内容を確認したカスタムコードに対して trust_remote_code=True を指定して読み込んでください。

キャッシュの場所： すべての Hugging Face キャッシュには HF_HOME を、Hub のファイルだけには HF_HUB_CACHE を設定します。必要なモデルのスナップショットがすでにキャッシュされている場合にのみ、HF_HUB_OFFLINE=1 を使用してください。

クイックスタート

手動設定なしですばやく推論するには、Pipeline API を使用します。

from transformers import pipeline

# Text generation (prefer max_new_tokens for causal LMs)
generator = pipeline("text-generation", model="Qwen/Qwen2.5-1.5B")
result = generator("The future of AI is", max_new_tokens=50)

# Text classification
classifier = pipeline("text-classification")
result = classifier("This movie was excellent!")

# Question answering
qa = pipeline("question-answering")
result = qa(question="What is AI?", context="AI is artificial intelligence...")

主な機能

1. すばやい推論のためのパイプライン

さまざまなタスクにわたる、シンプルで最適化された推論に使用します。テキスト生成、分類、NER、質問応答、要約、翻訳、画像分類、物体検出、音声分類などに対応しています。

使用する場面：すばやいプロトタイピング、シンプルな推論タスク、カスタムの前処理が不要な場合。

タスクと最適化の全般については、references/pipelines.md を参照してください。

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

設定、デバイスへの配置、精度を細かく制御しながら、事前学習済みモデルを読み込みます。

使用する場面：カスタムモデルの初期化、高度なデバイス管理、モデルの検査。

読み込みのパターンとベストプラクティスについては、references/models.md を参照してください。

3. テキスト生成

さまざまなデコード戦略（貪欲法、ビームサーチ、サンプリング）と制御パラメーター（temperature、top-k、top-p）を使って、LLM でテキストを生成します。

使用する場面：創造的なテキスト生成、コード生成、会話型 AI、テキスト補完。

生成戦略とパラメーターについては、references/generation.md を参照してください。

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

自動混合精度、分散トレーニング、ロギングを備えた Trainer API を使って、カスタムデータセットで事前学習済みモデルをファインチューニングします。

使用する場面：タスク固有のモデル適応、ドメイン適応、モデル性能の向上。

トレーニングのワークフローとベストプラクティスについては、references/training.md を参照してください。

5. トークナイズ

テキストをトークンとトークン ID に変換し、パディング、切り詰め、特殊トークンの処理を行います。

使用する場面：カスタム前処理パイプライン、モデル入力の理解、バッチ処理。

トークナイズの詳細は references/tokenizers.md を参照してください。

一般的なパターン

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

単純なタスクには、パイプラインを使用します。

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

パターン 2：カスタムモデルの使用

より高度な制御には、モデルとトークナイザーを個別に読み込みます。

from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("model-id")
model = AutoModelForCausalLM.from_pretrained("model-id", device_map="auto")

inputs = tokenizer("text", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

パターン 3：ファインチューニング

タスクへの適応には、Trainer を使用します。

from transformers import Trainer, TrainingArguments

training_args = TrainingArguments(
    output_dir="./results",
    num_train_epochs=3,
    per_device_train_batch_size=8,
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
)

trainer.train()

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

各コンポーネントの詳細については、以下を参照してください。

• パイプライン：references/pipelines.md - サポートされているすべてのタスクと最適化
• モデル：references/models.md - 読み込み、保存、設定
• 生成：references/generation.md - テキスト生成の戦略とパラメーター
• トレーニング：references/training.md - Trainer API によるファインチューニング
• トークナイザー：references/tokenizers.md - トークナイズと前処理

エージェントの作業手順

1. 環境を確認します。 Python 環境とライブラリのバージョン（python -c "import pkg; print(pkg.__version__)"）を確認し、データの形状、型、欠損値を調べます。
2. 入力を特定します。 データまたはユーザーに確認して、形式、識別子、パラメーターを特定します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 最初にサンプルまたは単一のフォールドで実行し、実行時間とメモリ使用量を確認します。
4. 上記の手順とリファレンスを使用して、タスク全体を実行します。
5. 結果を検証します。 ホールドアウトデータ、固定した乱数シード、適切な指標を使用し、データリークがないか確認して、不確実性（CI、シード間の標準偏差）を報告します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の不確実性を明記します。

次の状況が発生した場合	対応
メモリ不足、または実行が非常に遅い	サブサンプリング、チャンク処理や遅延計算の使用、またはモデルサイズの縮小を行い、変更内容をユーザーに伝えます。
この手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計値を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えます。
• このセッションで計算していない指標を報告してはいけません。すべての数値について、その算出に使ったコードの経路を示します。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用の発生、共有 GPU やクラウドのクォータの消費、個人データや患者データへのアクセス、または取り消せない操作を行う前に、ユーザーに確認します。

関連スキル

• axolotl：Axolotl を使った大規模言語モデルのファインチューニングに関するガイダンスを提供します。YAML トレーニング設定、LoRA、QLoRA、選好トレーニングなどを扱います…
• unsloth：LoRA と QLoRA を使った、より高速でメモリ効率の高いトレーニング向けライブラリ Unsloth を使った大規模言語モデルのファインチューニングに関するガイダンスを提供します…
• huggingface-tokenizers：BPE、WordPiece、Unigram のトレーニングと使用に対応する HuggingFace Tokenizers ライブラリ（Rust コアと Python、Node.js バインディング）を提供します…