---
tags: [nanochat, tokenizer, rustbpe]
阶段: 03-分词器Tokenizer
难度: ★★★
created: 2026-10-22
related: "[[字节对编码BPE原理]], [[词表与特殊token]], [[为什么需要分词]], [[Tokenizer与BPE]]"
---

# nanochat的Rust分词器实现

## 定义

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

本篇符号约定如下。

| 符号 | 含义 |
|---|---|
| `enc` | `tiktoken.Encoding` 对象，承担全部编码与解码 |
| `mergeable_ranks` | `dict[bytes, int]`，字节串到 rank 的映射，含 256 个单字节项 |
| `tokens_offset` | 特殊 token 的 id 起点，等于 `len(mergeable_ranks)` |
| $K$ | 合并次数，nanochat 中 $K=32503$ |
| $V$ | 词表大小，$V=32768$ |
| `token_bytes` | 形状 $(V,)$ 的 int32 张量，逐 token 的原始字节数 |
| bpb | bits per byte，$\text{bpb}=\sum\text{nats}/(\ln2\cdot\sum\text{bytes})$ |

其余术语在首次出现处定义：**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

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

| 能力 | rustbpe | tiktoken |
|---|---|---|
| 从语料训练合并表 | 提供 `Tokenizer.train_from_iterator` | 不提供 |
| 取回训练用的 pattern | `get_pattern` | 不适用 |
| 取回合并表 | `get_mergeable_ranks` | 只作为构造参数 |
| 编码 | `encode`、`batch_encode` | `encode_ordinary`、`encode_ordinary_batch` |
| 单 token 解码 | `decode` | `decode_single_token_bytes` |
| 特殊 token 查询 | 无 | `encode_single_token`、`special_tokens_set` |
| 词表大小 | `vocab_size` | `n_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 行，分五步：

```python
# 第一步：用 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)`，支持字符串与字符串列表两条路径：

```python
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)`：

```python
@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` 末尾的构造逻辑如下：

```python
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` 用该张量计算：

$$
\text{bpb}=\frac{\sum_{t}\ell_{t}}{\ln 2\cdot\sum_{t}\text{token\_bytes}[y_{t}]},
$$

其中 $\ell_{t}$ 是位置 $t$ 的交叉熵（nats），$y_{t}$ 是目标 token。代码先算 `loss2d` 与 `token_bytes[y]`，对 $y<0$（`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` 安装。

## 关键直觉

> [!tip] 分词器的可移植单元是三元组
> 训练产物不是「一个模型文件」，而是 `(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` 的五步。

```python
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）：

```text
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` 为例：

```python
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])
```

```text
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`，则

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

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

### 例 3：训练、评测与产物

```bash
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` 存在说明评测口径已就绪。

## 易错点

> [!warning] 以下七条与 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 词表小实验与之同构但规模不同。
