搜 responses api 常见问题的人,多半已经拿到 Key、也照文档发过一次请求,但结果不是报错就是回的东西跟示例对不上。这篇不重复 API 是什么,而是按「请求拼错、会话接不上、流式读不出来、报错看不出层次」四条线,给判断标准和可执行的排查顺序,让你在动手调之前就知道该看哪一格。
搜 responses api 常见问题的人,基本都不是刚听说这玩意儿。Key 有了,文档也扫过一遍,请求发出去了,结果不是 400 就是返回的东西跟示例长得不一样。这时候最烦的是不知道该怀疑哪一层:代码写错了?网络断了?还是中转那边没接住?
这篇不解释接口是什么。按四条线拆:请求拼错、会话接不上、流式读不出来、报错看不出层次。每条都给判断标准和排查顺序,让你在动手改之前就知道该看哪一格。先说清楚一个前提:下面的做法都建立在「你能拿到完整请求体和原始返回」之上,抓不到这两样,调多久都是猜。
先分清它和以前那套接口差在哪
最容易踩的坑是把它当成「换个地址」:旧代码里 URL 一改就往上报。实际用下来,这么改第一次请求就挂的概率很高,因为请求体的组织方式和返回结构都变了,不是只换个域名的事。
怎么判断自己是不是还在用旧思路?看你代码里有没有两个动作:手动往数组里一条条塞消息,以及从返回里取第一个候选。有这两个,说明你写的是旧接口的调用方式,直接搬过来只会得到参数类型不对之类的报错,而不是内容不对。
- 砍到最小请求只放一个输入文本,不带工具、不带多轮、不带系统提示。目的是先看清这个接口的返回结构到底长什么样。
- 把原始返回存下来别只在控制台打印一行摘要,整段响应存成文件。后面加字段出问题时,拿它当基准对照。
- 逐个加字段工具、系统提示、多轮历史,一次只加一样。加哪个报错,嫌疑就锁定在哪个字段,比通读文档快得多。
请求拼错:八成错在输入和角色这两处
参数错里,十次有七八次出在同一个地方:输入字段的写法。这个字段现在既接受一个纯字符串,也接受结构化的列表,两种都行,但不能混着来。你要是把字符串塞进本该放列表的位置,或者反过来,报错信息通常只说类型不对,不会告诉你具体哪一格。
另一处是角色名。角色得用文档里列出来的那几个值,自己造一个像 system_prompt 这样的键,很多情况下不会明显报错,只是被悄悄忽略。表现出来就是「明明写了要求,它完全没照做」,然后你去怀疑模型,方向就偏了。
| 现象 | 先查哪里 | 怎么验证 |
|---|---|---|
| 提示参数类型不对 | 输入字段是字符串还是列表,有没有混用 | 换成另一种写法重发一次,看报错是否变化 |
| 要求没被执行 | 角色键名是否在枚举里 | 把自定义键改成文档里的标准值再试 |
| 报错指到某个键名 | 该键的取值类型和嵌套层级 | 按报错里的名字逐层往上对,别整段重写 |
排查顺序记住一条就够:先砍到只剩输入文本,跑通,然后一次加一个字段。加哪个错哪个,那个字段就是问题本身。这套笨办法比对着文档反复读省时间。
多轮接不上:会话是靠你传还是靠它存
「它忘了上一句」是问得最多的现象之一。但这事儿麻烦在,得先搞清楚你用的这个接法里,上下文到底是谁在维护。有的用法是服务端帮你把会话续上,你只传一个标识;有的用法是每次请求都得自己把历史带上。这是两套完全不同的写法,混着用一定出问题。
如果你是自己带历史的那种,那它忘事基本不用怀疑模型。先去把发出去的请求体打印出来,看历史到底有没有真的带上去。实际用下来,多半是历史被某段业务逻辑截断了,或者拼进去的顺序反了,模型看到的是一段乱序对话。
- 服务端维护会话:确认你传的标识和上一轮是同一个,换了标识等于开了新会话
- 自己带历史:把请求体打印出来,人工数一遍消息条数和顺序对不对
- 两种都试过还对不上:把最小请求加上一轮历史单独跑,排除业务代码干扰
- 单轮任务(抽取、分类之类):这一节可以直接跳过,不用管
流式读不出来,先看你在收什么
流式这块最常见的错,是拿解析普通响应的方式去读流。流式返回是一段一段的事件,不是一次完整的 JSON,你按整段 JSON 去解析,必然抛错。还有一种更隐蔽:能读出字,但最后拼不完整,这时候问题在拼接逻辑,不在网络。
curl -N -s <你的接口地址> -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d @min.json | head -c 2000上面这条命令的意思很直白:先把流原样打出来看几行,认清事件之间的边界长什么样,再动手写解析。别一上来就套现成的解析库,库对不上这个事件格式的时候,报错信息往往跟真实原因差着十万八千里。
判断标准也简单:如果读出来的字是完整的、只是顺序乱了,那是你拼接的时机不对;如果读出来的片段本身就断在半个字上,那要去检查事件边界有没有被正确地切开。
报错排查顺序:从状态码到字段名
很多人一报错就改请求体,这是最容易白费功夫的做法。先看状态码定层:认证类、路径类、限流类、服务端类,各有各的方向,请求体写错往往不是这些层的问题。定完层再往下走。
- 看状态码定层认证失败就别去动请求体,先去查 Key 和请求头;路径不对先去对地址;限流就等或者换通道。
- 看报错里的字段名多数参数错会直接指到出问题的那个键。按名字改,比把文档从头读一遍快。
- 并排对照把出错请求体和一次成功的最小请求放一起,逐字段对。差异处就是嫌疑点,改完重发验证。
这套顺序的价值在于不让你在错误的层上浪费次数。改请求体改十次,如果问题本来在认证,那十次全是白改。
走中转站时多出来的一层
如果你不是直连,中间还有一层通道,那多出来的变量就值得单独拿出来说。中转站如果只兼容旧接口,这种新结构很可能被直接拒掉,或者更麻烦:被悄悄转译成旧格式,于是你看到的症状是「参数全对,结果就是不对」。
判断方法也不复杂:同一个最小请求,直连官方能过,走中转不过,那问题就不在你的代码上。先别改代码,先去比对两边返回的结构差异,再决定是改写法还是换通道。
- 先拿最小请求分别打直连和中转,各存一份原始返回
- 对比两份返回的顶层结构,看是不是同一套格式
- 返回被转译过的话,字段名和嵌套层级会有明显出入
- 确认是通道问题后,去站内 中转站目录(/sites) 按可信度筛选,别在错通道上反复调代码
接进项目前的自检清单
真正接进业务之前,把这五关逐个勾一遍,比上线后半夜爬起来排查省心。每一关都要能独立复现通过,不能靠「刚才好像跑通了」。
- 最小请求能过,且返回结构你认得清
- 加字段能过,一次加一个,每个都单独验证过
- 多轮能过,历史确实带上了或者会话确实续上了
- 流式能拼完整,事件边界切得对
- 报错能定位到层,知道该查认证还是查字段
还有两件事容易被忽略,但返工成本最高。一是 Key 放环境变量,别写进代码里,提交一次就得处理一次泄露。二是留一份能复现的请求样例,出问题时先跑它,先把「是不是业务代码改坏了」这个可能性排除掉。另外,如果你要估算不同通道的成本差异,去站内 价格追踪(/price-watch) 核对当时的数字,别照着旧截图做预算。
下一步接口本身调通只是第一步,通道是否稳定决定了上线后你会不会天天救火。去中转站目录按检测结果筛一遍,再决定用哪条线。→常见问题
responses api 和以前那套接口能混着用吗?
不建议混。两边的请求结构和返回结构不同,混写的结果是看着能跑、拿到的字段却是空的。要么统一用一套,要么在中间加一层适配把结构转过去,别让业务代码同时认两种格式。
为什么我的请求参数都填了还是报错?
先看报错里的字段名,多数情况它会指到具体的键,问题常在类型上:该传列表的传了字符串、该传字符串的传了对象。把出错的请求砍到最小再逐字段加回来,比通读文档快得多。
多轮对话里它老是忘上一句怎么办?
先确认你这套接法里历史是不是要自己带。要自己带却没带,那跟模型没关系;确认带了还忘,就去打印实际发出去的请求体,多半是拼历史时被截断或顺序错了。
流式返回解析总失败是什么原因?
流式返回的是一串事件而不是一个完整 JSON,用解析普通响应的方式读会直接抛错。先把原始流打印几行看边界,再写拼接逻辑,最后处理结束标记,顺序别颠倒。
走中转站时结果对不上,是代码问题吗?
先用同一个最小请求分别打官方和中转,对比返回结构。官方过、中转不过或者结构不同,问题在通道那一层,改代码没用;两边都不过才是你的请求写法有问题。