Python + JSON Schema 实现工单结构化输出与本地复核
内容提要
文章以客服工单为例，指出结构化输出仅保证JSON形状，不保证业务正确。作者用Python结合JSON Schema和本地validate函数复核分类、金额和必填字段，超限退款只进人工队列，并提醒处理漏字段、金额格式和网络超时，同时保存原文、模型与Schema版本及校验结果。
延伸解读
结构化输出与业务校验的分工
文章强调，JSON Schema 只约束模型输出的形状，如字段类型和必填项，但无法保证业务正确性。例如，模型可能返回分类为 refund 且金额为 9999 元，这符合 Schema 却超出自动处理范围。因此，必须增加本地 validate 函数，对枚举值、金额范围和必填字段进行二次复核，形成“模型生成+程序校验”的双重保障。
本地校验的关键检查点
validate 函数针对工单场景检查摘要非空、分类在允许集合内，并对退款金额进行十进制解析和范围限制（0 < 金额 ≤ 500）。若金额格式错误或超限，则拒绝并转入人工队列。这能防止模型将“退款 9999 元”直接执行，确保高风险操作不自动化。
常见失败模式与应对
文章列举三类常见问题：模型漏字段、金额带“元”或逗号、网络超时或 429。应对策略包括：利用 Schema 的 required 字段并回问模型；拒绝非数字金额并要求重新输出；真实调用设置 20 秒超时和指数退避，且避免对可能有副作用的操作盲目重试。
工程化落地与审计建议
为便于追溯和优化，建议为每条记录保存原文、模型版本、Schema 版本和校验结果，并利用脱敏历史样本统计拒绝率。这有助于监控模型输出质量，评估校验规则有效性，并为后续调整提供数据支持。
Q&A
结构化输出能保证模型返回的工单数据业务上正确吗？
不能。结构化输出只保证 JSON 形状符合 Schema，不保证业务正确。例如模型可能返回“退款 9999 元”这样的指令，但金额是否合理、分类是否合法、必填字段是否缺失，都需要本地程序复核。
如何用 Python 和 JSON Schema 对工单做本地复核？
定义一个 validate 函数，检查必填字段（如 summary 非空）、分类是否在允许集合内（如 refund、shipping、other），并对退款金额用 Decimal 解析后判断是否在 0 到 MAX_REFUND 之间。只有全部通过才进入自动队列，否则拒绝或转人工。
工单结构化输出后常见的失败情况有哪些？
常见失败有三类：模型漏字段，需通过 Schema 的 required 字段强制并要求回问；金额带“元”或逗号，应拒绝并让模型只输出数字字符串；网络慢或 429 错误，真实调用需设 20 秒超时并指数退避，且不要在超时后盲目重试有副作用的动作。
超限退款工单应该如何处理？
超限退款（金额超过 MAX_REFUND 或不在允许范围）不应进入自动执行队列，而应只进入人工队列等待复核。示例中 validate 返回 QUEUED_FOR_REVIEW，不会直接退款。
工程化落地时，每条工单记录需要保存哪些信息？
需要为每条记录保存原文、模型版本、Schema 版本和校验结果。此外，可用脱敏历史样本统计拒绝率，以监控系统表现。
这种结构化输出加本地复核的方案适合哪些场景？
适合把自由文本变成工单、表单和审核草稿。不适合拿模型结果直接放款、删库或处理医疗结论。
