w wyl123ly 的博客
MD

nanochat的Rust分词器实现

24 KB 2026.10.22 原文件

nanochat的Rust分词器实现

定义

RustBPETokenizer 是 nanochat/tokenizer.py 中定义的分词器包装类:训练阶段调用 Rust 库 rustbpe 从语料构建合并表,推理阶段把同一份 pattern、合并表与特殊 token 表交给 tiktoken.Encoding 执行编码。token_bytes 是与词表等长的一维整型张量,第 个元素是 token 的原始字节数,特殊 token 记为 0。

本篇符号约定如下。

符号含义
enctiktoken.Encoding 对象,承担全部编码与解码
mergeable_ranksdict[bytes, int],字节串到 rank 的映射,含 256 个单字节项
tokens_offset特殊 token 的 id 起点,等于 len(mergeable_ranks)
合并次数,nanochat 中
词表大小,
token_bytes形状 的 int32 张量,逐 token 的原始字节数
bpbbits per byte,

其余术语在首次出现处定义:rank 是合并产物在合并表中的序号,tiktoken 用它决定合并优先级;普通编码(ordinary encoding)指不识别特殊 token 字面量的编码路径;pickle 持久化指用 Python pickle 把 tiktoken.Encoding 对象整体写入 tokenizer.pkl;换行/退化字符指不能单独构成合法 UTF-8 的字节片段被解码器替换为 U+FFFD 的现象。

为什么重要

分词器在训练与推理两侧的使用方式完全不同,性能瓶颈也不同。训练侧要执行 32503 次「统计相邻对、选最高频、改写片段」的合并步,语料规模达数亿到十亿级字符;推理侧则要在数据加载器与生成循环中反复对短文本编码,要求低延迟、可批量、可多线程。nanochat/tokenizer.py 的模块文档用一句话概括这一分工:训练用 rustbpe,推理用 tiktoken。

这一分工的直接后果是分词器的产物形态。rustbpe 训练结束后,真正需要保存的只有三样东西:预切分 pattern、合并表、特殊 token 表。train_from_iterator 把它们组装成 tiktoken.Encoding,此后所有下游代码只面向 tiktoken 的接口:nanochat/dataloader.py 调用 encode(doc_batch, prepend=bos),scripts/chat_sft.py 调用 render_conversation,nanochat/engine.py 调用 encode_special 与 decode,scripts/tok_eval.py 调用 encode 与 get_vocab_size。因此 rustbpe 的 Python 接口只需要覆盖训练,tiktoken 的接口必须覆盖编码、解码、批处理、特殊 token 与词表大小查询。

第三样产物是 token_bytes.pt。它不参与编码,但决定评测口径:没有它只能报告依赖词表大小的平均损失,无法得到跨词表可比的 bpb。scripts/tok_train.py 在保存分词器后用同一份词表生成该文件,nanochat/loss_eval.py 在验证时用它作分母,nanochat/common.get_base_dir() 决定它落在 ~/.cache/nanochat/tokenizer/。

没有这一层封装,代价是可量化的:纯 Python 的 BPE 训练在 2B 字符语料上需要数小时到数十小时,而 tok_train.py 的默认语料规模正是 2B 字符;手写编码器则要自行处理预切分、rank 合并、特殊 token 匹配与批量线程,任何一处与训练不一致都会使 bpb 静默变差。

原理与推导

1 为什么训练用 rustbpe、推理用 tiktoken

两个库的能力边界正好互补,可用接口对照表说明。

能力rustbpetiktoken
从语料训练合并表提供 Tokenizer.train_from_iterator不提供
取回训练用的 patternget_pattern不适用
取回合并表get_mergeable_ranks只作为构造参数
编码encode、batch_encodeencode_ordinary、encode_ordinary_batch
单 token 解码decodedecode_single_token_bytes
特殊 token 查询无encode_single_token、special_tokens_set
词表大小vocab_sizen_vocab

训练是唯一需要 rustbpe 的环节。train_from_iterator 的签名是 (iterator, vocab_size, buffer_size=8192, pattern=None):Python 侧只提供一个文本迭代器,Rust 侧按 buffer_size 拉取并统计,因此不需要把 2B 字符全部驻留内存,也不需要把语料预处理成文件。scripts/tok_train.py 的 text_iterator() 正是这样做的:它从 parquets_iter_batched(split="train") 逐行组取文档,按 --doc-cap 截断,累计到 --max-chars 后 return。

