Chat Completions → Responses

Chat Completions 使用 messages 和 choices 组织对话；Responses 使用 input、Typed Items 和 output 表达输入、工具调用与结果。迁移时不仅要更换端点，还要调整输入结构、响应解析、工具循环和流式状态机。

是否需要迁移

适合迁移到 Responses 的情况：

• 新项目希望使用统一的 Typed Input 和 Output Items；
• 需要 previous_response_id 等多轮状态能力；
• 需要 Responses 已支持的内置工具；
• 应用愿意按照 Item 类型处理文本、工具调用和其他输出。

可以继续使用 Chat Completions 的情况：

• 现有应用稳定依赖 messages、choices 和 Chat Delta；
• 目标模型或所需工具只支持 Chat Completions；
• 当前没有足够回归测试覆盖工具、多轮和 Streaming；
• 迁移收益不足以覆盖响应解析和状态管理的改造成本。

核心变化

最小请求 Before / After

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "回答要简洁、准确。"
    },
    {
      "role": "user",
      "content": "请用一句话介绍 AGTCloud。"
    }
  ]
}

使用 OpenAI SDK 时，Client 的 Base URL 仍为 https://api.agtcloud.cn/v1。方法从 client.chat.completions.create(...) 改为 client.responses.create(...)。完整 Python 和 TypeScript 初始化方式请参阅 OpenAI SDK。

迁移响应读取

Chat Completions 通常从第一条 Choice 读取助手消息：

choices[0].message.content

Responses 返回有序的 output[]。其中可能同时包含消息、函数调用、搜索调用或其他 Item。SDK 的 output_text 可以用于读取聚合文本，但需要处理工具或其他输出时，应遍历完整 output。

response.output_text
response.output[]

迁移多轮状态

使用 previous_response_id 时，上一轮 instructions 不会自动继承。每一轮仍需要根据应用需要重新设置指令。

迁移后不要同时完整回放同一段历史并再次通过 previous_response_id 引用它，否则可能造成重复上下文。

迁移 Function Calling

工具定义

Chat Completions 将函数定义放在 tools[].function 中：

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "查询城市天气",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}

Responses 将函数信息直接放在 Function Tool 对象中：

{
  "type": "function",
  "name": "get_weather",
  "description": "查询城市天气",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" }
    },
    "required": ["city"]
  }
}

结果回传

• Chat：从 assistant.tool_calls[] 读取调用，并追加带 tool_call_id 的 Tool Message。
• Responses：从 output[] 读取 function_call，再发送 function_call_output，其中 call_id 必须与原调用一致。

无论使用哪种协议，函数都由你的应用执行。不要直接执行未经校验的参数，也不要把工具异常伪装成正常结果。

迁移 Streaming

Chat Completions 通过每个 Chunk 的 choices[].delta 返回增量，通常以 [DONE] 结束。

Responses 使用具名事件，例如：

• response.created；
• response.output_item.added；
• response.content_part.added；
• response.output_text.delta；
• response.output_text.done；
• response.completed。

迁移时应将原来的“只拼接文本”逻辑改成事件分派器：先按事件类型处理，再根据 output_index、content_index、item_id 等标识更新对应状态。

迁移 Structured Outputs

Chat Completions 将输出格式配置放在 response_format；Responses 将对应配置放在 text.format。迁移时需要同步修改：

1. 请求字段位置；
2. JSON Schema 包装结构；
3. SDK 的解析辅助方法；
4. 拒绝、不完整响应和 Schema 校验失败的处理。

详细字段请分别查看 Chat Completions 和 OpenAI Responses。

迁移 Web Search

两种协议的搜索入口不同：

• Chat Completions 使用 web_search_options，并要求选择支持搜索的模型；
• Responses 在 tools 中启用支持的 Web Search Tool，并可能返回搜索调用 Item 和引用。

域名过滤、来源列表、用户位置和实时互联网访问等设置取决于所选协议与模型。完整示例请参阅 OpenAI Web Search。

Usage、错误与中断

迁移监控与计费读取逻辑时，至少调整：

同时保留 HTTP 状态码、错误对象和 Request ID。不要只捕获 SDK 异常文本；应用日志应能区分鉴权失败、模型不可见、限流、服务错误和连接中断。

分阶段迁移

回归与回退清单

• 普通文本、空输出、拒绝、不完整和失败状态；
• 单工具、多工具、工具失败和参数校验失败；
• 无状态历史回放与 previous_response_id；
• Streaming 正常完成、断流和重复事件；
• Structured Outputs 校验失败；
• Usage、错误信息、Request ID、超时和限流；
• 目标模型不支持某项 Responses 能力时，能够切回 Chat Completions。

在生产切换前，为 Chat 与 Responses 保留独立配置和可控开关。确认业务指标、日志和错误处理稳定后，再清理旧解析路径。

下一步

• 使用 OpenAI SDK 配置 Python 或 TypeScript Client；
• 查看文本与对话理解 Responses 的日常调用流程；
• 在 OpenAI Responses 核对完整字段和响应；
• 遇到调用错误时查看 错误与排障。