不少团队把“模型输出能被 JSON.parse”当作 Structured Outputs 验收标准，但生产事故常发生在下一步：枚举突然多了一个值，旧客户端把 null 当作字符串，或模型在拒答时只返回半个对象。格式合法只是起点，关键是 Schema 变化能否被客户端、安全策略和下游工具共同承受。
从契约而不是示例开始
为每个输出定义必填字段、可空字段、枚举范围、数值上下界和未知字段策略。示例能展示理想结果，契约才能约束边界。特别是工具调用参数，要区分“字段缺失”“值为空”“请求不适用”三种状态，不能用一个默认值把业务含义抹平。
Schema 演进的四种用例
新增可选字段、扩大枚举、收紧格式、删除字段，分别测试旧客户端和新客户端。一般而言，服务端先新增可忽略信息，客户端能容忍未知字段，再逐步启用新语义。若必须破坏兼容性，应通过明确的版本号或 endpoint 切换，而不是让模型悄悄改变结构。
不要把校验失败交给下游猜
中转站应在模型响应进入业务系统前执行 Schema 校验，并把失败区分为：模型拒答、截断、类型错误、超限、未知枚举和业务规则冲突。可安全重试的只有少数场景，例如网络中断或明确的可重试服务错误；对写操作，重试必须与幂等键配套。
用变异测试检验真实韧性
故意删除必填字段、把整数变为字符串、插入未知字段、制造超长数组，观察客户端是否安全失败。也要用不同模型和不同温度重复运行，因为模型更新可能改变边缘格式。只在单一供应商、单一提示词下通过的 Schema，不能视为稳定协议。
借助 top-api.cc 统一多模型调用时，可以把输出 Schema 版本、校验结果和回退模型记录在一次调用链中。对团队来说，这比在每个业务服务里分散处理解析异常更容易追踪和回滚。
上线门槛
- 合法响应、拒答响应和截断响应都有确定的客户端行为；
- 新旧 Schema 有兼容矩阵与退役日期；
- 未知字段不会触发危险默认动作；
- 校验错误不会泄露原始敏感内容到用户界面或日志；
- 关键写操作在结构不完整时绝不执行。
Structured Outputs 的价值不是让 JSON 更漂亮，而是让模型结果成为可测试、可升级、可审计的工程契约。
Leave a Reply