JSON mode 怎么用才稳定：结构化输出的实现原理、常见坑与调用侧校验重试

把大模型接入业务流程时，最麻烦的往往不是答得对不对，而是它答得不像数据。客服工单要落库、订单要拆成字段、分析报告要进 BI，下游系统只认结构化内容。于是 JSON 结构化输出从一个可选技巧，变成了工程默认项。很多人问 JSON mode 到底怎么用，其实要先搞清它的实现原理，以及调用侧需要补哪些兜底。

JSON 结构化输出，指的是让模型按约定的结构返回内容，而不是自由文本。它其实有两层含义：一层是语法合法，返回字符串能被 JSON 解析器解析；另一层是结构合法，字段名、类型、必填项、枚举值都符合预先定义的 Schema。前者只是及格线，后者才是业务真正能用的状态，也是判断一个接口值不值得接入的关键。

实现原理上，主流有两条路线。第一条是约束解码：模型逐 token 生成时，把 JSON Schema 或语法规则编译成状态机，每生成一步就计算当前允许出现的字符集合，对不合法的 token 施加极低概率，相当于在解码阶段把非法分支封死。这样出来的结果天然是合法 JSON，配合严格模式还能保证字段结构符合约定。

第二条是软约束路线：用提示词写清格式要求，配 few-shot 示例，生成后再用校验器检查，不合格就带着错误信息重试。它实现简单，但对模型能力依赖较大，Schema 一复杂，失败率和重试成本就会上升。生产环境里两者常常混用，能约束解码就约束，不能约束就用提示加校验补上。

落到调用层面，JSON mode 并不是加一句请返回 JSON 就完事。请求里通常有专门的参数位用来声明输出格式，同时要把 Schema 写进系统提示，明确哪些字段必填、哪些是枚举、是否允许额外字段。示例也别省，一个正例配一个反例，对稳住字段名和嵌套层级很有帮助。参数与提示的双重声明，比只写其中一样稳得多。

调用侧要做的第一件事是校验，而不是直接取值。拿到返回后先用 Schema 校验器检查类型、必填、枚举、嵌套和长度，通过了再进业务逻辑。校验失败不要直接抛异常，而是把失败原因拼进下一轮提示，例如指出某个字段类型不对、某个枚举值越界，让模型带着具体错误自我修正，通常两三次之内就能收敛。

最常见的坑是输出被包在代码块里，或者在 JSON 前后多了一句解释。解析时不能直接上手解析，要先做清洗：截掉代码围栏标记，取第一个左花括号到最后一个右花括号之间的内容，再尝试解析。这个兜底逻辑看着粗糙，却能救回相当一部分请求，属于投入产出比最高的一段代码。

第二个高频坑是截断。Schema 一复杂、字段一多，输出就很长，一旦撞上最大输出 token 限制，字符串会在半途断掉，右括号永远等不到。处理办法是提前估算输出长度并给足上限，解析失败时先判断是否属于截断，必要时把一个大结构拆成几次小结构请求，或者让模型只返回核心字段，其余字段由服务端补齐。

第三类坑藏在细节里。文本字段可能出现未转义的引号或换行，模型偶尔把数字写成字符串，把布尔写成是或否，浮点精度也可能被截断。调用侧要么在 Schema 层用宽松类型加二次转换，要么在提示里明确类型约束，两者至少做一样，别指望模型每次都规规矩矩。

第四类坑是幻觉字段和枚举漂移。模型可能多返回几个 Schema 里没定义的字段，也可能在枚举里造一个新值。服务端要提前定好策略：多余字段直接丢弃并记录，枚举越界按业务默认值兜底或判失败。关键是把失败样本收集起来，看看哪个字段最容易出错，再回头针对性地改提示和收紧 Schema。

流式场景还要单独处理。推送回来的 JSON 往往是半截的，直接解析必然报错。常见做法是用增量解析器逐字符喂入，或者先缓冲到结构完整再解析；如果产品要求边生成边展示，可以约定先输出简单字段再补复杂嵌套，让前端提前渲染。重试与幂等也要一起考虑，避免同一条业务数据被写入两次。

在上量之前，建议先用小流量把成功率跑出来，再决定重试策略与模型档位。快米兔的模型 API 中转面向国产合规模型接入，注册送 5 元测试金、按量计费，适合拿真实 Schema 做一轮验证：同一段提示、同一份 Schema 跑上几百次，统计解析失败率、截断率和字段漂移率。落地时把 Schema 做扁平、给每个字段标明类型与取值范围，并把校验、重试、日志收敛到统一网关层，结构化输出才会是稳定管道而非事故来源。