Tokenizer 兼容性迁移：词表指纹、双轨编码与无损回滚

Tokenizer 迁移不是把一个 JSON 文件替换掉。相同文本一旦被编码为不同 token ID，模型看到的输入、上下文截断位置、停止条件、计费数量和缓存键都会变化；新增一个特殊 token 还可能要求扩展 embedding 矩阵。只验证“新 tokenizer 能把一句话编码再解码”，无法证明它与现有权重、历史会话和生产协议兼容。

把 tokenizer 当作模型制品的一部分

先为完整编码链路生成指纹，而不是只记录库名称。指纹应覆盖词表及 ID 顺序、merges 或 SentencePiece model、normalizer、pre-tokenizer、post-processor、特殊 token 映射、added tokens、聊天模板和实现版本。服务启动时同时校验模型配置里的 vocab_size、输入 embedding 行数、输出 head 行数及特殊 token ID；任何一项不一致都拒绝 ready。

{
  "tokenizerDigest": "sha256:41d9...",
  "vocabSize": 128256,
  "bosTokenId": 128000,
  "eosTokenIds": [128001, 128009],
  "normalizer": "NFC-v3",
  "chatTemplateDigest": "sha256:57aa...",
  "modelDigest": "sha256:12bc..."
}

不要把 tokenizer-v2 作为唯一版本，因为同名文件可以被覆盖。模型路由、请求日志和离线数据集都记录 digest。理解 BPE 和 token 成本的基础可参考 Tokenizer 入门，迁移门禁关注的是同一文本在两个确定制品之间发生了什么变化。

先划分兼容等级

逐字节相同的 encode 结果属于完全兼容，可以作为重新打包处理；仅修复 decode 展示但 token ID 不变，需要验证日志与界面；新增词表项、改变规范化、调整特殊 token 或重排 ID 都属于破坏性变更。即使旧 ID 保持不变，新增 token 的 embedding 若没有经过训练，也不能因为“append-only”就自动放行。

构建冻结黄金语料，至少包含简繁中文、英文、混合标点、emoji、组合字符与 NFC/NFD、零宽字符、URL、代码缩进、JSON、连续空格、控制字符、领域专名，以及恰好位于上下文边界的长样本。对每条样本保存原始 UTF-8 bytes、规范化结果、token ID、offset、decode 文本和特殊 token 掩码。测试要分别调用生产服务实际使用的快速实现与参考实现，避免只测一个语言绑定。

门禁不能只检查 round-trip。合法 tokenizer 可能按已声明契约执行 NFKC、lowercase 或 StripAccents，旧版本身也未必能恢复原始 bytes，因此通用门槛应是：相对冻结基线新增且未在版本化规范化契约中声明的不可逆样本为零，所有已声明差异与预期集合完全一致。工具协议和聊天边界的特殊 token 序列必须一致；P50 token 数变化在 2% 内，任一核心语言 P95 膨胀不超过 5%；最大上下文样本的截断位置不得丢失系统指令；领域专名的任务指标不低于旧版。只有业务明确要求字节保真的字段，才把任何规范化差异都判为失败。

历史 token ID 不能跨版本复用

数据库如果只保存 token ID 而没有原文，迁移后通常无法安全恢复。在线会话、训练样本和审计记录应以原始文本为事实，并绑定产生它的 tokenizer digest；需要重放时使用原版本解码，或从原文按目标版本重新编码。迁移前盘点所有保存 token 的位置，包括消息压缩、批任务、提示缓存、向量化队列和人工标注导出。

所有 token 级缓存键都加入 modelDigest + tokenizerDigest + templateDigest。旧前缀缓存、KV Cache、计算后的长度预算和 stop token 集合不能被新版本读取。应用层结果缓存若依赖被截断的 prompt，也应失效。缓存版本管理可借鉴 LLM 缓存策略，但不能用短 TTL 代替严格的版本隔离。

客户端上报的 token 数只用于展示，准入、计费和截断由服务端目标 tokenizer 重新计算。否则旧 SDK 可能说请求为 7,900 token，新服务实际编码为 8,300，最终在错误位置截断。告警应跟踪按语言和客户端版本分组的 token 膨胀、超窗拒绝、未知 token、decode 失败及 stop 条件未触发。

双轨运行必须绑定完整请求

迁移阶段部署 A、B 两条不可变编码路径。先对脱敏流量双编码，比较长度、边界和 token ID；再让 B 影子推理，比较结构化成功率、任务质量和延迟。切真实流量时，按会话稳定路由，而不是让同一多轮对话的前半段用 A、后半段用 B。长上下文策略也要独立验证，相关风险可结合 长上下文与 RAG 取舍 的上下文预算方法。

推荐将迁移配置显式写成：黄金语料 20,000 条，特殊 token 契约 100% 通过，核心切片 token P95 增幅不超过 5%，结构化任务成功率下降不超过 0.5 个百分点，影子样本至少覆盖七天与一次峰值。数字应按产品风险调整，但必须在实验前冻结。

回滚时，路由同时恢复旧 tokenizer、聊天模板、模型权重、stop ID 和缓存命名空间，不能只把模型别名指回去。新版本已经创建的会话继续固定在 B，或从原始消息完整重放到 A；绝不能把 B 的 token ID 直接交给 A。发布控制可接入 模型服务金丝雀发布，并为两条路径保留足够容量直到回滚观察窗结束。

可靠迁移的判断标准不是“新词表覆盖更多字符”，而是团队能解释每个编码差异，确认权重和协议匹配，量化真实 token 变化，并能在不混用任何 ID 或缓存的前提下恢复旧链路。

延伸阅读

• Tokenizer 入门
• LLM 缓存策略
• 长上下文与 RAG 取舍
• 模型服务金丝雀发布