推理侧选择 tiktoken 的理由写在类文档里:efficient inference。tiktoken.Encoding 的编码核心是 Rust 实现,encode_ordinary_batch(text, num_threads=8) 可在多线程下处理一批文本;它同时是特殊 token 的标准实现,encode_single_token 只接受已注册的特殊 token 字面量,decode_single_token_bytes 返回原始字节。nanochat 的下游代码依赖这些具体接口,换成 rustbpe 的 encode 需要重写数据加载、对话渲染与引擎三处。

两侧共享的契约是 pattern。train_from_iterator 训练完成后调用 tokenizer.get_pattern(),而不是把 SPLIT_PATTERN 再传一次;这样训练与推理使用同一个正则对象,避免两处常量漂移。

2 train_from_iterator 逐段拆解

该方法共 20 行,分五步:

# 第一步:用 rustbpe 训练合并表
tokenizer = rustbpe.Tokenizer()
vocab_size_no_special = vocab_size - len(SPECIAL_TOKENS)
assert vocab_size_no_special >= 256, f"vocab_size_no_special must be at least 256, got {vocab_size_no_special}"
tokenizer.train_from_iterator(text_iterator, vocab_size_no_special, pattern=SPLIT_PATTERN)

# 第二步:取回 pattern 与合并表
pattern = tokenizer.get_pattern()
mergeable_ranks_list = tokenizer.get_mergeable_ranks()
mergeable_ranks = {bytes(k): v for k, v in mergeable_ranks_list}

# 第三步:特殊 token 从合并表末尾开始编号
tokens_offset = len(mergeable_ranks)
special_tokens = {name: tokens_offset + i for i, name in enumerate(SPECIAL_TOKENS)}

# 第四步:构造 tiktoken 编码器
enc = tiktoken.Encoding(
    name="rustbpe",
    pat_str=pattern,
    mergeable_ranks=mergeable_ranks,
    special_tokens=special_tokens,
)

# 第五步:包装并绑定 BOS
return cls(enc, "<|bos|>")

第一步的 vocab_size_no_special 是 32759 = 32768 − 9。rustbpe 的 vocab_size 参数包含 256 个单字节 token,因此它实际执行 32503 次合并。断言 >= 256 保证至少覆盖全部单字节;若小于 256,某些字节没有对应 token,任何包含该字节的文本都无法编码。

第二步的 get_mergeable_ranks() 返回 list[tuple[list[int], int]],每个元素是「字节值列表、rank」。bytes(k) 把字节值列表转成 bytes,从而构造 tiktoken 要求的 dict[bytes, int]。该列表包含 256 个单字节项与 32503 个合并产物,共 32759 项,rank 与 id 一致。

第三步的 tokens_offset 用 len(mergeable_ranks) 而不是常量,使特殊 token 的 id 随词表大小自动平移。special_tokens 是 dict[str, int],键为字面量,值为 id;enumerate 的顺序就是 SPECIAL_TOKENS 的顺序,因此 BOS 得到 32759,<|output_end|> 得到 32767。

第四步构造的 Encoding 中,name="rustbpe" 只是标签,不影响编码;pat_str 决定预切分;mergeable_ranks 决定合并;special_tokens 决定哪些字面量被当作单个 id。构造完成后 enc.n_vocab 等于合并表项数加特殊 token 数,即 32768。

第五步的 cls(enc, "<|bos|>") 触发 __init__,其中 self.bos_token_id = self.encode_special(bos_token),把 BOS 字面量换成 id 缓存起来,供 get_bos_token_id() 与 encode(..., prepend=...) 使用。

3 encode / decode / encode_special 的实现

encode 的签名是 encode(text, prepend=None, append=None, num_threads=8),支持字符串与字符串列表两条路径:

if prepend is not None:
    prepend_id = prepend if isinstance(prepend, int) else self.encode_special(prepend)
if isinstance(text, str):
    ids = self.enc.encode_ordinary(text)          # 不解析特殊 token 字面量
    if prepend is not None:
        ids.insert(0, prepend_id)
    if append is not None:
        ids.append(append_id)
