本页列出已实现的 tokenizer.json 组件。未知组件会在加载阶段抛出 UnsupportedComponent。
英文版：../components.md
type | 状态 | 说明 |
|---|
BPE / byte-level BPE | ✅ | 支持 byte_fallback、fuse_unk、ignore_merges |
WordPiece | ✅ | 贪心最长匹配，支持 ## 前缀、end_of_word_suffix 与 max_input_chars_per_word |
Unigram | ✅ | Viterbi；支持 byte_fallback、fuse_unk |
WordLevel | ✅ | 整词查表，支持 unk |
type | 状态 |
|---|
Lowercase、Strip、Replace、Prepend、Sequence | ✅ |
StripAccents | ✅ |
BertNormalizer | ✅ |
NFC / NFD / NFKC / NFKD | ✅ |
Nmt | ✅ |
ByteLevel normalizer | ✅ |
Precompiled | ✅ 解析 SentencePiece 二进制 double-array precompiled_charsmap；空 map 保留 NFKC + 全 Unicode 空白折叠与 ASCII fast path |
type | 状态 |
|---|
ByteLevel | ✅ |
Whitespace、WhitespaceSplit、BertPreTokenizer、Punctuation、Metaspace、Sequence | ✅ |
Split：GPT-2 / Qwen-Llama3 / o200k / CLIP / CJK / digit-triplet / 尾部空白正则族 | ✅ |
Digits、Delimiter、FixedLength、UnicodeScripts | ✅ |
Split 正则策略 | ✅ 已支持的 deterministic family 正常加载；JSON 中不支持的 regex pattern 在加载期抛 UnsupportedComponent（手写构造的运行时 fallback 仍为单段） |
type | 状态 |
|---|
TemplateProcessing、BertProcessing、RobertaProcessing、ByteLevel、Sequence | ✅ |
type | 状态 |
|---|
ByteLevel、WordPiece、BPEDecoder、Metaspace、Fuse、Replace、Strip、Sequence | ✅（WordPiece cleanup 已改为单遍 BERT 标点/缩写 fast path） |
ByteFallback | ✅ |
CTC | ✅ |
在可选 fixture 存在时，39 个真实模型与 Python tokenizers token id 对齐： gpt2、roberta、llama、bert/bert-cased、distilbert、t5、albert、xlm-roberta、 Qwen2.5、Qwen3、DeepSeek-V2、Phi-3、Mistral、Falcon、StarCoder2、GPT-NeoX、 CLIP、DeBERTa、Llama-3.2、Phi-4-mini、DeepSeek-R1-Distill-Qwen、DeepSeek-V3.2、 GPT-OSS、GLM-4.5、Granite-4、Qwen3-Coder、Qwen3-VL、BGE-M3、multilingual-E5、 ModernBERT、GTE-ModernBERT、MiniLM、BGE-large-en、Jina embeddings、Nomic Embed、 E5-small、MixedBread、SmolLM2。
- 正则策略： 本项目有意不内置完整 backtracking 或完整通用 Unicode regex 引擎。当前支持的
Split / Replace regex family 来自真实 HuggingFace tokenizer 配置，并以 deterministic scanner 实现。look-ahead/look-behind、 backreference、任意 alternation/grouping 语义以及未覆盖的 Unicode property 组合会显式失败，而不是近似匹配。 - Precompiled charsmap 字素簇： charsmap 变换与 HF 0.22.2 一致：先对整个字素簇 （基础字符 + 后随组合记号，UTF-8 长度 < 6 字节）整体查 trie，因此 t5 类 normalizer 下分解形式
e + U+0301 会组合为 é；未命中回退逐字符查找； 6 字节及以上的簇（如谚文 jamo 对）保持不组合，与上游守卫一致。 - Precompiled charsmap： tokenizer.json 中的
precompiled_charsmap 会先做 base64 解码，再按 SentencePiece double-array trie 应用到 Unicode scalar；空/缺失 map 继续走常见 SPM NFKC + Unicode 空白折叠路径，并保留 ASCII fast path。 - 任意 Split 正则： 当前识别主流 tokenizer 的常见正则族，并覆盖 literal / escaped-literal alternatives（
foo|bar、(foo) / (?:foo)、(foo|bar)、 (?:foo|bar)、foo|a\\.b、 {2,}，以及 ^foo$ / \\bfoo\\b / ^(?:foo|bar) / (?:foo|bar)$ / \\b(?:foo|bar)\\b / ^\\b(?:foo|bar)\\b$ 这类 anchored / word-boundary 形式）、\s+、 \S+、\s+$、\s{2,} / \s{3,} / \s{4,} 以及 \s{2} / \s{3} / \s{4} 精确空白 run、[\r\n]+ 及 {2,} / {3,} / {4,}、{2} / {3} / {4} 换行量词、[^\S\r\n]+ 及水平空白 {2..4} 最小/精确量词、\d+、\D+、 [\d]+ / [^\d]+ / \P{N}+ 数字类别名、\d{2,} / [\d]{2,} 最小数字 run、\d{2} / \d{3} / \d{4} 精确数字 run、 \d{1,2} / \d{1,3} / \d{1,4} / \d{2,4} 及 \p{N} 别名、anchored digit/word/letter run、 \w{2,} / \w{3,} / \w{2} / {1,2} / {1,3} / {1,4} bounded 与 {2,3} / {2,4} / {3,4} ranged word/ASCII/Unicode letter run / [A-Za-z]{2,} / \p{L}{3} 等 word/letter 量词 run、 \p{P}{2,} / \p{P}{2} / \p{S}{2} / {1,n} bounded 与 {2,n} ranged punctuation/symbol/\p{P}\p{S} union run / [\p{P}\p{S}]{2,} 等 punctuation/symbol 量词 run， 以及 \D{3,} / \D{4}、\S{2,}、\W{2}、\P{L}{3,}、\P{P}{4}、\P{S}{2,}、反向 ASCII class、[^\p{P}\p{S}]{3,} 和 [^\s\p{L}\p{N}]{4} 等 exact/min/bounded/ranged 反集 run、 \w+ / \W+、[A-Za-z0-9]+ / [A-Za-z]+ 及反集、\p{L}+ / \P{L}+、\p{P}+ / \P{P}+、 \p{S}+ / \P{S}+、[\p{P}\p{S}]+、[^\s\p{L}\p{N}]+ 等简单 span，以及每个分支都是普通或 escaped literal 的简单 literal / alternation（如 ^foo$ / \\bfoo\\b / foo|bar / (?:foo|bar) / ^(?:foo|bar) / (?:foo|bar)$ / \\b(?:foo|bar)\\b）；复杂未知 pattern 会在加载时抛出 UnsupportedComponent，避免静默产生不对齐切分。通用 Unicode regex 引擎不在现阶段范围内。 - Regex Replace：
Replace normalizer/decoder 已支持 \s+、^\s+、\s+$、 \s{2,} / \s{3,} / \s{4,} 与 \s{2} / \s{3} / \s{4}、 [\r\n]+ 及 {2..4} 最小/精确换行量词、[^\S\r\n]+ / [ \t]+ 水平空白 {2..4} 最小/精确量词、 {2,}、anchored positive/inverse class run（如 ^\s+ / \s+$ / ^\S+ / \D+$ / ^\P{Letter}+ / \P{Punctuation}+$ / ^[^\p{P}\p{S}]+ / [^\s\p{L}\p{N}]+$）， 以及 \d+ / [\d]+ / \D+ / \P{N}+、\d{2,} / [\d]{2,}、\d{2} / \d{3} / \d{4} / \d{2,4}、\w{2,} / \w{3,} / \w{2} / {1,2} / {1,3} / {1,4} bounded 与 {2,3} / {2,4} / {3,4} ranged word/ASCII/Unicode letter run / [A-Za-z]{2,} / \p{L}{3}、\p{P}{2,} / \p{P}{2} / \p{S}{2} / {1,n} bounded 与 {2,n} ranged punctuation/symbol/\p{P}\p{S} union run / [\p{P}\p{S}]{2,}、\D{3,} / \D{4} / \W{2} / \P{L}{3,} / \P{P}{4} / \P{S}{2,} / [^\s\p{L}\p{N}]{4} 等 exact/min/bounded/ranged 反集 run、\w+ / \W+、[A-Za-z0-9]+ / [A-Za-z]+ 及反集、\p{L}+ / \P{L}+、 \p{P}+ / \P{P}+、\p{S}+ / \P{S}+、[\p{P}\p{S}]+、 [^\s\p{L}\p{N}]+ 和简单 literal alternation 替换；Normalizer 与 Decoder Replace 会先分发 bounded/ranged 量词热路径，再进入通用 span fallback，使对应 micro benchmark 保持快于 HF；更复杂正则替换待补。 - 标点分类： BertPreTokenizer 与 Punctuation pre-tokenizer 使用 HF 分类器 （
is_ascii_punctuation || is_punctuation）。P* 表由 scripts/gen_unicode_punct.py 对 Python tokenizers 0.22.2 的 BertPreTokenizer 分类器做 0-2 平面全量扫描经验生成，因此各文字系统标点 （叙利亚/藏/缅甸/泰文等）、竖排/小形变体、片假名中点与星面 P* 均已覆盖； ASCII 符号（$ + < = > ^ \ | ~`）通过 ASCII 并集计为标点。BertPreTokenizer 不再对 CJK 逐字切分（那是 BertNormalizer 的 `handle_chinese_chars` 职责），与 HF 一致。`merged_with_previous`/ `merged_with_next` 只合并 run 的第一个/最后一个分隔符，与 HF 0.22.2 一致。 - Offsets（原文参照）： encode 偏移为指向原文的字符偏移，对齐 HuggingFace NormalizedString 的 alignment 语义：归一化阶段为每个归一化字符维护原文 span （NFD 组合记号折叠到基础字符、NFC 组合保留首个被组合字符的 span、Strip/Prepend/ Replace（内容附着命中末字符 span）/BertNormalizer/charsmap 各自映射回原文），added-vocabulary 切分与模型 token 发射经对齐列转换，ByteLevel/Metaspace 的 piece 改写（多字节扩展、空格→▁、 前缀插入）映射回输入字符坐标。行为对比扫描验证：合成 857 → 971/1008、真实模型 59 → 94/100。
- Offsets： 默认返回字符偏移；可通过 byte-offset encode API 对齐 HF byte offsets。
- Decoder 语义： BPEDecoder 对每个 token 做子串级 suffix 全量替换——非末 token 替换为空格、末 token 仅删除；Metaspace 解码在
always/first 方案下 丢弃首 token 内全部替换符（never 则映射为空格）；CTC 先折叠连续重复 token、删除任意位置（含 token 内部）的 pad 串，cleanup=true 时逐 token 应 用 wordpiece cleanup 后再把词分隔符映射为空格（否则保留字面量）；WordPiece 与 CTC 的 cleanup 使用与上游一致的精确规则表；Replace 类 decoder 为逐 token replace-all，超出受支持 regex 族的 pattern 在独立与 Sequence 两条路 径上均显式报错而非静默按字面量替换。 - 截断溢出窗口： encode 与 HF
tokenizers 0.22.2 一致：两种方向、 stride = 0 / stride > 0 的窗口均写入 enc.overflowing，后处理器包裹 每个窗口，固定 padding 同步 pad 窗口。pair encode 复刻 0.22.x 的窗口叉积 （每侧窗口与对侧主编码/窗口全组合，主 pair 除外）；注意 HuggingFace 主分支 （0.23-dev）已将该方案改为简单的每侧独立截断窗口。配置期 stride 校验与上游 一致：with_truncation / enable_truncation 在 stride > 0 且超过 max_length - num_special_tokens_to_add(单序列) 时抛错；加载 tokenizer.json 保持宽松，非法存量配置在编码时报错，与上游一致。 - Batch：
encode_batch 为串行实现，适配 wasm/js 目标。 - 性能： BPE 合并使用优先队列与惰性失效，BPE / WordPiece / Unigram 均带 repeated-word cache；加载时直接填充 dense 反向词表。重复或交替
from_str 加载会复用小型 parsed-JSON cache，但每次仍构建全新的 tokenizer 状态。 - 训练： 已支持确定性 WordLevel 训练，可使用默认
WhitespaceSplit、调用方传入的 pre-tokenizer 或已预切分 token 流，并支持 min_frequency、special_tokens、 vocab_size 以及 HF 风格的频次/词典序词表排序；也已提供确定性 WordPiece、 BPE 与 Unigram trainer MVP，支持相同输入模式以及 continuation prefix、 end-of-word suffix、max_input_chars_per_word、byte_fallback 等常见参数； WordPiece 与 BPE training 还支持 HF 风格 initial_alphabet / limit_alphabet， WordPiece 已支持 end_of_word_suffix 的 encode 与 JSON 往返，WordPiece/BPE 均支持 max_token_length，并提供 byte_level_alphabet() 暴露 256 个 ByteLevel symbols，便于 GPT-2/RoBERTa 风格训练。 - 构造型 tokenizer 序列化： 训练得到的 WordLevel / WordPiece / BPE / Unigram tokenizer 可序列化常见 pre-tokenizer，如 ByteLevel、Metaspace、Punctuation、Split、Digits、Delimiter、 FixedLength、UnicodeScripts 和 Sequence。