wehub-resource-sync
441 lines
14 KiB
Markdown
441 lines
14 KiB
Markdown
# Tokenizer
|
||
|
||
MNN LLM 的 Tokenizer 负责文本编码（encode）和解码（decode），是 LLM 推理的核心组件。当前支持两种文件格式：
|
||
|
||
- **`.mtok` 二进制格式**（推荐）：Pipeline Tokenizer，高性能二进制格式
|
||
- **`.txt` 文本格式**（旧版）：兼容早期导出的模型
|
||
|
||
## .mtok 文件格式
|
||
|
||
`.mtok` 是 MNN 自定义的二进制 Tokenizer 格式，采用「Python 导出时预计算 + C++ 加载时零拷贝」的设计，具有加载快、编码效率高、无外部依赖等优点。
|
||
|
||
### 文件结构总览
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ Text Header │ ← 文本行，与旧格式兼容
|
||
│ Line 1: "430 4\n" │
|
||
│ Line 2: "special stop prefix\n" │
|
||
│ Line 3: "id1 id2 ... \n" │
|
||
├─────────────────────────────────────┤
|
||
│ Binary Body │ ← 二进制数据，顺序读取
|
||
│ ┌─────────────────────────────┐ │
|
||
│ │ Normalizer │ │
|
||
│ │ (可含 NFKC/NFD 归一化表) │ │
|
||
│ ├─────────────────────────────┤ │
|
||
│ │ PreTokenizer │ │
|
||
│ ├─────────────────────────────┤ │
|
||
│ │ Model (BPE/WP/Unigram) │ │
|
||
│ ├─────────────────────────────┤ │
|
||
│ │ Decoder │ │
|
||
│ ├─────────────────────────────┤ │
|
||
│ │ Added Tokens │ │
|
||
│ ├─────────────────────────────┤ │
|
||
│ │ Chat Template (optional) │ │
|
||
│ ├─────────────────────────────┤ │
|
||
│ │ EOS Token (optional) │ │
|
||
│ ├─────────────────────────────┤ │
|
||
│ │ Flags (optional) │ │
|
||
│ ├─────────────────────────────┤ │
|
||
│ │ BOS Token (optional) │ │
|
||
│ └─────────────────────────────┘ │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### Text Header
|
||
|
||
前 3 行为文本格式，与旧版 `.txt` 格式的 Header 结构相同：
|
||
|
||
| 行 | 内容 | 说明 |
|
||
|----|------|------|
|
||
| 1 | `430 4` | magic number (430) + tokenizer type (4=PIPELINE) |
|
||
| 2 | `{special_num} {stop_num} {prefix_num}` | 各类特殊 token 的数量 |
|
||
| 3 | `{id1} {id2} ...` | 所有特殊、stop、prefix token 的 ID |
|
||
|
||
### 基础二进制类型
|
||
|
||
所有整数均为**小端序 (little-endian)**，字符串格式为 `[uint16 len][bytes]`：
|
||
|
||
```
|
||
u8 = 1 字节无符号整数
|
||
u16 = 2 字节无符号整数 (little-endian)
|
||
u32 = 4 字节无符号整数 (little-endian)
|
||
f64 = 8 字节双精度浮点 (IEEE 754)
|
||
str = [u16 len][len bytes] // 变长字符串
|
||
str_ref = [u16 len][len bytes] // 同 str，C++ 端用 StringRef 零拷贝引用
|
||
```
|
||
|
||
### Normalizer
|
||
|
||
文本归一化器，对输入文本进行预处理（大小写、Unicode 归一化等）。
|
||
|
||
```
|
||
[u8 type]
|
||
0 = None // 无归一化
|
||
1 = NFKC // NFKC 归一化（无内嵌表，使用旧路径）
|
||
2 = Prepend // 前缀添加
|
||
[str prepend_str]
|
||
3 = Replace // 字符串替换
|
||
[str pattern] [str content]
|
||
4 = Sequence // 多个归一化器组合
|
||
[u32 count] [Normalizer × count]
|
||
5 = BertNormalizer // BERT 风格归一化
|
||
[u8 clean] [u8 handle_chinese] [u8 strip_accents] [u8 lowercase]
|
||
6 = NFKC+Table // NFKC 归一化（内嵌预计算表）
|
||
[NormTable]
|
||
7 = BertNormalizer+NFD // BERT + NFD 归一化
|
||
[u8 clean] [u8 handle_chinese] [u8 strip_accents] [u8 lowercase]
|
||
if strip_accents: [NormTable] // NFD 归一化表
|
||
```
|
||
|
||
#### Unicode 归一化表 (NormTable)
|
||
|
||
`.mtok` 将 Unicode 归一化所需的映射表直接内嵌到文件中，使得 C++ 端无需依赖 ICU 等外部 Unicode 库。
|
||
|
||
**表结构：**
|
||
|
||
```
|
||
[u32 count] // 条目数量
|
||
For each entry:
|
||
[u32 codepoint] // 原始 Unicode 码点
|
||
[u16 utf8_len] // 归一化后的 UTF-8 字节长度
|
||
[utf8_len bytes] // 归一化后的 UTF-8 字节序列
|
||
```
|
||
|
||
**生成方式（Python 导出时预计算）：**
|
||
|
||
导出时遍历整个 Unicode 码点空间（U+0000 ~ U+10FFFF），对每个码点执行归一化，仅记录归一化结果与原始字符不同的条目：
|
||
|
||
```python
|
||
# NFKC 表：用于 SentencePiece 等模型的归一化
|
||
for cp in range(0x110000):
|
||
ch = chr(cp)
|
||
normalized = unicodedata.normalize('NFKC', ch)
|
||
if normalized != ch:
|
||
entries.append((cp, normalized.encode('utf-8')))
|
||
|
||
# NFD 表：用于 BERT 的 strip_accents（去除变音符号）
|
||
for cp in range(0x110000):
|
||
ch = chr(cp)
|
||
decomposed = unicodedata.normalize('NFD', ch)
|
||
if decomposed != ch:
|
||
entries.append((cp, decomposed.encode('utf-8')))
|
||
```
|
||
|
||
**C++ 端查找（二分查找）：**
|
||
|
||
表按 codepoint 升序排列，C++ 加载后通过二分查找完成归一化，单次查找 O(log n)：
|
||
|
||
```cpp
|
||
size_t lo = 0, hi = table_.size();
|
||
while (lo < hi) {
|
||
size_t mid = (lo + hi) / 2;
|
||
if ((uint32_t)cp > table_[mid].first) lo = mid + 1;
|
||
else if ((uint32_t)cp < table_[mid].first) hi = mid;
|
||
else { /* 命中，返回归一化结果 */ break; }
|
||
}
|
||
```
|
||
|
||
**典型场景：**
|
||
- **NFKC 表** (type=6)：将兼容字符映射到标准形式，如 `fi` → `fi`，`①` → `1`。用于 SentencePiece (Llama/Gemma) 等模型
|
||
- **NFD 表** (type=7)：将字符分解为基字符 + 组合字符，如 `é` → `e` + `◌́`。用于 BERT 的 `strip_accents` 功能，分解后去除组合标记（category `Mn`）实现去变音符号
|
||
|
||
### PreTokenizer
|
||
|
||
预分词器，将输入文本拆分为子串，再分别送入 Model 进行编码。
|
||
|
||
```
|
||
[u8 type]
|
||
0 = None
|
||
1 = ByteLevel // GPT-2 / Llama3 风格
|
||
[u8 use_regex] // 是否使用正则/scanner 拆分
|
||
2 = Digits // 数字拆分
|
||
[u8 individual_digits] // 是否逐位拆分
|
||
3 = Metaspace // SentencePiece 风格
|
||
[str replacement] [u8 add_prefix_space]
|
||
4 = Split // 自定义正则拆分
|
||
[str pattern] [u8 invert] [u8 behavior]
|
||
5 = BertPreTokenizer // BERT 风格（空格+标点拆分）
|
||
6 = Sequence // 多个预分词器组合
|
||
[u32 count] [PreTokenizer × count]
|
||
```
|
||
|
||
### Model
|
||
|
||
核心分词模型，支持三种算法：
|
||
|
||
#### BPE (type=0)
|
||
|
||
```
|
||
[u8 type=0]
|
||
[u32 vocab_size]
|
||
[u8 byte_fallback] // 是否支持 byte fallback
|
||
[u8 byte_level] // 是否为 byte-level BPE
|
||
[u32 merge_size] // merge 规则数量
|
||
|
||
// 词表（按 token 字符串字典序预排序，支持二分查找）
|
||
[str_ref token, u32 id] × vocab_size
|
||
|
||
// Merge 规则（按 key=(id1<<32)|id2 预排序，支持二分查找）
|
||
[u32 id1, u32 id2, u32 rank] × merge_size
|
||
```
|
||
|
||
#### WordPiece (type=1)
|
||
|
||
```
|
||
[u8 type=1]
|
||
[u32 vocab_size]
|
||
[str unk_token] // 未知 token，如 "[UNK]"
|
||
[str continuing_subword_prefix] // 子词前缀，如 "##"
|
||
[u32 max_chars] // 单词最大字符数
|
||
|
||
// 词表（按 token 字符串字典序预排序）
|
||
[str_ref token, u32 id] × vocab_size
|
||
```
|
||
|
||
#### Unigram (type=2)
|
||
|
||
```
|
||
[u8 type=2]
|
||
[u32 vocab_size]
|
||
[u32 unk_id] // 未知 token ID
|
||
[u8 byte_fallback] // 是否支持 byte fallback
|
||
|
||
// 词表（按 token 字符串字典序预排序）
|
||
[str_ref token, u32 id, f64 score] × vocab_size
|
||
```
|
||
|
||
### Decoder
|
||
|
||
解码器，将 token ID 序列还原为文本。
|
||
|
||
```
|
||
[u8 type]
|
||
0 = ByteLevel // byte → unicode 反映射
|
||
1 = ByteFallback // byte token 还原
|
||
2 = Metaspace // '▁' → 空格
|
||
[str replacement] [u8 add_prefix_space]
|
||
3 = WordPiece // 移除 "##" 前缀
|
||
[str prefix] [u8 cleanup]
|
||
4 = Fuse // 拼接所有 token
|
||
5 = Replace // 字符串替换
|
||
[str pattern] [str content]
|
||
6 = Strip // 去除首尾字符
|
||
[str content] [u32 start] [u32 stop]
|
||
7 = Sequence // 多个解码器组合
|
||
[u32 count] [Decoder × count]
|
||
```
|
||
|
||
### Added Tokens
|
||
|
||
模型额外添加的特殊 token（如 `<|im_start|>`、`<tool_call>` 等）。
|
||
|
||
```
|
||
[u32 count]
|
||
For each token:
|
||
[u32 id]
|
||
[u8 special] // 是否为特殊 token
|
||
[u8 lstrip] // 匹配时是否去左空格
|
||
[u8 rstrip] // 匹配时是否去右空格
|
||
[str content] // token 文本
|
||
```
|
||
|
||
### Chat Template（可选）
|
||
|
||
内嵌 Jinja2 chat template，加载后无需额外读取 `tokenizer_config.json`。
|
||
|
||
```
|
||
[u32 tpl_len]
|
||
[tpl_len bytes] // Jinja2 模板 UTF-8 文本
|
||
|
||
[u16 eos_len]
|
||
[eos_len bytes] // EOS token 文本
|
||
|
||
[u8 flags] // bit0: clean_up_tokenization_spaces
|
||
|
||
[u16 bos_len]
|
||
[bos_len bytes] // BOS token 文本
|
||
```
|
||
|
||
## Chat Template 支持
|
||
|
||
MNN Tokenizer 内置了 Jinja2 模板引擎，用于将多轮对话格式化为模型所需的 prompt 格式。
|
||
|
||
### 模板来源
|
||
|
||
| 格式 | 模板来源 |
|
||
|------|---------|
|
||
| `.mtok` | 内嵌在文件尾部，从 `tokenizer_config.json` 中提取并写入 |
|
||
| `.txt` | 从 `llm_config.json` 的 `jinja.chat_template` 字段读取 |
|
||
|
||
### 使用方式
|
||
|
||
```cpp
|
||
// 简单对话
|
||
std::string prompt = tokenizer->apply_chat_template("你好");
|
||
|
||
// 多轮对话
|
||
ChatMessages messages = {
|
||
{"system", "You are a helpful assistant."},
|
||
{"user", "Hello!"},
|
||
{"assistant", "Hi there!"},
|
||
{"user", "What's the weather?"}
|
||
};
|
||
std::string prompt = tokenizer->apply_chat_template(messages);
|
||
```
|
||
|
||
### 模板语法
|
||
|
||
支持 Jinja2 核心语法子集：
|
||
|
||
```jinja
|
||
{# 变量 #}
|
||
{{ messages }}
|
||
{{ eos_token }}
|
||
{{ bos_token }}
|
||
|
||
{# 控制流 #}
|
||
{% for message in messages %}
|
||
{% if message.role == 'user' %}
|
||
<|im_start|>user\n{{ message.content }}<|im_end|>\n
|
||
{% endif %}
|
||
{% endfor %}
|
||
|
||
{% if add_generation_prompt %}
|
||
<|im_start|>assistant\n
|
||
{% endif %}
|
||
|
||
{# 过滤器 #}
|
||
{{ value | tojson }}
|
||
{{ value | trim }}
|
||
{{ value | length }}
|
||
{{ value | upper }}
|
||
|
||
{# 循环变量 #}
|
||
{{ loop.index }} {# 1-based 序号 #}
|
||
{{ loop.first }} {# 是否第一次迭代 #}
|
||
{{ loop.last }} {# 是否最后一次迭代 #}
|
||
```
|
||
|
||
### 模板上下文变量
|
||
|
||
| 变量 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `messages` | array | 消息数组，每项包含 `role` 和 `content` |
|
||
| `add_generation_prompt` | bool | 是否在末尾添加 assistant 提示 |
|
||
| `eos_token` | string | EOS 特殊 token 文本 |
|
||
| `bos_token` | string | BOS 特殊 token 文本 |
|
||
| `tools` | array | 工具定义（可选，用于 function calling） |
|
||
|
||
---
|
||
|
||
## 旧版 tokenizer.txt 文件格式
|
||
|
||
旧版采用纯文本格式，以 base64 编码存储 token。支持 4 种 tokenizer 类型。
|
||
|
||
### 文件结构
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ Line 1: "430 {type}" │ ← type: 0/1/2/3
|
||
│ Line 2: "{special} {stop} {pfx}" │
|
||
│ Line 3: "id1 id2 ..." │
|
||
├─────────────────────────────────────┤
|
||
│ Vocab Section (type-specific) │
|
||
│ ... │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### Type 0: SENTENCEPIECE
|
||
|
||
适用于 Llama、Baichuan、ChatGLM 等使用 SentencePiece 的模型。
|
||
|
||
```
|
||
Line 4: "{vocab_size}"
|
||
|
||
Lines 5 ~ 4+vocab_size:
|
||
"{base64_token} {score} {type}"
|
||
|
||
score: float，Unigram 概率分数
|
||
type: 1=NORMAL, 2=UNKNOWN, 3=CONTROL, 4=USER_DEFINED, 5=UNUSED, 6=BYTE
|
||
```
|
||
|
||
示例：
|
||
```
|
||
430 0
|
||
5 2 1
|
||
0 1 2 3 4 100 101 151643
|
||
32000
|
||
PHM+ -1000 3
|
||
PA== -1000 2
|
||
PGJ5dGVfMHgwMD4= 0 6
|
||
...
|
||
```
|
||
|
||
### Type 1: TIKTOKEN
|
||
|
||
适用于 Qwen、GPT-4 等使用 Tiktoken 的模型。
|
||
|
||
```
|
||
Line 4: "{vocab_size}"
|
||
|
||
Lines 5 ~ 4+vocab_size:
|
||
"{base64_token}"
|
||
|
||
按行序排列，行号即 token ID
|
||
```
|
||
|
||
### Type 2: BERT
|
||
|
||
适用于 BERT、MiniLM 等模型。
|
||
|
||
```
|
||
Line 4: "{vocab_size}"
|
||
|
||
Lines 5 ~ 4+vocab_size:
|
||
"{base64_token}"
|
||
|
||
按行序排列，行号即 token ID
|
||
使用 WordPiece 算法编码，"##" 前缀表示子词
|
||
```
|
||
|
||
### Type 3: HUGGINGFACE
|
||
|
||
适用于使用 HuggingFace Tokenizers 库的模型（BPE 算法）。
|
||
|
||
```
|
||
Line 4: "{vocab_size} {merge_size}"
|
||
|
||
Lines 5 ~ 4+vocab_size:
|
||
"{token}" // 未经 base64 编码的原始 token
|
||
|
||
Lines 5+vocab_size ~ 4+vocab_size+merge_size:
|
||
"{token1} {token2}" // BPE merge 规则，按优先级排列
|
||
```
|
||
|
||
### 类型对比
|
||
|
||
| 特性 | `.mtok` (type=4) | `.txt` (type=0-3) |
|
||
|------|-------------------|-------------------|
|
||
| 文件格式 | 二进制 | 纯文本 |
|
||
| 词表存储 | 预排序数组 + 零拷贝 | `unordered_map<string, int>` |
|
||
| 词表查找 | 二分查找 O(log n) | 哈希表 O(1)~O(n) |
|
||
| Merge 规则 | 预计算 uint64 key + 二分 | wstring pair 哈希表 |
|
||
| 预分词 | 手写 Unicode scanner | `std::regex` |
|
||
| Unicode 归一化 | 预计算表内嵌文件，无外部依赖 | 运行时依赖 Unicode 库或不支持 |
|
||
| Chat Template | 内嵌文件 | 需从 config 读取 |
|
||
| 文件 I/O | 单次读取，零拷贝 | 逐行解析 |
|
||
| 字符串分配 | StringRef 指向 buffer | 每个 token 分配 string |
|
||
|
||
### 导出方式
|
||
|
||
```bash
|
||
# 导出模型（自动选择格式，优先 .mtok）
|
||
cd transformers/llm/export
|
||
python llmexport.py --path /path/to/model --export mnn
|
||
|
||
# 产物:
|
||
# 有 tokenizer.json → 导出 tokenizer.mtok
|
||
# 无 tokenizer.json → 导出 tokenizer.txt
|
||
```
|