elif isinstance(text, list):
    ids = self.enc.encode_ordinary_batch(text, num_threads=num_threads)
    for ids_row in ids:
        if prepend is not None:
            ids_row.insert(0, prepend_id)
        if append is not None:
            ids_row.append(append_id)

三个细节值得注意。其一,prepend 既接受 int 也接受字符串:数据加载器传入已缓存的 bos_token 整数,tests/test_tokenizer.py 传入 "<|bos|>" 字面量,两条路径都走 encode_special 或直接使用整数。其二,编码使用 encode_ordinary,它不识别特殊 token,因此普通文本中出现的 "<|bos|>" 会被当作 7 个普通字节编码;需要特殊 token 时必须显式调用 encode_special。其三,insert(0, ...) 需要搬移整个列表,但每个文档只做一次,相对编码本身可以忽略。

encode_special 只有一行,但带 @lru_cache(maxsize=32):

@lru_cache(maxsize=32)
def encode_special(self, text):
    return self.enc.encode_single_token(text)

缓存的意义在 SFT 数据加载路径上:render_conversation 对每条对话调用 8 次 encode_special(user/assistant 两对、python 一对、output 一对),scripts/chat_sft.py 的 refill_buffer 会连续渲染数千条对话。若每次都走 encode_single_token 的字典查找与类型检查,开销会随对话数线性累积;缓存后每个字面量只查一次。缓存上限 32 大于特殊 token 总数 9,因此不会被驱逐。

decode 直接委托 self.enc.decode(ids);decode_single_token_bytes 委托同名方法并返回原始字节。id_to_token 用 decode([id]) 取单个 token 的文本表示,仅用于调试;对不构成合法 UTF-8 的 token,该表示包含替换字符,不能用于字节统计。

类还提供 get_vocab_size(enc.n_vocab)、get_special_tokens(enc.special_tokens_set)、__call__(转发到 encode)、save(pickle 整个 enc)与 from_directory(读取 tokenizer.pkl)。from_pretrained 走另一条路径:tiktoken.get_encoding("gpt2") 或 tiktoken.get_encoding("cl100k_base"),并把 BOS 字面量设为 <|endoftext|>,用于与 GPT-2、GPT-4 词表比较压缩率。

4 token_bytes 与 bpb 的分母

scripts/tok_train.py 末尾的构造逻辑如下:

vocab_size = tokenizer.get_vocab_size()
special_ids = set(tokenizer.encode_special(s) for s in tokenizer.get_special_tokens())
token_bytes = []
for token_id in range(vocab_size):
    if token_id in special_ids:
        token_bytes.append(0)  # 特殊 token 不计入字节数
    else:
        num_bytes = len(tokenizer.decode_single_token_bytes(token_id))
        token_bytes.append(num_bytes)
token_bytes = torch.tensor(token_bytes, dtype=torch.int32, device='cpu')
with open(os.path.join(tokenizer_dir, "token_bytes.pt"), "wb") as f:
    torch.save(token_bytes, f)

两条规则必须同时成立。第一,特殊 token 记 0:它们不承载字节,若按字面量长度计入,bpb 的分母会随文档数与对话轮数变化。第二,长度取原始字节数,而不是 decode([id]) 后字符串的长度。原因是词表中有大量不能单独构成合法 UTF-8 的 token:它们是多字节字符的前缀或后缀,bytes 长度与解码后字符数不同,而 decode 会把无效序列替换为 U+FFFD,长度随之改变。

nanochat/loss_eval.py 的 evaluate_bpb 用该张量计算:

其中 是位置 的交叉熵(nats), 是目标 token。代码先算 loss2d 与 token_bytes[y],对 (ignore_index)的位置把字节数置 0 并跳过,最后跨 rank all_reduce 求和。特殊 token 的目标位置因 token_bytes=0 自然不贡献分母,同时代码用 (num_bytes2d > 0) 把它们的损失也从分子剔除。

5 线程、批与持久化

