Hugging Face transformers入門｜pipelineとタスク一覧

pipeline() は、タスク名とモデル名を渡すだけで「前処理 → モデル → 後処理」をまとめて動かす transformers の関数です。 モデルは Hugging Face Hub から初回に自動でダウンロードされ、キャッシュ（~/.cache/huggingface/hub）に保存されます。

from transformers import pipeline

clf = pipeline("text-classification", model="distilbert/distilbert-base-uncased-finetuned-sst-2-english")
print(clf("This movie is disgustingly good !"))
# ソースの docstring の例の出力：[{'label': 'POSITIVE', 'score': 1.0}]

transformers 5 で変わった主な点は次のとおりです。以前の記事のコードがそのまま動かないときは、まずここを見ます。

確認環境：transformers 5.19.0（pip の最新版）・huggingface_hub 2.2.0・tokenizers 0.23.3・safetensors 0.8.0・fugashi と unidic-lite・Python 3.11.15（Linux）。タスクの一覧と既定のモデル、削除されたタスクのエラー、トークナイザーと設定（config）の保存・読み込み、キャッシュの場所と環境変数、オフラインでの読み込みとエラー、PyTorch が無いときのエラーは、この版で実行して確かめました。トークナイザーと設定は、手元で作った極小のもの（語彙144語・隠れ層32次元の BERT の設定）を使いました。モデルの推論の出力・GPU の指定・量子化は、transformers のソース（docstring）と huggingface.co/docs/transformers の記載に基づきます（確認日 2026年10月13日）。

インストール

pip install "transformers[torch]"      # transformers と PyTorch・accelerate
pip install "transformers[torch,sentencepiece]"   # SentencePiece を使うモデル（T5 など）
pip install fugashi unidic-lite        # MeCab で分ける日本語 BERT を使うとき

pip install transformers だけでは PyTorch は入りません。 その状態で import すると、次の1行が表示されました。トークナイザーと設定は使えますが、モデルは読み込めません。

[transformers] PyTorch was not found. Models won't be available and only tokenizers, configuration and file/data utilities can be used.

仮想環境の作り方は、関連記事「Python venvの使い方｜仮想環境の作成・有効化・削除をOS別にコピペ」で扱っています。

pipeline のタスク一覧

5.19.0 の pipeline が受け付けるタスクは24個でした（transformers.pipelines.SUPPORTED_TASKS の件数）。model= を省いたときに使われる既定のモデルも、ソースに書かれています。

別名は sentiment-analysis（= text-classification）・ner（= token-classification）・text-to-speech（= text-to-audio）の3つでした。

既定のモデルの多くは英語用です。 日本語の文を分類するなら、日本語で学習したモデルを model= で指定します。model= を省くと、次の警告が出ました。

[transformers] No model was supplied, defaulted to distilbert/distilbert-base-uncased-finetuned-sst-2-english and revision 714eb0f.
Using a pipeline without specifying a model name and revision in production is not recommended.

v5 で無くなったタスクと移り先

要約・翻訳・質問応答（抽出型）は、5.19.0 では KeyError になりました。

KeyError: 'The task summarization has been removed from transformers. Use the `text-generation` pipeline with a chat model instead. See the migration guide for more details: https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md#pipelines'

pipeline の基本の書き方

分類・穴埋め・ゼロショット分類

from transformers import pipeline

clf = pipeline("text-classification", model="モデル名", device="cpu")

clf("とても良い映画でした")                          # 1件
clf(["良かった", "つまらなかった"], batch_size=8)    # まとめて
clf("とても良い映画でした", top_k=None)              # 全ラベルのスコア

zsc = pipeline("zero-shot-classification", model="モデル名")
zsc("VPNにつながりません", candidate_labels=["障害", "質問", "要望"])

