OpenAI Responses API 中文指南：从 Chat Completions 迁移到统一多模态接口

OpenAI 的 Responses API 是面向新一代 AI 应用的统一接口。它把文本生成、图像理解、工具调用、结构化输出、流式响应和多轮上下文放在同一套调用方式里，更适合构建客服助手、知识库问答、代码助手、自动化 Agent 和企业内部工作流。

如果你过去一直使用 Chat Completions API，可以把 Responses API 理解为更现代的“应用级入口”：它不只是让模型回复一段文字，而是让模型在一次任务里读取上下文、调用工具、返回结构化结果，并把过程管理得更清楚。

官方入口：
OpenAI API 文档
Responses API 指南
迁移到 Responses API

1. Responses API 适合什么场景？

Responses API 的核心价值是“统一”。当你的应用只是简单聊天时，传统对话接口也能完成任务；但一旦出现下面这些需求，Responses API 会更顺手：

场景	为什么适合 Responses API
多模态输入	同一次请求中处理文本、图片、文件等内容
工具调用	让模型按需调用搜索、数据库、业务系统或自定义函数
结构化输出	直接返回符合 JSON Schema 的结果，方便进入后续程序
Agent 工作流	让模型围绕目标执行多个步骤，而不是只生成一段回复
流式体验	把生成结果实时推送给前端，降低等待感
上下文管理	更自然地承接上一轮响应，构建连续任务流程

简单说：如果你要做的是“AI 功能”，Responses API 通常够用；如果你要做的是“AI 应用”，Responses API 更值得优先考虑。

2. 基础调用示例

下面是一个最小可用的 Node.js 示例，用 Responses API 让模型回答一个中文问题。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.responses.create({
  model: "gpt-5.5",
  input: "请用三句话解释 Responses API 适合哪些开发场景。",
});

console.log(response.output_text);

Python 版本也很直接：

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    input="请用三句话解释 Responses API 适合哪些开发场景。"
)

print(response.output_text)

在真实项目中，建议把模型名称、超时、重试次数、日志开关等配置放进统一的配置层，不要散落在业务代码里。

3. 与 Chat Completions 的主要区别

很多开发者最关心的问题是：已有项目是否需要迁移？答案取决于你的应用复杂度。

对比项	Chat Completions API	Responses API
主要定位	对话消息生成	统一任务响应接口
输入形式	messages 数组	更灵活的 input 内容
多模态能力	支持，但形态较分散	更统一地组织多模态内容
工具调用	支持函数调用	更适合工具链和 Agent 流程
结果读取	从 choices 中取消息	可直接读取 output_text 等结果
未来应用	适合保留稳定旧项目	更适合新项目和复杂工作流

对于新项目，建议优先从 Responses API 开始；对于已有 Chat Completions 项目，可以先迁移最需要工具调用、结构化输出或多模态能力的模块。

4. 多轮上下文怎么处理？

传统聊天接口通常由开发者维护完整 messages 历史。Responses API 可以通过上一轮响应继续任务，让业务代码更轻。

const first = await client.responses.create({
  model: "gpt-5.5",
  input: "帮我列出做一个 AI 客服系统的 5 个核心模块。",
});

const second = await client.responses.create({
  model: "gpt-5.5",
  previous_response_id: first.id,
  input: "把第 2 个模块展开成开发任务清单。",
});

console.log(second.output_text);

这种写法很适合“连续拆解任务”的应用，例如产品需求分析、代码审查、研究报告生成和复杂客服工单处理。

5. 结构化输出：让 AI 结果更容易进系统

如果只是把模型输出展示给用户，自然语言文本已经足够。但如果你要把结果写入数据库、触发流程或进入 BI 系统，就应该使用结构化输出。

const response = await client.responses.create({
  model: "gpt-5.5",
  input: "从这句话中提取客户姓名、意向产品和紧急程度：王女士想尽快了解企业版 API 套餐。",
  text: {
    format: {
      type: "json_schema",
      name: "sales_lead",
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          product: { type: "string" },
          urgency: { type: "string", enum: ["low", "medium", "high"] }
        },
        required: ["name", "product", "urgency"],
        additionalProperties: false
      },
      strict: true
    }
  }
});

结构化输出最常见的用途包括：

