Hugging Face's logo

Transformers documentation

トークナイザー

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

トークナイザー

トークナイザーは、テキストをテンソルに変換します。このテンソルはモデルの入力となります。トークナイザーは、テキストの正規化と分割を行い、トークナイズアルゴリズムを適用し、特殊トークンを追加し、出力IDをテキストにデコードします。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer("Sphinx of black quartz, judge my vow.", return_tensors="pt")
{
    'input_ids': tensor([[     2, 235277,  82913,    576,   2656,  30407, 235269,  11490,    970,  29871, 235265]]),
    'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]])
}

このガイドでは、読み込み、エンコード、デコード、バッチ処理、および利用可能なトークナイザーバックエンドについて説明します。

トークナイザを読み込む

AutoTokenizer クラスまたはモデル固有のトークナイザークラスを使用して、トークナイザを読み込みます。

AutoTokenizer
モデル固有のトークナイザー

AutoTokenizer.from_pretrained() reads the model config, resolves the correct tokenizer class, and returns an instance of it. You don’t need to know the tokenizer class beforehand. Most tokenizers resolve to a subclass of TokenizersBackend, a fast Rust-based tokenizer from the Tokenizers library.

AutoTokenizer を使用して読み込むのが推奨される方法です。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")

エンコードとデコード

TokenizersBackend.call() メソッドは、テキストまたはテキストのバッチを input_ids、attention_mask、およびその他のモデル入力にエンコードします。また、パディング、切り詰め、特殊トークンの挿入も制御します。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer("Sphinx of black quartz, judge my vow.", return_tensors="pt")
{
    'input_ids': tensor([[     2, 235277,  82913,    576,   2656,  30407, 235269,  11490,    970,  29871, 235265]]),
    'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]])
}

TokenizersBackend.encode() はこれと似ていますが、input_ids のみを返します。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
input_ids = tokenizer.encode("Sphinx of black quartz, judge my vow.")
[2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]

TokenizersBackend.decode() は、トークン化された input_ids の単一シーケンスまたはバッチをテキストに変換します。

tokenizer.decode(input_ids)
'<bos>Sphinx of black quartz, judge my vow.'

TokenizersBackend.decode() は、トークン化時のスペースを正確に保持します。句読点の前のスペースを削除するには clean_up_tokenization_spaces を、出力から特殊トークンを除去するには skip_special_tokens を設定してください。

tokenizer.decode(input_ids, skip_special_tokens=True)
'Sphinx of black quartz, judge my vow.'

特殊トークン

特殊トークンは、シーケンス内の構造的な境界（シーケンスの開始位置やパディング位置など）を示します。各モデルは独自の特殊トークンのセットを定義しています。トークナイザーを呼び出す際に、これらが追加されます。

input_ids = tokenizer.encode("Sphinx of black quartz, judge my vow.")
[2, 235277, 82913, 576, 2656, 30407, 235269, 11490, 970, 29871, 235265]
tokenizer.decode(input_ids)
'<bos>Sphinx of black quartz, judge my vow.'

extra_special_tokens 引数を使用して、追加の命名済み特殊トークンを登録します。マルチモーダルモデルでは、これらを画像、動画、または音声のプレースホルダーとして使用します。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained(
    "google/gemma-3-4b-pt",
    extra_special_tokens={"image_token": "<image>"}
)

バッチ処理

バッチ処理では、複数のシーケンスを1回の呼び出しでトークン化します。TokenizersBackendはRustベースのバックエンドがスレッド間で処理を並列化するため、大規模なバッチをより高速に処理できます。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
    [
        "Sphinx of black quartz, judge my vow.",
        "Pack my box with five dozen liquor jugs.",
        "How vexingly quick daft zebras jump!"
    ],
    return_tensors="pt"
)

バッチ処理では、すべてのシーケンスが同じ長さである必要があります。パディングと切り詰めは、長さが異なるシーケンスを扱うための戦略です。

パディング

