1. 接口演进背后的真实驱动力1.1 从补全到对话再到响应式接口的三级跳如果你在过去两年里维护过任何调用大模型API的服务大概率经历过这样一条迁移路径最早用的是Completions接口传入一段 prompt模型续写一段文本后来Chat Completions出来把输入结构改成消息数组区分 system、user、assistant 角色再后来Responses接口出现把一次调用重新定义成一次有状态的响应过程。这三步不是简单的 API 换皮而是三种不同的交互范式。Completions本质是文本续写模型只负责接着写它不知道自己在对话也没有角色概念。Chat Completions把对话结构显式建模让多轮上下文、工具调用、结构化输出有了统一的承载方式。Responses则更进一步把工具调用、多模态输入、状态管理、流式事件都收进一个统一的响应对象里。我自己的判断是Completions是文本接口Chat Completions是对话接口Responses是任务接口。这个区分很重要因为它决定了你在做技术选型时该看什么维度——不是看哪个更新而是看你的业务到底在解决哪一类问题。1.2 为什么 OpenAI 要推 Responses 而不是继续修补 Chat Completions很多人会问Chat Completions 已经能跑通绝大多数场景了为什么还要搞一个新接口我踩过的坑告诉我Chat Completions 在复杂场景下有三个绕不开的硬伤。第一工具调用和对话历史耦合太紧。每次工具调用都要把完整的 messages 数组重新传一遍上下文越长请求体越大token 消耗和延迟都上去了。第二多模态输入的处理方式不统一图片、文件、音频各自有不同的字段结构写起来很碎。第三流式输出的语义不够清晰delta 里混着文本、工具调用参数、结束标记解析逻辑容易写错。Responses的设计思路是把这些拆开用input承载输入用output承载输出用previous_response_id做状态延续工具调用变成独立的 output item。这样做的直接好处是多轮任务不需要每次重传全部历史服务端帮你维护状态客户端只传增量。注意状态延续不是免费的。服务端保存响应对象是有时间窗口的超过窗口后previous_response_id会失效你还是得自己存历史。这一点在文档里往往写得很轻但实际做长会话产品时是必须处理的。1.3 开源兼容层的真实处境热词里出现了开源兼容这个词这其实是很多团队最关心的问题。现实情况是大量开源模型服务框架、推理引擎、网关最早都是照着Chat Completions的规范实现的。当Responses出来之后兼容层面临一个尴尬局面——要么只做字段映射要么真正实现状态管理和事件流语义。我实测下来目前多数开源兼容方案走的是第一条路把Responses的请求翻译成Chat Completions的请求再把返回翻译回去。这种方案能跑通简单场景但一旦涉及previous_response_id、内置工具、多模态 output item就会出现语义丢失。所以如果你在做选型不要只看支持 Responses这个标签要问清楚它支持到什么程度。2. 核心概念拆解与字段级对比2.1 三种接口的请求结构差异先把三者的请求结构摆在一起看差异一目了然。维度CompletionsChat CompletionsResponses输入字段promptmessagesinput角色建模无system/user/assistant/tool通过 input item 类型区分多模态不支持部分支持content 数组原生支持input_image、input_file 等工具调用无toolstool_choicetools 内置工具状态管理无无每次重传previous_response_id流式语义text deltadelta tool_calls事件类型化response.output_text.delta 等输出结构choices[].textchoices[].messageoutput[]数组这张表里最关键的一行是状态管理。Completions和Chat Completions都是无状态的服务端不记得你上一次说了什么所有上下文靠客户端每次重传。Responses引入了previous_response_id让服务端可以关联上一次的响应客户端只传新增输入。这个设计对长对话、多步工具调用场景非常友好但也带来一个新问题你的服务端和 OpenAI 的服务端之间形成了状态依赖。如果中间隔了网关、代理、缓存层状态延续就可能断掉。我在做网关适配时就遇到过网关把previous_response_id当普通字段透传结果因为路由到了不同后端节点状态找不到直接报错。2.2 输出结构的本质变化Completions的输出是choices[].text一个纯字符串。Chat Completions的输出是choices[].message里面有role、content、tool_calls。Responses的输出是output[]一个数组每个元素是一个 output item类型可能是 message、function_call、reasoning 等。这个变化的意义在于输出不再是一段文本而是一组结构化结果。比如模型先思考reasoning item再调用工具function_call item最后给出回答message item这三者在output[]里是并列的、有序的。客户端可以按类型分别处理而不是从一段文本里猜。我个人的经验是这种结构化输出对做 Agent 类产品帮助很大。以前用 Chat Completions 做工具调用得从tool_calls里解析参数再拼回 messages逻辑很绕。现在 output item 直接告诉你这是一个函数调用参数是 JSON处理起来干净很多。2.3 流式事件的类型化Chat Completions的流式返回是 SSE每个 chunk 里是choices[].deltadelta 里可能有content也可能有tool_calls还可能两者都有。解析的时候要判断字段存在性写起来很啰嗦。Responses的流式返回把事件类型显式化了比如response.created、response.output_item.added、response.output_text.delta、response.completed。每个事件有明确的type字段客户端按类型分发处理即可。这个改动看起来是小事但实际写代码时省了很多判断。我做过一个对比同样实现一个带工具调用的流式对话用 Chat Completions 大概要写 200 行解析逻辑用 Responses 大概 120 行而且可读性更好。提示事件类型化不等于事件顺序固定。工具调用和文本输出可能交错出现客户端要能处理乱序和并发。我见过有团队假设先文本后工具结果遇到模型先调工具再回答的场景就崩了。3. 实操迁移从 Chat Completions 到 Responses3.1 最小可用迁移示例先看一个最简单的迁移。假设你原来用 Chat Completions 发一条消息# 旧写法Chat Completions from openai import OpenAI client OpenAI(api_keyYOUR_KEY) resp client.chat.completions.create( modelgpt-4o, messages[ {role: system, content: 你是一个简洁的助手}, {role: user, content: 用一句话解释什么是接口规范} ] ) print(resp.choices[0].message.content)迁移到 Responses 之后# 新写法Responses from openai import OpenAI client OpenAI(api_keyYOUR_KEY) resp client.responses.create( modelgpt-4o, instructions你是一个简洁的助手, input用一句话解释什么是接口规范 ) print(resp.output_text)注意几个变化messages变成了instructionsinputsystem 角色被instructions替代user 消息直接作为input字符串。resp.output_text是一个便捷属性直接拿到文本输出不用再遍历output[]。这个最小示例能跑通但只适合单轮、无工具、无多模态的场景。真实业务里往往更复杂下面逐项拆。3.2 多轮对话的状态管理Chat Completions 做多轮你得自己维护 messages 数组每次把历史全带上# 旧写法手动维护历史 history [{role: system, content: ...}] def chat(user_input): history.append({role: user, content: user_input}) resp client.chat.completions.create(modelgpt-4o, messageshistory) reply resp.choices[0].message.content history.append({role: assistant, content: reply}) return replyResponses 可以用previous_response_id做状态延续# 新写法服务端状态延续 last_id None def chat(user_input): global last_id kwargs {model: gpt-4o, input: user_input} if last_id: kwargs[previous_response_id] last_id resp client.responses.create(**kwargs) last_id resp.id return resp.output_text看起来更简洁但这里有个坑previous_response_id只在服务端保留一段时间超过窗口就失效。所以生产环境里我建议还是自己存一份历史把previous_response_id当作优化手段而不是唯一依赖。3.3 工具调用的写法差异Chat Completions 的工具调用工具定义放在tools里模型返回tool_calls你执行完再把结果作为tool角色消息塞回 messages再调一次。# 旧写法工具调用 tools [{ type: function, function: { name: get_weather, parameters: {type: object, properties: {city: {type: string}}} } }] resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 北京天气}], toolstools ) if resp.choices[0].message.tool_calls: call resp.choices[0].message.tool_calls[0] result get_weather(json.loads(call.function.arguments)[city]) messages [ {role: user, content: 北京天气}, resp.choices[0].message, {role: tool, tool_call_id: call.id, content: result} ] resp2 client.chat.completions.create(modelgpt-4o, messagesmessages, toolstools)Responses 里工具调用变成 output item处理逻辑更线性# 新写法工具调用 tools [{ type: function, name: get_weather, parameters: {type: object, properties: {city: {type: string}}} }] resp client.responses.create( modelgpt-4o, input北京天气, toolstools ) for item in resp.output: if item.type function_call: args json.loads(item.arguments) result get_weather(args[city]) # 把工具结果作为新输入继续 resp2 client.responses.create( modelgpt-4o, previous_response_idresp.id, input[{type: function_call_output, call_id: item.call_id, output: result}], toolstools )注意工具定义的 schema 变了Chat Completions 是{type: function, function: {...}}Responses 是{type: function, name: ..., parameters: ...}少了一层嵌套。这个细节很容易写错我第一次迁移时就在这里卡了半小时。3.4 多模态输入的写法Chat Completions 的多模态是把 content 变成数组# 旧写法图片输入 messages [{ role: user, content: [ {type: text, text: 这张图里有什么}, {type: image_url, image_url: {url: https://example.com/a.jpg}} ] }]Responses 用独立的 input item 类型# 新写法图片输入 input_items [ {type: input_text, text: 这张图里有什么}, {type: input_image, image_url: https://example.com/a.jpg} ] resp client.responses.create(modelgpt-4o, inputinput_items)字段名从image_url.url变成image_url从嵌套对象变成字符串。这种扁平化在 Responses 里是普遍趋势好处是结构简单坏处是迁移时容易漏改。4. 开源兼容层的实现真相与选型建议4.1 兼容层通常怎么做开源生态里兼容 Responses 的方案大致分三档。第一档是纯字段映射。收到 Responses 请求把input拼成messages把instructions变成 system 消息转发给后端 Chat Completions 接口再把返回包装成 Responses 格式。这种方案实现快但previous_response_id、内置工具、reasoning item 这些特性基本不支持。第二档是状态模拟。在网关层维护一个响应存储自己生成 response id收到previous_response_id时从存储里取出历史拼成完整 messages 再转发。这种方案能支持多轮但状态存储的可靠性、过期策略、并发一致性都要自己扛。第三档是原生实现。后端推理引擎直接按 Responses 的语义实现包括事件流、output item、状态管理。这种方案最完整但工作量最大目前只有少数框架在做。我实测下来多数团队用第一档就够了因为他们的业务场景其实不需要previous_response_id自己维护历史反而更可控。只有做 Agent 平台、需要服务端状态管理的团队才值得上第二档或第三档。4.2 选型时要问清楚的几个问题如果你在评估一个开源兼容方案别只看 README 里写的支持 Responses要具体问previous_response_id支持吗状态存哪里过期时间多久流式事件类型完整吗response.output_item.added、response.output_text.delta这些都有吗工具调用的 output item 结构对吗call_id、arguments字段齐全吗多模态 input item 支持哪些类型input_image、input_file都支持吗内置工具如 web search、file search支持吗还是只支持自定义 function这些问题问下来基本能判断一个兼容层是真支持还是能跑通 demo。注意有些兼容层会在文档里写部分支持但不列出具体不支持哪些。这种模糊表述要警惕最好直接看源码或跑测试用例验证。4.3 自建兼容层的核心难点如果你打算自己写一层兼容我分享几个踩过的坑。第一个坑是流式事件的顺序。Chat Completions 的流式返回是线性的一个 chunk 接一个 chunk。Responses 的事件流里response.output_item.added可能在文本 delta 之前也可能之后取决于模型行为。你的兼容层要能正确处理这种交错不能假设固定顺序。第二个坑是工具调用的参数拼接。Chat Completions 的tool_calls参数是分片返回的要自己拼 JSON 字符串。Responses 的function_callitem 里arguments也是分片的但事件类型更明确。兼容层做转换时要保证拼接逻辑正确否则 JSON 解析会失败。第三个坑是错误语义。Chat Completions 的错误是 HTTP 状态码 error 对象。Responses 的错误可能出现在事件流里比如response.failed事件。兼容层要把这两种错误语义对齐否则客户端处理错误时会漏掉。5. 常见问题排查与避坑清单5.1 迁移过程中的典型报错报错信息可能原因排查方向unexpected endpoint or method请求路径或方法不对确认用的是/v1/responses而非/v1/chat/completionsmissing optional dependencySDK 或运行时依赖缺失检查 SDK 版本重装依赖previous_response_id not found状态过期或路由不一致检查状态存储和网关路由invalid input item typeinput item 类型写错对照文档确认类型名tool schema invalid工具定义 schema 不匹配确认是 Responses 格式而非 Chat 格式stream event parse error事件类型未处理补全事件分发逻辑这张表是我在实际迁移中整理出来的基本覆盖了 80% 的报错。其中previous_response_id not found最隐蔽因为它在单机测试时不会出现只有多节点部署、网关路由不一致时才暴露。5.2 流式解析的常见错误流式解析最容易犯的错是假设事件顺序。我见过有代码这样写# 错误示范假设先文本后工具 for event in stream: if event.type response.output_text.delta: buffer event.delta elif event.type response.function_call_arguments.delta: tool_args event.delta这段代码在模型先调工具再回答时会出错因为工具参数 delta 可能在文本 delta 之前。正确做法是按 output item 的 index 分别维护缓冲区最后再按顺序组装。# 正确示范按 index 维护 items {} for event in stream: if event.type response.output_item.added: items[event.output_index] {type: event.item.type} elif event.type response.output_text.delta: items[event.output_index].setdefault(text, ) items[event.output_index][text] event.delta elif event.type response.function_call_arguments.delta: items[event.output_index].setdefault(args, ) items[event.output_index][args] event.delta这个写法能正确处理交错事件也是我在生产环境里验证过的。5.3 状态管理的坑previous_response_id用起来方便但有几个坑要注意。第一状态过期。服务端保留响应对象有时间限制具体多久官方文档会更新但你不能假设它永久有效。我的做法是本地也存一份历史previous_response_id失效时自动降级为全量重传。第二并发问题。如果同一个 response id 被多个请求同时引用行为可能不确定。做多用户产品时每个用户会话要有独立的 response id 链不能混用。第三跨区域问题。如果你的服务部署在多个区域而状态存储是区域内的跨区域请求可能找不到状态。这种场景下要么做状态同步要么干脆不用previous_response_id。提示我个人的建议是把previous_response_id当作性能优化而不是架构依赖。核心历史还是自己存这样即使状态失效业务也不会断。5.4 工具调用的参数解析坑Responses 的function_callitem 里arguments是 JSON 字符串但它是分片到达的。如果你在流式场景下处理要等response.function_call_arguments.done事件到了再解析否则会拿到不完整的 JSON。我踩过一次坑在delta事件里就尝试json.loads结果因为 JSON 还没传完直接抛异常。正确做法是累积到 done 事件再解析。# 正确做法等 done 再解析 tool_args_buffer for event in stream: if event.type response.function_call_arguments.delta: tool_args_buffer event.delta elif event.type response.function_call_arguments.done: args json.loads(tool_args_buffer) # 执行工具这个细节在文档里往往一笔带过但实际写代码时是必踩的坑。6. 接口选型的实战判断框架6.1 什么场景该用哪个接口我的判断框架很简单看三个维度是否需要多轮状态、是否需要工具调用、是否需要多模态。如果三个都不需要用Completions或Chat Completions都行看你的 SDK 支持。如果只需要多轮对话Chat Completions足够自己维护历史更可控。如果需要工具调用或多模态Responses的结构化优势明显。如果需要服务端状态管理Responses的previous_response_id能省不少事。但这里有个现实约束你的后端模型服务支持哪个接口。如果你用的是开源模型自部署很多推理引擎只实现了Chat Completions那你就得在网关层做兼容或者干脆继续用Chat Completions。6.2 迁移的时机判断不要为了迁移而迁移。我见过有团队在Responses刚出来时就全面迁移结果遇到兼容层不完善、文档不全、社区案例少的问题踩了一堆坑。我的建议是新项目可以直接用Responses因为它的结构更清晰长期看是趋势。老项目如果Chat Completions跑得稳不用急着迁等兼容层成熟、团队熟悉了再动。迁移的触发点应该是现有接口遇到了绕不开的限制而不是新接口出来了。6.3 兼容层的长期维护成本如果你自建了兼容层要有心理准备这是一笔长期维护成本。OpenAI 的接口规范还在演进字段可能增删事件类型可能调整。你的兼容层要跟着更新否则某天上游一变你的服务就挂了。降低维护成本的办法是把兼容层做薄只做必要的字段映射不做复杂的语义转换。语义转换越多上游一变你要改的地方越多。我自己的做法是兼容层只负责请求和响应的格式转换状态管理、工具执行这些逻辑放在业务层这样上游变化时影响面可控。7. 我个人的实操体会接口演进这件事表面看是 API 换名字实际是交互范式的变化。Completions到Chat Completions是从文本到对话Chat Completions到Responses是从对话到任务。理解这个脉络比记住字段名更重要。我在实际项目里的体会是不要被最新接口绑架。选型的核心是匹配业务需求而不是追新。Responses的结构化输出和状态管理确实好用但它的生态成熟度还不如Chat Completions兼容层、工具链、社区案例都还在完善中。如果你的业务场景简单继续用Chat Completions完全没问题。最后分享一个小技巧做迁移时先写一层适配器把新旧接口的调用统一成一个内部接口业务代码只依赖内部接口。这样迁移时可以逐个模块切换不用一次性全改风险可控。这个适配器不用做复杂的语义转换只做参数映射和返回包装维护成本很低。等哪天你确定要全面迁移了把适配器里的旧实现删掉就行。