OpenAI 在 2025 年 3 月公开 Responses API。迁移的重点不是把 endpoint 名称替换掉，而是接受新的响应结构：输入可从简单字符串开始，输出由一组 typed items 组成，SDK 的 output_text 是读取文本的便利属性，多轮状态则需要明确选择由服务端响应链或应用自身保存。

先锁定现有行为

迁移前为 Chat Completions 路径保存一组代表性评测：普通回答、拒答、空输出、超时和超长输入。记录模型快照或稳定模型名、system/developer 指令、温度等参数、最大输出与错误处理。不要同时换模型、改 prompt、引入工具并改 API，否则结果变化无法归因。

最小 Python 请求可以保持很薄：

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

response = client.responses.create(
    model=os.environ.get("OPENAI_MODEL", "gpt-5-mini"),
    instructions="Answer concisely and state uncertainty.",
    input="Explain why idempotency matters in one paragraph.",
)

print(response.output_text)

密钥来自环境变量，不能写进源码或文章。示例使用 gpt-5-mini 作为默认值，但生产应通过配置固定经过评测的模型。自动检查只解析代码，不调用付费 API。

不要假定 output 只有一段文字

Chat Completions 常从 choices[0].message.content 取文本。Responses 的 output 可以包含多种 item；output_text 会汇总文本，适合简单终端程序。需要审计、流式显示或工具调用时，应遍历并按类型处理 item，未知类型保留或记录，而不是用数组固定下标强制转换。

应用层定义自己的结果类型，例如 Answer(text, response_id, usage, status)。OpenAI SDK 对象只停留在 adapter 内，这样测试可以用普通值，未来响应字段变化也不会渗透到路由、数据库和界面。空文本不必等同于成功；先检查状态与错误，再决定向用户显示什么。

明确对话状态的所有者

简单后续请求可以使用 previous_response_id 连接前一个响应：

follow_up = client.responses.create(
    model=os.environ.get("OPENAI_MODEL", "gpt-5-mini"),
    previous_response_id=response.id,
    input="Now give one counterexample.",
)

这减少了应用重复发送上下文的代码，但数据库仍应保存业务会话与响应标识的对应关系。若产品要求自行控制保留、重放或跨供应商迁移，就由应用保存经过裁剪的消息并显式提交。两种模式不能含糊混用，否则重试可能重复上下文或把错误用户的链连接起来。

用户身份、会话身份和 OpenAI response id 分开存储；访问 response id 前重新鉴权。对“重新生成”决定是创建新分支还是覆盖展示，审计记录不能因 UI 替换文本而消失。

错误、重试与幂等

为连接失败、限流、服务端错误、无效请求和认证失败设置不同策略。只有瞬时错误适合有限次数指数退避；参数错误和无权限不应自动重试。设置调用超时，并让上游取消能够停止等待。日志记录请求关联标识、模型、延迟和状态，不记录密钥或完整私密 prompt。

生成请求是否可以安全重试取决于应用副作用。若返回结果之后会发送邮件或写入订单，模型调用与真实工具执行必须分开，工具层使用幂等键和人工审批。API 响应成功不意味着业务动作已经被授权。

用 adapter 做双轨迁移

定义 TextGenerator 接口，让旧 Chat Completions 和新 Responses adapter 返回相同领域结果。先在离线评测中比较，再将少量内部流量切到新实现。比较任务成功、拒答、格式合格率、延迟和 token 使用，不只比较措辞是否相同。生成模型具有非确定性，逐字一致不是合理迁移门槛。

上线时通过配置回退，监控按 API 路径和模型分组。等 Responses 路径稳定后再移除旧 adapter；不要在迁移中顺便清理所有 prompt 和业务代码，使回滚变得不可用。

结论

最小迁移路径是：冻结旧行为，新增窄 Responses adapter，正确读取 typed output，选择一种状态所有权，并为错误、取消和评测建立门槛。Responses API 为后续工具与多模态工作提供统一基础，但第一步无需启用全部能力。先让一条文本链路可观察、可回退，之后每增加一种 item 或工具都能独立验收。