# 自定义分词器

Tokenizer 与其学习到的词表是解耦的。这使得你可以初始化一个空的 tokenizer 用于训练，或者直接使用自定义的词表创建一个 tokenizer。底层的分词流程保持不变（normalizer、pre-tokenizer、tokenization algorithm），因此你无需从头重新构建它。

本指南将展示如何训练并创建自定义分词器。

> [!AgentPrompt]
> 帮助用户选择如何创建或调整 Transformers 分词器。首先确定他们需要训练新的词汇表、定义自定义词汇表，还是修改分词流程。使用本指南来选择相应的方案。
>
> 1. 询问语言或领域、语料库来源及规模、起始分词器、期望的词汇表大小、目标模型以及预期用途。仅当缺失的细节会影响选择时，才提出后续问题，并明确标注你的假设。 2. 选择匹配的工作流。若要为现有分词器添加令牌，对于常规令牌请使用 `add_tokens`，若需要特殊令牌行为则使用 `add_special_tokens`。如果你为与模型配对的令牌器添加令牌，请使用 `resize_token_embeddings(len(tokenizer))` 调整模型的令牌嵌入大小。对于保留现有分词器流水线的新词汇表，请使用 `train_new_from_iterator` 配合具有代表性的文本批次。对于提供的词汇表和合并规则，请检查分词器是否支持这些输入。仅当现有流水线无法表达所需行为时，才使用自定义后端。 3. 检查与目标模型的兼容性。新词汇表可能会改变令牌 ID，因此不要假设其与预训练模型的嵌入相匹配。说明模型是否需要匹配的嵌入或进一步的训练。 4. 验证结果。保存并重新加载分词器，然后在具有代表性的领域文本和特殊令牌上测试编码和解码。报告创建的文件、起始分词器、词汇表大小、测试结果以及未解决的兼容性问题。

## 训练分词器

空的 trainable tokenizer 会用新的目标词汇表替换原有词汇表。这在适应新领域（如金融）、低资源语言或代码等场景下非常有用。

创建一个空的 tokenizer 并加载一个数据集。

```py
from datasets import load_dataset
from transformers import GemmaTokenizer

tokenizer = GemmaTokenizer()
dataset = load_dataset("Josephgflowers/Finance-Instruct-500k", split="train")
```

使用 [TokenizersBackend.train_new_from_iterator()](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend.train_new_from_iterator) 方法训练分词器。该方法接受一个生成器函数，用于从数据集中返回文本块，而无需一次性将所有内容加载到内存中。`vocab_size` 参数用于设置分词器的词表大小。

```py
def batch_iterator(batch_size=1000):
    for i in range(0, len(dataset), batch_size):
        yield dataset[i : i + batch_size]["assistant"]

trained_tokenizer = tokenizer.train_new_from_iterator(
    batch_iterator(),
    vocab_size=32000,
)
encoded = trained_tokenizer("The stock market rallied today.")
print(encoded["input_ids"])
[5866, 11503, 98, 5885, 8617, 13381, 30]
```

使用 `new_special_tokens` 参数添加新的特殊标记，或使用 `special_tokens_map` 将旧的特殊标记重命名为新的特殊标记。

使用 [save_pretrained()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained) 保存新的 finance tokenizer，或使用 [push_to_hub()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 将其保存并上传到 Hub。这会生成一个 `tokenizer.json` 文件，其中包含新训练的词汇表、合并规则以及完整的流水线配置。

```py
trained_tokenizer.save_pretrained("./finance-gemma-tokenizer")
trained_tokenizer.push_to_hub("finance-gemma-tokenizer")
```

## 自定义词汇表

空的 tokenizer 支持通过 `vocab` 和 `merges` 参数使用自定义词汇表。

- `vocab` 是分词器所识别的完整 token 集合，其中每个条目将一个 token 映射到其输入 id。
- `merges` 定义了 BPE 算法应如何合并相邻的 token。

```py
from transformers import GemmaTokenizer

vocab={
    "<pad>": 0,
    "</s>": 1,
    "<s>": 2,
    "<unk>": 3,
    "<mask>": 4,
    "▁the": 5,
    "▁stock": 6,
    "▁market": 7,
    "▁": 8,
    "r": 9,
    "a": 10,
    "l": 11,
    "i": 12,
    "e": 13,
    "d": 14,
    "ra": 15,
    "li": 16,
    "lie": 17,
    "lied": 18,
    "ral": 19,
    "ralli": 20,
    "rallie": 21,
    "rallied": 22,
}
merges=[
    ("r", "a"),       # r + a → ra
    ("l", "i"),       # l + i → li
    ("li", "e"),      # li + e → lie
    ("lie", "d"),     # lie + d → lied
    ("ra", "l"),      # ra + l → ral
    ("ral", "li"),    # ral + li → ralli
    ("ralli", "e"),   # ralli + e → rallie
    ("rallie", "d"),  # rallie + d → rallied
]

tokenizer = GemmaTokenizer(vocab=vocab, merges=merges)
encoded = tokenizer("the stock market rallied")
print(encoded["input_ids"])
```

## 子类化 TokenizersBackend

Tokenizers 支持四种不同的 [后端](./fast_tokenizers#backends)。通常，你应该使用 [TokenizersBackend](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 来定义新的分词器，因为它速度更快。

> [!TIP]
> [PythonBackend](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.PythonBackend) 是一个纯 Python 分词器，不依赖 Rust、SentencePiece 或 mistral-common 等后端。只有在你构建一个无法用 Rust 后端表达的高度专用分词器时，才应使用 [PythonBackend](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.PythonBackend)。

1. 通过类属性（例如填充侧和要使用的分词算法）对 [TokenizersBackend](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.TokenizersBackend) 进行子类化。
2. 在 `__init__` 中定义分词流水线。这包括要使用的分词算法、在应用该算法之前如何切分原始文本，以及如何将 token 解码回文本。

```py
from tokenizers import Tokenizer, decoders, pre_tokenizers
from tokenizers.models import BPE
from transformers import TokenizersBackend

class NewTokenizer(TokenizersBackend):
    padding_side = "left"
    model = BPE

    def __init__(
        self,
        vocab=None,
        merges=None,
        unk_token="<unk>",
        bos_token="<s>",
        eos_token="</s>",
        pad_token="<pad>",
    ):
        self._vocab = vocab or {
            str(unk_token): 0,
            str(bos_token): 1,
            str(eos_token): 2,
            str(pad_token): 3,
        }
        self._merges = merges or []

        self._tokenizer = Tokenizer(
            BPE(vocab=self._vocab, merges=self._merges, fuse_unk=True)
        )
        self._tokenizer.pre_tokenizer = pre_tokenizers.ByteLevel(add_prefix_space=False)
        self._tokenizer.decoder = decoders.ByteLevel()

        super().__init__(
            unk_token=unk_token,
            bos_token=bos_token,
            eos_token=eos_token,
            pad_token=pad_token,
        )
```

训练或保存新的空分词器。

```py
tokenizer = NewTokenizer()

# train on new corpus
corpus = ["The stock market rallied today.", "Bond yields fell sharply."]
trained_tokenizer = tokenizer.train_new_from_iterator(corpus, vocab_size=32000)
# save tokenizer
trained_tokenizer.save_pretrained("./new-tokenizer")
```

