AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

从零构建一个 tokenizer ​

第 01 课给了你一个玩具。这一课给你一件武器。

类型： Build 语言： Python 前置要求： 阶段 10，第 01 课（Tokenizer：BPE、WordPiece、SentencePiece） 预计时间： ~90 分钟

学习目标 ​

  • 构建一个生产级 BPE tokenizer，能处理 Unicode、空白归一化和特殊 token
  • 实现字节级兜底，让 tokenizer 能编码任意输入（包括 emoji、中日韩文字和代码）而不产生未知 token
  • 加入预分词正则模式，在应用 BPE 合并之前先在词边界处切分文本
  • 在一份语料上训练自定义 tokenizer，并在多语言文本上和 tiktoken 对比其压缩比

问题背景 ​

你在第 01 课写的 BPE tokenizer 对英文文本能用。现在扔一段日语给它。或者 emoji。或者一段 tab 和空格混用的 Python 代码。

它崩了。

不是因为 BPE 错了——而是因为实现不完整。一个生产级 tokenizer 要处理任意编码的原始字节，在切分前归一化 Unicode，管理那些永远不会被合并的特殊 token，把预分词和子词切分串起来，而且要快到不会拖累一条处理 15 万亿 token 的训练流水线。

GPT-2 的 tokenizer 有 50,257 个 token。Llama 3 有 128,256 个。GPT-4 大约 100,000 个。这些不是玩具数字。这些词表背后的合并表，是在几百 GB 的文本上训练出来的，而周边那套机制——归一化、预分词、特殊 token 注入、chat 模板格式化——才是区分一个只能处理 "hello world" 的 tokenizer 和一个能处理整个互联网的 tokenizer 的关键。

你要构建的就是这套机制。

核心概念 ​

完整流水线 ​

一个生产级 tokenizer 不是单个算法。它是一条由五个阶段组成的流水线，每个阶段解决一个不同的问题。

mermaid
graph LR
    A[原始文本] --> B[归一化]
    B --> C[预分词]
    C --> D[BPE 合并]
    D --> E[特殊 token]
    E --> F[Token ID]

    style A fill:#1a1a2e,stroke:#e94560,color:#fff
    style B fill:#1a1a2e,stroke:#e94560,color:#fff
    style C fill:#1a1a2e,stroke:#e94560,color:#fff
    style D fill:#1a1a2e,stroke:#e94560,color:#fff
    style E fill:#1a1a2e,stroke:#e94560,color:#fff
    style F fill:#1a1a2e,stroke:#e94560,color:#fff

每个阶段都有具体职责：

阶段它做什么为什么重要
NormalizeNFKC Unicode，可选小写化，可选去重音"fi" 连字（U+FB01）变成 "fi"（两个字符）。没有这一步，同一个词会得到不同的 token。
Pre-Tokenize在 BPE 之前把文本切成块防止 BPE 跨词边界合并。"the cat" 永远不该产出一个 "e c" 的 token。
BPE Merge把学到的合并规则应用到字节序列上核心压缩。把原始字节变成子词 token。
Special Tokens注入 [BOS]、[EOS]、[PAD]、chat 模板标记这些 token 有固定 ID。它们从不参与 BPE 合并。模型靠它们来组织结构。
ID Mapping把 token 字符串转成整数 ID模型看到的是整数，不是字符串。

字节级 BPE ​

第 01 课的 tokenizer 在 UTF-8 字节上工作。那个选择是对的。但我们跳过了一件重要的事：当这些字节不是合法 UTF-8 时怎么办？

字节级 BPE 通过把每一个可能的字节值（0-255）都当成合法 token 来解决这个问题。你的基础词表恰好是 256 个条目。任何文件——文本、二进制、损坏的——都能被分词而不产生未知 token。

GPT-2 加了个小技巧：把每个字节映射到一个可打印的 Unicode 字符，让词表保持人类可读。在它的映射里，字节 0x20（空格）变成字符 "G"。这纯粹是为了好看。算法并不在乎。

真正的威力在于：字节级 BPE 能处理地球上的每一种语言。中文字符每个占 3 个 UTF-8 字节。日语可以是 3-4 字节。阿拉伯文、天城文、emoji——全都只是字节序列。BPE 算法在这些字节序列里找模式的方式，和它在英文 ASCII 字节里找模式的方式一模一样。

预分词 ​

在 BPE 碰你的文本之前，你需要把它切成块。这能防止合并算法造出跨词边界的 token。

GPT-2 用一个正则模式来切分文本：

'(?:[sdmt]|ll|ve|re)| ?\p{L}+| ?\p{N}+| ?[^\s\p{L}\p{N}]+|\s+(?!\S)|\s+

