huggingface-tokenizers

HuggingFace Tokenizers - NLP 向け高速トークナイズ

Rust のパフォーマンスと Python の使いやすさを備えた、本番環境対応の高速トークナイザーです。

HuggingFace Tokenizers を使う場面

次の場合は HuggingFace Tokenizers を使用します。

• 非常に高速なトークナイズが必要な場合（テキスト 1 GB あたり 20 秒未満）
• カスタムトークナイザーをゼロからトレーニングする場合
• アライメント追跡（トークン → 元のテキスト内の位置）が必要な場合
• 本番環境向けの NLP パイプラインを構築する場合
• 大規模なコーパスを効率的にトークナイズする必要がある場合

パフォーマンス：

• 速度：CPU で 1 GB をトークナイズするのに 20 秒未満
• 実装：Rust コアと Python／Node.js バインディング
• 効率：純粋な Python 実装より 10～100 倍高速

代わりに次を使用します。

• SentencePiece：言語に依存せず、T5／ALBERT で使用されています
• tiktoken：GPT モデル向けの OpenAI の BPE トークナイザー
• transformers AutoTokenizer：事前学習済みモデルの読み込みのみ（内部でこのライブラリを使用します）

クイックスタート

インストール

# Install tokenizers
pip install tokenizers

# With transformers integration
pip install tokenizers transformers

事前学習済みトークナイザーを読み込む

from tokenizers import Tokenizer

# Load from HuggingFace Hub
tokenizer = Tokenizer.from_pretrained("bert-base-uncased")

# Encode text
output = tokenizer.encode("Hello, how are you?")
print(output.tokens)  # ['hello', ',', 'how', 'are', 'you', '?']
print(output.ids)     # [7592, 1010, 2129, 2024, 2017, 1029]

# Decode back
text = tokenizer.decode(output.ids)
print(text)  # "hello, how are you?"

カスタム BPE トークナイザーをトレーニングする

from tokenizers import Tokenizer
from tokenizers.models import BPE
from tokenizers.trainers import BpeTrainer
from tokenizers.pre_tokenizers import Whitespace

# Initialize tokenizer with BPE model
tokenizer = Tokenizer(BPE(unk_token="[UNK]"))
tokenizer.pre_tokenizer = Whitespace()

# Configure trainer
trainer = BpeTrainer(
    vocab_size=30000,
    special_tokens=["[UNK]", "[CLS]", "[SEP]", "[PAD]", "[MASK]"],
    min_frequency=2
)

# Train on files
files = ["train.txt", "validation.txt"]
tokenizer.train(files, trainer)

# Save
tokenizer.save("my-tokenizer.json")

トレーニング時間：100 MB のコーパスで約 1～2 分、1 GB で約 10～20 分

パディングを使用したバッチエンコーディング

# Enable padding
tokenizer.enable_padding(pad_id=3, pad_token="[PAD]")

# Encode batch
texts = ["Hello world", "This is a longer sentence"]
encodings = tokenizer.encode_batch(texts)

for encoding in encodings:
    print(encoding.ids)
# [101, 7592, 2088, 102, 3, 3, 3]
# [101, 2023, 2003, 1037, 2936, 6251, 102]

トークナイズアルゴリズム

詳細、コード例、パラメーター表については、references/tokenization-algorithms.md を参照してください。この手順が該当する場合に読んでください。

トークナイズパイプライン

完全なパイプライン：正規化 → 事前トークナイズ → モデル → 後処理

正規化

テキストをクリーンアップして標準化します。

from tokenizers.normalizers import NFD, StripAccents, Lowercase, Sequence

tokenizer.normalizer = Sequence([
    NFD(),           # Unicode normalization (decompose)
    Lowercase(),     # Convert to lowercase
    StripAccents()   # Remove accents
])

# Input: "Héllo WORLD"
# After normalization: "hello world"

一般的な正規化器：

• NFD、NFC、NFKD、NFKC - Unicode 正規化形式
• Lowercase() - 小文字に変換
• StripAccents() - アクセント記号を除去（é → e）
• Strip() - 空白を除去
• Replace(pattern, content) - 正規表現による置換

事前トークナイズ

テキストを単語に似た単位に分割します。

from tokenizers.pre_tokenizers import Whitespace, Punctuation, Sequence, ByteLevel

# Split on whitespace and punctuation
tokenizer.pre_tokenizer = Sequence([
    Whitespace(),
    Punctuation()
])

