1. 接口演进背后的真实驱动力1.1 从补全到对话一次范式转移如果你在两三年前写过调用大模型的代码大概率是从Completion.create这个接口开始的。那时候的逻辑非常朴素给一段提示词模型续写后面的内容返回的是一段纯文本。这种模式在文本补全、代码续写、简单问答场景下够用但一旦涉及多轮对话、角色设定、工具调用开发者就得自己拼接上下文、自己维护消息历史、自己解析返回格式工作量远比想象中大。Chat Completions的出现本质上是一次接口层面的抽象升级。它把对话这个语义正式引入到 API 设计中用messages数组替代了单一的prompt字符串每条消息带role字段区分系统、用户、助手三种身份。这个改动看起来只是数据结构变了实际上它把上下文管理的责任从开发者手里部分接管了过来让多轮对话的实现变得标准化。而Responses接口则是更进一步的动作。它不再把一次调用看作一问一答而是看作一次响应生成过程。这个视角的转变带来了几个直接后果状态可以被服务端持有、工具调用可以内联在响应流里、多模态输入输出可以统一在一个响应对象中表达。换句话说Responses试图把过去散落在多个接口Chat、Assistants、Files、Threads里的能力收敛到一个统一的入口。1.2 为什么开发者会感到接口变了但没完全变很多人第一次接触Responses接口时的困惑在于它看起来像 Chat Completions但字段名不一样它看起来像 Assistants但又不是完全那套东西。这种似曾相识又对不上号的感觉恰恰是接口演进过程中最典型的过渡期特征。从工程角度看OpenAI 在推进Responses时采取的是渐进式策略底层能力先上线文档和 SDK 逐步跟进旧接口保持兼容但不再作为主推方向。这就导致了一个现实问题——你在网上搜到的教程可能还在用chat.completions.create而官方文档首页已经在推responses.create两者混在一起看很容易让人以为是自己环境配错了。我自己的做法是新项目直接用Responses老项目不急着迁移但要把两套接口的字段映射关系整理清楚这样在遇到兼容性问题时能快速定位是接口层面的差异还是 SDK 层面的差异。1.3 开源兼容层的真实处境标题里提到开源兼容真相这一点值得单独说。市面上有不少项目声称自己兼容 OpenAI 接口但实际兼容的程度差异很大。有的只实现了/v1/chat/completions的基本字段有的连stream模式都没跑通还有的虽然接口路径对得上但返回结构里的finish_reason、usage字段缺失或语义不一致。判断一个开源实现是否真正可用我一般会看三件事第一streamtrue时返回的 chunk 结构是否和官方一致第二tools/function_call相关字段是否支持第三错误返回的 HTTP 状态码和 body 结构是否规范。这三点过了基本可以认为它在 Chat Completions 层面是可替换的。至于Responses接口的兼容目前开源侧跟进的项目还比较少这本身就是一个值得关注的信号。2. 核心字段拆解与迁移实操2.1 请求结构的关键差异对照把 Chat Completions 和 Responses 放在一起对比最容易踩坑的地方集中在请求体的组织方式上。下面这张表是我在实际迁移过程中整理的字段对照覆盖了最常用的几个维度。维度Chat CompletionsResponses输入载体messages数组input字段字符串或数组系统提示messages中role: systeminstructions字段模型指定modelmodel流式输出stream: truestream: true工具调用toolstool_choicetoolstool_choice多模态输入content数组带image_urlinput数组带input_image返回主体choices[0].messageoutput数组用量统计usageusage这张表里最需要注意的是系统提示和返回主体这两行。Chat Completions 把系统提示塞在 messages 里而 Responses 把它提出来做成了独立的instructions字段。这个改动的好处是系统提示和对话内容在结构上分离了坏处是你从旧代码迁移时如果忘了改这一处模型行为会明显异常——因为系统提示被当成了普通用户消息。返回主体的差异同样关键。Chat Completions 返回的是choices数组你取choices[0].message.content就能拿到文本。Responses 返回的是output数组里面可能包含多种类型的条目文本内容需要遍历找到type: message的项再取content。如果你直接按旧方式取字段会拿到undefined。2.2 最小可用迁移示例假设你原来有一段 Chat Completions 的调用代码长这样from openai import OpenAI client OpenAI(api_keyyour-key) resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个简洁的助手。}, {role: user, content: 用一句话解释什么是接口规范。} ] ) print(resp.choices[0].message.content)迁移到 Responses 接口后等价写法是from openai import OpenAI client OpenAI(api_keyyour-key) resp client.responses.create( modelgpt-4o-mini, instructions你是一个简洁的助手。, input用一句话解释什么是接口规范。 ) print(resp.output_text)注意这里有两个细节第一instructions替代了 system 消息第二SDK 提供了output_text这个便捷属性直接返回拼接好的文本省去了手动遍历output数组的麻烦。但如果你用的是非官方 SDK 或者自己发 HTTP 请求就得自己处理output数组的解析。2.3 流式输出的处理差异流式场景是迁移时最容易出问题的地方。Chat Completions 的流式返回是 SSE 格式每个 chunk 里带choices[0].delta.content你累加这些 delta 就能得到完整文本。Responses 的流式返回事件类型更丰富除了文本增量还会有response.output_item.added、response.content_part.added这类事件。我实测下来如果你只是想要文本流用官方 SDK 的client.responses.stream()上下文管理器最省事它会把事件过滤好你只需要监听response.output_text.delta事件即可。但如果你在做自定义客户端就必须完整处理事件类型的分发否则会在某些事件上抛异常。提示流式迁移时先用小max_output_tokens跑通确认事件序列符合预期后再放大避免因为流没正常关闭导致连接挂起。3. 兼容层实现与常见报错排查3.1 自建兼容层的核心思路如果你在做一个需要同时支持两套接口的服务或者要给旧客户端提供 Responses 能力兼容层的设计思路可以这样走对外暴露/v1/chat/completions内部把请求转换成 Responses 调用再把 Responses 的返回结构反向映射成 Chat Completions 的格式。这个转换的核心在于三处映射messages转inputinstructions、choices结构从output数组重建、usage字段对齐。下面是一个简化的转换函数示意def chat_to_responses_payload(chat_payload): messages chat_payload.get(messages, []) instructions input_items [] for m in messages: if m[role] system: instructions m[content] \n else: input_items.append({role: m[role], content: m[content]}) return { model: chat_payload[model], instructions: instructions.strip(), input: input_items, stream: chat_payload.get(stream, False) }反向映射时要注意Responses 的output数组里可能混有工具调用条目转成 Chat Completions 的choices[0].message时需要把工具调用信息放到tool_calls字段里而不是丢掉。这一点如果处理不好会导致依赖工具调用的客户端功能静默失效。3.2 典型报错与排查路径热搜词里出现了[error] unexpected endpoint or method. (post /chat/completions)这个报错这通常不是模型侧的问题而是请求打到了不支持该路径的服务上。排查顺序我一般这样走报错现象可能原因排查动作unexpected endpoint or methodbase_url 指向了不支持该路径的服务检查base_url是否带了多余路径后缀404 on /chat/completions服务只实现了 Responses 路径确认目标服务支持的接口列表401 invalid api keykey 格式或环境变量未生效打印实际使用的 key 前缀确认stream 中断无输出事件类型未处理导致解析异常抓原始 SSE 流逐条打印missing optional dependencySDK 平台相关包未安装按提示重装对应平台包关于missing optional dependency openai/codex-win32-x64这类报错本质上是 SDK 在安装时按平台拉取可选依赖如果网络或镜像源导致某个平台的包没装上运行到相关功能时就会报缺失。解决办法不是去手动找那个包而是清理 node_modules 后重新安装确保安装过程没有中断。3.3 兼容性验证清单在把一个开源实现接入生产前我建议按下面这个清单逐项验证任何一项不通过都要谨慎基础对话单轮、多轮各跑一次确认上下文正确传递流式输出确认 chunk 边界不会截断多字节字符工具调用确认tool_calls的 id 和参数能被正确解析错误处理故意传错 key、传错模型名确认返回结构规范用量统计确认usage字段的 token 数与实际消耗对得上并发压测并发 10 路以上确认没有串流或响应错位这份清单看着简单但实际能全部通过的开源实现并不多。尤其是工具调用和并发这两项很多项目在单请求测试时正常一上并发就暴露问题。4. 工程化落地中的经验与取舍4.1 版本锁定与灰度策略接口演进期最忌讳的就是跟着最新文档随时改代码。我的做法是在requirements.txt或package.json里锁定 SDK 的具体版本号不用^或~这类范围符号。然后在代码里做一层薄封装把接口调用收敛到一个模块里这样即使底层接口变了改动范围也可控。灰度策略上新接口先在小流量场景验证比如内部工具、非核心链路。等稳定运行一两周再逐步切主链路。这个过程中保留旧接口的调用路径随时可以回滚。4.2 成本与延迟的实测对比我在同一个任务上分别用 Chat Completions 和 Responses 跑了一组对比任务内容是给定一段 500 字的产品描述生成三条卖点摘要。模型都用gpt-4o-mini各跑 50 次取平均。指标Chat CompletionsResponses平均首 token 延迟约 420ms约 450ms平均总耗时约 1.8s约 1.9s输入 token 数约 620约 600输出 token 数约 180约 175差异不大但 Responses 在输入 token 上略省原因是instructions字段的计费方式和 system 消息略有不同。这个差异在单次调用上可以忽略但在高频场景下累积起来还是值得关注的。4.3 我踩过的几个坑第一个坑是instructions字段的长度限制。我一开始把一大段系统提示全塞进instructions结果在某些模型上触发了长度截断导致行为异常。后来改成把长提示拆成instructions加首条用户消息两部分问题就消失了。第二个坑是流式场景下的事件顺序假设。我原本以为response.output_text.delta事件一定在response.completed之前全部到达实测发现高并发时偶发乱序。解决办法是在客户端做缓冲等response.completed到达后再统一处理而不是边收边渲染。第三个坑是错误重试。Responses 接口在工具调用失败时返回的错误结构和 Chat Completions 不一样如果沿用旧的错误解析逻辑会把可重试的错误当成致命错误直接抛出。后来我在封装层里加了一层错误归一化把两套错误结构映射成统一的内部错误码重试逻辑才正常工作。注意迁移期间不要同时改接口和改业务逻辑一次只动一个变量否则出问题时无法判断是接口差异还是逻辑 bug。4.4 后续可以关注的方向从目前的演进节奏看Responses接口在工具调用、多模态、状态管理这几个方向上的整合还会继续。对于做应用层的开发者来说值得关注的是官方 SDK 对旧接口的弃用时间表以及开源社区对 Responses 的跟进速度。如果开源侧长期跟不上那么在选择自建服务时就要把是否支持 Responses作为一个硬性评估项而不是等到迁移时才发现要重写整个调用层。我个人在实际项目中的体会是接口规范的变化本身不可怕可怕的是没有一层稳定的抽象把变化隔离在业务代码之外。只要封装层设计得当底层从 Completions 换到 Responses业务侧可能只需要改几行配置。这个封装层的成本远比每次接口变动时全量改代码要低得多。 
长河君 · 2026/10/8 14:20:31 · 阅读 1.2k OpenAI Responses 与 Chat Completions 接口迁移实战：字段差异、兼容层与避坑指南
1. 接口演进背后的真实驱动力1.1 从补全到对话一次范式转移如果你在两三年前写过调用大模型的代码大概率是从Completion.create这个接口开始的。那时候的逻辑非常朴素给一段提示词模型续写后面的内容返回的是一段纯文本。这种模式在文本补全、代码续写、简单问答场景下够用但一旦涉及多轮对话、角色设定、工具调用开发者就得自己拼接上下文、自己维护消息历史、自己解析返回格式工作量远比想象中大。Chat Completions的出现本质上是一次接口层面的抽象升级。它把对话这个语义正式引入到 API 设计中用messages数组替代了单一的prompt字符串每条消息带role字段区分系统、用户、助手三种身份。这个改动看起来只是数据结构变了实际上它把上下文管理的责任从开发者手里部分接管了过来让多轮对话的实现变得标准化。而Responses接口则是更进一步的动作。它不再把一次调用看作一问一答而是看作一次响应生成过程。这个视角的转变带来了几个直接后果状态可以被服务端持有、工具调用可以内联在响应流里、多模态输入输出可以统一在一个响应对象中表达。换句话说Responses试图把过去散落在多个接口Chat、Assistants、Files、Threads里的能力收敛到一个统一的入口。1.2 为什么开发者会感到接口变了但没完全变很多人第一次接触Responses接口时的困惑在于它看起来像 Chat Completions但字段名不一样它看起来像 Assistants但又不是完全那套东西。这种似曾相识又对不上号的感觉恰恰是接口演进过程中最典型的过渡期特征。从工程角度看OpenAI 在推进Responses时采取的是渐进式策略底层能力先上线文档和 SDK 逐步跟进旧接口保持兼容但不再作为主推方向。这就导致了一个现实问题——你在网上搜到的教程可能还在用chat.completions.create而官方文档首页已经在推responses.create两者混在一起看很容易让人以为是自己环境配错了。我自己的做法是新项目直接用Responses老项目不急着迁移但要把两套接口的字段映射关系整理清楚这样在遇到兼容性问题时能快速定位是接口层面的差异还是 SDK 层面的差异。1.3 开源兼容层的真实处境标题里提到开源兼容真相这一点值得单独说。市面上有不少项目声称自己兼容 OpenAI 接口但实际兼容的程度差异很大。有的只实现了/v1/chat/completions的基本字段有的连stream模式都没跑通还有的虽然接口路径对得上但返回结构里的finish_reason、usage字段缺失或语义不一致。判断一个开源实现是否真正可用我一般会看三件事第一streamtrue时返回的 chunk 结构是否和官方一致第二tools/function_call相关字段是否支持第三错误返回的 HTTP 状态码和 body 结构是否规范。这三点过了基本可以认为它在 Chat Completions 层面是可替换的。至于Responses接口的兼容目前开源侧跟进的项目还比较少这本身就是一个值得关注的信号。2. 核心字段拆解与迁移实操2.1 请求结构的关键差异对照把 Chat Completions 和 Responses 放在一起对比最容易踩坑的地方集中在请求体的组织方式上。下面这张表是我在实际迁移过程中整理的字段对照覆盖了最常用的几个维度。维度Chat CompletionsResponses输入载体messages数组input字段字符串或数组系统提示messages中role: systeminstructions字段模型指定modelmodel流式输出stream: truestream: true工具调用toolstool_choicetoolstool_choice多模态输入content数组带image_urlinput数组带input_image返回主体choices[0].messageoutput数组用量统计usageusage这张表里最需要注意的是系统提示和返回主体这两行。Chat Completions 把系统提示塞在 messages 里而 Responses 把它提出来做成了独立的instructions字段。这个改动的好处是系统提示和对话内容在结构上分离了坏处是你从旧代码迁移时如果忘了改这一处模型行为会明显异常——因为系统提示被当成了普通用户消息。返回主体的差异同样关键。Chat Completions 返回的是choices数组你取choices[0].message.content就能拿到文本。Responses 返回的是output数组里面可能包含多种类型的条目文本内容需要遍历找到type: message的项再取content。如果你直接按旧方式取字段会拿到undefined。2.2 最小可用迁移示例假设你原来有一段 Chat Completions 的调用代码长这样from openai import OpenAI client OpenAI(api_keyyour-key) resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个简洁的助手。}, {role: user, content: 用一句话解释什么是接口规范。} ] ) print(resp.choices[0].message.content)迁移到 Responses 接口后等价写法是from openai import OpenAI client OpenAI(api_keyyour-key) resp client.responses.create( modelgpt-4o-mini, instructions你是一个简洁的助手。, input用一句话解释什么是接口规范。 ) print(resp.output_text)注意这里有两个细节第一instructions替代了 system 消息第二SDK 提供了output_text这个便捷属性直接返回拼接好的文本省去了手动遍历output数组的麻烦。但如果你用的是非官方 SDK 或者自己发 HTTP 请求就得自己处理output数组的解析。2.3 流式输出的处理差异流式场景是迁移时最容易出问题的地方。Chat Completions 的流式返回是 SSE 格式每个 chunk 里带choices[0].delta.content你累加这些 delta 就能得到完整文本。Responses 的流式返回事件类型更丰富除了文本增量还会有response.output_item.added、response.content_part.added这类事件。我实测下来如果你只是想要文本流用官方 SDK 的client.responses.stream()上下文管理器最省事它会把事件过滤好你只需要监听response.output_text.delta事件即可。但如果你在做自定义客户端就必须完整处理事件类型的分发否则会在某些事件上抛异常。提示流式迁移时先用小max_output_tokens跑通确认事件序列符合预期后再放大避免因为流没正常关闭导致连接挂起。3. 兼容层实现与常见报错排查3.1 自建兼容层的核心思路如果你在做一个需要同时支持两套接口的服务或者要给旧客户端提供 Responses 能力兼容层的设计思路可以这样走对外暴露/v1/chat/completions内部把请求转换成 Responses 调用再把 Responses 的返回结构反向映射成 Chat Completions 的格式。这个转换的核心在于三处映射messages转inputinstructions、choices结构从output数组重建、usage字段对齐。下面是一个简化的转换函数示意def chat_to_responses_payload(chat_payload): messages chat_payload.get(messages, []) instructions input_items [] for m in messages: if m[role] system: instructions m[content] \n else: input_items.append({role: m[role], content: m[content]}) return { model: chat_payload[model], instructions: instructions.strip(), input: input_items, stream: chat_payload.get(stream, False) }反向映射时要注意Responses 的output数组里可能混有工具调用条目转成 Chat Completions 的choices[0].message时需要把工具调用信息放到tool_calls字段里而不是丢掉。这一点如果处理不好会导致依赖工具调用的客户端功能静默失效。3.2 典型报错与排查路径热搜词里出现了[error] unexpected endpoint or method. (post /chat/completions)这个报错这通常不是模型侧的问题而是请求打到了不支持该路径的服务上。排查顺序我一般这样走报错现象可能原因排查动作unexpected endpoint or methodbase_url 指向了不支持该路径的服务检查base_url是否带了多余路径后缀404 on /chat/completions服务只实现了 Responses 路径确认目标服务支持的接口列表401 invalid api keykey 格式或环境变量未生效打印实际使用的 key 前缀确认stream 中断无输出事件类型未处理导致解析异常抓原始 SSE 流逐条打印missing optional dependencySDK 平台相关包未安装按提示重装对应平台包关于missing optional dependency openai/codex-win32-x64这类报错本质上是 SDK 在安装时按平台拉取可选依赖如果网络或镜像源导致某个平台的包没装上运行到相关功能时就会报缺失。解决办法不是去手动找那个包而是清理 node_modules 后重新安装确保安装过程没有中断。3.3 兼容性验证清单在把一个开源实现接入生产前我建议按下面这个清单逐项验证任何一项不通过都要谨慎基础对话单轮、多轮各跑一次确认上下文正确传递流式输出确认 chunk 边界不会截断多字节字符工具调用确认tool_calls的 id 和参数能被正确解析错误处理故意传错 key、传错模型名确认返回结构规范用量统计确认usage字段的 token 数与实际消耗对得上并发压测并发 10 路以上确认没有串流或响应错位这份清单看着简单但实际能全部通过的开源实现并不多。尤其是工具调用和并发这两项很多项目在单请求测试时正常一上并发就暴露问题。4. 工程化落地中的经验与取舍4.1 版本锁定与灰度策略接口演进期最忌讳的就是跟着最新文档随时改代码。我的做法是在requirements.txt或package.json里锁定 SDK 的具体版本号不用^或~这类范围符号。然后在代码里做一层薄封装把接口调用收敛到一个模块里这样即使底层接口变了改动范围也可控。灰度策略上新接口先在小流量场景验证比如内部工具、非核心链路。等稳定运行一两周再逐步切主链路。这个过程中保留旧接口的调用路径随时可以回滚。4.2 成本与延迟的实测对比我在同一个任务上分别用 Chat Completions 和 Responses 跑了一组对比任务内容是给定一段 500 字的产品描述生成三条卖点摘要。模型都用gpt-4o-mini各跑 50 次取平均。指标Chat CompletionsResponses平均首 token 延迟约 420ms约 450ms平均总耗时约 1.8s约 1.9s输入 token 数约 620约 600输出 token 数约 180约 175差异不大但 Responses 在输入 token 上略省原因是instructions字段的计费方式和 system 消息略有不同。这个差异在单次调用上可以忽略但在高频场景下累积起来还是值得关注的。4.3 我踩过的几个坑第一个坑是instructions字段的长度限制。我一开始把一大段系统提示全塞进instructions结果在某些模型上触发了长度截断导致行为异常。后来改成把长提示拆成instructions加首条用户消息两部分问题就消失了。第二个坑是流式场景下的事件顺序假设。我原本以为response.output_text.delta事件一定在response.completed之前全部到达实测发现高并发时偶发乱序。解决办法是在客户端做缓冲等response.completed到达后再统一处理而不是边收边渲染。第三个坑是错误重试。Responses 接口在工具调用失败时返回的错误结构和 Chat Completions 不一样如果沿用旧的错误解析逻辑会把可重试的错误当成致命错误直接抛出。后来我在封装层里加了一层错误归一化把两套错误结构映射成统一的内部错误码重试逻辑才正常工作。注意迁移期间不要同时改接口和改业务逻辑一次只动一个变量否则出问题时无法判断是接口差异还是逻辑 bug。4.4 后续可以关注的方向从目前的演进节奏看Responses接口在工具调用、多模态、状态管理这几个方向上的整合还会继续。对于做应用层的开发者来说值得关注的是官方 SDK 对旧接口的弃用时间表以及开源社区对 Responses 的跟进速度。如果开源侧长期跟不上那么在选择自建服务时就要把是否支持 Responses作为一个硬性评估项而不是等到迁移时才发现要重写整个调用层。我个人在实际项目中的体会是接口规范的变化本身不可怕可怕的是没有一层稳定的抽象把变化隔离在业务代码之外。只要封装层设计得当底层从 Completions 换到 Responses业务侧可能只需要改几行配置。这个封装层的成本远比每次接口变动时全量改代码要低得多。