这个模式在缩写处切分（"don't" 变成 "don" + "'t"）、在带可选前导空格的词处、数字处、标点处和空白处切分。前导空格保留在词上——所以 "the cat" 变成 [" the", " cat"]，而不是 ["the", " ", "cat"]。

Llama 用 SentencePiece，完全跳过正则。它把原始字节流当成一条长序列，让 BPE 算法自己搞清楚边界。这更简单，但给了 BPE 更大的自由去造跨词 token。

这个选择很重要。GPT-2 的正则阻止 tokenizer 学到 "一个词结尾的 the 和下一个词开头的 the 应该合并"。SentencePiece 允许这样，有时能产出更高效的压缩，但 token 的可解释性更差。

特殊 token ​

每个生产级 tokenizer 都为结构标记保留一些 token ID：

Token用途谁在用
[BOS] / <s>序列开始Llama 3、GPT
[EOS] / </s>序列结束所有模型
[PAD]批次对齐用的填充BERT、T5
[UNK]未知 token（字节级 BPE 消除了它）BERT、WordPiece
<|im_start|>chat 消息边界起始ChatGPT、Qwen
<|im_end|>chat 消息边界结束ChatGPT、Qwen
<|user|>用户轮次标记Llama 3
<|assistant|>助手轮次标记Llama 3

特殊 token 永远不会被 BPE 切分。它们在合并算法运行之前被精确匹配出来，替换成各自的固定 ID，周围的文本则正常分词。

chat 模板 ​

这里就是大多数人犯迷糊、大多数实现出错的地方。

当你给一个 chat 模型发消息时，API 接受一个消息列表：

[
  {"role": "system", "content": "You are helpful."},
  {"role": "user", "content": "Hello"},
  {"role": "assistant", "content": "Hi there!"}
]

模型看不到 JSON。它看到的是一条扁平的 token 序列。chat 模板用特殊 token 把消息转成那条扁平序列。每个模型做法都不一样：

Llama 3:
<|begin_of_text|><|start_header_id|>system<|end_header_id|>

You are helpful.<|eot_id|><|start_header_id|>user<|end_header_id|>

Hello<|eot_id|><|start_header_id|>assistant<|end_header_id|>

Hi there!<|eot_id|>

ChatGPT:
<|im_start|>system
You are helpful.<|im_end|>
<|im_start|>user
Hello<|im_end|>
<|im_start|>assistant
Hi there!<|im_end|>

模板弄错了，模型就会产出垃圾。它是在一种确切的格式上训练出来的。任何偏差——少一个换行、换错一个 token、多一个空格——都会把输入推到训练分布之外。

速度 ​

Python 对生产级分词来说太慢了。

tiktoken（OpenAI）用 Rust 写成，带 Python 绑定。HuggingFace tokenizers 也是 Rust。SentencePiece 是 C++。这些相比纯 Python 能做到 10-100 倍加速。

举个直观的例子：为 Llama 3 预训练分词 15 万亿 token，以每秒 100 万 token（快的 Python）计，要花 174 天。以每秒 1 亿 token（Rust）计，只要 1.7 天。

你用 Python 来构建是为了理解算法。在生产里，你会用一个编译后的实现，只碰那层 Python 封装。

figure
weight-tying

动手构建 ​

第 1 步：字节级编码 ​

地基。把任意字符串转成字节序列，把每个字节映射到一个可打印字符用于展示，再把过程逆转回来。

python
def bytes_to_tokens(text):
    return list(text.encode("utf-8"))

def tokens_to_text(token_bytes):
    return bytes(token_bytes).decode("utf-8", errors="replace")

在多语言文本上测试，看看字节数：

python
texts = [
    ("English", "hello"),
    ("Chinese", "你好"),
    ("Emoji", "🔥"),
    ("Mixed", "hello你好🔥"),
]

for label, text in texts:
    b = bytes_to_tokens(text)
    print(f"{label}: {len(text)} chars -> {len(b)} bytes -> {b}")

"hello" 是 5 字节。"你好" 是 6 字节（每个字符 3 字节）。火焰 emoji 是 4 字节。字节级 tokenizer 不在乎是什么语言。字节就是字节。

第 2 步：带正则的预分词器 ​

用 GPT-2 的正则模式把文本切成块。每一块由 BPE 独立分词。

python
import re

try:
    import regex
    GPT2_PATTERN = regex.compile(
        r"""'(?:[sdmt]|ll|ve|re)| ?\p{L}+| ?\p{N}+| ?[^\s\p{L}\p{N}]+|\s+(?!\S)|\s+"""
    )
