AI 应用 JSON Schema 怎么做版本兼容：新增字段、枚举变更与回滚边界

AI 应用一旦把模型输出接入订单、工单或自动化流程，JSON Schema 就不只是提示词附件，而是服务之间的契约。顺着“解析—校验—兼容—回滚”这条链路，就能理清如何演进 schema，避免模型已经生成新字段、下游却按旧结构崩溃。

先把 Schema 当成可版本化的接口

为每份结构保存版本号、用途和变更说明。请求中的 schema_version 与响应元数据应同时落库；线上出现校验失败时，才能区分模型问题、提示词问题和消费者尚未升级。

{"schema_version":"v2","data":{"answer":"...","sources":[]}}

新增字段通常是兼容变更

v2 新增可选字段时，旧消费者应继续读取已知字段并忽略未知字段。校验器要区分 required 与 optional；生产环境先采用“宽读严写”的规则落地。

枚举收缩和类型替换要单独发版

把 status 从三个值收缩到两个，或把字符串改成数组，都会让旧消费者失效。先保留旧 status、增加 status_v2，并在旧客户端归零后再删除旧字段。

{"status":"queued","status_v2":"pending"}

校验失败要有可恢复路径

解析失败时保留原始响应、schema 版本、模型版本和 trace id，随后进入有限次修复流程：让模型只输出校正后的 JSON，再由同一版本校验器复验。仍失败就进入旧版本兜底。

回滚不等于把提示词改回去

回滚应同时冻结 schema、模型配置和消费者路由。用 feature flag 选择 v1/v2，并让新旧版本并行，直到错误率、未知字段比例和落库成功率稳定。

发布前的兼容性清单

• 新增字段是否可选，旧消费者是否能忽略。
• 枚举、类型、嵌套层级是否有破坏性变化。
• 是否保存原始输出和校验上下文。
• 是否有旧版本兜底与回滚开关。

常见问题

新增字段一定兼容吗？

不一定。如果旧消费者拒绝未知字段，或新增字段被错误设为必填，就会形成破坏性变化；应先验证消费者的解析策略。

模型输出校验失败要不要自动重试？

可以有限次重试，但必须保存原始输出并限制预算。超过次数后走旧版本或人工兜底，避免无限生成。

结语

稳定的 AI 输出依赖契约治理，而不是一次更长的提示词。把 schema 版本、校验失败和回滚开关纳入发布流程，才能让模型能力变化保持可观测、可恢复。