# Input: "Hello, world!"
# After pre-tokenization: ["Hello", ",", "world", "!"]

一般的な事前トークナイザー：

• Whitespace() - スペース、タブ、改行で分割
• ByteLevel() - GPT-2 形式のバイトレベル分割
• Punctuation() - 句読点を分離
• Digits(individual_digits=True) - 数字を個別に分割
• Metaspace() - スペースを ▁ に置換（SentencePiece 形式）

後処理

モデル入力用の特殊トークンを追加します。

from tokenizers.processors import TemplateProcessing

# BERT-style: [CLS] sentence [SEP]
tokenizer.post_processor = TemplateProcessing(
    single="[CLS] $A [SEP]",
    pair="[CLS] $A [SEP] $B [SEP]",
    special_tokens=[
        ("[CLS]", 1),
        ("[SEP]", 2),
    ],
)

一般的なパターン：

# GPT-2: sentence <|endoftext|>
TemplateProcessing(
    single="$A <|endoftext|>",
    special_tokens=[("<|endoftext|>", 50256)]
)

# RoBERTa: <s> sentence </s>
TemplateProcessing(
    single="<s> $A </s>",
    pair="<s> $A </s> </s> $B </s>",
    special_tokens=[("<s>", 0), ("</s>", 2)]
)

アライメント追跡

元のテキスト内のトークン位置を追跡します。

output = tokenizer.encode("Hello, world!")

# Get token offsets
for token, offset in zip(output.tokens, output.offsets):
    start, end = offset
    print(f"{token:10} → [{start:2}, {end:2}): {text[start:end]!r}")

# Output:
# hello      → [ 0,  5): 'Hello'
# ,          → [ 5,  6): ','
# world      → [ 7, 12): 'world'
# !          → [12, 13): '!'

用途：

• 固有表現認識（予測結果をテキストに対応付ける）
• 質問応答（回答スパンを抽出する）
• トークン分類（ラベルを元の位置に対応付ける）

transformers との統合

AutoTokenizer で読み込む

from transformers import AutoTokenizer

# AutoTokenizer automatically uses fast tokenizers
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

# Check if using fast tokenizer
print(tokenizer.is_fast)  # True

# Access underlying tokenizers.Tokenizer
fast_tokenizer = tokenizer.backend_tokenizer
print(type(fast_tokenizer))  # <class 'tokenizers.Tokenizer'>

カスタムトークナイザーを transformers 用に変換する

from tokenizers import Tokenizer
from transformers import PreTrainedTokenizerFast

# Train custom tokenizer
tokenizer = Tokenizer(BPE())
# ... train tokenizer ...
tokenizer.save("my-tokenizer.json")

# Wrap for transformers
transformers_tokenizer = PreTrainedTokenizerFast(
    tokenizer_file="my-tokenizer.json",
    unk_token="[UNK]",
    pad_token="[PAD]",
    cls_token="[CLS]",
    sep_token="[SEP]",
    mask_token="[MASK]"
)

# Use like any transformers tokenizer
outputs = transformers_tokenizer(
    "Hello world",
    padding=True,
    truncation=True,
    max_length=512,
    return_tensors="pt"
)

一般的なパターン

イテレーターからトレーニングする（大規模データセット）

from datasets import load_dataset

# Load dataset
dataset = load_dataset("wikitext", "wikitext-103-raw-v1", split="train")

# Create batch iterator
def batch_iterator(batch_size=1000):
    for i in range(0, len(dataset), batch_size):
        yield dataset[i:i + batch_size]["text"]

# Train tokenizer
tokenizer.train_from_iterator(
    batch_iterator(),
    trainer=trainer,
    length=len(dataset)  # For progress bar
)

パフォーマンス：1 GB を約 10～20 分で処理します

切り詰めとパディングを有効にする

# Enable truncation
tokenizer.enable_truncation(max_length=512)

# Enable padding
tokenizer.enable_padding(
    pad_id=tokenizer.token_to_id("[PAD]"),
    pad_token="[PAD]",
    length=512  # Fixed length, or None for batch max
)

# Encode with both
output = tokenizer.encode("This is a long sentence that will be truncated...")
print(len(output.ids))  # 512

マルチプロセッシング

from tokenizers import Tokenizer
from multiprocessing import Pool

# Load tokenizer
tokenizer = Tokenizer.from_file("tokenizer.json")

def encode_batch(texts):
    return tokenizer.encode_batch(texts)