device を省くと、CUDA・MPS などのアクセラレータがあればそこに、無ければ CPU に置かれます（ソースの docstring）。dtype="auto" は、モデルを保存したときの精度で読み込む指定です。ドキュメントでは、batch_size は「必ず速くなるとは限らない。CPU や、入力の長さがばらばらのときは向かない」とされています。

trust_remote_code=True は、Hub からダウンロードした Python のコードを手元で実行します。中身を確かめたリポジトリだけに付けます。

文の生成とチャット：text-generation

from transformers import pipeline
import torch

gen = pipeline("text-generation", model="モデル名", dtype=torch.bfloat16, device_map="auto")

# 文字列を渡す
out = gen("RAGとは", max_new_tokens=100, return_full_text=False)
print(out[0]["generated_text"])

# チャットモデルにはメッセージのリストを渡す
messages = [
    {"role": "system", "content": "短く答えます。"},
    {"role": "user", "content": "次の文を3行で要約して：..."},
]
out = gen(messages, max_new_tokens=200, do_sample=False)
print(out[0]["generated_text"][-1]["content"])   # 最後が assistant の返答

ソースの docstring の例では、メッセージのリストを渡すと generated_text に会話の全部が入り、最後に {'role': 'assistant', 'content': 'Paris'} が足されて返ります。文字列を渡したときは、既定（return_full_text=True）で入力の文も含めて返るので、新しく作った部分だけ欲しいときは return_full_text=False を付けます。

モデルの generation_config.json に指定が無いとき、text-generation の既定は max_new_tokens=256・do_sample=True・temperature=0.7 です（ソースの docstring）。同じ入力で同じ答えにしたいときは do_sample=False を付けます。

AutoTokenizer・AutoModel：pipeline の中身を自分で書く

pipeline は、トークナイザー（文 → 数値の列）とモデル（数値の列 → 結果）をつないだものです。 出力を細かく扱いたいとき、学習（ファインチューニング）するときは、2つを自分で使います。

import torch
from transformers import AutoTokenizer, AutoModelForSequenceClassification

name = "モデル名"
tokenizer = AutoTokenizer.from_pretrained(name)
model = AutoModelForSequenceClassification.from_pretrained(name)
model.eval()

inputs = tokenizer(["良かった", "つまらなかった"], padding=True, truncation=True, max_length=128, return_tensors="pt")
with torch.no_grad():
    logits = model(**inputs).logits
probs = logits.softmax(dim=-1)
for p in probs:
    i = int(p.argmax())
    print(model.config.id2label[i], float(p[i]))

Auto で始まるクラスは、config.json の model_type（例：bert）を見て、合うクラス（BertTokenizer・BertForSequenceClassification など）を選びます。

トークナイザーの動き（手元の極小モデルで確認）

手元で作った極小のトークナイザー（語彙144語）を save_pretrained() で保存し、AutoTokenizer.from_pretrained("./tiny") で読み込んだ結果です。

from transformers import AutoTokenizer

t = AutoTokenizer.from_pretrained("./tiny")
enc = t("有給休暇の申請は前日までです。")
print(enc)
print(t.convert_ids_to_tokens(enc["input_ids"]))

batch = t(["経費精算は月末締めです。", "在宅勤務"], padding=True, truncation=True,
          max_length=16, return_tensors="np")
print({k: v.shape for k, v in batch.items()})
print(batch["attention_mask"])

{'input_ids': [2, 139, 100, 93, 22, 3], 'attention_mask': [1, 1, 1, 1, 1, 1]}
['[CLS]', '有給休暇の申請は前', '##日まで', '##です', '。', '[SEP]']
{'input_ids': (2, 4), 'attention_mask': (2, 4)}
[[1 1 1 1]
 [1 1 1 0]]

• 文の前後に [CLS]（2）と [SEP]（3）が自動で付く
• padding=True で短い文の後ろが埋められ、attention_mask の 0 が「埋めた部分」を表す
• return_tensors="np" は NumPy、"pt" は PyTorch のテンソルで返す

