调接口要 JSON,回来一段带解释的文字;加了 schema,报参数不合法;好不容易拿到 JSON,loads 又炸了。这三种失败长得像,改的地方完全不一样,很多人一上来就改提示词,改一下午没用。这篇给一套按层排查的顺序:先确认报错是谁抛的,再决定动提示词、动请求参数,还是动解析代码。
调接口要 JSON,回来一段带解释的文字;加了 schema,报参数不合法;好不容易拿到 JSON,loads 又炸了。这三种失败长得像,改的地方完全不一样,很多人一上来就改提示词,改一下午没用。这篇给一套按层排查的顺序:先确认报错是谁抛的,再决定动提示词、动请求参数,还是动解析代码。
先讲个最常见的误判。有人在本地跑得好好的,部署到另一台机器上就报解析失败,第一反应是模型抽风,把温度调到最低、提示词加了三行「必须只输出 JSON」,结果还是炸。最后发现是依赖里的解析库版本不同,旧版本不接受末尾多余的逗号。这类问题改提示词一辈子也改不好。所以动手之前,先搞清楚一件事:这个错,到底是谁在挑毛病。
先别改提示词,先看报错是谁抛的
报错文本能分成四种来源:模型返回的内容不合你的预期、客户端解析或反序列化时抛异常、服务端直接把请求参数拒了、你自己的业务校验没通过。这四类问题的修复动作完全在不同的文件里,混着改只会越改越乱。判断的入口就是错误栈第一行和 HTTP 状态码,这两样东西十秒钟就能看完,但大部分人跳过这步直接去调提示词。
| 现象 | 大概率来源 | 先动哪里 |
|---|---|---|
| 状态码 200,返回是文字或带解释的片段 | 模型没照格式做 | 提示词和约束 |
| 状态码 200,内容看着像 JSON 但解析抛异常 | 客户端解析层 | 解析代码和清洗逻辑 |
| 状态码 4xx,请求基本没发出去 | 请求参数或兼容层不支持 | 请求体和账号配置 |
| 状态码 200,解析也过了,业务层报字段缺失 | 你自己的校验逻辑 | 字段映射和断言 |
| 状态码 5xx 或超时 | 服务端 | 重试策略和备用入口 |
快速判定有个土办法:先把响应原文打印出来看前几十个字符。如果是反引号开头或者一句「好的,以下是结果」,问题在生成侧;如果压根没拿到响应体、只有一段错误结构,问题在参数侧。SDK 抛的异常一般带类名,比如某个解析异常或者参数校验异常,扫一眼类名就知道该去翻哪个文件。网关拒绝通常是 HTTP 4xx 加一段错误体,里面会写哪个字段不对。不管哪种,先把一次完整请求和响应原文存下来,这比反复重试有价值得多,重试十次不如留一条能复现的样本。
模型侧:它没照做,往往是约束没给够
确认是模型没照格式做之后,第一个要看的是那句格式要求放在哪。塞在长提示词中间特别容易被忽略,尤其是前面铺了几百字背景之后。把它放到最后的指令位更稳,因为模型对结尾部分的注意力通常更高。还有个细节:如果你把格式要求写在一段很长的系统提示开头,中间隔了一大段工具说明,效果也会打折。
措辞上别堆形容词。写「必须严格只输出 JSON,不要任何解释」不如直接给一段示例输出,让它照着长。结构化的字段说明比「必须」「只能」这类词管用得多,尤其是嵌套结构,示例里把层级摆出来,比文字描述省事。长对话场景要定期把格式要求重述一遍,上下文一长,早先的约束会被稀释,这不是模型不听话,是它真的看不见了。什么情况下不适用:对本来就以自然语言为主的输出,强行套严格结构只会让它更难写对,改成分段标记或者固定小标题反而更实际。
参数侧:请求里那几个字段对不上
参数被拒的时候,先确认当前账号和模型是否支持你填的响应格式字段。很多中转站和兼容层只透传一部分参数,你写了等于没写,甚至直接报不支持。这事儿麻烦在有些入口不报错、默默忽略,结果你以为约束生效了,其实压根没传过去。schema 字段的必填项、类型、枚举值要和示例输出完全一致,多一个不存在的字段也会被拒,层级套错一层同样会挂。
改完 schema 别只看一次结果。同一条请求连发三次,三次都稳定才算约束到位,偶尔成功说明约束太松,上线后迟早出问题。具体哪些模型支持哪种响应格式、字段名怎么写,去站内模型资料库对一下当页描述,那里列的比接口文档里的兼容说明更贴近实际可用状态。
查模型支持情况不同入口对响应格式参数的支持程度不一样,动手前先对一遍当页说明,省得改半天发现参数根本没透传。→解析侧:JSON 外面裹了一层东西
解析失败的第一个动作永远是打印原始字符串,不是加 try 再试。很多情况就是前后带了代码块标记,或者开头有一句「以下是整理好的结果」。看清了再动手,别凭想象写清洗逻辑。清洗只做最小动作:去掉包裹符号,截取第一个左括号到最后一个右括号之间的内容。别写万能正则去匹配各种奇形怪状的输出,那种正则会误伤正常内容,而且改起来没人敢动。
- 落日志解析失败时把原始内容整段写进日志,带上请求 id 和当时的请求参数,确保之后能原样复现。
- 做最小清洗只去包裹符号和前后说明文字,截取第一个左括号到最后一个右括号,其余内容不动。
- 先宽松解析用类型宽松的解析器接住结构,再逐字段断言,报错时能直接说出缺的是哪一项,比强类型反序列化一次糊一片好定位。
- 补校验业务层对关键字段做存在性和类型判断,缺失时返回结构化错误,别把空值直接往下游传。
重试要带信息,不要原地重发
原样重发基本是碰运气。第一次失败时把错误原因拼进下一轮请求,告诉模型哪里不合规、哪一项不是合法枚举,成功率会明显不一样。这不算什么高级技巧,就是把解析器报的那句话翻译成模型能读懂的话塞回去。次数上设个上限,超过就降级:返回一个结构化错误给调用方,或者切到备用模型,别让一个请求卡在那里转半天。
失败样本别改一次删一次,攒起来。攒够一批再看规律,是某类字段老出错,还是某类长文本老丢约束,一次调完比改一版测一版省事得多。并发高的场景要防重试风暴,重试请求也得算进限流预算里,否则主请求没挂,先把自己限流挂掉了。
- 重试请求附带上一轮的错误原因,而不是原文复制
- 设次数上限,到顶就走降级路径
- 失败样本按类型归档,攒批处理
- 重试流量计入限流预算,单独估算峰值
换中转站或换模型后,先做一次格式对照
同一段提示词、同一份 schema,在新旧两个入口各跑几条,对比返回结构和字段命名。有的兼容层会把字段名大小写改掉,或者把嵌套层级抹平,这类差异不会报错,只会在下游业务里炸,排查起来比格式错误更费劲。跑对照的时候顺便记录一下是否带额外包装层,有的入口会多包一层结果对象,解析代码里就得对应的多剥一层。
把对照结果记成一张小表,字段名、嵌套层级、是否带包装、是否支持响应格式参数,之后换站直接照表核,不用每次重新踩。想先量一下新入口的延迟基线,用站内测速页跑一轮,心里对重试配几次有个数,别等到线上超时了才估。
跑一轮延迟基线换入口前先量一下响应时间,重试次数和超时阈值配起来才有依据。→一份能照着走的排查清单
下面这些按顺序走,前一步没结论别跳到下一步。大部分格式类报错卡在前两步就能定住,后面几步是给反复出问题的场景准备的。
- 留证据请求参数、原始响应、状态码、请求 id,四样齐了再动手改代码。
- 判来源200 先看内容能不能解析,4xx 先看参数和账号配置,5xx 看服务状态和重试。
- 改约束确认是模型侧问题时,把格式要求挪到末尾、补上示例输出,别只改措辞。
- 稳解析解析层只做最小清洗,先宽松接住再逐字段断言,失败必须落原始内容。
- 带信息重试重试附上错误原因,设上限,准备降级;失败样本攒批再统一调。
- 换站先对照新入口先跑格式对照,字段名、层级、包装层记成表,再做切换。
常见问题
模型返回的 JSON 看着对但解析总失败,最可能是什么原因?
多半是字符串外面还裹了代码块标记或者前后带说明文字,也可能是字段里有未转义的引号。先把原始字符串完整打出来看首尾那几个字符,别靠猜。清洗逻辑只做去包裹和首尾截取,其余交给解析器报错细节。
加了严格响应格式参数还是返回自由文本,是不是接口不支持?
有可能。不少兼容层只透传部分参数,写了会被静默丢掉。先在同一条请求里确认参数名拼写和层级对不对,再去站内模型库看这个模型当前页面的能力描述。确认不支持就走提示词约束加解析兜底这条路。
提示词里已经说清楚要 JSON,为什么还是偶尔带解释?
偶发说明约束强度不够。把格式要求从提示词中段挪到结尾,并给一段完整的示例输出,通常能压下去。长对话场景还要定期重述,因为前面聊的内容多了,约束会被稀释。
重试几次能解决吗?
原地重发基本没用,同样的输入大概率同样的结果。要重试就把上一次的错误原因拼进新请求,告诉它哪里不合规。同时设次数上限,超了就降级返回结构化错误,别让重试把并发额度吃光。
换了一家中转站之后格式开始出问题,该从哪查?
先做对照:同提示词、同 schema 在两个入口各跑几条,看字段名、大小写、嵌套层数、有没有额外包装。这类差异通常不报错,只在下游出问题。把对照结果记下来,之后换站照表核一遍就行。