LumTokenizer 1.0.8

LumTokenizer 1.0.8

English: A BPE tokenizer for .NET that loads Hugging Face tokenizer.json (vocab, merges, added_tokens, normalizer, pre_tokenizer) and runs a compiled encode-time pipeline aligned with upstream behavior, with DeepSeek V4–style configs as the primary interoperability target.

面向 .NET（当前目标框架 .NET 10）的 BPE 分词库：从 tokenizer.json 加载词表与合并规则，并在编码路径上执行与上游尽量一致的 normalizer 与 pre_tokenizer 管线。

快速开始

安装

dotnet add package LumTokenizer

编码与解码

using LumTokenizer.Tokenizer;

// 从 tokenizer.json 加载（merges / pattern 等见下文「自动适配」）
var tokenizer = BPETokenizer.CreateTokenizer("path/to/tokenizer.json");
var ctokenizer = ConcurrentBPETokenizer.CreateTokenizer("path/to/tokenizer.json");

Console.WriteLine(tokenizer.VocabSize);

var ids = tokenizer.Encode("hello!  你好");
Console.WriteLine(string.Join(",", ids));
Console.WriteLine(tokenizer.Decode(ids));

// 可选：限制词表大小（按 id 升序保留前 vocabSize 个 token）
// BPETokenizer.CreateTokenizer("path/to/tokenizer.json", vocabSize: 32000);

• BPETokenizer：单线程使用。
• ConcurrentBPETokenizer：多线程共享实例时使用。

加载时的自动适配（无需额外参数）

CreateTokenizer(path) 内部统一调用 TokMap.LoadFromTokenizerJson。不要求为 merges 格式单独传开关，下列由实现根据 JSON 自动判断：

文件须为含 "model" 节点的合法 JSON（扩展名不限）；不再提供「强制字符串 merges」的公开 API——与 HF 导出的两种 merges 形态均由上表自动覆盖。

为何以 DeepSeek V4 的 tokenizer.json 为适配基准

DeepSeek V4（及同族）导出的 tokenizer.json 在真实业务里同时具备：

• model.merges 为字符串数组（"a b" 一行一个 pair），而非仅二维 ["a","b"]；
• pre_tokenizer 常为 Sequence，内含 多段 Split（正则 / String 字面量等多种 JSON 形态） 再接 ByteLevel；
• added_tokens 与对话模板中的特殊串强相关。

我们以 该类配置文件能正确加载、且编码结果与 Hugging Face tokenizers / 官方推理栈一致 为第一目标；其它模型的 tokenizer.json 只要在下列字段能力范围内，一般也可直接使用。若某模型超出下表（例如 normalizer: Precompiled），会在构造或编译管线时显式报错或标注未支持。

设计取舍（我们是怎么考虑的）

1. 语义优先于「手写 RegexType」
   早期可在代码里固定一套正则做预切分；一旦对接任意 tokenizer.json，切分规则必须以 JSON 里的 pre_tokenizer 为准。因此编码前增加 由 JSON 编译出的管线（TokenizerEncodePipeline）：构造完成后根据 normalizer / pre_tokenizer 生成委托与步骤数组，避免在热路径上反复解析 JSON。

2. ByteLevel 与 BPE 的衔接
   当 pre_tokenizer 链 以 ByteLevel 结尾 时，片段已是词表所用字符空间，实现上会 跳过再次 UTF-8 + byte 映射，直接与 BPE 表交互，避免双重映射错误。

3. merges 双格式
   Hugging Face 常见为字符串行；部分工具导出为二维数组。加载时根据 model.merges[0] 的 JSON 类型自动分支（见上文「加载时的自动适配」），再统一成内部 BPE 所需的 merge 顺序。

4. 性能与 AOT
   BPE 核心仍配合 ArrayPool 等习惯用法；编码前管线工作在 string 片段列表上，与「纯 Span、零配置」相比会增加分配与分支，这是为兼容真实 tokenizer.json 的必要成本。
   类库仍标记 IsAotCompatible；运行时编码路径不依赖反射。加载 JSON 仍使用 System.Text.Json 的反射式反序列化，在 裁剪 / Native AOT 宿主中需按 .NET 文档自行处理 trim 或源生成上下文（与多数类库一致）。

5. 与上游的边界
   极端 Split 行为、Metaspace.prepend_scheme、UnicodeScripts 等与 Rust 版逐字节一致性的差异可能存在；遇到与官方不一致时，建议以 同一段文本 + 同一份 tokenizer.json 对照 HF 输出再提 issue。

tokenizer.json 字段与能力（概览）

下列为 当前版本会读取或参与编码语义 的节点；未列出的字段（如 decoder、post_processor、model 非 BPE 等）未接入 本库的加载与编码逻辑。

model

added_tokens

normalizer

支持 type: "Sequence" 嵌套，以及下列子类型（未列出即构造编译阶段可能 NotSupportedException）：

pre_tokenizer

支持 type: "Sequence" 与下列子类型：

测试与贡献

• 仓库内 UnitTest 覆盖基础与鲁棒性用例；对接新模型时建议用 HF tokenizers 或 transformers 对同一输入做 id 对比。
• 欢迎通过 Issue / PR 反馈未覆盖的 tokenizer.json 片段或边界行为。

许可证

LumTokenizer 使用 MIT 许可证，见 LICENSE。