数据加载器的默认参数是 tokenizer_threads=4、tokenizer_batch_size=128:nanochat/dataloader.py 的 _document_batches 每 128 个文档成批 yield,refill_buffer 调 tokenizer.encode(doc_batch, prepend=bos_token, num_threads=tokenizer_threads),走 encode_ordinary_batch 的多线程路径。encode 自身的默认值是 8,数据加载器显式传 4,这样编码线程与训练进程的其他线程不会争抢过多核心。

持久化用 pickle 保存整个 Encoding 对象,而不是分别保存三个字段。好处是加载端只需 pickle.load,不必重建 dict;代价是 tiktoken.Encoding 的内部结构与库版本绑定,跨大版本加载可能失败或行为变化。若要长期保存,可靠做法是保存 (pattern, mergeable_ranks, special_tokens) 三元组并在加载时重新构造;nanochat 选择 pickle 是因为训练与推理在同一环境内完成。

在 nanochat 中的落地

  • nanochat/tokenizer.py 第 34 至 138 行:RustBPETokenizer 的全部方法;第 37 至 39 行的 __init__ 绑定 bos_token_id;第 41 至 61 行的 train_from_iterator;第 63 至 68 行的 from_directory;第 70 至 78 行的 from_pretrained;第 89 至 91 行的 encode_special;第 132 至 138 行的 save。
  • 同文件第 264 至 279 行:get_tokenizer() 从 ~/.cache/nanochat/tokenizer 读取,get_token_bytes() 断言 token_bytes.pt 存在后 torch.load(..., map_location=device)。
  • scripts/tok_train.py 第 44 至 58 行训练并保存,第 71 至 91 行生成 token_bytes.pt。
  • nanochat/dataloader.py 第 100 至 109 行:取 BOS、批量编码、prepend。
  • nanochat/loss_eval.py 第 8 至 64 行:evaluate_bpb 的求和与归一化。
  • pyproject.toml 依赖 rustbpe>=0.1.0、tiktoken>=0.11.0、pyarrow>=21.0.0,由 uv sync 安装。

关键直觉

分词器的可移植单元是三元组

训练产物不是「一个模型文件」,而是 (pattern, mergeable_ranks, special_tokens) 三者的组合:pattern 决定片段边界,mergeable_ranks 决定片段的合并方式,special_tokens 决定控制符号的 id。tiktoken.Encoding 与 pickle 只是这三者的运行时载体;正确性来自三者与训练时一致,而不是来自文件格式。token_bytes 则由 mergeable_ranks 与 special_tokens 派生,是评测口径的一部分,不属于编码逻辑。

例子与代码

例 1:安装 rustbpe 后的最小训练与编码

以下脚本不依赖 nanochat 仓库,只依赖 rustbpe 与 tiktoken(pip install rustbpe tiktoken,或在本仓库中 uv sync 后运行)。它完整复现 train_from_iterator 的五步。

import rustbpe, tiktoken

SPECIALS = ["<|bos|>", "<|user_start|>", "<|user_end|>", "<|assistant_start|>",
            "<|assistant_end|>", "<|python_start|>", "<|python_end|>",
            "<|output_start|>", "<|output_end|>"]
PATTERN = r"""'(?i:[sdmt]|ll|ve|re)|[^\r\n\p{L}\p{N}]?+\p{L}+|\p{N}{1,2}| ?[^\s\p{L}\p{N}]++[\r\n]*|\s*[\r\n]|\s+(?!\S)|\s+"""
corpus = ["The quick brown fox jumps over the lazy dog.",
          "hello world, hello tokenizer, hello hello hello",
          "Numbers like 12345 and unicode like naïve café 你好 should survive.",
          "def f(x):\n    return x + 1\n"] * 200

tk = rustbpe.Tokenizer()
tk.train_from_iterator(iter(corpus), 300, pattern=PATTERN)      # 300 = 256 字节 + 44 合并
ranks = {bytes(k): v for k, v in tk.get_mergeable_ranks()}
specials = {name: len(ranks) + i for i, name in enumerate(SPECIALS)}
enc = tiktoken.Encoding(name="demo", pat_str=tk.get_pattern(),
                        mergeable_ranks=ranks, special_tokens=specials)

