Update tokenizer README in Chinese

README.md

@@ -11,16 +11,51 @@ tags:
 
 # OLMo3-190M-zh-v2 Tokenizer
 
-Self-trained 48k Chinese ByteLevel BPE tokenizer for the OLMo3-190M zh v2 pretraining pipeline.
+这是 OLMo3-190M 中文 v2 预训练链路使用的自训练 tokenizer。
 
-## Configuration
+它的作用是统一后续几个阶段的 token 语义：
 
-- vocab_size: 48,000
-- normalizer: NFC
-- pre_tokenizer: Qwen regex split + ByteLevel
-- decoder: ByteLevel
-- min_frequency: 2
-- training corpus: sampled raw text from Ultra-FineWeb-zh and Fineweb-Edu-Chinese-V2.2
+```text
+原始中文语料 -> tokenizer -> tokenized.bin -> OLMo3-190M base pretrain
+                                      -> continue pretrain
+                                      -> SFT / reasoning 数据准备
+```
+
+注意：token id 本身只是数字，数字的语义由 tokenizer 决定。使用本项目的 `tokenized.bin`、模型 config 和 checkpoint 时，必须使用这个 tokenizer，不能和其他 tokenizer 混用。
+
+## 基本信息
+
+| 项目 | 值 |
+|---|---|
+| 算法 | ByteLevel BPE |
+| 词表大小 | 48,000 |
+| normalizer | NFC |
+| pre_tokenizer | Qwen regex split + ByteLevel |
+| decoder | ByteLevel |
+| min_frequency | 2 |
+| initial_alphabet | ByteLevel alphabet |
+| 主要语言 | 中文 |
+| 主要用途 | OLMo3-190M 中文 v2 base/continue/SFT 链路 |
+
+## 训练语料
+
+Tokenizer 训练语料来自 base pretrain 原始语料的代表性抽样，不混入 SFT 对话数据。
+
+| 数据源 | 作用 |
+|---|---|
+| Ultra-FineWeb-zh | 通用中文网页文本，提供覆盖面 |
+| Fineweb-Edu-Chinese-V2.2 | 教育类中文文本，提高知识密度 |
+
+训练 tokenizer 的抽样规模：
+
+| 指标 | 数值 |
+|---|---:|
+| raw shard 数 | 10 |
+| 文档数 | 445,359 |
+| 字符数 | 660,001,818 |
+| 训练耗时 | 约 2,388 秒 |
+
+这样做的目的不是“用满所有预训练语料”，而是从最终 base 语料中抽一个足够大、分布尽量代表性的子集，让 BPE merge 规则覆盖中文网页、说明文、教育文本和少量中英混排场景。
 
 ## Special Tokens
 
@@ -35,7 +70,29 @@ Self-trained 48k Chinese ByteLevel BPE tokenizer for the OLMo3-190M zh v2 pretra
 </think>      -> 7
 ```
 
-## Usage
+| token | 用途 |
+|---|---|
+| `<|endoftext|>` | 文档结束符，预训练 packed 数据的文档边界 |
+| `<|pad|>` | padding，评估和 batch 对齐时使用 |
+| `<|bos|>` | 序列开始符，兼容生成和部分模板 |
+| `<|unk|>` | 未知 token |
+| `<|im_start|>` / `<|im_end|>` | 为后续 SFT 多轮对话格式预留 |
+| `<think>` / `</think>` | 为后续 reasoning 数据格式预留 |
+
+## 验证样例
+
+| 输入 | token 数 |
+|---|---:|
+| `人工智能是机器学习和深度学习的重要方向。` | 8 |
+| `北京大学位于北京市海淀区。` | 5 |
+| `Python 是一种常用的编程语言。` | 5 |
+| `今天天气不错，我准备去图书馆学习。` | 9 |
+| `<|im_start|>user\n你好<|im_end|>` | 5 |
+| `<think>先分析问题</think>` | 4 |
+
+所有 special token 均为单 token，`AutoTokenizer` 可正常加载，固定中文测试句 encode/decode 可还原。
+
+## 使用方法
 
 ```python
 from transformers import AutoTokenizer
@@ -44,3 +101,27 @@ tok = AutoTokenizer.from_pretrained("Nwna/olmo3-190m-zh-v2-tokenizer")
 ids = tok.encode("人工智能是机器学习的重要方向。", add_special_tokens=False)
 text = tok.decode(ids, skip_special_tokens=False)
 ```
+
+## 与模型配置的关系
+
+后续 OLMo3-190M 模型 config 必须从 tokenizer 单向同步这些字段：
+
+```text
+vocab_size = 48000
+eos_token_id = 0
+pad_token_id = 1
+bos_token_id = 2
+unk_token_id = 3
+```
+
+如果模型 config 的 `vocab_size` 仍保留其他模型的值，例如 100278，会造成 embedding/lm_head 大小和 tokenized 数据不一致。
+
+## 相关数据
+
+匹配的正式 base tokenized 数据：
+
+```text
+Nwna/olmo3-190m-zh-v2-base-data
+```
+
+该数据使用本 tokenizer 编码，保存为 `uint16 tokenized.bin`。由于 vocab size 小于 65,535，`uint16` 可以覆盖所有 token id，同时比 `uint32` 节省一半磁盘和 IO。