接入结构化输出后,最烦的往往不是模型答得不好,而是返回的 JSON 时好时坏:缺字段、多包一层、带解释文字、引号没转义,解析器直接抛异常。这篇按「先分清是哪一层出的问题,再按顺序修」的思路,讲清格式控制报错的常见原因、修复手法和验证方法,帮你把这类问题从碰运气变成可复现可收敛。
接入结构化输出以后,最让人头疼的往往不是模型答得不好,而是返回的 JSON 时好时坏:这次正常,下次就缺字段、多包一层、前面带一句解释、引号没转义,解析器当场抛异常。很多人第一反应是改提示词,改来改去还是碰运气,因为根本不知道是哪一层出的问题。
这篇按「先分清是哪一层出的问题,再按顺序修」的思路讲。重点不是给你一套万能提示词,而是把这类报错从不可控变成可复现、可收敛:能定位、能验证、知道什么情况下不适用。
先别改提示词,先定位报错出在哪一层
格式报错看起来都长一个样,其实来源差得很远。先别动提示词,把整条链路拆开看,再判断是模型没按格式给,还是你的代码读错了。这一步没做,后面所有修改都是盲改。
- 请求参数层
- 你选的模型或模式本身是否支持格式约束,相关字段有没有真的发出去。
- 响应体层
- 返回内容有没有被网关、代理或客户端包装、截断、改写。
- 解析器层
- 代码是否读错字段、多剥或少剥了一层、把字符串当对象解析。
- 业务校验层
- 必填字段、类型、枚举值卡得太死,模型给的是合理近似但校验直接拒绝。
- 停掉业务代码用原始请求体把同一条 prompt 单独打一次,不经过业务封装。
- 存原始响应把返回的原文(不是解析后的对象)写成文件,连同 finish 原因一起记下来。
- 分层判断原文就不是合格结构,问题在模型或参数层;原文合格但解析报错,问题在解析器或校验层。
格式约束的三种做法,各自会在哪翻车
约束格式大致有三条路,稳定度不一样,翻车点也不一样。先认清自己走的是哪条,再去对号入座地查,比笼统地说「模型不听话」有用得多。
| 做法 | 强在哪 | 常见翻车点 |
|---|---|---|
| 仅靠提示词描述格式 | 灵活,改起来快 | 长输出、多字段时容易补解释句或漏掉可选字段 |
| 用 schema 或严格模式约束 | 约束力强,结构稳定 | schema 本身不合法、字段嵌套过深,或所走通道没透传参数 |
| 靠函数或工具调用回传 | 稳定度较好,结构清晰 | 参数名拼错、结果多包一层,需要单独拆解 |
- 提示词路线:适合字段少、输出短的场景,字段一多就别指望它稳定。
- schema 路线:先确认所走通道真的把格式相关参数透传了,这点最容易被忽略。
- 工具调用路线:拿到的往往是包了一层的参数对象,解析前先确认实际结构。
- 混用路线:三种叠在一起用,出问题时更难定位,不建议一开始就这么做。
工具调用多包一层、参数名对不上这类问题,站内有专门一篇在讲处理思路,可以配合本篇一起看。判断标准很简单:你要是没法在日志里一眼看出返回的原始结构长什么样,就先补观测,再谈修复。
修复顺序:从最容易排除的开始
修格式问题最忌讳一上来就大改提示词。按从易到难的顺序排,多数问题在前两步就能排掉,剩下的才需要动提示词和兜底逻辑。
- 查参数透传确认请求里与格式相关的字段没有被中转层或客户端丢弃、改写。验证方法:把实际发出去的请求体打出来,和你以为发出去的对一遍。
- 简化 schema先只保留必填字段,跑通再逐个加回字段,直到某次失败,就能定位是哪个字段或哪层嵌套惹的祸。
- 收紧输出边界明确要求只输出结构体、不要解释、不要代码块包裹,并给一个最小示例。示例越接近真实输入越好。
- 加兜底解析失败时先做一次结构提取或重试,仍失败就降级为宽松解析并记录,别让一次格式抖动直接把请求打挂。
兜底那一步要注意适用范围:如果业务下游对字段类型和完整性要求极严,宽松解析等于把错误往后传,这时宁可让请求失败并告警,也不要悄悄吞掉结构问题。
上线前的验证清单
修完不是跑一次通了就算完。格式问题最大的坑是单次通过、批量翻车,所以验证要按用例组跑,看的是失败分布,不是某一次结果。
- 准备一组覆盖边界情况的用例:空值、超长文本、含引号与换行的字段、可选字段缺失。
- 同一组用例多跑几次,看失败是否集中在某类输入,而不是只看单次是否通过。
- 把解析失败率做成监控并设阈值告警,别等业务方来报错才知道。
- 换模型或换通道后重跑这组用例,兼容层差异会直接反映在格式稳定性上。
想看各家模型在结构化输出上的已知差异与支持情况,到 查当时的资料;价格和可用性这类会变的信息,统一到 核对当时的数字,别拿旧结论套新情况。
下一步如果你正卡在格式报错上,建议先把原始请求和原始响应各存一份,再去对照文档确认所用通道是否支持格式约束;站内模型资料与通道说明可以直接对照着看。→常见问题
模型明明返回了 JSON,为什么代码还是解析失败?
多半是响应里夹了额外内容,比如代码块标记、前置解释文字,或者你的解析代码多剥了一层。先把原始响应打出来看首尾字符,再决定是改提示约束还是改解析逻辑。
加了严格格式约束还是偶尔失败,问题在哪?
常见原因是 schema 本身有歧义或嵌套过深,或者请求经过的通道没有完整透传格式参数。先把 schema 砍到最小、确认参数真的到达模型,再逐步加回来。
格式报错要不要一律加重试?
不建议无脑重试。要先区分是模型输出漂移还是解析代码 bug,后者重试一百次也没用。只有确认是偶发的输出不稳定时,才值得加一次重试兜底。