Responses API迁移指南：与Chat Completions架构对比

随着Agent应用、代码智能体快速普及，OpenAI推出的Responses API正在逐步登上核心API舞台。传统的Chat Completions虽然依旧完整可用，但二者在设计理念、数据结构、流式输出、状态管理上存在本质差异。很多开发者在对接Codex、各类中转网关、多厂商大模型服务时，很容易混淆两套协议，出现请求报错、解析异常、工具调用逻辑失效等一系列问题。本文将从设计定位、请求响应结构、流式机制、工具调用、迁移难点、网关适配方案等角度完整拆解两套接口，为业务选型和系统改造提供参考。

一、接口的核心定位差异

Chat Completions（接口地址/v1/chat/completions）是行业广泛普及的传统聊天接口，设计初衷面向一轮轮人机对话。整个交互模型建立在消息数组messages之上，客户端需要维护全部对话历史，每次请求都要把完整上下文全部上传，属于典型无状态接口。它的核心逻辑：用户消息传入 → 模型生成候选回复choices数组 → 取出消息内容返回给调用方。

而Responses API（接口地址/v1/responses）定位是通用AI任务运行时，不再局限于简单聊天对话。它原生支持多模态输入输出、推理过程、工具调用、网页检索、代码解释器、Agent长周期任务，引入input作为输入单元，output作为输出单元，并且支持previous_response_id实现服务端侧上下文续接。简单理解：Chat Completions解决“模型聊天”，Responses API解决“让模型完成一整套复杂任务”。

注意：官方并未废弃Chat Completions，仅标记老版Assistants API为废弃。大量第三方模型、兼容服务依旧高度依赖chat/completions，生产环境不能直接下线该接口，两套接口需要长期共存。

二、请求与返回体关键结构对比

2.1 请求字段变化

最直观的变化是输入字段由messages变成input。

• Chat Completions中，system提示词、用户提问、助手回复、工具返回结果，全部平铺塞进messages[]数组，system角色消息也放在数组内部。业务复杂之后，system规则、业务提示、用户对话历史全部混杂在一起，维护难度持续上升。
• Responses API新增独立顶层字段instructions，专门存放系统级长期指令，input数组仅承载本轮交互输入，职责划分更加清晰。input既可以直接传字符串，也可以传入结构化Item数组，支持文本、图片、工具调用结果等多种类型单元。

简单文本示例请求对比： Chat Completions需要组装完整messages数组；Responses API只需要model与input两个核心字段，极简场景代码行数更少。

2.2 返回数据结构的重大改动

Chat Completions依靠choices候选数组承载结果，业务代码通常固定写choices[0].message.content提取文本。

Responses API抛弃choices概念，改用output输出项数组。数组内部每一个对象拥有type字段，类型包含普通消息message、函数调用function_call、推理内容reasoning等。开发者不能直接默认取数组第0项就是最终文本，必须循环判断type类型分别处理不同输出单元。

这个改动的根本原因：Agent场景下，一次模型运行不会只输出一段文字，中间会穿插多次工具调用、推理片段。把不同行为封装为独立Output Item，可以完整还原任务执行全链路，便于调试、日志审计、错误定位。

三、多轮对话与状态管理机制

这是两套接口工程实践中差距最大的地方。 在Chat Completions体系，服务端不保存任何会话状态。全部历史对话由客户端自己保存，每一轮新请求，都把所有历史消息拼接进messages再发送给模型。会话越长，请求包体积越大，token开销随之上涨。

Responses API引入previous_response_id机制。每一次调用会返回全局唯一response ID，下一轮请求带上该ID，服务端可以接续上一轮的上下文，客户端不需要完整拼接全部历史消息。这对长时间运行的Agent任务十分友好，减少重复传输大量上下文，降低网络开销。当然该能力依赖上游服务支持，私有化、第三方兼容后端不一定完整实现该特性。

四、工具调用（Function Calling）实现区别

Chat Completions的工具调用属于附加能力。工具定义放在请求体，模型把工具调用嵌套在message对象内部。完整Agent循环全部由客户端驱动：拿到工具调用结果，手动包装成role=tool的消息，再重新塞回messages数组发起新一轮请求。整套循环逻辑、状态流转完全交给业务代码实现。