except ImportError:
    GPT2_PATTERN = re.compile(
        r"""'(?:[sdmt]|ll|ve|re)| ?[a-zA-Z]+| ?[0-9]+| ?[^\s\w]+|\s+(?!\S)|\s+"""
    )

def pre_tokenize(text):
    return [match.group() for match in GPT2_PATTERN.finditer(text)]

regex 模块支持 Unicode 属性转义（\p\{L\} 表示字母，\p\{N\} 表示数字）。标准库的 re 模块不支持，所以我们退回到 ASCII 字符类。生产级多语言 tokenizer 请装 regex。

试一下：

python
print(pre_tokenize("Hello, world! Don't stop."))
# [' Hello', ',', ' world', '!', " Don", "'t", ' stop', '.']

前导空格留在词上。缩写在撇号处切开。标点成为自己的一块。BPE 永远不会跨这些边界合并 token。

第 3 步：在字节序列上做 BPE ​

第 01 课的核心算法，但现在是在预分词后的块上独立运行。

python
from collections import Counter

def get_byte_pairs(chunks):
    pairs = Counter()
    for chunk in chunks:
        byte_seq = list(chunk.encode("utf-8"))
        for i in range(len(byte_seq) - 1):
            pairs[(byte_seq[i], byte_seq[i + 1])] += 1
    return pairs

def apply_merge(byte_seq, pair, new_id):
    merged = []
    i = 0
    while i < len(byte_seq):
        if i < len(byte_seq) - 1 and byte_seq[i] == pair[0] and byte_seq[i + 1] == pair[1]:
            merged.append(new_id)
            i += 2
        else:
            merged.append(byte_seq[i])
            i += 1
    return merged

第 4 步：特殊 token 处理 ​

特殊 token 需要精确匹配和固定 ID。它们完全绕过 BPE。

python
class SpecialTokenHandler:
    def __init__(self):
        self.special_tokens = {}
        self.pattern = None

    def add_token(self, token_str, token_id):
        self.special_tokens[token_str] = token_id
        escaped = [re.escape(t) for t in sorted(self.special_tokens.keys(), key=len, reverse=True)]
        self.pattern = re.compile("|".join(escaped))

    def split_with_specials(self, text):
        if not self.pattern:
            return [(text, False)]
        parts = []
        last_end = 0
        for match in self.pattern.finditer(text):
            if match.start() > last_end:
                parts.append((text[last_end:match.start()], False))
            parts.append((match.group(), True))
            last_end = match.end()
        if last_end < len(text):
            parts.append((text[last_end:], False))
        return parts

第 5 步：完整的 tokenizer 类 ​

把所有东西串起来：归一化、按特殊 token 切分、预分词、BPE 合并、映射到 ID。

python
import unicodedata

class ProductionTokenizer:
    def __init__(self):
        self.merges = {}
        self.vocab = {i: bytes([i]) for i in range(256)}
        self.special_handler = SpecialTokenHandler()
        self.next_id = 256

    def normalize(self, text):
        return unicodedata.normalize("NFKC", text)

    def train(self, text, num_merges):
        text = self.normalize(text)
        chunks = pre_tokenize(text)
        chunk_bytes = [list(chunk.encode("utf-8")) for chunk in chunks]

        for i in range(num_merges):
            pairs = Counter()
            for seq in chunk_bytes:
                for j in range(len(seq) - 1):
                    pairs[(seq[j], seq[j + 1])] += 1
            if not pairs:
                break
            best = max(pairs, key=pairs.get)
            new_id = self.next_id
            self.next_id += 1
            self.merges[best] = new_id
            self.vocab[new_id] = self.vocab[best[0]] + self.vocab[best[1]]
            chunk_bytes = [apply_merge(seq, best, new_id) for seq in chunk_bytes]

    def add_special_token(self, token_str):
        token_id = self.next_id
        self.next_id += 1
        self.special_handler.add_token(token_str, token_id)
        self.vocab[token_id] = token_str.encode("utf-8")
        return token_id

    def encode(self, text):
        text = self.normalize(text)
        parts = self.special_handler.split_with_specials(text)
        all_ids = []
        for part_text, is_special in parts:
            if is_special:
                all_ids.append(self.special_handler.special_tokens[part_text])
            else:
                for chunk in pre_tokenize(part_text):
                    byte_seq = list(chunk.encode("utf-8"))
                    for pair, new_id in self.merges.items():
                        byte_seq = apply_merge(byte_seq, pair, new_id)
                    all_ids.extend(byte_seq)
        return all_ids

    def decode(self, ids):
        byte_parts = []
        for token_id in ids:
            if token_id in self.vocab:
                byte_parts.append(self.vocab[token_id])
        return b"".join(byte_parts).decode("utf-8", errors="replace")

    def vocab_size(self):
        return len(self.vocab)

