要求模型返回固定结构的 JSON,结果一会儿是裸文本、一会儿被代码块包住、一会儿字段被改名,接口直接抛解析异常。这多半不是模型不行,而是约束没落到正确的层、或者解析端没做兼容。这篇按报错出现的环节给出排查顺序:先看请求有没有真的把格式约束带上、再看返回内容哪里不合格,最后决定改提示、改约束参数还是改解析代码,并说明哪些手段在你的场景下不适用。
让模型稳定吐出固定结构的 JSON,最常见的翻车不是模型笨,而是约束没落到对的那一层,或者解析端没有容错。同一个请求,有时候返回裸文本,有时候被代码块包住,有时候字段名悄悄改了,接口直接抛解析异常。先别急着改提示词,先定位异常到底抛在链路的哪一段,再决定是补请求字段、调提示里的示例,还是改解析代码。
下面按报错出现的环节给一套排查顺序:先确认请求有没有真的带上格式约束,再看返回内容哪里不合格,最后按成本从低到高决定修哪一层。每一步都给出可验证的动作和判断标准,也会说清哪些手段在什么情况下不适用。
先分清报错发生在哪一层
把一次调用拆成四段:请求构造、服务端接受约束、模型生成、客户端解析。异常抛在哪一段,决定了你该改什么。上来就重写提示词是最常见的浪费,因为大多数稳定复现的失败其实出在前两段。
- 请求构造:你代码里写的格式字段,是不是真的进了发出的请求体,打印出来看一眼最直接
- 服务端接受约束:格式对象的结构和取值是否符合你所用协议的规范,写错会被拒或被忽略
- 模型生成:内容本身没遵守 schema,字段缺、类型错、夹带说明文字
- 客户端解析:返回其实是合法 JSON,但被代码块包裹或前后有说明,解析器报错
请求体字段被中转层丢掉,和模型不听话,现象很像,但修法完全不同。判断办法是把实际发出的请求体打印出来逐字段核对,再看返回。用一句短指令加一个简单 schema 做最小复现,确认问题与业务提示词无关,再区分偶发还是稳定复现:偶发多半是采样波动或输出被截断,稳定失败多半是约束根本没生效。
约束没生效:请求侧最常见的几处漏配
约束没生效时,先查请求侧。常见是:指定的输出格式字段没写进请求,兼容层或中转层不支持这个字段,就在转发时静默丢掉;字段名或取值不符合协议,比如格式对象的类型与 schema 结构写错;调的是 OpenAI 口径却按 Anthropic 口径拼字段,或反过来。字段差异到站内模型资料库对照,具体支持度以接口实际返回为准。
| 现象 | 优先怀疑 | 验证动作 |
|---|---|---|
| 返回里完全没有结构意识 | 请求里格式字段没带上或被丢弃 | 打印请求体,对比官方通道与中转通道各发一次 |
| 服务端直接报参数错误 | 格式对象结构或取值写错 | 用最小 schema 单独试一次,逐字段加回 |
| 同一请求两个通道表现不同 | 链路上有字段转换损失 | 同一请求双通道对比,看返回是否一致 |
| 字段名每次都随机改 | 提示里示例不稳定或没给示例 | 固定一份字段清单写进提示,再复测 |
判断标准很干脆:把同一请求发到官方通道和中转通道各一次,返回是否一致;不一致就是链路上有转换损失,去修通道或换通道,而不是继续调提示。如果两条通道都稳定不合规,问题在提示或模型本身。
解析侧:让代码先扛住常见的不干净输出
能解析但报错的情况里,绝大多数是前后夹带说明文字、被代码块包裹、末尾多逗号、中文标点混入这几类。解析前先做清洗,再交给 JSON 解析器,能挡掉一大半无效报错。以下是可直接落到代码里的清洗顺序。
- 剥代码块如果内容以代码块标记开头,取出标记之间的部分;取不到就按原文继续。验证方式是拿一条被包裹的返回跑一遍,看是否还原成裸 JSON
- 截取括号区间从第一个左花括号截到最后一个右花括号,中间的说明文字一并去掉。验证方式是前后各加一句废话再跑
- 去控制字符与多余逗号去掉不可见控制字符,处理末尾多余逗号。验证方式是用带中文标点的返回跑一次
- 解析并校验字段交给 JSON 解析器后按 schema 校验;字段缺失或类型不符要能降级,只有必填字段缺失才算硬失败
修复顺序与重试策略
修复按成本从低到高排:先补请求字段,再调提示里的格式示例,再缩短单次输出长度避免被截断,最后才考虑换模型或换通道。这个顺序的原因是,越靠前的改动越可逆,也不会影响其他调用方。
- 对可重试的格式失败设次数上限,并把首次原始返回留档,否则重试几次后再也复现不了
- 截断类失败先查输出长度上限和结束原因字段,别当成模型不听话
- 把每次格式失败的类型记成枚举打日志,连续记一段时间后按类型分布决定先修哪类
- 字段清单固定写进提示,别每次换措辞,示例稳定比示例漂亮更重要
日志里至少要能看出:失败类型、是否重试、首次原始返回、实际发出的请求体摘要。有这几样,一周后你就能按分布判断该先动请求、动提示还是换通道,而不是凭感觉。
什么情况下不要继续修格式
有些场景继续修格式是负收益。任务本身需要模型先自由推理再归纳,强行套严格 schema 会明显拉低内容质量,这时应放宽结构或改成两段式调用:先自由生成,再单独一轮做结构化抽取。模型基础能力不足时,怎么加约束都会输出不合规,换一个原生支持结构化输出的模型比反复调提示划算。
| 场景 | 是否继续修格式 | 替代做法 |
|---|---|---|
| 需要深度推理再总结 | 不建议 | 两段式调用,第二段只做抽取 |
| 模型本身不稳 | 不建议 | 换支持结构化输出的模型 |
| 中转层持续剥离格式参数 | 短期可接受 | 客户端校验加降级,长期换通道 |
| 需要严格审计落库 | 必须修,不许清洗 | 判失败并留原始返回 |
判断标准:连续多次最小复现仍失败,且请求体已确认正确,就不该再在提示上花时间。这时该做的是换通道、换模型,或者把解析端降级逻辑补上。各家模型对结构化的支持情况到站内模型资料库核对,中转通道的稳定性和参数透传情况参考站内中转站可信度检测的结果。
下一步想让排查少走弯路,先确认你走的通道有没有静默丢参数,再对照模型资料看它本身支不支持结构化输出,两件事一起看比单改提示有效。→常见问题
模型返回的 JSON 外面总带一段解释文字,是哪里出了问题?
多半是提示里没明确只输出结构、或者约束字段没生效。先把请求里的格式约束补上并确认服务端接受了它,再在提示里加一句「只输出 JSON,不要解释」。已在解析端做清洗的话,这类问题不算硬故障,但会增加不稳定性。
为什么本地调试好好的,上线后格式报错变多?
常见两类原因:一是线上并发高时超时被截断,输出只有一半;二是线上走了不同的中转或兼容层,把格式参数吃掉了。先比对线上与本地实际发出的请求体和返回的结束原因,再决定是调超时还是换通道。
加了严格格式约束后内容变差了,还要继续用吗?
要分场景看。字段固定的抽取、分类任务一般不受影响;需要模型的推理和表达时,严格约束会压缩它的发挥空间。这种任务建议拆成两步:先让它自由生成,再单独一次调用做结构转换,而不是硬塞进一个 schema。