训练数据 Schema 演进：兼容矩阵、语义迁移与发布门禁

把 label 从整数改成字符串，文件仍可能被成功读取，训练却已悄悄学习另一套类别；把延迟从毫秒改成秒，类型完全没变，数值分布却缩小一千倍。训练数据的兼容性因此有两层：编码层能否解析，以及训练语义是否仍然相同。只跑一次反序列化测试，守不住后者。

RAG 权限元数据迁移 关注查询时 ACL 不被旧索引绕过，本篇关注离线样本如何被 tokenizer、collator 和 trainer 解释。TypeScript 运行时信任边界 说明类型声明不能验证外部输入；训练管道同样必须在读入边界执行真实 Schema 和语义门禁。

字段身份与语义一起版本化

字段只靠名字识别会让重命名变成“删除再新增”。合同为字段分配稳定 ID，并记录物理类型、逻辑类型、nullability、默认值、单位、归一化、敏感级别、允许范围和 owner。标签还要固定词表摘要、未知类别行为与 loss 中的 ignore 值：

schema: training.example.v4
fields:
  - id: 17
    name: response_latency_ms
    physical: int64
    logical: duration
    unit: millisecond
    nullable: false
    range: [0, 600000]
  - id: 23
    name: outcome
    physical: string
    vocabulary: sha256:94c1...
    unknownPolicy: reject
normalizer: sha256:12ee...

Avro 的 writer/reader Schema 解析规则可处理字段新增和默认值，Iceberg 用稳定 field ID 支持重命名与重排；这些机制解决结构匹配，不会自动证明单位、标签或缺失值语义正确。新增可空字段只有在默认值不混淆“未知”和真实零时才兼容；整数扩宽通常安全，浮点缩窄、单位改变、标签合并、分词规范化和数组顺序变化都应视为需要显式迁移的变更。

每个提案生成 change record，列出 from/to、兼容类别、转换函数摘要、受影响消费者、回填策略和撤销期限。删除字段先停止新 consumer 依赖，再等待所有受支持 reader 版本越过退役水位；不能看到生产者不再写就立即物理删除。Tokenizer 兼容迁移 属于训练 ABI 的另一部分，tokenizer digest 必须与数据 Schema 一起进入快照，但不能假装只是一个普通文本字段。

兼容矩阵覆盖真实读写组合

注册表保存每个 producer 能写的版本、每个 consumer 能读的区间和用途。CI 至少运行 old writer -> new reader、new writer -> current reader、新版本往返，以及仍在回滚窗口内的 trainer 镜像。未知字段、未知 enum、空值、极值、非法 UTF-8、超长数组和缺失默认值都要有明确错误，不允许 parser 自动转成零或空串。

结构通过后再跑语义 golden set。固定样本同时经旧、新转换，比较 sample ID、split、标签、数值误差、token 长度和拒绝原因；允许变化必须由 change record 给出阈值。影子统计比较 null 率、唯一值、分位数、类别频率、序列长度和各关键切片标签率。全局均值接近不能掩盖小语言或高风险类别被全部映射到 unknown。

训练数据集快照 固定唯一 recordSchema digest。混合版本源数据必须先由有版本的 converter 生成新快照，不允许 trainer 按首行猜 Schema，或在同一个 shard 内动态选择不同默认值。回填 worker 记录源 snapshot、输入/输出计数、reject 集、checkpoint 和单调水位；重试同一分区得到相同输出摘要，不同转换版本绝不覆盖同一路径。

迁移用双读证据而不是直接替换

发布顺序通常是先部署能读新旧版本的 consumer，再让 producer 双写或影子转换，最后切新快照并退役旧 writer。若双写跨两个独立事务，必须以稳定 sample ID 对账，不宣称原子；更稳妥的做法是保留一份源事实，由两个确定性 converter 派生。门禁要求不支持 reader 数为零、不可解释 reject 为零，并由数据 owner 与模型 owner共同批准差异报告。

故障注入包括 producer 提前写新 enum、字段 ID 被复用、单位元数据未更新、旧 worker 迟到覆盖回填、半数分区仍是旧版本、默认值改变、词表文件同名替换，以及回滚 trainer 只能读旧 Schema。指标按 schema digest 记录解析失败、未知字段、转换拒绝、双读不一致、分布漂移、旧 reader 存量和回填水位；禁止把高基数字段放进监控标签。

切换后保留旧快照和兼容 reader 到观察窗口结束。异常时 CAS 把训练别名切回旧 snapshot，并提升 generation，不将已转换文件原地改回；新产生且只有旧 reader 无法解释的数据保持隔离。训练分片原子发布 保证 worker 不会混读两个 Schema 的物理文件。真正的兼容完成标准，是所有受支持读写组合和关键语义切片都有证据，而不是 Schema Registry 显示绿色。

延伸阅读

• RAG 权限元数据迁移
• Tokenizer 兼容迁移
• 训练数据集快照
• 训练分片原子发布