print("ranks", len(ranks), "n_vocab", enc.n_vocab, "bos", specials["<|bos|>"])
text = "hello world"
ids = enc.encode_ordinary(text)
print("ids", ids)
print("roundtrip", enc.decode(ids) == text)
print("bos id", enc.encode_single_token("<|bos|>"))
print("plain bos literal ->", enc.encode_ordinary("<|bos|>"))
print("bytes of ids", [enc.decode_single_token_bytes(i) for i in ids])

本机运行输出(rustbpe 0.1.0、tiktoken 0.14.0、Python 3.12):

ranks 300 n_vocab 309 bos 300
ids [259, 287, 111, 114, 271]
roundtrip True
bos id 300
plain bos literal -> [60, 124, 98, 111, 115, 124, 62]
bytes of ids [b'hello', b' w', b'o', b'r', b'ld']

输出验证了四件事。ranks=300 说明 rustbpe 的 vocab_size 包含 256 个字节;n_vocab=309 说明 9 个特殊 token 追加在合并表之后;bos id=300 等于 len(ranks),与 tokens_offset 的定义一致;plain bos literal 返回 7 个字节 id,说明 encode_ordinary 不把 <|bos|> 当特殊 token。最后一行显示 hello world 被切成 hello | w | o | r | ld,切分结果完全由这 300 个 rank 决定,与 nanochat 的 32768 词表不同。

需要提醒的是语料规模。若把 corpus 减到几行,rustbpe 可能在达到 300 个 rank 之前就统计不到新的相邻对而提前停止,此时 len(ranks) < 300、n_vocab 也随之变小;nanochat 的 2B 字符语料不存在这个问题,但自造小语料时必须检查 len(ranks) 是否符合预期。

例 2:token_bytes 的构造与「原始字节」规则

tok_train.py 的循环可以直接套用到任意 tiktoken.Encoding 上。以 cl100k_base 为例:

import tiktoken

enc = tiktoken.get_encoding("cl100k_base")
special_ids = set(enc.encode_single_token(s) for s in enc.special_tokens_set)
token_bytes, bad = [], []
for i in range(enc.n_vocab):
    try:
        b = enc.decode_single_token_bytes(i)
    except KeyError:
        continue                       # cl100k 有保留槽位,需跳过
    if i in special_ids:
        token_bytes.append(0)
        continue
    token_bytes.append(len(b))
    if len(b.decode("utf-8", errors="replace")) != len(b):
        bad.append((i, b, len(b), len(b.decode("utf-8", "replace"))))
print("n_vocab", enc.n_vocab, "token_bytes 之和", sum(token_bytes), "长度不一致的 token", len(bad))
print("示例", bad[0][0], bad[0][1], "字节", bad[0][2], "字符", bad[0][3])
n_vocab 100277 token_bytes 之和 643830 长度不一致的 token 4816
示例 378 b'\xe2\x80' 字节 2 字符 1

输出说明两点。第一,4816 个 token 的字节长度与解码后字符长度不同,若用 len(decode([id])) 统计,bpb 的分母会系统性偏小。第二,cl100k_base 的特殊 token 槽位不连续,decode_single_token_bytes 对保留 id 抛 KeyError;nanochat 的词表不存在这个问题,因为特殊 token 恰好占据末尾连续的 9 个 id,可以直接按 range(vocab_size) 遍历。

有了 token_bytes,bpb 就是一次加权除法。设某验证批累计 total_nats = 1000、total_bytes = 800,则

import math
print(1000 / (math.log(2) * 800))    # 1.803

即每字节约 1.80 比特。换一个词表后 total_nats 与 total_bytes 都会变,但二者的比值在同一段验证文本上可比,这是 nanochat/loss_eval.py 存在的理由。

例 3:训练、评测与产物

uv sync --extra gpu                       # 安装 rustbpe、tiktoken、pyarrow 等依赖
python -m scripts.tok_train               # 默认 2B 字符、doc-cap 10000、词表 32768
python -m scripts.tok_eval                # 与 gpt2、cl100k_base 比较压缩率

ls ~/.cache/nanochat/tokenizer/
# tokenizer.pkl   token_bytes.pt

tok_train.py 会打印 max_chars、doc_cap、vocab_size、Training time 与 Saved tokenizer encoding to ...,然后做一次 Hello world! ... Unicode: 你好世界 的自检:encoded = tokenizer.encode(test_text)、decoded = tokenizer.decode(encoded)、assert decoded == test_text。最后打印 Saved token_bytes to ...。这三行输出是判断训练是否成功的最短检查:自检通过说明编码可逆,token_bytes.pt 存在说明评测口径已就绪。