PyTorch が無い状態で return_tensors="pt" を指定すると、ImportError: Unable to convert output to PyTorch tensors format, PyTorch is not installed. になりました。v5 では、AutoTokenizer が返すクラスは TokenizersBackend でした（移行ガイドでは、以前の「slow」「fast」の2種類が1つにまとめられ、TokenizersBackend が優先して使われるとあります）。

設定（config）だけを読む・作る

from transformers import AutoConfig, BertConfig

config = BertConfig(hidden_size=32, num_hidden_layers=2, num_attention_heads=2,
                    intermediate_size=64, num_labels=2,
                    id2label={0: "NEGATIVE", 1: "POSITIVE"}, label2id={"NEGATIVE": 0, "POSITIVE": 1})
config.save_pretrained("./tiny")                  # config.json ができる

c = AutoConfig.from_pretrained("./tiny")
print(type(c).__name__, c.model_type, c.hidden_size, c.id2label)

BertConfig bert 32 {0: 'NEGATIVE', 1: 'POSITIVE'}

config.json だけなら数 KB なので、モデル本体をダウンロードする前に、層の数・語彙の数・扱える長さ（max_position_embeddings）・ラベル名を確かめられます。ドキュメントでは、AutoModelForSequenceClassification.from_config(config) で、この設定からランダムな重みのモデルを作れます（動作確認やテスト用）。

日本語モデルの選び方の観点

日本語の文を扱うなら、日本語のデータで学習したモデルを選びます。 Hub のモデルのページ（モデルカード）で、次の点を確かめます。

トークナイザーで、分かれ方が大きく変わる

日本語は単語の間に空白がありません。空白で区切る前提のトークナイザーと、MeCab（形態素解析）で区切るトークナイザーでは、同じ文の分かれ方がまったく違いました。

空白で区切る極小のトークナイザー：['[CLS]', '有給休暇の申請は前', '##日まで', '##です', '。', '[SEP]']
MeCab（unidic-lite）で区切る：     ['有給', '休暇', 'の', '申請', 'は', '前日', 'まで', 'です', '。']

MeCab で区切る日本語 BERT（BertJapaneseTokenizer）は、fugashi と辞書が要ります。入れていないと、次のエラーになりました。

ModuleNotFoundError: You need to install fugashi to use MecabTokenizer. See https://pypi.org/project/fugashi/ for installation.

pip install fugashi unidic-lite（または pip install "transformers[ja]"）で入ります。[ja] を付けると fugashi・ipadic・unidic_lite・unidic・sudachipy など日本語用のパッケージがまとめて入る指定でした。どの辞書を使うかはモデルの tokenizer_config.json で決まります。

検索用の文のベクトルを作るなら、feature-extraction より、文の埋め込み用に学習したモデル（sentence-transformers の形のもの）が向いています。考え方は、関連記事「エンベディングとは？ベクトル検索とコサイン類似度を計算例で解説」で扱っています。

GPU・CPU とメモリの目安

モデルの重みが使うメモリは、だいたい「パラメータ数 × 1つあたりのバイト数」です。 推論では、これに入力の長さに応じた作業用のメモリが足されます。

（重みだけの計算値です。GB は 10 の 9 乗バイトで計算しています。）

• BERT 程度の分類モデルは、CPU でも動く大きさです。件数が多いときは GPU のほうが速くなります
• 数 B（数十億）以上の生成モデルは、GPU のメモリに重みが収まるかを先に計算します
• ドキュメントでは、device_map="auto" は GPU に収まらない分を CPU などに分けて置きます（遅くなります）
• 量子化は bitsandbytes を入れて、model_kwargs={"quantization_config": BitsAndBytesConfig(load_in_8bit=True)} で指定します（v5 では load_in_8bit=True を直接渡す書き方は削除）

import torch
from transformers import pipeline

print(torch.cuda.is_available())     # GPU が使えるか

