OpenAI Responses API迁移指南：Chat Completions升级

引言

近半年，大量基于OpenAI接口开发的应用项目陆续遇到一类共性问题：代码逻辑完全符合文档描述，但调用/chat/completions接口时，随机抛出unexpected endpoint报错。根源在于OpenAI正在进行接口范式升级，从传统Chat Completions逐步迁移至全新Responses接口。本次迭代并非简单更换API端点，而是整套对话交互模型的底层重构。

本文梳理Chat Completions的发展历程、能力边界，对比两套接口在请求结构、流式输出、工具调用、状态管理上的核心差异，提供可落地的迁移步骤、代码示例、兼容层设计方案，同时梳理开源框架适配现状与常见故障排查方案，适合存量项目做接口迁移评估，也可供新开发者理解Responses接口的设计逻辑。

1. 演进背景：接口规范迭代的底层逻辑

1.1 Completions到Chat Completions的技术迭代

OpenAI最早对外提供的文本生成接口为POST /v1/completions。该接口仅支持纯文本prompt输入，模型返回一段连续文本，没有对话、多轮上下文、系统指令等概念，属于基础文本补全能力。

后续迭代推出Chat Completions，端点为POST /v1/chat/completions。该接口引入messages消息数组，支持system、user、assistant三类角色，多轮对话依靠在请求体中完整携带全部历史消息实现。自GPT-3.5发布之后，Chat Completions迅速成为行业事实标准，各类服务SDK、前端框架、开源API网关均围绕该接口完成适配，支撑了OpenAI生态爆发阶段绝大多数业务场景。

1.2 Chat Completions的优势与固有局限

Chat Completions的核心设计思路，是将对话抽象为消息列表的输入输出模型。对于普通对话场景，这套模型足够简洁易用。但面向Agent开发场景，接口短板会集中暴露。

1. 状态管理压力：多轮对话的上下文全部由客户端维护，每次请求都需要携带完整历史消息，token消耗随对话轮次持续上涨。
2. 工具调用流程繁琐：function calling需要在请求内声明tools，模型返回tool_calls；客户端执行函数后，再以tool角色消息回填至消息列表，多轮工具调用时消息拼接极易出错。
3. 内置能力缺失：联网检索、代码执行、多模态操作等高级能力，需要开发者自行对接独立接口，没有统一的调用规范。

1.3 Responses API的设计目标

2024年底，OpenAI正式推出Responses API，端点为POST /v1/responses。官方文档已经将新功能入口全部切换至该接口；Chat Completions接口仍会持续维护，但不再作为主要演进方向。

Responses接口并非简单的Chat Completions升级版。它把对话闭环迁移至服务端维护：引入response_id与previous_response_id机制，由服务端保管对话状态；工具能力统一收纳至tools数组，web_search、code_interpreter、computer_use等内置工具可直接配置启用。
这套设计的核心目标，是完成从客户端“补全文本”到服务端“响应任务”的范式升级，专门适配Agent复杂任务，同时保留传统对话场景的兼容能力。

2. 核心差异拆解：从messages到input的范式切换

2.1 请求模型：messages变更为input

Chat Completions请求的核心载体是messages消息数组。

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "你是一名资深数据分析师"},
    {"role": "user", "content": "帮我分析这份销售数据的异常点"}
  ]
}

在Responses接口中，消息参数名称改为input，底层结构沿用消息数组的形式。

{
  "model": "gpt-4o",
  "input": [
    {"role": "system", "content": "你是一名资深数据分析师"},
    {"role": "user", "content": "帮我分析这份销售数据的异常点"}
  ]
}

这是官方设计的平滑迁移策略。简单对话场景，仅需要将messages字段替换为input即可完成基础调用。Responses额外新增instructions参数，可独立设置系统指令，效果等同于input内的system角色消息，但该参数不参与多轮状态传递，更适合固定角色设定。

> 注意优先级：当instructions和input中的system角色同时存在时，instructions优先级更高，容易覆盖原有角色设定，迁移时建议只保留其中一种写法。

