Responses API 与 Chat Completions 有什么区别？

官方资料（2026-10-29 核对）：迁移到 Responses API · Create a response · Create chat completion · Conversation state · Streaming responses

一张表看懂核心区别

什么时候应该选 Responses API？

• 新项目：希望跟随 OpenAI 当前推荐的生成接口，减少未来二次迁移。
• 推理与多步骤工具：需要保留 typed reasoning、function call 或工具输出项，而不是只读取一段 assistant 文本。
• 托管工具：需要网页搜索、文件搜索等官方当前支持的工具，并接受其权限、价格与数据边界。
• 会话状态：希望通过 previous_response_id 快速串联回合，或用 Conversations API 管理持久会话对象。
• 统一多模态输入：想在同一套 Item 模型中处理文本、图片、文件及工具结果。

如果你只需要简单单轮文本生成，Responses 也能保持很轻；不要为了“Agent”一词加入不需要的工具和状态。

什么时候继续使用 Chat Completions？

• 现有流程稳定、监控完善，近期没有 Responses 独有能力需求。
• 大量业务代码、测试与数据结构依赖 messages、choices 和 delta。
• 第三方网关或内部 SDK 尚未完整支持 Responses 的 Items、事件和工具形状。
• 迁移风险大于当前收益，需要先做双写或小比例灰度。

继续使用不等于永远不评估。把迁移拆成单轮文本、结构化输出、函数调用、流式和多轮状态五类，逐项验证，比一次性替换更安全。

最小请求对照：不是只换一个 URL

Chat Completions

import OpenAI from "openai";
const client = new OpenAI();

const completion = await client.chat.completions.create({
  model: "YOUR_MODEL",
  messages: [
    { role: "developer", content: "回答要简洁。" },
    { role: "user", content: "解释幂等性。" }
  ]
});

console.log(completion.choices[0].message.content);

Responses API

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "YOUR_MODEL",
  instructions: "回答要简洁。",
  input: "解释幂等性。"
});

console.log(response.output_text);

output_text 适合只取最终文本。使用推理、工具或多模态输出时，应遍历 response.output，根据 Item 的 type 分别处理 message、reasoning、function_call 等类型，不能假设数组里只有 assistant message。

多轮对话：状态由谁管理？

Responses 提供三种常见方式，选择前先明确保留、成本和可观测性要求。

1. previous_response_id：把上一条 Response ID 传给下一条，适合快速串联；但顶层 instructions 不会自动继承，需要每次重发。
2. 手动回放 Items：把之前的 output Items 放入下一次 input，适合自己裁剪上下文或采用无状态处理；必须保留工具、函数输出和需要的 reasoning Items。
3. Conversations API：需要持久会话对象时使用；应单独设计生命周期、删除、访问控制与数据保留。

previous_response_id 不是省 Token 开关。官方说明链中此前输入 Token 仍作为输入计费。应使用 API Usage 比较实际 Token 与成本，而不是只看请求体是否变短。

函数调用与工具迁移的三个坑

1. 定义形状变化：Chat Completions 与 Responses 的函数工具配置结构不同，不能原样复制后假设等价。
2. 调用和结果是两个 Item：Responses 用 function_call 输出项与 function_call_output 输入项配对，并通过 call_id 关联。
3. 不要丢失中间 Items：手动维护上下文时，遗漏 reasoning、工具调用或工具结果会破坏后续回合。

迁移前为每个函数准备固定测试：参数 Schema 校验、拒绝路径、超时、重复执行和幂等键。端点切换成功但工具副作用重复，仍然是失败迁移。

Structured Outputs 和 Streaming 怎么改？

结构化输出

Chat Completions 常把 JSON Schema 放在 response_format；Responses 使用 text.format。迁移后要重新验证 Schema、拒答、截断和解析错误，不能只检查 HTTP 200。

流式输出

Chat Completions 的处理器通常读 choices[0].delta。Responses 会发出带类型的 SSE 事件，例如 response.created、response.output_text.delta、response.completed 和 error。前端或代理应按 event.type 分支，并处理连接中断后的未完成状态。

const stream = await client.responses.create({
  model: "YOUR_MODEL",
  input: "用三点解释缓存。",
  stream: true
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
  if (event.type === "error") {
    // 记录 request id、错误类型和可安全重试的边界
  }
}

可回滚的迁移步骤

1. 先盘点：列出模型、消息角色、函数、Structured Outputs、Streaming、n、日志和状态保存方式。
2. 选单轮文本流：从无工具、无流式的低风险场景开始，建立 Responses 基线。
3. 改输入输出：把 messages 映射为 input/instructions，把 choices 读取改为 output_text 或 typed Items。
4. 明确状态：选择 previous_response_id、手动 Items 或 Conversations；写清保留和删除策略。
5. 逐类迁移：结构化输出、函数调用、托管工具和流式处理分别验收。
6. 双端对比：使用同一脱敏测试集比较答案、延迟、Token、工具成功率、错误率和费用。
7. 小流量灰度：设置可快速回滚的功能开关，不在同一发布中同时更换模型、Prompt 和端点。
8. 扩量后复盘：查看 Usage、429 和 5xx/超时，确认限额与重试没有恶化。

迁移验收清单

• 每条路径都能读取正确的最终文本或 typed Items。
• 系统/开发者 instructions 在每次需要的请求中出现。
• 函数结果使用正确 call_id，副作用有幂等保护。
• Structured Outputs 使用正确字段并通过 Schema 测试。
• 流式消费者处理 completed、error 和断线。
• 日志记录端点、模型、response/request ID、延迟、usage 与错误类型，但不记录 Secret。
• 同一模型、同一测试集完成质量、Token、延迟与成本对比。
• 保留 Chat Completions 回滚路径，直到 Responses 流量稳定。

常见问题

结构化输出字段已经迁移，下一步还要选模式：查看 Structured Outputs 与 JSON mode 区别和完整 Schema 配置。