易错点

以下七条与 repo 的具体实现一一对应

1. 只保存 mergeable_ranks 而丢失 pattern。重建 Encoding 时必须用训练时的 pat_str,否则同一文本的片段边界改变,编码结果与训练分布不符。

2. 用 encode 处理含特殊 token 字面量的文本。encode_ordinary 不识别它们,"<|bos|>" 会被拆成普通字节;必须用 encode_special 或 prepend/append 参数。

3. 用 len(decode([id])) 生成 token_bytes。不能单独构成合法 UTF-8 的 token 会被替换为 U+FFFD,字符数与字节数不等;必须用 decode_single_token_bytes。

4. 把特殊 token 计为 1 字节或按字面量长度计入。token_bytes 对特殊 token 必须记 0,否则 bpb 的分母随文档数变化。

5. 改动 SPECIAL_TOKENS 后只重训分词器而不重训模型。特殊 token 的 id 起点是 len(mergeable_ranks),词表或列表顺序变化都会平移 id,旧 checkpoint 的嵌入行整体错位。

6. 跨 tiktoken 大版本加载 tokenizer.pkl。pickle 保存的是 Encoding 对象内部结构;长期复现应保存三元组并重建。

7. 在极小语料上假设 rustbpe 一定产出 vocab_size 个 rank。语料中相邻对耗尽时训练提前停止,len(ranks) 小于请求值,n_vocab 随之变小。

关联笔记

  • 前置 字节对编码BPE原理:合并表的训练算法与预切分 pattern 的语义。
  • 前置 词表与特殊token:9 个特殊 token 的用途与 id 分配,本篇只讲它们如何写入 tiktoken.Encoding。
  • 后续 为什么需要分词:token_bytes 与 bpb 的换算关系,以及词表大小对参数与显存的影响。
  • 跨库 Tokenizer与BPE:BPE 编码算法与 tiktoken 的通用用法;本篇只写 nanochat 的双实现封装。
  • 对照 检查点与恢复:checkpoint 保存的是模型权重与 config,tokenizer.pkl 必须与之一并保留,否则恢复后 id 语义不一致。

达标检测

  • [ ] 说明 rustbpe 与 tiktoken 各自负责训练/推理的哪些步骤,列出至少三个只有 tiktoken 提供的接口。
  • [ ] 逐行解释 train_from_iterator 的五个步骤,写出 32759 与 32767 两个数字的来源。
  • [ ] 解释 assert vocab_size_no_special >= 256 的必要性,并说明去掉后哪类文本无法编码。
  • [ ] 说明 encode 中 prepend 的两种取值路径,以及 encode_ordinary 与 encode_special 的行为差异。
  • [ ] 解释 lru_cache(maxsize=32) 为什么设在 encode_special 上,缓存上限为何不需要更大。
  • [ ] 复述 token_bytes 的两条构造规则,并用 cl100k_base 的 4816 个 token 说明为什么不能用解码后的字符数。
  • [ ] 独立运行例 1 的脚本,核对 ranks、n_vocab、bos 三个数值与本文一致。

参考来源

  • Karpathy, nanochat 仓库(commit 92d63d4):nanochat/tokenizer.py、scripts/tok_train.py、nanochat/dataloader.py、nanochat/loss_eval.py、tests/test_tokenizer.py —— 对应本篇全部代码位置与默认值。
  • Karpathy, rustbpe 仓库 —— 对应第 1 节的训练接口、get_pattern、get_mergeable_ranks 与 buffer_size 参数。
  • OpenAI, tiktoken 仓库 —— 对应第 1 节的推理接口、encode_ordinary_batch 的多线程路径与 decode_single_token_bytes 的字节语义。
  • Sennrich et al., "Neural Machine Translation of Rare Words with Subword Units", arXiv:1508.07909 —— 对应第 2 节合并表训练的算法来源。
  • Karpathy, nanochat dev/LOG.md —— 对应词表与预切分粒度实验,例 1 的 300 词表小实验与之同构但规模不同。