Paddingは、バッチ内の最長シーケンスに短めのシーケンスを合わせるために特殊トークンを付加します。Attention maskは、パディングの位置を0としてマークし、モデルがそれらを無視するようにします。padding=Trueを設定すると最長シーケンスに合わせてパディングが行われ、max_lengthを渡すと固定サイズに合わせてパディングが行われます。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
    [
        "Sphinx of black quartz, judge my vow.",
        "Pack my box with five dozen liquor jugs.",
        "How vexingly quick daft zebras jump!"
    ],
    return_tensors="pt",
    padding=True,
)
{
    'input_ids': tensor([
        [     2, 235277,  82913,    576,   2656,  30407, 235269,  11490,    970,  29871, 235265],
        [     0,      2,   6519,    970,   3741,    675,   4105,  25955,  42184, 225789, 235265],
        [     0,      2,   2299,  73378,  17844,   4320, 224463,   4949,  48977,  9902, 235341]
    ]),
    'attention_mask': tensor([
        [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
        [0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
        [0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
    ])
}

大規模言語モデルは、右側から次のトークンを予測する生成を妨げないよう、左側にパディングを行います。

切り詰め

Truncationは、シーケンスが最大長に収まるようにトークンを切り詰めます。これを有効にするには、truncation=Trueを設定し、max_lengthを指定します。

Paddingとtruncationは連携して動作します。短いシーケンスにはpaddingトークンが追加され、長いシーケンスからは末尾のトークンが削除されます。これにより、詰められた長方形のテンソルが生成されます。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer(
    [
        "Sphinx of black quartz, judge my vow.",
        "Pack my box with five dozen liquor jugs.",
        "How vexingly quick daft zebras jump!"
    ],
    return_tensors="pt",
    padding=True,
    truncation=True,
    max_length=5
)
{
    'input_ids': tensor([
        [     2, 235277,  82913,    576,   2656],
        [     2,   6519,    970,   3741,    675],
        [     2,   2299,  73378,  17844,   4320]
    ]),
    'attention_mask': tensor([
        [1, 1, 1, 1, 1],
        [1, 1, 1, 1, 1],
        [1, 1, 1, 1, 1]
    ])
}

バックエンド

各モデルのトークナイザーは単一のファイルで定義され、4つのトークナイズバックエンドをサポートしています。

バックエンド実装説明
TokenizersBackendトークナイザーほとんどのモデルのデフォルト
SentencePieceBackendSentencePieceSentencePieceを必要とするモデル
PythonBackendPython特殊なカスタムトークナイザーを必要とするモデル
MistralCommonBackendmistral-commonMistral と Pixtral モデル

すべてのバックエンドは PreTrainedTokenizerBase を継承しており、エンコード、デコード、パディング、切り詰め、保存、読み込みの API を共有しています。違いは、その下で実行されるトークナイズ処理パイプラインです。

AutoTokenizer は、from_pretrained() を呼び出す際に、利用可能な最適なバックエンドを選択します。

  1. tokenizer_class フィールドのために、tokenizer_config.json ファイルを読み取ります。
  2. レジストリはtokenizer_classをクラス名に一致させます。解決されたクラスは、4つのバックエンドのいずれかを継承します。例えば、GemmaTokenizerはTokenizersBackendを継承し、SiglipTokenizerはSentencePieceBackendを継承します。 GLMのような一部のモデルは、tokenizer.jsonファイルがパイプラインを完全に記述しているため、TokenizersBackendに直接マッピングされます。GemmaTokenizerは、tokenizer.jsonでは表現できない追加のモデル固有の設定をPythonで定義しているため、サブクラスとして存在します。 mistral-commonのようなバックエンドがインストールされていない場合、AutoTokenizerはTokenizersBackendにフォールバックします。

TokenizersBackend へのフォールバック

一部のモデルには専用のトークナイザークラスがなく、また一部のチェックポイントには、実際のtokenizer.jsonファイルと一致しないtokenizer_classが含まれています。AutoTokenizerは、汎用的なTokenizersBackendを通じてtokenizer.jsonからパイプラインを読み込むことで、これらの両方のケースに対応します。Hubからのクラス名よりもシリアライズされたトークナイザーを優先するため、tokenizer_classの不一致によって誤ったトークンIDが生成されるような問題を修正できます。

チェックポイントが汎用のTokenizersBackendに解決されるのは、以下の3つの理由のいずれかです。

理由動作例
専用のトークナイザークラスはありませんモデルタイプは、tokenizer.json がパイプラインを完全に記述しているため、そのまま TokenizersBackend にマッピングされます。GLM、Granite、OLMo 2、GPT BigCode
Hubのトークナイザークラスが誤って認識されているHub に記録されている tokenizer_class がモデルタイプに対して誤っているため、AutoTokenizer はこれを無視し、代わりに tokenizer.json を読み込みます。DeepSeek V3、LLaVA、Qwen2、ModernBERT
特定のチェックポイントの上書きHub の設定がまだ修正が必要なチェックポイントは、モデル ID で一致させられ、バックエンドに強制適用されます。deepseek-ai/DeepSeek-R1-Distill-*, Salesforce/blip2-*, google/umt5-small

設定が Hub 上で修正されるにつれて、影響を受けるモデルタイプとチェックポイントの数は増加していきます。現在のセットについては、tokenization_auto.py 内の MODELS_WITH_INCORRECT_HUB_TOKENIZER_CLASS および MODEL_IDS_TO_TOKENIZERS_BACKEND の定義を参照してください。

フォールバックは自動で行われ、from_pretrained()の呼び出し方法は変更されません。生成されるトークナイザーは、tokenizer.jsonで指定されたとおりにエンコードおよびデコードを行います。

backendプロパティを使用して、トークナイザーがどのバックエンドを使用しているかを確認できます。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
tokenizer.backend
'tokenizers'

トークナイザーのアーキテクチャを確認する

_tokenizer 属性を使用して、トークナイザーの内部コンポーネント（normalizer、pre-tokenizer、model、decoder）を調べます。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google/gemma-2-2b")
print(tokenizer._tokenizer.normalizer)
print(tokenizer._tokenizer.pre_tokenizer)
print(tokenizer._tokenizer.model)
print(tokenizer._tokenizer.decoder)

リソース

Update on GitHub

←レガシーモデルの貢献 トークナイザーのカスタマイズ→