---
tags: [nanochat, tokenizer, special-token]
阶段: 03-分词器Tokenizer
难度: ★★★
created: 2026-10-22
related: "[[字节对编码BPE原理]], [[nanochat的Rust分词器实现]], [[对话数据与SmolTalk]], [[有监督微调SFT]]"
---

# 词表与特殊token

## 定义

**特殊 token**（special token）是词表中不参与 BPE 频次统计、由字面量精确匹配识别、id 固定分配在全部合并 token 之后的控制符号；nanochat 的词表由 256 个单字节符号、32503 个合并产物与 9 个特殊 token 三段拼接而成。

本篇符号约定如下。

| 符号 | 含义 |
|---|---|
| $V$ | 词表大小，nanochat 中 $V=32768$ |
| $K$ | 合并次数，$K=32503$ |
| $\mathcal{S}$ | 特殊 token 集合，$\lvert\mathcal{S}\rvert=9$ |
| $s_{i}$ | 第 $i$ 个特殊 token 的字面量，$i=0,\dots,8$ |
| $\mathrm{id}(s_{i})$ | 特殊 token 的整数 id，等于 $256+K+i$ |
| 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 布局：

1. `vocab_size_no_special = vocab_size - len(SPECIAL_TOKENS)`，32768 减 9 得 32759。
2. `tokenizer.train_from_iterator(text_iter, 32759, pattern=SPLIT_PATTERN)`，rustbpe 在这个预算内完成 32503 次合并，加上 256 个单字节 token，共 32759 个合并 token。
3. `mergeable_ranks = {bytes(k): v for k, v in tokenizer.get_mergeable_ranks()}`，得到 32759 个「字节串到 rank」的条目。
4. `tokens_offset = len(mergeable_ranks)`，即 32759；`special_tokens = {name: tokens_offset + i for i, name in enumerate(SPECIAL_TOKENS)}`。
5. `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` 表示助手消息内的一个片段：

```text
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 后，第 $i$ 条消息的角色必须是 user（$i$ 偶数）或 assistant（$i$ 奇数），否则断言失败。这排除了连续两条 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:]`，位置 $t$ 的目标是 token $t+1$，所以要用 `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]`，原因有四条：

1. 词表已经包含 BOS。新增 pad token 会把 $V$ 从 32768 改成 32769，破坏「32768 是 64 的倍数」这一对齐前提，并使旧 checkpoint 不兼容。
2. BOS 是文档起点标记，模型在预训练中见过大量「BOS + 文档」，把填充位放在行尾虽然与预训练位置不同，但至少是已学过的 token，不会引入全新的嵌入行。
3. mask 与 target 双重屏蔽。填充位置的 mask 为 0，`targets[mask_targets == 0] = -1` 已使其不参与损失；`row_lengths` 再把 `content_len-1` 之后的位置显式置 -1，作为第二道保护。
4. `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 合并、工具片段、截断五组断言。

## 关键直觉

> [!tip] 特殊 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 的数量取决于切分：

```text
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 词表的小分词器，渲染一条两轮对话，并打印序列总长与监督位置数量。

```python
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 去掉最后一条助手消息

```python
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` 这一性质不变。

## 易错点

> [!warning] 以下六条均可在 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 从合并段长度开始，$32768=256+32503+9$ 的来源。
- 后续 [[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 的来源。