2.2 响应模型：choices转变为output

Chat Completions返回多候选结构，模型回复内容读取路径为choices[0].message.content。
Responses接口返回output数组，数组内包含多种类型输出节点，文本回复放置在message类型节点内。官方SDK提供output_text快捷属性，直接读取模型输出文本，简化代码层级。

2.3 工具与内置能力整合，是最大变化点

Chat Completions实现function calling，需要在请求体声明tools，模型返回tool_calls；客户端执行业务函数后，再把结果以tool角色消息追加进messages数组。多轮工具调用场景，消息拼接逻辑复杂，很容易出现状态错乱。

Responses将工具调用做扁平化处理。开发者只需要在tools数组声明工具，模型完成工具调用后，客户端仅需要把工具结果作为新消息追加至下一轮input，配合previous_response_id，对话状态链由服务端维护。
内置工具使用更加便捷，例如联网检索能力，仅需要在tools数组添加{"type":"web_search"}，模型就会自动执行联网检索，无需开发者自行实现检索逻辑。Codex CLI等官方Agent工具，底层就是基于Responses接口构建。

2.4 流式协议与事件模型变更

Chat Completions流式返回数据块，每个chunk中模型文本增量存放在choices[0].delta.content。
Responses流式输出采用事件模型，文本增量通过response.output_text.delta事件返回。

Chat Completions流式示例：

# Chat Completions 流式调用
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "讲个冷笑话"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Responses流式示例：

