写结构化输出的人多半撞过这一幕:本地跑得好好的,上线就开始 intermittent 地返回半截 JSON、字段类型不对、调用直接 400。这时候最容易干的事是反复改提示词,改十遍还是那个错。这篇不说概念,讲怎么从报错本身倒推是哪一层出的问题,然后按层修。
写结构化输出的人多半撞过这一幕:本地跑得好好的,上线就开始间歇性返回半截 JSON、字段类型不对,或者调用直接吃 4xx。这时候最容易干的事是反复改提示词,改十遍还是那个错,因为你根本没搞清楚是谁在拒你。
这篇不讲概念,讲怎么从报错本身倒推是哪一层出的问题,然后按层修。修不干净的时候,还有一套兜底顺序可以照抄。
先别改提示词,把报错文本读三遍
报错来源基本就三种,认错了层,后面的功夫全是白费。第一种是模型正常回话,但内容不合你想要的格式;第二种是请求还没到模型就被接口打回 4xx;第三种是响应拿到了,卡在你自己的解析代码那一行才炸。这三种的修法完全不同。
4xx 里带字段名的,别犹豫,就是 schema 或者参数拼错了,跟模型一点关系没有。这时候去改提示词纯属浪费时间。模型自由发挥型的,麻烦在于你日志里得能看到原始返回,很多人一个 try/except 把异常吞了,连原文都没存下来,排查时只能靠猜。
| 报错长什么样 | 大概率是哪一层 | 先做什么 |
|---|---|---|
| 4xx,消息里点了某个字段名 | 请求参数或 schema 拼错 | 去对照接口文档核对字段名和类型,别动提示词 |
| 200 但内容不是合法 JSON | 模型没被约束住 | 存下原文,看是多了围栏还是截断 |
| JSON 能解析,字段类型或缺失不对 | schema 约束不到位 | 补 required 和字段描述,解析端加归一化 |
| 偶发,重试就好 | 输出太长被截断或通道抖动 | 看 finish_reason,到站内测速页确认通道状态 |
约束写在提示词里还是写在 Schema 里,这是两回事
提示词里写「请返回 JSON」只是建议,不是命令。输出短的时候模型听话,输出一长就开始加解释、加 markdown 围栏,甚至自己编字段。这事儿麻烦在它是概率性的,测试十次过九次,上线就翻车。
真正的硬约束是严格模式、JSON mode 这类开关,或者是函数调用 / 工具调用路径。但这里有个坑:你以为开了,实际没开。中转站不一定透传了这个字段,中间层可能把它丢了还不报错。判断办法很简单,故意传一个明显不合规的 schema 进去,如果接口照样返回 200,说明约束根本没生效。
- 字段描述里写清楚取值范围、是否必填、允许的枚举,比在提示词里列一堆格式要求管用得多。
- 提示词只交代业务含义和边界情况,比如空值怎么表示、多语言要不要统一。
- 每次改完拿同一批难样本回归一遍,别只跑那条最顺的 case。
- 确认严格模式生效之后,再删掉提示词里那些重复的格式叮嘱,留着只会互相打架。
Schema 本身写错的几个典型位置
第一处是必填项没写进 required。模型很合理地省掉一个它觉得不重要的字段,你解析端拿到 null 就当成 bug 报。这不是模型不听话,是你没告诉它这是必须的。第二处是嵌套对象少了 additionalProperties 声明,或者根节点写成了数组而接口要的是对象,校验层直接拒,连模型都没见着。
第三处更隐蔽:枚举值和模型的实际输出对不上。你写的是大写常量,模型给你小写;你写英文,它回中文。这种不建议硬掰模型,在解析端做一次大小写和别名的归一化,再走校验,省事得多。
- 把 schema 单独拿出来校验不经过模型,直接构造几组合法和非法样本喂给你的校验函数,确认 schema 自己没问题。
- 检查 required 和嵌套层级逐个字段过一遍哪些是必填,嵌套对象有没有声明额外字段策略,根节点类型对不对。
- 枚举做归一化映射解析后先转小写、去空格、按别名表映射,再做枚举校验,别让大小写差异变成报错。
- 留一条最小复现请求把出错那次请求的参数原样存成脚本,改一次跑一次,别靠记忆对比。
修不干净的时候,按这个顺序上兜底
有些报错你就是修不利索,尤其是长输出和偶发截断。这时候别死磕,按层兜。第一层,解析失败重试一次,把报错原文和原始返回一起塞回对话让它自己改,成功率不低,成本也就多一次调用。第二层,降级成宽松解析:剥掉 markdown 围栏,从返回里截取第一个完整对象,实在不行用容错解析库顶上。
第三层是换成函数调用或工具调用路径,把结构约束交给接口层管,代价是要多写一点注册代码。最后才考虑换模型或换通道。换之前先去站内测速页和在线实测确认不是通道在中间截断,不然你换了模型还是一样错。各家模型对结构化输出的支持程度不同,可以到 /models 翻一下当时的资料,价格和可用性到 /price-watch 核对当时的数字。
报错先分层,再动手。改提示词是最后的手段,不是第一反应。下一步把手里那条复现请求跑一遍站内测速,确认通道没在中间截断,再去模型资料库对一下你用的模型到底支不支持严格模式。→
常见问题
本地能跑通,线上一直报格式错,差在哪?
大概率差在输出长度和采样参数上。线上上下文更长、返回更长,模型中途收紧格式的概率上升。先对比两边的 max_tokens 和温度设置,再把线上出错的原始返回抓下来看是截断还是格式偏。截断的补长度,格式偏的补约束。
加了严格模式还是报错怎么办?
先确认这个字段真的到了上游。中转站和兼容层对不认识的参数有的直接丢、有的报 400。用最简单的请求单独测一次,看返回里有没有报 schema 相关的错误;如果没有,说明请求根本没走到校验那一层,问题在通道不在你的写法。
重试能解决吗,重试几次合适?
格式类错误重试是有意义的,因为多数是概率问题。但次数别多,两次够了,第三次开始把原始返回和提示词版本记进日志。反复重试还失败的,说明是系统性的写法问题,继续重试只是烧额度。