开发者调用 AI 模型时，怎么约定 JSON 输出才稳定？

把 AI 接到业务系统后，最容易被低估的问题是输出格式。人能看懂一段解释，程序却需要稳定字段、可校验类型和失败处理。JSON 约定做不好，后面的自动化流程都会变脆。

先把模型当成不稳定输入源

很多开发者第一次接入时，会在提示词里写“请返回 JSON”，然后直接 parse。测试几次能跑通，但上线后可能出现多余解释、字段缺失、类型错误、数组为空、中文标点混入、枚举值超范围等问题。AI 模型接口不是传统函数，模型会受上下文、输入噪声和重试策略影响，所以业务层必须先准备校验和兜底。

新手搜索“GPT 中转”时，通常关心的是如何把模型接进自己的系统。更规范的表达是 AI 模型接口接入与调用管理，其中 JSON 输出契约就是调用管理的一部分：它决定哪些结果能进入业务流程，哪些必须重试或转人工。

第一步：写字段表而不是只写提示词

先用表格定义字段：字段名、类型、是否必填、允许值、为空时含义、示例。比如做内容分类，可以约定 category 为枚举，confidence 为 0 到 1 的数字，summary 为 80 字以内中文摘要，needs_review 为布尔值，reasons 为字符串数组。字段表确定后，再让 Codex 帮你生成提示词、Schema 和测试样例。

字段越少越稳。不要一次让模型返回十几个业务动作。先把结果分成“模型判断”和“系统动作”两层：模型只返回分类、置信度和原因；系统根据规则决定是否入库、是否通知、是否分配给人工。这样即使模型判断有偏差，也不会直接执行高风险动作。

第二步：准备正反样例

每个 JSON 契约至少准备 10 个样例：5 个正常输入、3 个边界输入、2 个拒答或无法判断输入。样例要包含期望输出，而不是只给自然语言说明。开发者 AI 调用的提示词中可以放 2 到 3 个代表性样例，完整样例集则进入测试脚本。

如果模型返回不符合 Schema，不要立刻把原结果塞给业务系统。更稳的处理是记录原始输出，带着校验错误进行一次修复型重试；重试仍失败，就返回人工复核或默认安全状态。接口状态码、超时和模型名问题可参考 AI 模型接口报错排查清单，但格式校验要在业务层单独处理。

第三步：日志字段要服务复盘

模型调用管理不只是记录花了多少额度。JSON 场景至少要记录 request_id、业务入口、模型名、提示词版本、Schema 版本、校验结果、重试次数、最终处理动作和错误摘要。这样当某个字段频繁缺失时，你能判断是输入质量差、提示词不清楚，还是 Schema 设计过细。

对于团队协作，建议把 Schema 放进仓库并跟随代码评审。Codex 可以帮助补测试、生成模拟输入、检查字段命名是否一致，但不能让聊天记录成为唯一规范。规范应该能被后端、前端、测试和运营同时引用。

上线前检查点

• 字段表包含类型、必填、枚举、为空含义和示例。
• 模型输出先校验，再进入业务系统。
• 失败处理包含修复型重试、人工复核和默认安全状态。
• 日志能区分提示词版本、Schema 版本和模型名。
• 测试样例覆盖正常输入、边界输入和无法判断输入。

常见避坑

不要让模型决定数据库字段名，也不要把“看起来像 JSON”的文本直接入库。所有输出都应该经过 parser 和 Schema 校验。不要把失败重试做成无限循环，最多一到两次，并记录失败原因。需要进一步控制调用成本时，可参考 AI API 接入后的成本控制清单。

当业务流程开始依赖模型结果时，JSON 契约就是接口契约。永沃云枢建议把它和普通 API 文档一样维护：有版本、有测试、有负责人、有回滚方式。