• 从聊天记录中提取线索信息
• 把简历、合同、工单转成可检索字段
• 对用户反馈做标签分类
• 生成前端可以直接渲染的数据结构
• 让模型输出严格符合内部接口要求

6. 工具调用：让模型连接真实业务

AI 应用的关键不是“模型会说什么”，而是“模型能做什么”。工具调用可以让模型在需要时访问你的业务能力，例如查询订单、读取库存、搜索知识库、创建日程或提交工单。

一个典型工具定义会包含名称、说明和参数结构：

const response = await client.responses.create({
  model: "gpt-5.5",
  input: "帮我查询订单 20260707001 的物流状态。",
  tools: [
    {
      type: "function",
      name: "get_order_status",
      description: "根据订单号查询物流状态",
      parameters: {
        type: "object",
        properties: {
          order_id: {
            type: "string",
            description: "用户提供的订单号"
          }
        },
        required: ["order_id"],
        additionalProperties: false
      }
    }
  ]
});

在生产系统里，工具调用必须配合权限校验、参数校验、审计日志和失败兜底。不要因为请求来自模型就直接执行高风险操作，尤其是支付、删除、发货、改权限等动作。

7. 多模态输入：文本和图片一起处理

Responses API 可以把图片和文本放在同一个任务里，适合票据识别、页面截图分析、商品图理解、作业批改和质检巡检。

const response = await client.responses.create({
  model: "gpt-5.5",
  input: [
    {
      role: "user",
      content: [
        { type: "input_text", text: "请识别这张发票中的金额、日期和销售方名称。" },
        {
          type: "input_image",
          image_url: "https://example.com/invoice.jpg"
        }
      ]
    }
  ]
});

console.log(response.output_text);

如果图片来自用户上传，建议先做格式、大小、清晰度和敏感信息检查。对于身份证、银行卡、医疗影像等高敏数据，还应根据业务所在地的法律法规设置额外保护流程。

8. 流式输出：改善前端体验

长回答、报告生成、代码生成和客服对话都适合使用流式输出。用户不用等完整结果生成完毕，可以边看边继续判断是否有用。

前端体验上，建议做到三点：

• 首字出现前展示轻量加载状态
• 流式内容进入同一个消息气泡，不要频繁闪烁
• 生成完成后再显示复制、重新生成、引用来源等操作

对于服务端，也要处理好断线重连、请求取消、超时和部分结果保存。流式输出不是简单地“逐字打印”，而是一套完整的交互体验。

9. 迁移建议：先迁复杂模块，不要一次性全改

如果你的项目已经稳定运行，不建议为了追新而一次性重写所有接口。更稳妥的迁移顺序是：

1. 新功能直接使用 Responses API。
2. 把需要结构化输出的模块迁移过来。
3. 把需要工具调用的模块迁移过来。
4. 把多模态能力迁移到统一输入格式。
5. 保留低风险、低频、稳定的旧接口，等后续迭代再处理。

迁移时要准备一组固定测试样例，覆盖中文、英文、长文本、空输入、敏感词、工具失败、网络超时和 JSON 格式异常。模型能力很强，但生产系统不能只依赖“看起来回答对了”。

10. 生产环境最佳实践

上线前建议至少完成以下检查：

• 密钥安全：API Key 只放在服务端或安全环境变量中，不写入前端代码。
• 成本控制：为用户、团队、功能模块设置用量上限。
• 日志脱敏：日志中不要保存完整密钥、身份证、手机号、银行卡等敏感信息。
• 错误兜底：模型失败时返回可理解的提示，而不是直接暴露异常堆栈。
• 提示词版本化：重要系统提示词要纳入版本管理，方便回滚和 A/B 测试。
• 结果校验：结构化输出仍要在服务端再次验证。
• 人工审核：高风险业务保留人工确认环节。

总结

Responses API 的意义不是多一个接口名称，而是把 OpenAI 的模型能力组织成更适合真实应用的开发方式。它让文本、多模态、工具调用、结构化输出和上下文连续性变得更统一，也让团队更容易从“调用模型”升级到“构建 AI 工作流”。

如果你正在做新的 OpenAI API 项目，建议把 Responses API 作为默认选择；如果你维护的是旧项目，可以从工具调用、结构化输出和多模态模块开始逐步迁移。