第 6 步：多语言测试 ​

真正的测试。把英文、中文、emoji 和代码全扔给它。

python
corpus = (
    "The quick brown fox jumps over the lazy dog. "
    "The quick brown fox runs through the forest. "
    "Machine learning models process natural language. "
    "Deep learning transforms how we build software. "
    "def train(model, data): return model.fit(data) "
    "def predict(model, x): return model(x) "
)

tok = ProductionTokenizer()
tok.train(corpus, num_merges=50)

bos = tok.add_special_token("<|begin|>")
eos = tok.add_special_token("<|end|>")

test_texts = [
    "The quick brown fox.",
    "你好世界",
    "Hello 🌍 World",
    "def foo(x): return x + 1",
    f"<|begin|>Hello<|end|>",
]

for text in test_texts:
    ids = tok.encode(text)
    decoded = tok.decode(ids)
    print(f"Input:   {text}")
    print(f"Tokens:  {len(ids)} ids")
    print(f"Decoded: {decoded}")
    print()

中文字符每个产出 3 字节。emoji 产出 4 字节。这些都没有让 tokenizer 崩溃。都没有产生未知 token。这就是字节级 BPE 的威力。

实际使用 ​

对比真实的 tokenizer ​

加载 Llama 3、GPT-4 和 Mistral 的真实 tokenizer。看看每个怎么处理同一段多语言文字。

python
import tiktoken

gpt4_enc = tiktoken.get_encoding("cl100k_base")

test_paragraph = "Machine learning is powerful. 机器学习很强大。 L'apprentissage automatique est puissant. 🤖💪"

tokens = gpt4_enc.encode(test_paragraph)
pieces = [gpt4_enc.decode([t]) for t in tokens]
print(f"GPT-4 ({len(tokens)} tokens): {pieces}")
python
from transformers import AutoTokenizer

llama_tok = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3-8B")
mistral_tok = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-v0.1")

for name, tok in [("Llama 3", llama_tok), ("Mistral", mistral_tok)]:
    tokens = tok.encode(test_paragraph)
    pieces = tok.convert_ids_to_tokens(tokens)
    print(f"{name} ({len(tokens)} tokens): {pieces[:20]}...")

同一段文本，你会看到不同的 token 数。Llama 3 的 128K 词表在合并常见模式上更激进。GPT-4 的 100K 居中。Mistral 的 32K 产出更多 token，但 embedding 层更小。

权衡始终一样：更大的词表意味着更短的序列，但更多的参数。

拿去用 ​

本节课产出一个用于构建和调试生产级 tokenizer 的 prompt。见 outputs/prompt-tokenizer-builder.md。

练习 ​

  1. 简单： 加一个 get_token_bytes(id) 方法，显示任意 token ID 的原始字节。用它检查你最常见的那些合并 token 实际代表什么。
  2. 中等： 实现 Llama 风格的预分词器，它在空白和数字处切分但保留前导空格。在同一份语料上把它的词表和 GPT-2 正则方案对比。
  3. 困难： 加一个 chat 模板方法，接受一个 \{"role": ..., "content": ...\} 消息列表，并产出 Llama 3 chat 格式的正确 token 序列。拿它和 HuggingFace 的实现对照测试。

关键术语 ​

术语人们怎么说它实际是什么
字节级 BPE"在字节上工作的 tokenizer"基础词表为 256 个字节值的 BPE——处理任意输入而不产生未知 token
预分词"BPE 之前的切分"基于正则或规则的切分，防止 BPE 跨词边界合并
NFKC 归一化"Unicode 清理"规范分解后接兼容组合——"fi" 连字变成 "fi"，全角 "Ａ" 变成 "A"
chat 模板"消息怎么变成 token"把 role/content 消息列表转成扁平 token 序列的确切格式——因模型而异，且必须匹配训练格式
特殊 token"控制 token"绕过 BPE 的保留 token ID——[BOS]、[EOS]、[PAD]、chat 标记——在合并前被精确匹配
Fertility（产出率）"每个词几个 token"输出 token 数与输入词数之比——GPT-4 对英文是 1.3，韩语是 2-3，越高意味着 context 浪费越多
tiktoken"OpenAI 的 tokenizer"带 Python 绑定的 Rust BPE 实现——比纯 Python 快 10-100 倍
合并表"那个词表"训练时学到的字节对合并的有序列表——它就是 tokenizer 学到的知识本体

延伸阅读 ​