gen = pipeline("text-generation", model="モデル名",
               dtype=torch.bfloat16,  # 半分のメモリで読む
               device_map="auto")     # GPU に入らない分は自動で分ける
print(gen.model.device, gen.model.dtype)

キャッシュの場所と環境変数

ダウンロードしたモデルは、既定で ~/.cache/huggingface/hub に保存されます。 環境変数を変えたときの場所を、huggingface_hub 2.2.0 の constants で表示しました。

TRANSFORMERS_CACHE は v5 では読まれませんでした。 移行ガイドにも、TRANSFORMERS_CACHE・PYTORCH_TRANSFORMERS_CACHE は削除され、HF_HOME を使うとあります。ディスクの大きい場所に置きたいときは HF_HOME を設定します。

TRANSFORMERS_OFFLINE=1 も、huggingface_hub 側で HF_HUB_OFFLINE と同じ扱いになっていました（constants.py で両方を読む）。.env に書いて読ませる方法は、関連記事「.envの使い方と注意点｜APIキーを安全に管理する方法」で扱っています。

キャッシュの中身と、消し方

~/.cache/huggingface/hub/
└── models--example--tiny-bert/        ← models--{組織}--{名前}
    ├── blobs/                         ← 本体（ファイル名は sha256）
    ├── refs/main                      ← main が指すコミットのハッシュ
    └── snapshots/{コミットのハッシュ}/
        ├── config.json -> ../../blobs/9c56cc...
        ├── tokenizer.json -> ../../blobs/03b4b7...
        └── tokenizer_config.json -> ../../blobs/5ac4e7...

snapshots の中は blobs へのシンボリックリンクです。同じファイルは版が変わっても1つだけ保存されます。手元でこの形を作り、hf cache ls で一覧を出した結果です。

hf cache ls                     # 一覧とサイズ
hf cache rm model/example/tiny-bert   # 消す
hf cache prune                  # 使われていない版・途中のダウンロードを消す

ID                      SIZE LAST_ACCESSED     LAST_MODIFIED     REFS
----------------------- ---- ----------------- ----------------- ----
model/example/tiny-bert 6.4K a few seconds ago a few seconds ago main

Found 1 repo(s) for a total of 1 revision(s) and 6.4K on disk.

hf env で、使われているキャッシュの場所（HF_HUB_CACHE）とトークンの場所を確かめられます。

オフラインで使う

インターネットにつながらないサーバーで使うには、つながる環境で先にダウンロードし、そのファイルを持ち込みます。 方法は2つです。

方法1：キャッシュごと持ち込み、HF_HUB_OFFLINE=1 で読む

# つながる環境で
hf download モデル名                         # ~/.cache/huggingface/hub に入る
# キャッシュのフォルダ（$HF_HOME/hub）をオフラインのサーバーへコピー

# オフラインのサーバーで
export HF_HOME=/data/hf
export HF_HUB_OFFLINE=1
python app.py                                # from_pretrained("モデル名") がキャッシュから読む

手元で作ったキャッシュ（上の models--example--tiny-bert）を HF_HUB_OFFLINE=1 で読むと、Hub に接続せずに読み込めました。

from transformers import AutoTokenizer, AutoConfig

t = AutoTokenizer.from_pretrained("example/tiny-bert")   # キャッシュから
print(type(t).__name__, t("経費精算は月末締めです。")["input_ids"])
print(AutoConfig.from_pretrained("example/tiny-bert").num_labels)

TokenizersBackend [2, 143, 22, 3]
2

方法2：フォルダに保存し、パスで読む

# つながる環境で
from huggingface_hub import snapshot_download
snapshot_download(repo_id="モデル名", local_dir="./models/my-model")
# または：tokenizer.save_pretrained("./models/my-model"); model.save_pretrained("./models/my-model")

# オフラインのサーバーで
tokenizer = AutoTokenizer.from_pretrained("./models/my-model")
model = AutoModelForSequenceClassification.from_pretrained("./models/my-model")
clf = pipeline("text-classification", model="./models/my-model")