# Process large corpus in parallel
with Pool(8) as pool:
    # Split corpus into chunks
    chunk_size = 1000
    chunks = [corpus[i:i+chunk_size] for i in range(0, len(corpus), chunk_size)]

    # Encode in parallel
    results = pool.map(encode_batch, chunks)

高速化：8 コアで 5～8 倍

パフォーマンスベンチマーク

トレーニング速度

コーパスサイズ	BPE（語彙数 30k）	WordPiece（30k）	Unigram（8k）
10 MB	15 秒	18 秒	25 秒
100 MB	1.5 分	2 分	4 分
1 GB	15 分	20 分	40 分

ハードウェア：16 コア CPU、英語版 Wikipedia でテスト

トークナイズ速度

実装	1 GB のコーパス	スループット
純粋な Python	約 20 分	約 50 MB／分
HF Tokenizers	約 15 秒	約 4 GB／分
高速化	80 倍	80 倍

テスト：英語テキスト、平均文長 20 語

メモリ使用量

タスク	メモリ
トークナイザーを読み込む	約 10 MB
BPE をトレーニング（語彙数 30k）	約 200 MB
100 万文をエンコードする	約 500 MB

サポートされているモデル

from_pretrained() で利用できる事前学習済みトークナイザー：

BERT ファミリー：

• bert-base-uncased、bert-large-cased
• distilbert-base-uncased
• roberta-base、roberta-large

GPT ファミリー：

• gpt2、gpt2-medium、gpt2-large
• distilgpt2

T5 ファミリー：

• t5-small、t5-base、t5-large
• google/flan-t5-xxl

その他：

• facebook/bart-base、facebook/mbart-large-cc25
• albert-base-v2、albert-xlarge-v2
• xlm-roberta-base、xlm-roberta-large

すべてを閲覧：https://huggingface.co/models?library=tokenizers

参考資料

• トレーニングガイド - カスタムトークナイザーのトレーニング、トレーナーの設定、大規模データセットの処理
• アルゴリズムの詳細 - BPE、WordPiece、Unigram を詳しく解説
• パイプラインのコンポーネント - 正規化器、事前トークナイザー、後処理器、デコーダー
• Transformers との統合 - AutoTokenizer、PreTrainedTokenizerFast、特殊トークン

リソース

• ドキュメント：https://huggingface.co/docs/tokenizers
• GitHub：https://github.com/huggingface/tokenizers ⭐ 9,000+
• バージョン：0.20.0+
• コース：https://huggingface.co/learn/nlp-course/chapter6/1
• 論文：BPE（Sennrich et al., 2016）、WordPiece（Schuster & Nakajima, 2012）

エージェントの作業手順

1. 環境を確認します。 GPU の種類、メモリ、ドライバー／CUDA のバージョン（nvidia-smi）、フレームワークのバージョン、データセットの場所とサイズを確認します。
2. 入力を特定します。 データまたはユーザーから形式、識別子、パラメーターを確認します。結果が変わる値については、推測せずに質問します。
3. まず小規模な実行を行います。 スモークテストを実施します。小さなモデルまたはサブセットを使い、少ないステップで実行して、損失が減少しチェックポイントが保存されることを確認します。
4. 上記の手順と参考資料を使って、タスク全体を実行します。
5. 結果を検証します。 保留データのメトリクスを追跡し、ベースラインと比較して、シード、設定、ハードウェアを記録します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の点を説明します。

発生した問題	対処方法
CUDA のメモリ不足	バッチサイズを小さくする、勾配累積／チェックポイントまたは混合精度を有効にする、あるいはモデルをシャーディングします。
損失が NaN になる、または発散する	学習率を下げ、データに無効な値がないか確認し、勾配クリッピングを有効にします。
この手順に記載されている関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して適宜対応し、ユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計を決して捏造してはいけません。実行または検証できない場合は、そのことを明確に伝えます。
• ログなしにトレーニング結果を主張してはいけません。大規模なジョブを開始する前に、計算コストを見積もります。
• ここに記載されているバージョン固有の情報は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する、共有 GPU やクラウドのクォータを消費する、個人データや患者データを扱う、または取り消せない操作を行う前に、ユーザーに確認します。

関連スキル

• transformers：Hugging Face Transformers を使って Hub モデルを読み込み、パイプライン推論、テキスト生成、NLP、ビジョン、音声などのタスクで Trainer によるファインチューニングを実行します…
• sentencepiece：テキストを生の Unicode として扱う、言語に依存しないトークナイザーです。