从 Chat Completions 迁移到 OpenAI Responses API：关键差异与落地清单

本文是对 OpenAI 官方迁移文档的中文技术导读，重点放在工程决策与落地检查，不是原文翻译。

OpenAI 已将 Responses API 定位为新项目的推荐接口。它不是简单地把请求路径从 /chat/completions 换成 /responses，而是把模型输出、推理、工具调用和多轮状态统一成一组有类型的 Items。

为什么要迁移

Responses API 把文本、函数调用、函数结果、推理项等拆成独立对象。相比把信息都塞进 message，这种结构更适合 Agent：一次请求中可以连续调用网页搜索、文件搜索、代码解释器、远程 MCP 或自定义函数。

对普通文本生成，最小调用非常简单：

import OpenAI from 'openai'
 
const client = new OpenAI()
const response = await client.responses.create({
  model: 'gpt-5',
  input: '用三点解释向量检索'
})
 
console.log(response.output_text)

三个真正需要改的地方

1. 入口改变：生成请求改到 responses.create。
2. 输出改变：不要再假设结果一定在 choices[0].message，应读取带类型的 output；纯文本可使用 SDK 的 output_text 辅助属性。
3. 状态策略改变：可以使用 previous_response_id 串联多轮，也可以使用 Conversations API；对隐私敏感的业务则应明确设置 store: false。

迁移顺序建议

• 先迁移无工具的文本接口，并为新旧输出建立快照测试。
• 再迁移 Structured Outputs：Responses 中配置位置改为 text.format。
• 最后迁移函数调用，按 Item 类型处理 function_call 与 function_call_output。
• 对每个工具设置超时、参数校验、幂等键和审计日志。

常见误区

• 只替换 endpoint，却仍按 Chat Completions 的 choices 结构解析。
• 忽略默认存储行为，没有根据合规要求显式选择 store。
• 把模型给出的函数参数当成可信输入，跳过业务校验。
• 多轮对话同时使用手工历史和 previous_response_id，导致上下文重复。

如果现有系统稳定且只做简单聊天，不必在一天内重写；更稳妥的方式是按业务流逐个迁移，并保留一段时间的双路回归测试。

原文：OpenAI — Migrate to the Responses API