模型结构化输出改版后，怎样把旧样本重放到明确的版本适配器

模型结果从 v1 的 label 改为 v2 的 decision 后，旧样本还要重放，新样本也要读取。最容易出问题的做法是依次尝试两种解析器，哪个不报错就用哪个。字段相似时，一个新结构可能被旧解析器误接受，产生没有来路的默认值。

版本号是路由依据

本文把 schema_version 放在外层信封中，原始数据放在 payload。注册表明确包含 v1 与 v2 两个适配函数；缺版本或未知版本直接隔离，不能靠字段存在性猜版本。版本是项目自定义的结果合同，不是模型接口自动提供的迁移服务。

演示内部结构为 decision 与可空 reason。v1 的 label 映射到 decision，原因保留未知；v2 要求 decision 与 reason 都存在。这里 v1 的未知原因不能被填成“模型判断通过”，因为原数据没有这一事实。空值的含义在内部合同中明确为未提供，不冒充一个真实解释。

重放四类输入

附件包含合法历史、合法当前、未知 v9 和缺少必要字段的当前结果。前两类进入统一内部结构，并附带来源版本与原始 payload 经键排序、紧凑 JSON 序列化后的 UTF-8 摘要（不是接收原文的字节摘要）；后两类输出不同隔离原因。适配后还检查 decision 属于允许枚举，不能因为字段成功改名就跳过业务约束。

反例是适配器调用 payload.get('decision','accept')。一个损坏的 v2 会因此变为接受，缺字段反而成了通过路径。另一个反例是先把所有字段名改成小写，导致原本应判结构错误的输入被宽松吞掉。容忍范围应事先约定，并用单独的迁移版本解释。

保留原文才能追溯迁移

适配过程不覆盖原始响应。输出记录原始版本、目标内部版本、适配器版本与转换结果，使审查者能区分模型输出和客户端补充信息。后续更新适配器时，对同一历史集生成新记录而不是改写旧台账，便于核对行为变化。

每次发布前把全部历史样本送入注册表，检查已知版本的业务不变式仍成立。新增版本不意味着可以删除旧样本；只有在明确停止接收旧数据并迁移完存量后，才考虑退役对应适配器。重放成功表示转换符合示例合同，不等于模型在当前提示下仍会产生同样结果。

OpenAI 结构化输出资料提供 Schema 约束能力，本文在其之外处理应用版本演进。若实际接口的外层响应本身升级，应先按官方协议读取，再把业务 payload 交给本文注册表。不要把两层版本混成一个字段，也不要将本地迁移通过写成线上兼容实测。

配套文件与依据

本文的合成输入和参考结果可下载独立样本 a016.json，离线检查器 a016.py与样本放在同一目录后运行。检查器不调用模型接口。 使用 Python 3.12 或兼容版本，将上述文件下载到同一目录，执行 python a016.py。

一手资料1；一手资料2。资料核对日期：2026-10-24。