フォルダのパスを渡すと、キャッシュも Hub も使いません。ドキュメントでは、from_pretrained(..., local_files_only=True) でもキャッシュとローカルのファイルだけを読む指定になります。

オフライン・プロキシで出たエラー

プロキシで止められたときも、表に出るのは「設定が読み込めない」という OSError でした。 原因は例外の __context__（ProxyError('403 Forbidden')）に入っていました。モデル名が正しいのに読み込めないときは、トレースバックの上のほうにある元の例外を見ます。フォルダのパスを書き間違えると、フォルダが無いので Hub のモデル名として扱われ、「Repo id」のエラーになります。

よくあるエラーと原因

非公開や利用の同意が必要なモデル（gated model）は、Hub のページで同意してから、hf auth login か HF_TOKEN でトークンを渡します。エラーをまとめて AI に聞くときの渡し方は、関連記事「エラーを生成AIに聞くプロンプトの書き方｜スタックトレースの渡し方」で扱っています。

よくある質問

Q. pipeline と AutoModel、どちらを使いますか。 A. 推論の結果だけが欲しいなら pipeline のほうが短く書けます。ロジット（確率にする前の値）を使う、前処理を変える、学習するときは AutoTokenizer と AutoModelFor... を使います。

Q. 要約や翻訳は v5 ではできませんか。 A. 専用のタスクは無くなりましたが、text-generation でチャットモデルに「要約して」「英語に訳して」とメッセージで頼む書き方になります（移行ガイド）。

Q. ローカル LLM を手軽に動かすだけなら？ A. 生成だけが目的なら、Ollama のように重みの取得とサーバーをまとめて扱うツールもあります。関連記事「Ollamaの使い方｜ローカルLLMのコマンド一覧とAPIの呼び方」で扱っています。

Q. RAG に使えますか。 A. 埋め込み（feature-extraction や文の埋め込み用のモデル）と生成（text-generation）の両方を transformers で動かせます。組み立て方は、関連記事「RAGの作り方｜Pythonで動かす最小構成と精度の上げ方」で扱っています。

まとめ

• pip install "transformers[torch]"。v5 は PyTorch だけ。PyTorch が無いとトークナイザーと設定しか使えない
• pipeline("タスク名", model="モデル名")。5.19.0 のタスクは24個、既定のモデルは英語用が多い
• 要約・翻訳・質問応答は v5 で削除。text-generation とチャットモデルで書く
• 精度は dtype=（torch_dtype は非推奨）、置き場所は device=・device_map="auto"
• メモリは パラメータ数 × バイト数（7B の bfloat16 で約 14 GB）が重みの目安
• キャッシュは ~/.cache/huggingface/hub。場所は HF_HOME（TRANSFORMERS_CACHE は読まれない）
• オフラインは キャッシュを持ち込んで HF_HUB_OFFLINE=1、または フォルダに保存してパスで読む
• 日本語は、学習データ・トークナイザー（fugashi などの追加パッケージ）・ライセンスを確かめて選ぶ

参考・出典

確認日はいずれも 2026年10月13日です。

• Hugging Face ドキュメント「Installation」：https://huggingface.co/docs/transformers/installation
• Hugging Face ドキュメント「Pipeline」：https://huggingface.co/docs/transformers/pipeline_tutorial
• Hugging Face ドキュメント「Pipelines」（API）：https://huggingface.co/docs/transformers/main_classes/pipelines
• GitHub「transformers MIGRATION_GUIDE_V5.md」：https://github.com/huggingface/transformers/blob/main/MIGRATION_GUIDE_V5.md
• Hugging Face ドキュメント「Manage huggingface_hub cache-system」：https://huggingface.co/docs/huggingface_hub/guides/manage-cache
• Hugging Face ドキュメント「Environment variables」（huggingface_hub）：https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables
• PyPI「transformers」：https://pypi.org/project/transformers/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。