Responses API将工具调用提升为一等公民。工具调用本身就是output数组里面的一种Item类型。解析返回结果时，遍历output，识别function_call类型就执行对应工具，拿到结果之后作为input送入下一轮请求。整套数据模型更贴合Agent运行循环，天然适配Codex这类编程智能体。

五、流式输出SSE事件流差异

两者虽然都支持stream流式返回，但是事件模型完全不同。 Chat Completions流式返回持续输出delta增量分片，核心业务逻辑持续读取choices[0].delta.content拼接文本，事件结构围绕token增量设计。

Responses API采用事件驱动流式模型，会输出多种类型事件：response.created、output_item.added、output_text.delta、response.completed、response.failed。除了文本增量，还可以推送工具调用开始、推理片段、任务失败等不同生命周期事件。

对于API网关、中转代理系统，不能简单原样透传上游SSE流。网关必须解析事件类型，再按照下游期望协议重新编码输出，简单转发会造成下游SDK解析报错。

六、网关与中转平台的现实挑战

对于做模型中转、API网关的研发人员，不能简单二选一抛弃某一套协议。市面上DeepSeek、Qwen、Moonshot等大量开源模型生态主力仍然是Chat Completions接口；而Codex、新一代Agent工具优先使用Responses API。生产环境理想方案是两套协议同时对外提供服务。

这就引出协议双向转换难题：

1. Chat Completions向上游Responses API做转换：messages数组映射为input数组，system消息迁移至instructions，相对容易实现。
2. Responses API向下转换成Chat Completions：会出现信息损失。Responses独有的reasoning推理项、多类型output item、任务状态，在Chat Completions没有对应的字段。只能做降级适配，部分元数据会丢失。

做协议转换不能只做简单字段拷贝，需要构建一套内部统一抽象层。定义通用内部请求、事件、响应结构体，再分别编写两套适配器，分别转换成Chat Completions格式和Responses格式。后续如果协议迭代升级，只修改适配器，不需要改动核心业务逻辑。在维护多厂商异构模型服务的时候，可以借助koalaapi这款API网关完成请求鉴权、流量路由，减少重复开发协议适配工作。

七、不同业务场景选型建议

优先沿用Chat Completions的场景

普通对话机器人、客服问答、存量老系统改造、大量第三方开源模型接入。该协议生态成熟，SDK、工具、文档资料充足，改造风险低。

优先选择Responses API的场景

全新开发Agent、代码智能体、多工具编排、长周期任务、多模态复杂工作流。它原生适配智能体执行链路，状态管理、工具调用、事件流更贴合业务需求。

重要提醒：Responses API属于较新规范，第三方兼容后端实现程度参差不齐。上线前需要完整测试previous_response_id、各类output item、流式事件是否全部正常工作。

八、迁移过程中高频踩坑清单

1. 直接复用旧解析逻辑：迁移Responses后仍然写死取第0项output拿文本，遇到工具调用、推理输出直接解析异常。
2. 忽略instructions字段：直接把instructions塞进input数组，破坏指令优先级，模型行为出现偏差。
3. 流式简单透传SSE：网关没有做事件解析转换，下游旧SDK无法识别Responses事件类型。
4. 高估previous_response_id兼容性：部分兼容实现不支持该字段，强行使用会上下文错乱。
5. 协议转换期望无损：Responses部分特有概念无法映射到Chat Completions，必须设计降级逻辑。

九、总结

Responses API代表OpenAI接口设计范式的转变：从单纯对话生成接口转向AI任务运行时接口。但这不代表Chat Completions会立刻淘汰。开发者需要根据业务类型做理性选择：存量系统不必盲目迁移，新建Agent类应用可以优先评估Responses能力。

对于API网关、中转平台，最佳实践是搭建内部统一抽象层，通过适配器模式同时兼容两套协议，处理双向协议转换与降级逻辑，以此应对未来接口迭代。无论选择哪一套协议，都需要充分测试工具调用、流式输出、多轮上下文，规避上线后才暴露的解析异常。

了解更多：https://koalaapi.com