做结构化输出的开发者常碰到这些情况:请求发出去了,返回的却是一段带解释的文本;JSON 解析直接抛异常;字段名对但类型不对;换了个模型突然又不稳了。这些现象看起来都是「格式不对」,但根因分别落在提示词、schema、参数和客户端解析四层。这篇按报错现象分类,给一套从快到慢的排查顺序和对应改法。
先把报错分成四类,别一上来就改提示词
格式报错一冒出来,很多人的第一反应是往提示词里加「必须输出 JSON」「不要输出多余内容」。但报错的原因可能根本不在提示词上:有时是模型没被约束住,有时是外壳多包了一层,有时是字段对不上,还有时是请求在半路被截断或转义坏了。不改对地方,加多少句「必须」都白搭。
所以第一步不是改提示词,而是先看原始响应体。框架抛出的异常信息往往只告诉你「解析失败」,不告诉你失败在哪一层。把这次请求的完整响应原样打出来(包括前后空白、代码块标记、结尾是否被截断),对着它分类,再决定动哪里。
| 类别 | 典型表现 | 大概率原因 |
|---|---|---|
| 一、没有结构 | 整段是自然语言,找不到任何目标结构 | 指令没把格式约束住,或约束写在太靠前的位置 |
| 二、外壳污染 | 有 JSON,但外面套着说明文字或代码块标记 | 模型习惯性加解释,或提示词没有明确禁止包裹 |
| 三、结构不对 | 能解析,但字段缺失、类型不符、枚举越界 | schema 描述与模型理解不一致,或示例给得不够具体 |
| 四、链路问题 | 内容看着对,但结尾断掉、引号转义错乱、中文变乱码 | 客户端超时截断、网关改写、编码不一致 |
- 留下原始响应在解析之前把响应体完整落盘或打日志,别让框架先做一次解析再抛异常;确认拿到的是模型原样返回,不是被中间层处理过的版本。
- 肉眼过一遍头尾看开头有没有说明文字或代码块标记,看结尾是不是停在半个字段上;这两处能快速区分第二类和第四类。
- 尝试单独解析把响应体里疑似 JSON 的那段单独抠出来解析一次;能过就是外壳问题,过不了再往第三类查。
- 对 schema 逐字段核拿解析结果和你的字段定义逐项比对:缺哪个、哪个类型不对、哪个枚举值不在范围内,记下来再改提示词或校验层。
这个分法也有不适用的时候:如果同一条请求在别的网络环境或别的客户端上稳定复现不了,先按第四类查链路;如果响应里连目标结构的影子都没有,先按第一类查指令。分类只是缩小范围,最终还是要靠原始响应体说话。改完再跑一轮,记得把新旧响应都留着对比。
第一到第三类:从约束入口往下收紧
输出格式报错,大多数时候不是模型「不会」,而是你给的约束太松。先从最外面那层入口收紧:把「只输出什么」写在提示词最前面,别塞在最后一段,也别和业务说明混在一起。一句话讲清边界——只输出 JSON、不要解释、不要 markdown 代码块、字段顺序照着示例来。
- 把输出契约放到最前开头就写「只输出一个 JSON 对象,不要任何解释文字,不要 ``` 包裹」,然后才是任务描述。写完自己读一遍:如果开头三行里没有出现格式要求,模型很容易先自由发挥再补格式。
- 给一个最小完整示例示例控制在几个字段、两三行以内,字段顺序和你要求的完全一致。示例比字段说明表更管用,但别堆长示例——示例越长,正文里的约束越容易被冲淡。
- 字段定义收紧枚举写成有限取值(如 status 只能是 ok / failed),数字标明整数还是小数、有没有范围,必填项单独列一行。模糊字段是报错的高发区。
- 参数层面兜底把温度调低、限制最大输出长度,避免生成到一半被截断导致 JSON 不闭合。截断类报错的特征是尾部缺括号,一看就能认出来。
| 报错表现 | 常见原因 | 先改哪一层 |
|---|---|---|
| 输出前后带解释文字 | 格式要求写在末尾或被任务描述盖住 | 把「只输出 JSON」提到开头 |
| 字段名对不上、缺字段 | 只给了字段说明,没给完整示例 | 补一个短小完整的示例,顺序对齐 |
| 取值为自由文本 | 枚举没写死,模型自由发挥 | 把枚举收成有限集合 |
| JSON 尾部不闭合 | 输出被最大长度截断 | 调低随机性、放宽长度或拆任务 |
再往下一层是模型侧能力:支持 JSON 模式的接口可以直接强制结构化输出,支持严格 schema 的还能校验字段。但这里有个坑——不是所有中转站和模型都完整支持,有的大门写了支持、实际回显被改写或降级。上生产前先用一条最小请求打一次,看返回原文是不是干净的 JSON、字段有没有被吞,再去 /tools/relay-check 核对中转站的格式支持情况。
- 最小验证请求只留两三个字段,能看出回显有没有被包壳、有没有多出解释文字
- 同一请求连发几次,看格式是否稳定,偶发不合规说明约束还不够硬
- 强制格式不生效时退回提示词约束,两条腿走路比单押一边稳
解析层:兜底清洗与重试,别让一次失败炸掉整条链路
模型返回的字符串几乎不会是干净的 JSON:可能裹着代码块标记,前后带一句「好的,以下是结果」,甚至中间夹着解释。解析层的第一件事不是判定失败,而是做保守清洗:剥掉首尾的代码块围栏,再截取第一个左花括号到最后一个右花括号之间的内容。这一步只动包裹,不改内部字符,避免把合法内容误伤。
- 第一步:剥围栏去掉首尾的 ``` 及语言标记,只留中间正文;验证方式是看清洗后的首字符是不是 { 或 [
- 第二步:截括号区间从第一个 { 定位到最后一个 },其余前后文字丢掉;注意嵌套对象时不要用第一个 } 收尾
- 第三步:再解析一次清洗后重跑解析,成功就进入业务校验,失败才进入重试分支,不要一上来就重试浪费调用
- 第四步:格式修正重试把原始错误内容和「只输出合法 JSON,不要解释」一起回贴给模型,让它只做格式修复;重试次数设硬上限,到顶就降级返回可读错误
解析要用宽容模式,业务校验必须严。解析器能容忍尾逗号、单引号这类小瑕疵,但解析通过不等于数据可用:字段类型对不对、必填项在不在、枚举值是否落在白名单里,都要再过一遍。常见坑是模型把数字写成字符串、把布尔写成「是/否」,宽容解析照单全收,下游一用就炸。
| 校验项 | 宽容解析会放过的情况 | 业务层要补的检查 |
|---|---|---|
| 字段类型 | 数字被写成字符串 | 尝试转换,转不了就判该条无效 |
| 必填字段 | 缺 key 但语法合法 | 按 schema 逐项比对,缺一即拒 |
| 枚举值 | 拼写近似或自造值 | 对照白名单,不匹配走默认或报错 |
| 数组长度 | 空数组也算合法 | 按业务下限判断,空结果单独处理 |
- 重试只做格式修正,不要让模型重答业务问题,否则结果会漂移
- 重试次数写死上限,超过就返回结构化错误,别让整条链路卡死
- 把每次失败的原始响应采样留存,带上当时的 prompt 摘要
- 攒够几条后对比:同类错误反复出现,多半是 prompt 约束不够;偶发且内容无关,多半是模型波动
- 留存要脱敏,别把用户输入原样落盘
第四类:链路侧的三项检查
格式参数设了却不生效、返回的 JSON 缺字段、中文变成问号或乱码,很多情况不是模型不听话,而是请求经过的链路把东西改了。这一段按三项检查走,基本能定位到是哪一层出的问题。
| 检查项 | 典型症状 | 怎么验证 |
|---|---|---|
| 流式拼接 | 整段解析报「意外结束」,报错位置常在最后一个大括号附近 | 先把流式关掉用整段返回跑同一份请求,能过就说明是拼接逻辑的锅 |
| 响应体改写与编码 | 中文变乱码、引号转义多一层、字段名大小写被改 | 看原始响应字节,别只看客户端打印出来的对象 |
| 渠道兼容性 | 设了格式字段但输出照旧是自由文本,参数像没传 | 同一份请求换直连或多条不同渠道,对比报错与输出形态 |
- 先确认拼接方式翻出你调流式的那段代码,看是收到一个增量就试着解析一次,还是攒完再解析。增量解析必须处理半截 JSON,否则一定会切坏;不确定就先改成整段收完再解析跑一次作为对照。
- 核对响应体有没有被改把网关日志里的原始响应体拿出来看,重点看中文和转义引号。网关做二次序列化、按字符集重新编码、统一包一层壳,都会在这些地方留下痕迹。
- 对比直连和多条中转同一份请求、同样参数,直连官方跑一遍,再挑两三家不同中转各跑一遍。只有某一家坏,问题在链路;全都坏且形态一样,才回去怀疑提示词和模型本身。
- 流式场景下要求严格 JSON,本身风险就高,能关流式先关流式
- 网关里的统一响应包装最容易吃掉格式字段,记得确认字段有没有透传
- 字符集在某一跳被改,中文和转义符最先受害,别只盯着英文报错
- 换渠道时别改请求,保持参数一致,否则对比没有意义
- 官方返回的报错原文要留着,那是判断模型侧还是链路侧的关键证据
常见问题
提示词里写了只输出 JSON,模型还是加了说明文字怎么办?
这通常是指令强度不够,而不是模型做不到。把「只输出」放到提示词最后一句,前面给一个完整示例,再把随机性参数调低;如果还反复出现,就说明当前渠道的格式强制能力不可用,需要在解析层加清洗兜底,或者换一个明确支持严格 schema 的渠道。
设了 JSON 模式还是报解析错误,问题可能在哪?
优先看响应是不是被截断,最大输出长度太小会让 JSON 不闭合;其次看是不是走了不支持该参数的兼容渠道,参数被静默丢掉;最后看是不是流式拼接把内容切坏了。把完整原始响应打出来看结尾有没有闭合括号,基本就能定位。
字段类型老是错,比如要数字给了字符串,怎么改?
schema 里把类型写死之外,还要在字段说明里用一句话说清用途和取值形态,比只写 type 更有效。另外可以在提示词里要求按示例顺序输出,减少模型自造结构的空间。如果业务能容忍,就在解析层做一次宽松类型转换,把校验重点放在真正的业务约束上。