词表与特殊token
定义
特殊 token(special token)是词表中不参与 BPE 频次统计、由字面量精确匹配识别、id 固定分配在全部合并 token 之后的控制符号;nanochat 的词表由 256 个单字节符号、32503 个合并产物与 9 个特殊 token 三段拼接而成。
本篇符号约定如下。
| 符号 | 含义 | ||
|---|---|---|---|
| 词表大小,nanochat 中 | |||
| 合并次数, | |||
| 特殊 token 集合, | |||
| 第 个特殊 token 的字面量, | |||
| 特殊 token 的整数 id,等于 | |||
| mask | 与 token 序列等长的 0/1 序列,1 表示该位置参与损失 | ||
| BOS | Beginning of Sequence,`< | bos | >`,文档或对话的起点标记 |
其余术语在首次出现处定义:词表两段结构指「合并 token 段」与「特殊 token 段」的 id 区间划分;chat 协议指用成对特殊 token 把角色与内容分隔开的固定 token 布局;对话渲染(render)指把结构化消息列表转换为 id 序列与 mask 的函数;填充(padding)指把不足一个训练行的对话补齐到行长;停止符指生成过程中使当前行结束的 token id。
为什么重要
特殊 token 是模型看到的唯一结构信号。预训练阶段模型只见到 BOS + 文档,因此它学到的是「BOS 之后开始一篇新文档」;SFT 阶段模型见到 BOS + user_start + ... + assistant_end,学到的是「在 assistant_start 之后生成回答、在 assistant_end 停止」。这两件事都由固定 id 承载,而 id 由词表拼接顺序唯一确定,一旦改变顺序,旧 checkpoint 的嵌入行会整体错位。
在 nanochat 的流水线中,特殊 token 出现在五处:nanochat/tokenizer.py 的 SPECIAL_TOKENS 定义与 id 分配;nanochat/dataloader.py 的 prepend=bos_token;scripts/chat_sft.py 的 render_conversation 与 BOS 填充;nanochat/engine.py 的工具调用状态机与停止条件;scripts/chat_cli.py 的对话拼接。任何一处的 id 与训练时不一致,表现都不是报错,而是生成质量下降或对话无法终止。
缺少这 9 个 token 的后果是具体的:没有 BOS 就无法在预训练中分隔文档,跨文档注意力会产生虚假依赖;没有 user/assistant 标记,SFT 数据无法区分「谁说的话」,模型会把用户问题也当作要预测的目标;没有 python/output 标记,工具调用的代码与解释器返回无法区分,模型会学习预测解释器的输出;没有 assistant_end,生成过程没有停止条件。
特殊 token 还影响评测。scripts/tok_train.py 末尾构造 token_bytes 时把特殊 token 记为 0 字节,nanochat/loss_eval.py 据此把它们排除在 bpb 的分母之外。若把 BOS 按 1 字节计入,bpb 会随文档数量而非内容变化,跨数据集不可比。
原理与推导
1 词表的两段结构与 id 分配
RustBPETokenizer.train_from_iterator 的顺序决定了 id 布局:
vocab_size_no_special = vocab_size - len(SPECIAL_TOKENS),32768 减 9 得 32759。tokenizer.train_from_iterator(text_iter, 32759, pattern=SPLIT_PATTERN),rustbpe 在这个预算内完成 32503 次合并,加上 256 个单字节 token,共 32759 个合并 token。mergeable_ranks = {bytes(k): v for k, v in tokenizer.get_mergeable_ranks()},得到 32759 个「字节串到 rank」的条目。tokens_offset = len(mergeable_ranks),即 32759;special_tokens = {name: tokens_offset + i for i, name in enumerate(SPECIAL_TOKENS)}。tiktoken.Encoding(name="rustbpe", pat_str=pattern, mergeable_ranks=..., special_tokens=...),构造出n_vocab=32768的编码器。
因此 id 区间为:
| 区间 | 大小 | 内容 | id 范围 |
|---|---|---|---|
| 第一段 | 256 | 单字节 token | 0–255 |
| 第二段 | 32503 | BPE 合并产物 | 256–32758 |
| 第三段 | 9 | 特殊 token | 32759–32767 |
这两段的顺序不可交换。tiktoken 要求 mergeable_ranks 覆盖全部单字节,否则某些字节无法编码;train_from_iterator 的断言 vocab_size_no_special >= 256 正是对此的检查。特殊 token 编号从合并段的长度开始,因此「特殊 token 的 id = 256 + 合并次数 + 序号」这一关系在任何词表大小下都成立。
2 九个特殊 token 的用途与顺序
SPECIAL_TOKENS 的顺序是 BOS 在前,随后按对话角色与工具边界成对排列:
| id | 字面量 | 用途 | 出现阶段 | ||
|---|---|---|---|---|---|
| 32759 | `< | bos | >` | 文档起点、对话起点、推理停止符 | 预训练、SFT、推理 |
| 32760 | `< | user_start | >` | 用户消息开始 | SFT、推理 |
| 32761 | `< | user_end | >` | 用户消息结束 | SFT、推理 |
| 32762 | `< | assistant_start | >` | 助手消息开始;RL 中作为待补全的起点 | SFT、RL、推理 |
| 32763 | `< | assistant_end | >` | 助手消息结束、推理停止符 | SFT、RL、推理 |
| 32764 | `< | python_start | >` | 工具调用代码开始 | SFT、推理 |
| 32765 | `< | python_end | >` | 工具调用代码结束 | SFT、推理 |
| 32766 | `< | output_start | >` | 解释器输出开始 | SFT、推理 |
| 32767 | `< | output_end | >` | 解释器输出结束 | SFT、推理 |
顺序本身不携带语义,模型只依赖 id 的一致性。把 BOS 放在第一位的原因是它在预训练阶段就要使用,而其余 8 个只在 SFT 与推理中使用;把 user 与 assistant 成对相邻排列,使 render_conversation 中的 user_start, user_end = encode_special(...) 这类成对取用更不易出错。
有一个历史命名需要区分。from_pretrained 分支加载 GPT-2 或 cl100k_base 时,传入的 BOS 字面量是 <|endoftext|>,因为这两个词表用该符号作文档分隔符;nanochat 自己的词表命名为 <|bos|>,取 Beginning of Sequence 之意。RustBPETokenizer.from_pretrained 的注释说明了两者的对应关系:同一个符号在历史上常被称为 endoftext,但在 nanochat 中它几乎总是被前置到序列开头,因此改称 BOS。
3 BOS 的三种角色
预训练阶段,nanochat/dataloader.py 的 tokenizing_distributed_data_loader_with_state_bos_bestfit 在 refill_buffer 中调用 tokenizer.encode(doc_batch, prepend=bos_token, num_threads=tokenizer_threads),因此每个文档的第一个 token 都是 BOS。best-fit 打包把多个文档拼进同一行时,每个文档仍带自己的 BOS,模型据此知道「新文档从这里开始」;每行的第一个 token 也必然是 BOS。BOS 在 token_bytes 中记为 0 字节,bpb 不计它。
SFT 阶段,render_conversation 的第一行是 add_tokens(bos, 0):对话以 BOS 开头,mask 为 0,即不作为预测目标。填充时同样使用 BOS:scripts/chat_sft.py 在找不到可完整放入的对话后执行 row.extend([bos_token] remaining) 与 mask_row.extend([0] remaining),并用 row_lengths 记录真实内容长度,之后把 targets[i, content_len-1:] 置为 -1。
推理阶段,scripts/chat_cli.py 用 conversation_tokens = [bos] 初始化,之后每轮追加 user_start、用户内容、user_end、assistant_start,再交给 Engine。nanochat/engine.py 在 generate 中把 assistant_end 与 bos 都作为行结束标记:if next_token == assistant_end or next_token == bos: state.completed = True。因此 BOS 既是起点也是可采样的停止符;模型在无话可说时输出 BOS 结束当前行,这是预训练中「BOS 表示文档边界」的直接延伸。
4 chat 协议的 token 布局
对话被渲染为如下布局,其中 text 表示普通内容 token,part 表示助手消息内的一个片段:
conversation := BOS turn+
turn := user_turn assistant_turn
user_turn := <|user_start|> text <|user_end|>
assistant_turn := <|assistant_start|> part* <|assistant_end|>
part := text
| <|python_start|> code <|python_end|>
| <|output_start|> result <|output_end|>
该布局有三个由代码强制的性质:
- system message 不单独占用标记。
render_conversation检测到messages[0]["role"] == "system"时,断言第二条必须是 user,把 system 内容与 user 内容用"\n\n"拼接后放入同一条 user 消息,然后丢弃 system 项。tests/test_tokenizer.py的test_render_conversation_system_message_merged断言「带 system 的两条消息」与「把 system 手动拼进 user 的两条消息」渲染结果完全相同。 - 角色必须严格交替。去掉 system 后,第 条消息的角色必须是 user( 偶数)或 assistant( 奇数),否则断言失败。这排除了连续两条 user 消息、对话以 assistant 开头等不符合训练分布的数据。
- 助手消息可以是字符串或片段列表。字符串内容整体 mask=1;列表内容按
part["type"]分派:text与python的代码与定界符 mask=1,python_output的内容与定界符 mask=0。
RL 阶段使用 render_for_completion:它复制对话、断言最后一条是 assistant、弹出该条,再用 render_conversation 渲染剩余部分,最后追加一个 assistant_start。得到的序列以 assistant_start 结尾,作为待补全的提示;scripts/chat_rl.py 的两处调用都依赖这个性质。
5 render_conversation 的 mask 规则
render_conversation 返回等长的 ids 与 mask,规则可以逐条列出:
| 片段 | mask | 理由 | ||||
|---|---|---|---|---|---|---|
| BOS | 0 | 文档分隔符不是要预测的内容 | ||||
| `< | user_start | >、用户内容、< | user_end | >` | 0 | 用户输入不由模型生成 |
| `< | assistant_start | >` | 0 | 它是提示的一部分,模型从它之后开始生成 | ||
| 助手字符串内容 | 1 | 模型要生成的内容 | ||||
| `< | assistant_end | >` | 1 | 必须监督,否则模型学不会停止 | ||
| `< | python_start | >、代码、< | python_end | >` | 1 | 工具调用是模型生成的 |
| `< | output_start | >、输出、< | output_end | >` | 0 | 输出由解释器产生,测试时来自外部 |
| 填充 BOS | 0 | 不参与损失 |
scripts/chat_sft.py 把 mask 右移一位对齐 target:mask_targets = mask_tensor[:, 1:],targets[mask_targets == 0] = -1。因为输入是 batch[:, :-1]、目标是 batch[:, 1:],位置 的目标是 token ,所以要用 mask[1:] 而不是 mask。这是该文件中最容易写错的一行。
render_conversation(conversation, max_tokens=2048) 最后对 ids 与 mask 同时截断到 max_tokens。截断可能切断一个对话,使序列不以 assistant_end 结尾;在 SFT 中这会让最后一条助手消息的结尾失去监督信号,但因为 mask 同步截断,损失仍然只落在实际存在的位置上。
6 padding 为什么用 BOS
chat_sft.py 的 SFT 打包与预训练的 best-fit 不同:预训练在放不下时裁剪文档,SFT 在放不下时填充,以保证「不丢弃任何对话 token」。填充 token 选 BOS 而不是新增 [PAD],原因有四条:
- 词表已经包含 BOS。新增 pad token 会把 从 32768 改成 32769,破坏「32768 是 64 的倍数」这一对齐前提,并使旧 checkpoint 不兼容。
- BOS 是文档起点标记,模型在预训练中见过大量「BOS + 文档」,把填充位放在行尾虽然与预训练位置不同,但至少是已学过的 token,不会引入全新的嵌入行。
- mask 与 target 双重屏蔽。填充位置的 mask 为 0,
targets[mask_targets == 0] = -1已使其不参与损失;row_lengths再把content_len-1之后的位置显式置 -1,作为第二道保护。 token_bytes[bos] = 0,bpb 的分母不受填充长度影响。
风险在于第 3 条必须两处都正确。若只填充 BOS 而忘记把 mask 置 0,模型会被训练去预测一串 BOS;若 mask 正确但 row_lengths 的偏移写错,例如写成 content_len,则第一个填充目标位置(目标索引 content_len-1)不会被显式屏蔽,不过该位置属于 padding、mask 为 0,targets[mask==0] 仍会兜底。真正会误伤最后一个真实目标的偏移是 content_len-2,它会从倒数第二个真实目标开始屏蔽,表现为损失下降但模型不收敛。
在 nanochat 中的落地
nanochat/tokenizer.py顶部的SPECIAL_TOKENS:九个字面量与注释,注释明确说明 BOS 用于分隔文档,其余八个只在 SFT 渲染对话时使用。- 同文件的
RustBPETokenizer.train_from_iterator:tokens_offset = len(mergeable_ranks)与special_tokens = {name: tokens_offset + i ...},这是 id 分配的唯一来源。 - 同文件的
render_conversation:system 合并、交替断言、片段分派、截断。 - 同文件的
render_for_completion:弹出末条 assistant 消息并追加assistant_start。 scripts/chat_sft.py的sft_data_generator_bos_bestfit:SFT 数据生成器,best-fit 打包、BOS 填充、mask[1:]对齐、row_lengths二次屏蔽。nanochat/engine.py的Engine.generate与其内部的get_special:取特殊 token;状态机在采样到python_start时进入代码块、采样到python_end时执行并把结果以output_start ... output_end强制送回。tests/test_tokenizer.py的test_render_conversation与test_render_for_completion:mask、system 合并、工具片段、截断五组断言。
关键直觉
特殊 token 是条件,不是内容
特殊 token 不承载字节,因此在
token_bytes中记 0 字节,也不进入 bpb 的分母;模型对它们的学习目标是「在这个标记之后应输出什么分布」,标记本身是条件而不是被预测的内容。严格定义中的 id 分配规则,把这一语义固定为「合并段之后按下标连续编号」:顺序不影响模型行为,但一旦被写进 checkpoint 就不能改,因为嵌入矩阵的行号与 id 一一对应。
例子与代码
例 1:一段带工具调用的对话渲染
输入对话为:system 内容 "You are a helpful assistant.";user 内容 "What is 2+2?";assistant 内容由四个片段组成:文本 "Let me compute."、python 代码 "2+2"、python_output "4"、文本 "It is 4."。
在 32768 词表配置下,渲染结果为下表。内容 token 的具体 id 取决于合并表,因此只标注数量与 mask;特殊 token 的 id 是确定的。
| 序号 | 片段 | id | mask |
|---|---|---|---|
| 1 | BOS | 32759 | 0 |
| 2 | user_start | 32760 | 0 |
| 3 | "You are a helpful assistant.\n\nWhat is 2+2?" 的内容 token | 若干 | 0 |
| 4 | user_end | 32761 | 0 |
| 5 | assistant_start | 32762 | 0 |
| 6 | "Let me compute." 的内容 token | 若干 | 1 |
| 7 | python_start | 32764 | 1 |
| 8 | "2+2" 的内容 token | 若干 | 1 |
| 9 | python_end | 32765 | 1 |
| 10 | output_start | 32766 | 0 |
| 11 | "4" 的内容 token | 若干 | 0 |
| 12 | output_end | 32767 | 0 |
| 13 | "It is 4." 的内容 token | 若干 | 1 |
| 14 | assistant_end | 32763 | 1 |
写成 id 序列的骨架,… 表示该段内容 token 的数量取决于切分:
32759 | 32760 | … | 32761 | 32762 | … | 32764 | … | 32765 | 32766 | … | 32767 | … | 32763
mask: 0 0 … 0 0 … 1 … 1 0 … 0 … 1
该序列有三个可检查的特征:BOS 与全部定界符的 mask 为 0,助手侧内容与 python 定界符为 1,output 段整段为 0。注意 output_start 与 output_end 本身也是 mask=0:它们出现在训练数据中,但由推理时的状态机强制插入,模型不需要生成它们。
例 2:用断言验证 mask 结构
以下代码与 tests/test_tokenizer.py 的测试同构,在 uv sync 后的环境中可直接运行。它训练一个 300 词表的小分词器,渲染一条两轮对话,并打印序列总长与监督位置数量。
import tiktoken, rustbpe
from nanochat.tokenizer import RustBPETokenizer, SPECIAL_TOKENS, SPLIT_PATTERN
corpus = ["hello world", "the quick brown fox", "what is 2+2?", "it is 4"] * 50
tk = rustbpe.Tokenizer()
tk.train_from_iterator(iter(corpus), 300, pattern=SPLIT_PATTERN)
ranks = {bytes(k): v for k, v in tk.get_mergeable_ranks()}
specials = {name: len(ranks) + i for i, name in enumerate(SPECIAL_TOKENS)}
enc = tiktoken.Encoding(name="demo", pat_str=tk.get_pattern(), mergeable_ranks=ranks, special_tokens=specials)
tok = RustBPETokenizer(enc, "<|bos|>")
conv = {"messages": [
{"role": "user", "content": "hi"},
{"role": "assistant", "content": "hello"},
{"role": "user", "content": "bye"},
{"role": "assistant", "content": "later"},
]}
ids, mask = tok.render_conversation(conv)
assert ids[0] == tok.get_bos_token_id() and mask[0] == 0
assistant_end = tok.encode_special("<|assistant_end|>")
supervised = [i for i, m in zip(ids, mask) if m == 1]
expected = tok.encode("hello") + [assistant_end] + tok.encode("later") + [assistant_end]
assert supervised == expected
print("总长", len(ids), "监督位置", sum(mask))
该测试的全部断言在 repo 中已有对应实现:supervised == expected 说明只有助手内容与 assistant_end 被监督;mask[ids.index(python_start)] == 1 说明工具调用被监督;mask[start:end+1] 全为 0 说明解释器输出不被监督。断言比数字更可靠,因为词表 id 会随训练语料变化。本机以 rustbpe 0.1.0、tiktoken 0.14.0 运行同一语料,得到 285 个 rank,输出为 总长 19 监督位置 7;具体数值随合并表变化,但 supervised == expected 这一关系与词表大小无关。
例 3:render_for_completion 去掉最后一条助手消息
conv = {"messages": [
{"role": "user", "content": "hi"},
{"role": "assistant", "content": "this gets stripped"},
]}
ids = tok.render_for_completion(conv)
assert ids[-1] == tok.encode_special("<|assistant_start|>") # 以提示生成起点结尾
stripped = tok.encode("this gets stripped")
assert not any(ids[i:i + len(stripped)] == stripped for i in range(len(ids)))
print("长度", len(ids), "末位", ids[-1])
与 render_conversation 的区别是:render_for_completion 不返回 mask,因为 RL 只关心采样出的补全,损失由奖励而非逐 token 监督决定。该函数在 scripts/chat_rl.py 中被用来构造 rollout 的初始提示。本机实测该序列长度为 6、末位为 288,即 assistant_start 的 id 等于 285 个 rank 加下标 3;长度随词表与内容变化,末位是 assistant_start 这一性质不变。
易错点
以下六条均可在 repo 中找到对应实现
1. 把特殊 token 当普通文本编码。
tokenizer.encode("<|bos|>")走encode_ordinary,返回多个普通 token 而不是 1 个特殊 id;必须用encode_special或encode(..., prepend="<|bos|>")。tests/test_tokenizer.py的test_special_tokens断言了这一点。2. 改动
SPECIAL_TOKENS的顺序而不重训 tokenizer 与模型。id 随下标平移,旧 checkpoint 中所有特殊 token 的嵌入行错位,表现为对话格式崩坏而非报错。3. system message 不在首位或后面不接 user。
render_conversation的assert messages[1]["role"] == "user"会直接失败;把 system 插到对话中间不会报错,但会被当作普通 assistant 或 user 内容渲染。4. 给
python_output片段设 mask=1。解释器输出在测试时由外部产生,模型无法预测,监督它会教模型编造输出;repo 对该片段及其定界符统一设 0。5. 填充用 BOS 但忘记屏蔽。
chat_sft.py需要三件事同时正确:row.extend([bos_token] remaining)、mask_row.extend([0] remaining)、targets[i, content_len-1:] = -1。6. 以为
assistant_end不需要监督。它是停止条件,mask=0 会导致模型永不停止;repo 对assistant_end设 mask=1。
关联笔记
- 前置 字节对编码BPE原理:特殊 token 的 id 从合并段长度开始, 的来源。
- 后续 nanochat的Rust分词器实现:
SPECIAL_TOKENS如何被写入tiktoken.Encoding,以及encode_special的lru_cache。 - 后续 对话数据与SmolTalk:SmolTalk 的对话如何满足交替与 system 合并假设。
- 后续 有监督微调SFT:mask 与 BOS 填充在训练循环中的消费方式。
- 跨库 指令微调SFT:通用 SFT 的损失掩码与对话模板;本篇只写 nanochat 的 9 个特殊 token 与渲染规则。
达标检测
- [ ] 写出 9 个特殊 token 的字面量、id 与用途,并说明 32759 这个偏移量如何由词表大小推出。
- [ ] 说明 BOS 在预训练、SFT、推理三种场景中的不同作用,各给出对应的 repo 文件与函数。
- [ ] 画出「system + user + 带 python 工具调用的 assistant」渲染后的 id 序列骨架,并标注每个位置的 mask。
- [ ] 解释 system message 合并的实现细节(
deepcopy、"\n\n"拼接、messages[1:])以及不合并会破坏哪条断言。 - [ ] 说明 SFT 打包为什么用 BOS 填充而不是新增 pad token,列出四条理由与对应的代码行。
- [ ] 解释
targets[mask_targets == 0] = -1为什么用mask[1:]而不是mask,错位后会发生什么。 - [ ] 复述
render_for_completion与render_conversation的两处差异及其在 RL 中的用途。
参考来源
- Karpathy, nanochat 仓库(commit 92d63d4):
nanochat/tokenizer.py(SPECIAL_TOKENS、render_conversation、render_for_completion)、scripts/chat_sft.py(打包与掩码)、nanochat/engine.py(工具状态机)—— 对应本篇全部代码位置。 tests/test_tokenizer.py(同仓库)—— 对应第 5 节的 mask 规则与例 2、例 3 的断言。- OpenAI, tiktoken 仓库 —— 对应
tiktoken.Encoding的special_tokens参数与encode_ordinary不识别特殊 token 的行为。 - Radford et al., "Language Models are Unsupervised Multitask Learners", 2019 —— 对应
<|endoftext|>作为文档分隔符的历史用法,nanochat 将其更名为<|bos|>。 - SmolLM 团队, "SmolLM2"(arXiv:2502.02737)与 HuggingFace SmolTalk 数据集 —— 对应 SFT 对话格式与 system message 的来源。