跳到正文
Hugging Face Blog·· 2025-12-18精選AI 評分65

Transformers v5 重設分詞器架構,提升透明度與模組化

Tokenization in Transformers v5: Simpler, Clearer, and More Modular

AI 導讀

Transformers v5 將分詞器架構與訓練所得的詞彙、合併規則分離,並在類別中明確呈現正規化器等組件。相較 v4 每個模型各有 slow/fast 兩套實作,v5 改為每個模型一個檔案,預設採用 Rust-based TokenizersBackend;分詞器類別亦可直接實例化並用自有語料訓練。

推薦理由

文章對照 v4 與 v5,説明分離分詞器架構和訓練詞彙後,如何更直接檢查組件,並沿用模型架構訓練自訂分詞器。

正文 · 繁體中文

thumbnail

Transformers v5 重新設計了 tokenizer 的運作方式。大型 tokenizer 重整把 tokenizer 架構與訓練詞彙分開(類似 PyTorch 把神經網絡架構與學習權重分開)。結果是 tokenizer 更容易檢視、客製化,也更容易從頭訓練。

重點摘要:本文説明 Transformers 中的 tokenization 如何運作,以及 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 主要採用以下演算法:

  1. 位元組對編碼(BPE)會反覆合併出現頻率最高的字元對。這種演算法具確定性且廣泛使用。(閲讀更多BPE資訊。)
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("openai/gpt-oss-20b")
print(tokenizer._tokenizer.model)

# BPE(...)
  1. Unigram採用機率方法,從大型初始詞彙表中選出最可能的切分方式。相較嚴格的 BPE,這種方法更靈活。(閲讀更多Unigram資訊。)
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google-t5/t5-base")
print(tokenizer._tokenizer.model)

# Unigram(...)
  1. 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;底層的模型專用類別則會為特定模型配置後端。

class hierarchy
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,例如:

  • LlamaTokenizer
  • GemmaTokenizer

這些模型專用類別會為各自模型配置正確的詞彙、合併規則、特殊 token 和正規化設定。

PythonBackend 提供純 Python 混入類別

PythonBackend 繼承自 PreTrainedTokenizerBase,並以純 Python 實作 tokenization。此類別亦別名為 PreTrainedTokenizer。

採用純 Python 後端有以下幾個原因:

  • 自訂 tokenization 邏輯。部分模型需要的 tokenization 行為不符合標準 tokenizers 流程。
  • 舊版相容性。較舊模型實作可能依賴 Python 特有行為。

Python 後端比 Rust 後端慢。大部分用途均建議使用以 Rust 為後端的 TokenizersBackend。

繼承 PythonBackend(或其別名 PreTrainedTokenizer)的模型專用 tokenizer,包括部分較舊或專門模型,例如:

  • CTRLTokenizer
  • CanineTokenizer

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 的模型會繼承此後端,例如:

  • SiglipTokenizer
  • BartphoTokenizer

SentencePiece 後端繼承自 PythonBackend,而非直接繼承自 PreTrainedTokenizerBase,因為它共用大量相同介面及 padding/截斷邏輯。

AutoTokenizer 會自動選擇正確的 tokenizer 類別

AutoTokenizer 是建議用於載入 tokenizer 的入口點。它會自動判斷指定模型應使用哪個 tokenizer 類別,並回傳該類別的實例。

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("gpt2")

在背後,AutoTokenizer 會執行以下步驟:

  1. 下載 tokenizer 配置。from_pretrained 方法會從 Hub(或本機目錄)擷取 tokenizer_config.json。
  2. 識別模型類型。配置包含識別模型類型的中繼資料(例如「gpt2」、「llama」、「bert」)。
  3. 查找 tokenizer 類別。AutoTokenizer 會維護一個名為 TOKENIZER_MAPPING_NAMES 的對照,將模型類型映射至 tokenizer 類別名稱:
TOKENIZER_MAPPING_NAMES = {
    "gpt2": "GPT2Tokenizer",
    "llama": "LlamaTokenizer",
    "bert": "BertTokenizer",
    ...
}
  1. 實例化正確類別。AutoTokenizer 會匯入相應 tokenizer 類別,並呼叫其 from_pretrained 方法。
  2. 回傳已配置的 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 llama
v4 版 LlamaTokenizerFast 於 transformers 中的呈現

v4 也為每個模型維護兩套平行實作:

  1. 「慢速」Python tokenizer(LlamaTokenizer 繼承自 PreTrainedTokenizer),以及
  2. 「快速」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 llama
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 帶來三項改進:

  1. 每個模型只需一個檔案,不再分為慢速/快速兩套實作
  2. 架構清晰可見,可檢視正規化器、預先 tokenizer 和解碼器
  3. 可訓練範本,讓你建立符合任何模型設計的自訂 tokenizer

tokenizers 與 Transformers 之間的包裝層仍然不可或缺。它補上原始 tokenization 不提供的模型感知能力、上下文長度、聊天範本和特殊 token。v5 只是讓這一層更清晰、更易客製化。

如欲進一步瞭解 tokenization,可參考以下資源:

來源:Hugging Face Blog · huggingface.co