| # Tokenizer 深度讲解 |
|
|
| > 本仓库 `src/trainers/lm/train_tokenizer.py` 的 tokenizer 训练实现，覆盖 BPE 原理、特殊 token 体系、配置文件结构 |
| |
| ## 0. Tokenizer 在 LLM 中的位置 |
| |
| ``` |
| 原始文本 |
| | |
| v |
| +-------------+ |
| | Tokenizer | 文本 -> token ids |
| +------+------+ |
| | |
| v |
| +-------------+ |
| | Embedding | token ids -> 向量 |
| +------+------+ |
| | |
| v |
| Transformer |
| ``` |
| |
| Tokenizer 是 LLM 的"词典"，决定了模型如何理解文本。 |
| |
| --- |
| |
| ## Q1. 为什么用 BPE？ |
| |
| ### 分词方案对比 |
| |
| | 方案 | 优点 | 缺点 | |
| |------|------|------| |
| | 字符级 | 词表小，无 OOV | 序列长，语义弱 | |
| | 词级 | 语义强 | 词表大，有 OOV | |
| | BPE | 平衡词表大小和语义 | 需要训练 | |
| |
| ### BPE 核心思想 |
| |
| ``` |
| |
| 初始：所有字符独立 |
| "low" -> ['l', 'o', 'w'] |
| |
| 第1步：统计最频繁的相邻对 |
| "lo" 出现 100 次，"ow" 出现 80 次 |
| |
| 第2步：合并最频繁的对 |
| "lo w" -> ['lo', 'w'] |
| |
| 重复直到达到词表大小 |
| ``` |
| |
| ### BPE 训练三步 |
| |
| 训练 BPE tokenizer 只需要三步： |
| |
| ```python |
| # 1. 创建模型 |
| tokenizer = Tokenizer(models.BPE()) |
| |
| # 2. 配置预分词 + 训练器 |
| tokenizer.pre_tokenizer = pre_tokenizers.ByteLevel(add_prefix_space=False) |
| trainer = trainers.BpeTrainer(vocab_size=6400, special_tokens=[...]) |
| |
| # 3. 训练 |
| tokenizer.train_from_iterator(texts, trainer=trainer) |
| ``` |
| |
| > 面试点：BPE 和 WordPiece 的区别？BPE 基于频率合并，WordPiece 基于似然合并 |
| |
| --- |
| |
| ## Q2. 字节级 BPE（ByteLevel）为什么好？ |
| |
| ### 传统 BPE 的问题 |
| |
| - 基础字母表是 Unicode 字符 |
| - 不同语言需要不同处理 |
| - 可能出现 OOV |
| |
| ### 字节级 BPE 的优势 |
| |
| ```python |
| tokenizer.pre_tokenizer = pre_tokenizers.ByteLevel(add_prefix_space=False) |
| trainer = trainers.BpeTrainer( |
| initial_alphabet=pre_tokenizers.ByteLevel.alphabet(), # 256 个字节值 |
| ) |
| ``` |
| |
| **核心改进**： |
| |
| 1. 基础字母表是 256 个字节值，覆盖所有可能的输入 |
| 2. 任何文本都能无损表示，永远不会 OOV |
| 3. 中文/英文/emoji/代码都能统一处理 |
| 4. 加前缀空格是 GPT-2 风格，本仓库设为 False |
| |
| > 面试点：为什么字节级 BPE 比字符级好？封闭 256 词表、无 OOV、多语言无损 |
| |
| --- |
| |
| ## Q3. 本仓库的特殊 Token 体系 |
| |
| ### 三层结构（共 36 个） |
| |
| #### 第一层：核心特殊 token（21 个，special=True） |
| |
| | 类别 | Token | 用途 | |
| |------|-------|------| |
| | 对话结构 | `<|im_start|>` / `<|im_end|>` | ChatML 角色标记边界 | |
| | 视觉 | `<|vision_start|>` / `<|vision_end|>` | 视觉内容边界 | |
| | 视觉 | `<|image_pad|>` | 图像占位 token | |
| | 视觉 | `<|vision_pad|>` | 视觉填充 | |
| | 音频 | `<|audio_start|>` / `<|audio_end|>` | 音频内容边界 | |
| | 音频 | `<|audio_pad|>` | 音频占位 token | |
| | TTS | `<tts_pad>` | TTS 填充 | |
| | TTS | `<tts_text_bos>` / `<tts_text_eod>` | TTS 文本开始/结束 | |
| | TTS | `<tts_text_bos_single>` | TTS 单句开始 | |
| | 对象引用 | `<|object_ref_start|>` / `<|object_ref_end|>` | 对象引用边界 | |
| | 坐标 | `<|box_start|>` / `<|box_end|>` | 边界框坐标 | |
| | 坐标 | `<|quad_start|>` / `<|quad_end|>` | 四边形坐标 | |
| | 视频 | `<|video_pad|>` | 视频占位 token | |
| | 结束 | `<|endoftext|>` | 文本结束 / pad / unk | |
|
|
| #### 第二层：额外特殊 token（6 个，special=True） |
|
|
| | Token | 用途 | |
| |-------|------| |
| | `<tool_call>` / `</tool_call>` | 工具调用边界 | |
| | `<tool_response>` / `</tool_response>` | 工具响应边界 | |
| | `<think>` / `</think>` | 思考链边界 | |
|
|
| #### 第三层：预留 buffer token（9 个，special=False） |
|
|
| ``` |
| <|buffer1|> ~ <|buffer9|> |
| 用途：为未来扩展预留位置 |
| ``` |
|
|
| ### 为什么这样设计？ |
|
|
| 1. **ChatML 格式**：业界标准，兼容性好 |
| 2. **多模态支持**：视觉/音频 token 让模型区分不同模态 |
| 3. **工具调用**：支持 function calling |
| 4. **思考能力**：`<think>` / `</think>` 支持 chain-of-thought |
| 5. **预留扩展**：buffer token 为未来功能留空间 |
|
|
| --- |
|
|
| ## Q4. 训练数据加载 |
|
|
| ```python |
| def get_texts(data_path): |
| with open(data_path, 'r') as f: |
| for i, line in enumerate(f): |
| if i >= 10000: |
| break # 只取 10000 行 |
| data = json.loads(line) |
| # 提取所有对话中的 content 字段 |
| contents = [ |
| item['content'] |
| for item in data['conversations'] |
| if item.get('content') |
| ] |
| yield '\n'.join(contents) |
| ``` |
|
|
| 数据来源：sft_t2t_mini.jsonl（SFT 对话数据） |
| 格式：每行是 JSON，包含 conversations 数组 |
| 提取：将所有 content 字段拼成一段文本 |
|
|
| --- |
|
|
| ## Q5. BPE 训练内部过程 |
|
|
| ### 步骤 1：初始化词表 |
|
|
| ``` |
| 基础词表 = 256 个字节值 + 36 个特殊 token = 292 |
| 目标词表 = 6400 |
| 还需合并次数 = 6400 - 292 = 6108 |
| ``` |
|
|
| ### 步骤 2：统计字节对频率 |
|
|
| ``` |
| 输入: "the cat sat on the mat" |
| 统计相邻对频率: |
| "t", "h" -> 3 次 |
| "h", "e" -> 2 次 |
| "a", "t" -> 3 次 |
| ... |
| ``` |
|
|
| ### 步骤 3：合并最频繁对 |
|
|
| ``` |
| 合并 "th": |
| "the" -> ["th", "e"] |
| 继续合并 "he": |
| "the" -> ["the"] |
| 继续...直到词表达到 6400 |
| ``` |
|
|
| ### 最后一次合并 |
|
|
| ``` |
| 第 6108 次合并后，词表包含： |
| - 256 个字节 token |
| - 36 个特殊 token |
| - 6108 个合并后的子词 token |
| = 6400 个 token |
| ``` |
|
|
| --- |
|
|
| ## Q6. tokenizer.json 结构详解 |
|
|
| ### 整体结构 |
|
|
| ```json |
| { |
| "version": "1.0", |
| "model": { |
| "type": "BPE", |
| "vocab": { |
| "!": 0, |
| "\"": 1, |
| ... |
| "the": 256, |
| "ing": 257, |
| ... |
| }, |
| "merges": [ |
| "t h", |
| "h e", |
| "t h e", |
| ... |
| ] |
| }, |
| "added_tokens": [ |
| { |
| "id": 6400, |
| "content": "<|im_start|>", |
| "single_word": false, |
| "lstrip": false, |
| "rstrip": false, |
| "normalized": false, |
| "special": true |
| } |
| ] |
| } |
| ``` |
|
|
| | 字段 | 说明 | |
| |------|------| |
| | vocab | token -> id 映射（6400 个条目） | |
| | merges | BPE 合并规则（按合并顺序排列） | |
| | added_tokens | 额外添加的 token（36 个特殊 token） | |
| |
| --- |
| |
| ## Q7. tokenizer_config.json 关键配置 |
|
|
| ```json |
| { |
| "bos_token": "<|im_start|>", |
| "eos_token": "<|im_end|>", |
| "pad_token": "<|endoftext|>", |
| "unk_token": "<|endoftext|>", |
| "additional_special_tokens": [ |
| "<|object_ref_start|>", |
| "<|vision_start|>", |
| "<|vision_end|>", |
| "<|audio_start|>", |
| "<|audio_end|>", |
| "<|image_pad|>", |
| "<|audio_pad|>", |
| ... |
| ], |
| "chat_template": "...", |
| "image_token": "<|image_pad|>", |
| "audio_token": "<|audio_pad|>", |
| "video_token": "<|video_pad|>", |
| "vision_bos_token": "<|vision_start|>", |
| "vision_eos_token": "<|vision_end|>", |
| "audio_bos_token": "<|audio_start|>", |
| "audio_eos_token": "<|audio_end|>", |
| "tokenizer_class": "PreTrainedTokenizerFast" |
| } |
| ``` |
|
|
| ### 关键字段说明 |
|
|
| | 字段 | 值 | 说明 | |
| |------|-----|------| |
| | bos_token | `<|im_start|>` | 开始 token | |
| | eos_token | `<|im_end|>` | 结束 token | |
| | pad_token | `<|endoftext|>` | 填充 token | |
| | unk_token | `<|endoftext|>` | 未知 token | |
| | model_max_length | 131072 | 最大序列长度 | |
|
|
| --- |
|
|
| ## Q8. Chat Template 的工作原理 |
|
|
| ### 模板示例 |
|
|
| ``` |
| <|im_start|>system |
| 你是一个助手<|im_end|> |
| <|im_start|>user |
| 你好<|im_end|> |
| <|im_start|>assistant |
| 你好！有什么可以帮助你的？<|im_end|> |
| ``` |
|
|
| ### 代码调用 |
|
|
| ```python |
| messages = [ |
| {"role": "system", "content": "你是一个助手"}, |
| {"role": "user", "content": "你好"}, |
| ] |
| prompt = tokenizer.apply_chat_template(messages, tokenize=False) |
| # -> "<|im_start|>system\n你是一个助手<|im_end|>\n<|im_start|>user\n你好<|im_end|>\n<|im_start|>assistant\n" |
| ``` |
|
|
| ### Chat Template 格式 |
|
|
| ``` |
| {% for message in messages %} |
| <|im_start|>{{ message.role }} |
| {{ message.content }}<|im_end|> |
| {% endfor %} |
| <|im_start|>assistant |
| ``` |
|
|
| --- |
|
|
| ## Q9. 编码解码机制 |
|
|
| ### 编码过程（text -> token ids） |
|
|
| ``` |
| 输入: "你好世界" |
| |
| 分词过程: |
| 1. ByteLevel 预分词: 将文本转成字节序列 |
| 2. BPE 合并: 按 merges 规则合并字节对 |
| 3. 输出 token ids: [123, 456, 789] |
| |
| 底层原理: |
| "你好" 的 UTF-8 字节 -> [0xe4, 0xbd, 0xa0, 0xe5, 0xa5, 0xbd] |
| BPE 逐步合并字节对 -> 最终形成子词 token |
| ``` |
|
|
| ### 解码过程（token ids -> text） |
|
|
| ``` |
| 输入: [123, 456, 789] |
| |
| 解码过程: |
| 1. 查 vocab 得到 token 字符串 |
| 2. ByteLevel 解码: 字节序列 -> UTF-8 文本 |
| 3. 输出: "你好世界" |
| |
| 注意: decode 时 skip_special_tokens 参数 |
| - True: 跳过特殊 token（默认） |
| - False: 保留特殊 token |
| ``` |
|
|
| ### 编解码一致性测试 |
|
|
| ```python |
| text = "你好世界" |
| ids = tokenizer.encode(text) |
| decoded = tokenizer.decode(ids) |
| assert decoded == text # 字节级 BPE 保证无损 |
| ``` |
|
|
| --- |
|
|
| ## Q10. 压缩率评估 |
|
|
| ### 本仓库的评测方法 |
|
|
| ```python |
| def eval_compression(tokenizer, texts): |
| for text in texts: |
| encoded = tokenizer.encode(text) |
| char_count = len(text) |
| token_count = len(encoded) |
| ratio = char_count / token_count |
| print(f"Chars: {char_count}, Tokens: {token_count}, 压缩率: {ratio:.2f}") |
| ``` |
|
|
| ### 典型结果 |
|
|
| | 语言 | 样本 | 压缩率 | |
| |------|------|--------| |
| | 中文 | 200 字 | 3.5 chars/token | |
| | 英文 | 200 词 | 4.0 chars/token | |
| | 混合 | 中英混合 | 3.8 chars/token | |
|
|
| > 中文压缩率偏低，因为中文字符多，字节表示更密集 |
|
|
| --- |
|
|
| ## Q11. 流式解码 |
|
|
| ### 问题 |
|
|
| 逐 token 解码时，字节可能跨 token 分布，导致出现 Unicode 替换字符（\ufffd）。 |
|
|
| ### 本仓库的流式解码 |
|
|
| ```python |
| token_cache = [] |
| for tid in input_ids: |
| token_cache.append(tid) |
| current_decode = tokenizer.decode(token_cache) |
| # 只有当没有替换字符时才输出 |
| if current_decode and '\ufffd' not in current_decode: |
| print(current_decode, end='') |
| token_cache = [] |
| ``` |
|
|
| ### 为什么用缓存？ |
|
|
| - UTF-8 编码中，一个中文字符可能被拆成多个 token |
| - 需要等待完整字节序列再解码 |
| - `\ufffd` 检测确保输出完整的字符 |
|
|
| --- |
|
|
| ## Q12. 为什么不建议重复训练 tokenizer？ |
|
|
| ```python |
| # 脚本开头的注释： |
| # Note: It is not recommended to re-train the tokenizer. |
| # MiniMind already includes one. |
| ``` |
|
|
| ### 原因 |
|
|
| 1. **社区兼容性**：不同 tokenizer 导致模型不兼容 |
| 2. **数据敏感**：训练数据影响分词质量 |
| 3. **词表依赖**：下游任务依赖词表一致性 |
| 4. **已足够好**：6400 词表对小模型足够 |
|
|
| ### 什么时候需要重训？ |
|
|
| - 新领域：代码、法律、医疗等专业领域 |
| - 新语言：当前词表不支持的语言 |
| - 优化需求：压缩率不满足要求 |
|
|
| --- |
|
|
| ## Q13. tokenizer 与模型的交互 |
|
|
| ### 在模型前向传播中的位置 |
|
|
| ```python |
| # src/models/lm/model.py |
| class LMForCausalLM(PreTrainedModel): |
| def forward(self, input_ids, ...): |
| # input_ids = tokenizer.encode(text) |
| hidden_states = self.model.embed_tokens(input_ids) |
| # ... transformer ... |
| return logits |
| |
| def generate(self, input_ids, ...): |
| # 1. 编码: tokenizer.encode(prompt) |
| # 2. 逐 token 生成 |
| for _ in range(max_new_tokens): |
| logits = self(input_ids) |
| next_token = sample(logits) |
| input_ids = torch.cat([input_ids, next_token]) |
| # 3. 解码: tokenizer.decode(output_ids) |
| ``` |
|
|
| ### 交互流程 |
|
|
| ``` |
| 用户输入文本 |
| | |
| v |
| tokenizer.encode(text) -> [token ids] |
| | |
| v |
| model.forward(input_ids) -> logits |
| | |
| v |
| sample(logits) -> next token id |
| | |
| v |
| tokenizer.decode([next token]) -> 文本 |
| ``` |
|
|
| --- |
|
|
| ## Q14. Tokenizer 与多模态 |
|
|
| ### 占位 token 机制 |
|
|
| ```python |
| # 视觉占位 token |
| "<|image_pad|>" -> id 6412 |
| |
| # 在输入序列中的位置 |
| input_ids: [bos, ..., image_pad, image_pad, ..., eos] |
| | | |
| 1 个 token 对应 64 个视觉特征 |
| image_token_len = 64 |
| ``` |
|
|
| ### VLM 中的使用 |
|
|
| ```python |
| # src/models/vlm/model.py |
| def count_vision_proj(self, input_ids, vision_proj_output): |
| # 找到视觉占位 token 位置 |
| image_positions = (input_ids == self.config.image_ids[0]).nonzero() |
| # 替换为视觉特征 |
| for i, pos in enumerate(image_positions): |
| hidden_states[pos] = vision_proj_output[i] |
| ``` |
|
|
| ### 多模态特殊 token 的作用 |
|
|
| | Token | id | 在多模态中的角色 | |
| |-------|-----|-----------------| |
| | `<|vision_start|>` | 6408 | 视觉输入开始标记 | |
| | `<|vision_end|>` | 6409 | 视觉输入结束标记 | |
| | `<|image_pad|>` | 6412 | 图像特征占位符 | |
| | `<|audio_start|>` | 6414 | 音频输入开始标记 | |
| | `<|audio_pad|>` | 6416 | 音频特征占位符 | |
|
|
| --- |
|
|
| ## Q15. 常见面试问题 |
|
|
| ### Q: 词表大小怎么选？ |
|
|
| A: 本仓库用 6400。词表太小 -> 序列长；词表太大 -> Embedding 参数多。通常根据模型规模选：小模型（<1B）用 8k-16k，大模型用 32k-128k。 |
|
|
| ### Q: ByteLevel 和 WordLevel 的区别？ |
|
|
| A: ByteLevel 以字节为基本单元，WordLevel 以单词为基本单元。ByteLevel 更通用、无 OOV。 |
|
|
| ### Q: data_path 中的 jsonl 文件是什么格式？ |
| |
| A: 每行一个 JSON 对象，包含 conversations 数组，每个 conversation 包含 role 和 content 字段。 |
| |
| ### Q: 为什么需要 special_tokens_num 参数？ |
| |
| A: 预留位置给特殊 token。特殊 token 在 BPE 训练时直接加入词表，不会被进一步拆分。 |
| |
| ### Q: 怎样评估 tokenizer 的质量？ |
| |
| A: 看压缩率（chars/token）、编解码一致性、流式解码是否出现乱码。 |
| |
