Transformers v5 重設分詞器架構,提升透明度與模組化
Tokenization in Transformers v5: Simpler, Clearer, and More Modular
Transformers v5 將分詞器架構與訓練所得的詞彙、合併規則分離,並在類別中明確呈現正規化器等組件。相較 v4 每個模型各有 slow/fast 兩套實作,v5 改為每個模型一個檔案,預設採用 Rust-based TokenizersBackend;分詞器類別亦可直接實例化並用自有語料訓練。
文章對照 v4 與 v5,説明分離分詞器架構和訓練詞彙後,如何更直接檢查組件,並沿用模型架構訓練自訂分詞器。
Transformers v5 重新設計了 tokenizer 的運作方式。大型 tokenizer 重整把 tokenizer 架構與訓練詞彙分開(類似 PyTorch 把神經網絡架構與學習權重分開)。結果是 tokenizer 更容易檢視、客製化,也更容易從頭訓練。
重點摘要:本文説明 Transformers 中的 tokenization 如何運作,以及 v5 為何是重大重新設計:內部機制更清晰、類別階層更整潔,並採用單一快速後端。這是一份實用指南,適合想了解、客製化或訓練特定模型 tokenizer,而不再把它們當作黑箱的人。
目錄
- 甚麼是 Tokenization?
- Tokenization 流程
- Tokenization 演算法
- 使用
tokenizers,並透過transformers存取 transformers中的 Tokenizer 類別階層AutoTokenizer會自動選擇正確的 Tokenizer 類別- v5 把 Tokenizer 架構與訓練詞彙分開
- 摘要
專家請看:如果你已熟悉相關概念,想了解 v5 的改動,請前往v5 把 Tokenizer 架構與訓練詞彙分開一節。
在深入探討改動前,先快速介紹 tokenization 的作用,以及各部分如何配合。
甚麼是 tokenization?
語言模型不會直接讀取原始文字,而是處理通常稱為token ID 或輸入 ID的整數序列。Tokenization 是把原始文字轉換為這些 token ID 的過程。(可到這裏使用 tokenization 練習場,視覺化了解 tokenization。)
Tokenization 是自然語言處理和一般文字處理領域的廣泛概念。本文特別聚焦於大型語言模型(LLM)的 tokenization,並使用 transformers 和 tokenizers 函式庫。
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("HuggingFaceTB/SmolLM3-3B")
text = "Hello world"
tokens = tokenizer(text)
print(tokens["input_ids"])
# [9906, 1917]
print(tokenizer.convert_ids_to_tokens(tokens["input_ids"]))
# ['Hello', 'Ġworld']
Ġworld(上方)是一個 token,代表字元序列「 world」(包含前面的空格)。
Token 是模型可見的最小字串單位,可以是字元、單字,或像「play」或「##ing」這樣的子詞片段(「##」是一種模式,現在未完全理解也不用擔心 🤗)。詞彙表會把每個獨特 token 對應至 token ID。
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("HuggingFaceTB/SmolLM3-3B")
print(tokenizer.vocab)
# {'ÎĹÎľ': 106502, 'ĠPeel': 89694, '.languages': 91078, ...}
良好的 tokenizer 會把文字壓縮成盡可能少的 token。Token 愈少,在不增加模型規模下可用的上下文就愈多。訓練 tokenizer,歸根究柢就是為你的資料集找出最佳壓縮規則。例如,如果你處理中文語料,有時會遇上令人驚喜的結果 😉。
Tokenization 流程
Tokenization 分階段進行。每個階段都會轉換文字,再傳送至下一階段:
| 階段 | 用途 | 示例 |
|---|---|---|
| 正規化器 | 統一文字格式(轉為小寫、Unicode 正規化、清理空白) | "HELLO World" → "hello world" |
| 預先 Tokenizer | 把文字拆分為初步片段 | "hello world" → ["hello", " world"] |
| 模型 | 套用 tokenization 演算法(BPE、Unigram 等) | ["hello", " world"] → [9906, 1917] |
| 後處理器 | 加入特殊 token(BOS、EOS、padding) | [9906, 1917] → [1, 9906, 1917, 2] |
| 解碼器 | 把 token ID 轉迴文字 | [9906, 1917] → "hello world" |
每個元件都彼此獨立。你可以替換正規化器或更改演算法,無須重寫其他部分。
你可透過
_tokenizer存取 Rust 版本的 tokenizer。詳情請參閲本節。
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google/gemma-3-270m-it")
print(f"{tokenizer._tokenizer.normalizer=}")
# Replace(...)
print(f"{tokenizer._tokenizer.pre_tokenizer=}")
# Split(...)
print(f"{tokenizer._tokenizer.model=}")
# BPE(...)
print(f"{tokenizer._tokenizer.post_processor=}")
# TemplateProcessing(...)
print(f"{tokenizer._tokenizer.decoder=}")
# Sequence(decoders=[Replace(...), ByteFallback(), Fuse()])
Tokenization 演算法
現代語言模型 tokenizer 主要採用以下演算法:
- 位元組對編碼(BPE)會反覆合併出現頻率最高的字元對。這種演算法具確定性且廣泛使用。(閲讀更多BPE資訊。)
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("openai/gpt-oss-20b")
print(tokenizer._tokenizer.model)
# BPE(...)
- Unigram採用機率方法,從大型初始詞彙表中選出最可能的切分方式。相較嚴格的 BPE,這種方法更靈活。(閲讀更多Unigram資訊。)
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("google-t5/t5-base")
print(tokenizer._tokenizer.model)
# Unigram(...)
- WordPiece與 BPE 相似,但依據機率使用不同合併準則。(閲讀更多WordPiece資訊。)
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
print(tokenizer._tokenizer.model)
# WordPiece(...)
透過 transformers 使用 tokenizers
tokenizers 函式庫是以 Rust 編寫的 tokenization 引擎,速度快、效率高,而且完全不綁定任何語言模型。它處理文字與 token ID 之間的轉換機制。tokenizers 函式庫是通用工具,實作各種 tokenization 演算法,但不會實作把這些演算法連接至特定語言模型的慣例。
看看直接使用 tokenizers 函式庫搭配 SmolLM3-3B 模型時會怎樣:
from tokenizers import Tokenizer
tokenizer = Tokenizer.from_pretrained("HuggingFaceTB/SmolLM3-3B")
text = "Hello world"
encodings = tokenizer.encode(text)
print(encodings.ids)
# [9906, 1917]
print(encodings.tokens)
# ['Hello', 'Ġworld']
輸出會是原始 tokenization。你會取得 token ID 及其對應字串片段,除此以外沒有其他內容。
再看看當中缺少甚麼。SmolLM3-3B 是對話模型。與它互動時,通常會把輸入整理成包含「user」和「assistant」等角色的對話。語言模型預期以特殊格式 token 表示這些角色,但原始 tokenizers 函式庫並不理解這些概念。
如何連接原始 tokenization 與模型需求?
transformers 函式庫填補了這個缺口。它主要以模型定義函式庫聞名,但亦提供 tokenizer 抽象層,包裝原始 tokenizers 後端並加入模型感知功能。
以下是使用 transformers 包裝器進行相同 tokenization 的結果:
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("HuggingFaceTB/SmolLM3-3B")
# Format a conversation using the model's chat template
prompt = "Give me a brief explanation of gravity in simple terms."
messages = [{"role": "user", "content": prompt}]
text = tokenizer.apply_chat_template(
messages,
tokenize=False,
add_generation_prompt=True,
)
print(text)
# <|im_start|>system
# ...
# <|im_start|>user
# Give me a brief explanation of gravity in simple terms.<|im_end|>
# <|im_start|>assistant
model_inputs = tokenizer([text], add_special_tokens=False, return_tensors="pt")
請留意,<|im_start|> 和 <|im_end|> 等特殊 token 會在 tokenization 前套用至提示詞。這有助模型學習新序列的起點和終點。
transformers tokenizer 補上原始函式庫欠缺的所有功能:
- 套用聊天範本。
apply_chat_template方法會按模型預期格式整理對話,插入正確的特殊 token 和分隔符。 - 自動插入特殊 token。在模型預期位置加入序列起始和結束 token。
- 按上下文長度截斷。你可設定
truncation=True,tokenizer 便會遵守模型的最大序列長度。 - 以 padding 批次編碼。多個輸入可使用正確的 padding token 和方向補齊至相同長度。
- 輸出格式選項。你可要求輸出 PyTorch 張量(
return_tensors="pt")、NumPy 陣列等格式。
transformers實作整個 ML 社羣最常用的 tokenization API(encode、decode、convert_tokens_to_ids等)。
transformers 的 Tokenizer 類別階層
transformers 函式庫以類別階層組織 tokenizer。最上層是定義通用介面的基礎類別;其下的後端類別使用不同引擎處理實際 tokenization;底層的模型專用類別則會為特定模型配置後端。
![]() |
|---|
| transformers 內部的 Tokenizer 類別階層 |
PreTrainedTokenizerBase 為所有 tokenizer 定義通用介面
PreTrainedTokenizerBase 是 transformers 中所有 tokenizer 的抽象基礎類別,定義每個 tokenizer 都必須實作的介面。
基礎類別負責處理與 tokenization 後端無關的功能:
- 特殊 token 屬性。這裏定義
bos_token、eos_token、pad_token和unk_token等屬性,讓你存取模型用來標示序列邊界及處理未知輸入的特殊 token。 - 編碼介面。這裏定義
__call__、encode和encode_plus方法。這些方法接受文字輸入,並回傳 token ID、注意力遮罩及其他中繼資料。 - 解碼介面。
decode和batch_decode方法會把 token ID 轉迴文字。 - 序列化。
save_pretrained和from_pretrained方法負責下載正確檔案、讀取資訊,以及把 tokenizer 儲存至磁碟等工作。 - 聊天範本支援。
apply_chat_template方法位於此處,會按儲存在 tokenizer 配置中的 Jinja 範本整理對話。
transformers 中的所有 tokenizer 最終都會繼承 PreTrainedTokenizerBase。無論實際 tokenization 使用哪個後端,基礎類別都能確保行為一致。
TokenizersBackend 包裝 tokenizers 函式庫
TokenizersBackend 是大多數現代 tokenizer 的主要後端類別。它繼承自 PreTrainedTokenizerBase,並包裝以 Rust 編寫的 tokenizers 函式庫。
這個類別會在內部儲存 Rust tokenizer 物件:
class TokenizersBackend(PreTrainedTokenizerBase):
def __init__(self, tokenizer_object, ...):
self._tokenizer = tokenizer_object # The Rust tokenizer
...
呼叫 TokenizersBackend tokenizer 的編碼方法時,該類別會把實際 tokenization 工作交由 Rust 後端處理:
def _batch_encode_plus(self, batch_text_or_text_pairs, ...):
encodings = self._tokenizer.encode_batch(batch_text_or_text_pairs, ...)
...
Rust 後端負責高運算量工作,Python 包裝器則在其上加入模型感知功能。
許多模型專用 tokenizer 都會繼承 TokenizersBackend,例如:
LlamaTokenizerGemmaTokenizer
這些模型專用類別會為各自模型配置正確的詞彙、合併規則、特殊 token 和正規化設定。
PythonBackend 提供純 Python 混入類別
PythonBackend 繼承自 PreTrainedTokenizerBase,並以純 Python 實作 tokenization。此類別亦別名為 PreTrainedTokenizer。
採用純 Python 後端有以下幾個原因:
- 自訂 tokenization 邏輯。部分模型需要的 tokenization 行為不符合標準
tokenizers流程。 - 舊版相容性。較舊模型實作可能依賴 Python 特有行為。
Python 後端比 Rust 後端慢。大部分用途均建議使用以 Rust 為後端的
TokenizersBackend。
繼承 PythonBackend(或其別名 PreTrainedTokenizer)的模型專用 tokenizer,包括部分較舊或專門模型,例如:
CTRLTokenizerCanineTokenizer
SentencePieceBackend 處理 SentencePiece 模型
SentencePieceBackend 繼承自 PythonBackend,並整合 Google 的 SentencePiece 函式庫。SentencePiece 是一個獨立 tokenization 函式庫,許多模型都會使用,特別是 Google 訓練的模型。
這個後端會包裝 SentencePiece 處理器:
class SentencePieceBackend(PythonBackend):
def __init__(self, vocab_file, ...):
self.sp_model = spm.SentencePieceProcessor()
self.sp_model.Load(vocab_file)
...
採用 SentencePiece tokenization 的模型會繼承此後端,例如:
SiglipTokenizerBartphoTokenizer
SentencePiece 後端繼承自 PythonBackend,而非直接繼承自 PreTrainedTokenizerBase,因為它共用大量相同介面及 padding/截斷邏輯。
AutoTokenizer 會自動選擇正確的 tokenizer 類別
AutoTokenizer 是建議用於載入 tokenizer 的入口點。它會自動判斷指定模型應使用哪個 tokenizer 類別,並回傳該類別的實例。
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("gpt2")
在背後,AutoTokenizer 會執行以下步驟:
- 下載 tokenizer 配置。
from_pretrained方法會從 Hub(或本機目錄)擷取tokenizer_config.json。 - 識別模型類型。配置包含識別模型類型的中繼資料(例如「gpt2」、「llama」、「bert」)。
- 查找 tokenizer 類別。
AutoTokenizer會維護一個名為TOKENIZER_MAPPING_NAMES的對照,將模型類型映射至 tokenizer 類別名稱:
TOKENIZER_MAPPING_NAMES = {
"gpt2": "GPT2Tokenizer",
"llama": "LlamaTokenizer",
"bert": "BertTokenizer",
...
}
- 實例化正確類別。
AutoTokenizer會匯入相應 tokenizer 類別,並呼叫其from_pretrained方法。 - 回傳已配置的 tokenizer。你會取得完整配置、可直接使用且針對特定模型的 tokenizer。
AutoTokenizer的優點是無須知道模型採用哪個 tokenizer 類別。無論模型使用LlamaTokenizer、GPT2Tokenizer或BertTokenizer,呼叫AutoTokenizer.from_pretrained("model-name")即可。
transformers 的 tokenizer 系統採用分層架構:
| 層級 | 元件 | 職責 |
|---|---|---|
| 入口點 | AutoTokenizer |
自動選擇並實例化正確的 tokenizer 類別 |
| 模型專用 | LlamaTokenizer、GPT2Tokenizer 等 |
以模型專用的正規化器、預先 tokenizer 等架構、特殊 token 和設定配置後端 |
| 後端 | TokenizersBackend、PythonBackend、SentencePieceBackend |
使用指定引擎實作實際 tokenization |
| 基礎 | PreTrainedTokenizerBase |
定義通用介面及共用功能 |
| 引擎 | tokenizers(Rust)、SentencePiece、純 Python |
執行原始 tokenization |
v5 把 Tokenizer 架構與訓練詞彙分開
Transformers v5 最重要的改變,是重新思考 tokenizer 的定義方式。Tokenizer 現在像 PyTorch 的 nn.Module 一樣運作:先定義架構,再填入學得的參數。
v4 的問題:Tokenizer 不透明且緊密耦合
v4 中,tokenizer 是綁定預訓練檢查點檔案的黑箱。如果載入 LlamaTokenizerFast,便很難直接回答一些基本問題:
- 它使用 BPE 還是 Unigram?
- 它如何正規化文字?
- 它採用甚麼預先 tokenization 策略?
- 有哪些特殊 token,它們位於甚麼位置?
__init__ 方法沒有提供任何線索。你必須翻查序列化檔案或外部文件,才能理解 tokenizer 實際做了甚麼。
![]() |
|---|
v4 版 LlamaTokenizerFast 於 transformers 中的呈現 |
v4 也為每個模型維護兩套平行實作:
- 「慢速」Python tokenizer(
LlamaTokenizer繼承自PreTrainedTokenizer),以及 - 「快速」Rust 後端 tokenizer(
LlamaTokenizerFast繼承自PreTrainedTokenizerFast)。
這代表:
- 每個模型需要兩個檔案(例如
tokenization_llama.py和tokenization_llama_fast.py) - 數百個模型之間程式碼重複
- 慢速和快速版本的行為不一致,導致細微錯誤
- 測試套件愈來愈龐大,專門驗證慢速和快速 tokenizer 是否產生相同輸出
- 使用者不清楚應該在甚麼情況使用哪種 tokenizer
最糟的是,你無法建立空白的 tokenizer 架構。如果想用自己的數據訓練 LLaMA 風格 tokenizer,就沒有簡單方法實例化一個「空白」LLaMA tokenizer,再填入自己的詞彙和合併規則。Tokenizer 只能作為已載入的檢查點存在,不能當作可配置的範本。
v5 的方案:把架構與參數分開
v5 把 tokenizer 架構(正規化器、預先 tokenizer、模型類型、後處理器、解碼器)與訓練參數(詞彙、合併規則)分開。這與 PyTorch 把模型架構和學習權重分開的做法一致。
使用 nn.Module 時,你會先定義各層:
from torch import nn
model = nn.Sequential(
nn.Embedding(vocab_size, embed_dim),
nn.Linear(embed_dim, hidden_dim),
)
# Architecture defined; weights initialized randomly or loaded later
v5 tokenizer 採用相同模式:
from transformers import LlamaTokenizer
# Instantiate the architecture
tokenizer = LlamaTokenizer()
# Train on your own data to fill in vocab and merges
tokenizer.train(files=["my_corpus.txt"])
Tokenizer 類別現在會明確宣告自身結構。查看 v5 的 LlamaTokenizer,你可立即瞭解:
- 它採用 BPE 作為 tokenization 模型
- 它可能會在文字前加上前綴空格
- 其特殊 token(
unk、bos、eos)位於詞彙表中的特定位置 - 它不會正規化輸入文字
- 它的解碼器會把 metaspace 字元
▁替換為空格
![]() |
|---|
v5 版 LlamaTokenizer 於 transformers 中的呈現 |
在 v4 中,這些資訊都埋藏於序列化檔案,無法如此透明地檢視。
單一檔案、單一後端、單一建議路徑
v5 把每個模型原本的兩檔案系統整合為單一檔案。LlamaTokenizer 現在繼承自 TokenizersBackend,後者包裝先前以「快速」實作形式提供、現時設為預設的 Rust tokenizer。
舊有「慢速」Python 實作明確放在 PythonBackend 之下;需要 SentencePiece 的模型仍可使用 SentencePieceBackend,但以 Rust 為後端的 tokenization 是建議的預設選項。
這項改動消除了:
- 慢速/快速實作之間重複的程式碼
- 令人混淆的
Tokenizer與TokenizerFast命名方式 - 專門用來檢查慢速與快速版本是否一致的測試套件
現在使用者只有一個清晰的入口點。需要客製化的進階使用者仍可使用較低層元件,但函式庫不再迫使所有人面對兩套平行實作。
現在可從頭訓練特定模型的 tokenizer
假設你想要一個行為完全仿照 LLaMA 的 tokenizer:採用相同正規化方式、相同預先 tokenization 方法和相同 BPE 模型類型,但以特定領域語料(醫學文字、法律文件或新語言)訓練。v4 需要手動使用低階 tokenizers 函式庫原語重建 tokenizer 流程;v5 則可直接實例化架構並呼叫 train:
from transformers import LlamaTokenizer
from datasets import load_dataset
# Initialize blank tokenizer
tokenizer = LlamaTokenizer()
dataset = load_dataset("wikitext", "wikitext-2-raw-v1", split="train")
def get_training_corpus():
batch = 1000
for i in range(0, len(dataset), batch):
yield dataset[i : i + batch]["text"]
trained_tokenizer = tokenizer.train_new_from_iterator(
text_iterator=get_training_corpus(),
vocab_size=32000,
length=len(dataset),
show_progress=True,
)
trained_tokenizer.push_to_hub("my_custom_tokenizer")
tokenizer = LlamaTokenizer.from_pretrained("my_custom_tokenizer")
生成的 tokenizer 會採用你的自訂詞彙和合併規則,但處理文字的方式會與標準 LLaMA tokenizer 完全相同,包括空白處理、特殊 token 慣例和解碼行為。
| 項目 | V4 | V5 |
|---|---|---|
| 每個模型的檔案數量 | 兩個(tokenization_X.py、tokenization_X_fast.py) |
一個(tokenization_X.py) |
| 預設後端 | Python 和 Rust 分開提供 | 建議使用 Rust(TokenizersBackend) |
| 架構可見性 | 隱藏於序列化檔案 | 於類別定義中明確列出 |
| 從頭訓練 | 需要手動構建流程 | tokenizer.train(files=[...]) |
| 元件檢視 | 困難且沒有文件説明 | 直接存取屬性(tokenizer.normalizer 等) |
| 父類別 | PreTrainedTokenizer、PreTrainedTokenizerFast |
TokenizersBackend(或 SentencePieceBackend、PythonBackend) |
從「已載入檢查點形式的 tokenizer」轉向「可配置架構形式的 tokenizer」,令函式庫更模組化、更透明,也更符合從業者構建 ML 系統的思維方式。
摘要
Transformers v5 為 tokenization 帶來三項改進:
- 每個模型只需一個檔案,不再分為慢速/快速兩套實作
- 架構清晰可見,可檢視正規化器、預先 tokenizer 和解碼器
- 可訓練範本,讓你建立符合任何模型設計的自訂 tokenizer
tokenizers 與 Transformers 之間的包裝層仍然不可或缺。它補上原始 tokenization 不提供的模型感知能力、上下文長度、聊天範本和特殊 token。v5 只是讓這一層更清晰、更易客製化。
如欲進一步瞭解 tokenization,可參考以下資源:
來源:Hugging Face Blog · huggingface.co