# Responses 流式调用
stream = client.responses.create(
    model="gpt-4o",
    input=[{"role": "user", "content": "讲个冷笑话"}],
    stream=True
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

事件模型语义更清晰，但原有解析逻辑需要重写。下表为两套接口核心维度对比：

2.5 previous_response_id的使用逻辑

迁移过程中高频疑问，是previous_response_id的使用时机。单轮独立问答，不需要传入该参数；连续多轮对话场景，将上一轮返回的response_id传入下一次请求的previous_response_id。该方案可以降低长对话的token消耗，服务端直接引用历史状态，不需要每次完整回传全部对话文本。

3. 迁移实操：从Chat Completions平滑过渡到Responses

3.1 最简无工具迁移路径

仅对话、不涉及工具调用，不依赖流式特殊事件时，迁移成本很低。以OpenAI Python SDK为例，仅需要把chat.completions.create替换为responses.create，入参messages改为input，读取内容从choices[0].message.content改为output_text。

3.2 工具调用迁移细节

Chat Completions工具声明存在多层嵌套，function字段包裹函数描述。Responses对结构扁平化，去掉外层function层级。
Chat Completions工具定义示例：

{
  "type": "function",
  "function": {
    "name": "query_sales",
    "description": "查询销售数据",
    "parameters": {
      "type": "object",
      "properties": {
        "month": {"type": "string"}
      }
    }
  }
}

Responses扁平化工具定义：

{
  "type": "function",
  "name": "query_sales",
  "description": "查询销售数据",
  "parameters": {
    "type": "object",
    "properties": {
      "month": {"type": "string"}
    }
  }
}

结构简化，但工具调用的响应解析逻辑改动更大。模型返回tool_call，客户端执行本地函数，再把tool_result追加至下一轮input数组。

3.3 流式事件重构建议

流式迁移没有简化方案，事件解析代码必须重写。Chat Completions流式逻辑围绕choices.delta构建；Responses会推送多种事件类型，包含response.created、response.in_progress、response.completed等。开发阶段只监听业务需要的事件，其余类型直接忽略，精简代码逻辑。
Responses的response.usage事件会返回完整token统计，相比客户端逐块统计token，数据更加精准，适合业务用量统计场景。

3.4 推荐构建兼容适配层

大规模业务不建议一次性全量替换接口，推荐开发适配层，对外统一业务接口，内部通过开关切换Chat Completions与Responses。
适配层核心流程：请求参数标准化、端点分发、响应解析归一化、异常捕获。对外暴露统一的ask方法，配置use_responses开关，开启时走Responses链路，关闭则沿用旧接口。这种方案适合迭代周期短、流量大的生产环境，切换出现问题可以快速回滚。

3.5 迁移后的回归测试清单

迁移完成不能仅验证基础对话。需要覆盖多轮上下文继承、系统指令稳定性、工具调用结果回传、流式输出结束判断、token统计准确性、异常捕获。每次模型版本升级，也需要重复执行回归测试。

4. 开源兼容现状：不是简单改名，而是生态重构

4.1 SDK与网关的开放边界

OpenAI官方SDK已经完成Responses适配，但接口规范本身属于开放文档，协议字段、事件流定义由OpenAI主导。开源社区可以封装SDK、修改扩展，但是底层协议规则无法自主变更。很多开源框架滞后于官方更新，升级SDK之后依然会遇到unexpected endpoint报错。

4.2 主流开源框架适配进度

LangChain、LlamaIndex在2025年上半年逐步增加Responses支持，但默认调用仍然优先使用Chat Completions。大量项目直接硬编码接口路径，即使开发者写好Responses调用代码，网关层识别/v1/responses路径失败，请求依然会被拦截。
在API网关层面，不同网关对两套接口的兼容程度存在差异，koalaapi作为API gateway，可帮助业务统一封装新旧接口路由，降低项目在接口迁移阶段的适配成本。

4.3 本地模型的兼容局限

Ollama、vLLM、LM Studio等本地推理框架，对外主流兼容接口依旧是Chat Completions格式。Responses包含状态管理、内置工具、事件流整套体系，本地框架完整实现这套规范成本很高。
混合部署场景建议：本地模型继续使用Chat Completions，云端OpenAI模型切换至Responses，依靠网关做路由分发，这是现阶段成本最低的方案。

4.4 选型建议

选型时不能只看是否支持OpenAI，要区分是本地模型、云端OpenAI，确认业务是否需要内置工具、状态托管。中小型项目直接使用官方SDK即可；大型平台、多API接入场景，可考虑API网关做统一接入层。

5. 常见问题与排查方案

5.1 unexpected endpoint 报错

该报错是迁移阶段最高频问题，常见诱因：SDK版本老旧、网关仅支持旧接口、自定义转发路由未配置/v1/responses路径。
排查顺序：打印请求完整URL，确认端点路径；升级OpenAI SDK至最新版本；查看网关日志，确认上游是否支持新接口。自建网关场景，需要新增/v1/responses路由转发，未支持的场景可做流量降级。

5.2 Codex CLI安装依赖问题

Windows平台安装Codex CLI容易触发依赖缺失报错。优先使用npm重装，在项目目录手动安装对应可选依赖包；网络异常场景切换npm镜像源，安装完成后验证codex命令。

5.3 API Key权限与安全规范

API Key不建议直接交付前端，密钥放置在服务端环境变量，前端请求经过后端中转。使用独立密钥做限流、配额管控，避免密钥泄露带来的资源滥用风险。

5.4 其他高频报错

maximum context length exceeded：检查是否在Responses长对话中重复传入历史消息，previous_response_id启用后无需重复携带全部上下文。
流式连接中断：事件流存在超时机制，需要设置心跳保活，捕获连接断开异常，做好重试逻辑。

6. 迁移策略总结

Responses接口是面向Agent场景的新一代接口，具备服务端状态管理、原生工具调用、事件流式输出等优势。但对于纯对话业务，Chat Completions接口短期内仍会稳定可用，无需强制迁移。
推荐分阶段策略：优先评估业务是否用到内置工具、长对话状态托管；有对应需求则逐步迁移，搭建适配层做灰度切换；仅简单对话场景，可以维持原有Chat Completions方案，等待业务迭代再做升级。接口迁移的核心，不是替换接口地址，而是理解两套接口背后对话范式的变化。

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