OpenAI Responses API 详解

Responses API 是 OpenAI 于 2025 年推出的新一代 API，旨在简化 AI 应用开发。相比 Chat Completions API，它提供了更简洁的接口和内置工具支持。

为什么选择 Responses API？

Responses API 的设计理念：

传统的 Chat Completions API 要求开发者手动管理对话历史、处理工具调用循环、拼接消息数组。这在构建复杂应用时会带来大量样板代码。Responses API 的目标是让开发者专注于业务逻辑，而非 API 交互细节。

核心改进：

1. 简化输入：可以直接传递字符串，无需包装成消息数组
2. 自动状态管理：通过 response ID 链接对话，无需手动维护历史
3. 内置工具：网页搜索、代码执行等常用功能开箱即用
4. 自动工具循环：模型调用工具后自动执行并继续生成，无需多次请求

⚠️ 注意：Responses API 相对较新，如需与第三方服务兼容，建议使用 Chat Completions API。大多数 LLM 工具和框架目前仍以 Chat Completions 格式为主。

端点

POST https://api.openai.com/v1/responses

与 Chat Completions 的 /v1/chat/completions 不同，Responses API 使用独立的端点。认证方式相同，都使用 Bearer Token。

与 Chat Completions 的主要区别

详细对比：

消息管理

Chat Completions 要求你维护完整的消息数组，每次请求都要包含所有历史消息。Responses API 通过 previous_response_id 自动关联上下文，你只需要发送新的输入。

# Chat Completions - 需要手动维护历史
messages = [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "第一个问题"},
    {"role": "assistant", "content": "第一个回答"},
    {"role": "user", "content": "第二个问题"},  # 每次都要带上所有历史
]

# Responses API - 自动管理
response1 = client.responses.create(input="第一个问题")
response2 = client.responses.create(
    input="第二个问题",
    previous_response_id=response1.id  # 自动关联上下文
)

工具调用

Chat Completions 的工具调用需要多次请求：发送请求 → 收到 tool_calls → 执行工具 → 发送结果 → 收到最终回复。Responses API 可以自动完成这个循环。

内置工具

Responses API 提供了三个强大的内置工具，无需自己实现：

• web_search：实时搜索互联网
• code_interpreter：在沙箱中执行代码
• file_search：在上传的文件中搜索

请求参数

Responses API 的参数设计更加直观，减少了不必要的嵌套。

必需参数

input 参数的灵活性：

input 可以是简单的字符串，也可以是消息数组。这种设计让简单场景更简洁，复杂场景仍然灵活：

# 简单场景 - 直接传字符串
input="What is AI?"

# 复杂场景 - 传消息数组
input=[
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi!"},
    {"role": "user", "content": "What is AI?"}
]

# 多模态场景 - 包含图像
input=[{
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe this image"},
        {"type": "image_url", "image_url": {"url": "https://..."}}
    ]
}]

可选参数

instructions vs system message：

instructions 参数替代了 Chat Completions 中的 system message。它是一个顶级参数，更加突出和易于管理：

# Chat Completions 方式
messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello"}
]

# Responses API 方式
instructions="You are a helpful assistant.",
input="Hello"

previous_response_id 的工作原理：

每个响应都有唯一的 ID。通过传递上一个响应的 ID，API 会自动加载对话历史，无需手动维护消息数组。这大大简化了多轮对话的实现。

基础请求

简单文本输入

{
  "model": "gpt-4o",
  "input": "What is the capital of France?"
}

带系统指令

{
  "model": "gpt-4o",
  "instructions": "You are a helpful travel guide.",
  "input": "What should I visit in Paris?"
}

消息数组输入

{
  "model": "gpt-4o",
  "input": [
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"},
    {"role": "user", "content": "What's 2+2?"}
  ]
}

响应格式

Responses API 的响应结构与 Chat Completions 有显著不同，采用了更加模块化的设计。

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1699000000,
  "model": "gpt-4o-2024-08-06",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The capital of France is Paris."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 8,
    "total_tokens": 23
  },
  "status": "completed"
}

响应字段详解：

output 数组的设计理念：

与 Chat Completions 的 choices[0].message.content 不同，Responses API 的 output 是一个数组，可以包含多种类型的输出：

• message：文本消息
• tool_call：工具调用
• tool_result：工具执行结果
• file：生成的文件（如代码执行产生的图表）

这种设计使得复杂的多步骤响应更加清晰，每个步骤都是独立的输出项。

内置工具

内置工具是 Responses API 最强大的特性之一。这些工具由 OpenAI 托管和执行，无需开发者自己实现。

Web Search（网页搜索）

网页搜索工具允许模型实时搜索互联网，获取最新信息。这解决了模型训练数据截止日期的问题。

{
  "model": "gpt-4o",
  "input": "What are the latest news about AI?",
  "tools": [{"type": "web_search"}]
}

使用场景：

• 查询实时信息（新闻、股价、天气）
• 获取最新的技术文档
• 验证事实性信息

注意事项：

• 搜索结果会增加 Token 消耗
• 搜索可能增加响应延迟
• 搜索结果的准确性取决于搜索引擎

Code Interpreter（代码解释器）

代码解释器允许模型在安全沙箱中执行 Python 代码，并返回执行结果。

{
  "model": "gpt-4o",
  "input": "Calculate the first 10 Fibonacci numbers",
  "tools": [{"type": "code_interpreter"}]
}

使用场景：

• 数学计算和数据分析
• 生成图表和可视化
• 处理上传的文件（CSV、Excel）
• 验证代码逻辑

能力范围：

• 支持常用 Python 库（numpy、pandas、matplotlib 等）
• 可以读写文件
• 可以生成图像并返回
• 执行时间和资源有限制

File Search（文件搜索）

文件搜索工具允许模型在预先上传的文档中搜索相关信息，实现 RAG（检索增强生成）功能。

{
  "model": "gpt-4o",
  "input": "Find information about pricing in the uploaded documents",
  "tools": [
    {
      "type": "file_search",
      "vector_store_ids": ["vs_abc123"]
    }
  ]
}

使用场景：

• 企业知识库问答
• 文档分析和总结
• 合同审查
• 技术文档查询

工作原理：

1. 预先将文档上传到 Vector Store
2. 文档被自动分块和向量化
3. 查询时，相关片段被检索并提供给模型
4. 模型基于检索到的内容生成回答

自定义函数

除了内置工具，你仍然可以定义自定义函数，与 Chat Completions 的 Function Calling 类似。

{
  "model": "gpt-4o",
  "input": "What's the weather in Tokyo?",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string"}
        },
        "required": ["location"]
      }
    }
  ]
}

与 Chat Completions 的区别：

在 Responses API 中，自定义函数的调用可以配置为自动执行（如果你提供了执行逻辑），或者返回给你手动处理。这提供了更大的灵活性。

多轮对话

Responses API 通过 previous_response_id 实现多轮对话，这是与 Chat Completions 最大的区别之一。

使用 previous_response_id

// 第一轮
{
  "model": "gpt-4o",
  "input": "My name is Alice"
}
// 响应: {"id": "resp_abc123", ...}

// 第二轮
{
  "model": "gpt-4o",
  "input": "What's my name?",
  "previous_response_id": "resp_abc123"
}

工作原理：

1. 每个响应都有唯一的 id（如 resp_abc123）
2. 在后续请求中传递 previous_response_id
3. API 自动加载之前的对话历史
4. 模型可以访问完整的上下文

优势：

注意事项：

• 响应 ID 有有效期，过期后无法使用
• 无法修改历史对话，只能追加
• 如果需要”分支”对话，需要从某个点重新开始
• 长对话仍然受上下文窗口限制

流式传输

Responses API 的流式传输采用了更丰富的事件类型，提供了更细粒度的控制。

请求

{
  "model": "gpt-4o",
  "input": "Write a short poem",
  "stream": true
}

事件类型

事件详解：

与 Chat Completions 简单的 data: {...} 格式不同，Responses API 使用命名事件，每种事件有特定的用途：

• response.created：响应开始，包含响应 ID
• response.output_item.added：新的输出项（如消息、工具调用）开始
• response.output_text.delta：文本内容的增量更新，用于实现打字机效果
• response.completed：响应完成，包含最终的 usage 统计

这种设计使得处理复杂响应（如包含工具调用的响应）更加清晰。

流式响应示例

event: response.created
data: {"id": "resp_abc", "status": "in_progress"}

event: response.output_text.delta
data: {"delta": "The"}

event: response.output_text.delta
data: {"delta": " capital"}

event: response.output_text.delta
data: {"delta": " is Paris."}

event: response.completed
data: {"id": "resp_abc", "status": "completed"}

处理流式响应的最佳实践：

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\n--- 完成 ---")
        print(f"Token 使用: {event.usage}")

完整示例

cURL

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "instructions": "You are a helpful assistant.",
    "input": "Hello, how are you?"
  }'

Python

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    instructions="You are a helpful assistant.",
    input="Hello, how are you?"
)

print(response.output[0].content[0].text)

Python 流式

from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="gpt-4o",
    input="Write a haiku about coding",
    stream=True
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

Python 多轮对话

from openai import OpenAI

client = OpenAI()

# 第一轮
response1 = client.responses.create(
    model="gpt-4o",
    input="My favorite color is blue"
)

# 第二轮（引用上一轮）
response2 = client.responses.create(
    model="gpt-4o",
    input="What's my favorite color?",
    previous_response_id=response1.id
)

print(response2.output[0].content[0].text)

Node.js

import OpenAI from 'openai';

const openai = new OpenAI();

const response = await openai.responses.create({
  model: 'gpt-4o',
  instructions: 'You are a helpful assistant.',
  input: 'Hello!'
});

console.log(response.output[0].content[0].text);

迁移指南：Chat Completions → Responses

之前 (Chat Completions)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are helpful."},
        {"role": "user", "content": "Hello"}
    ]
)
text = response.choices[0].message.content

之后 (Responses)

response = client.responses.create(
    model="gpt-4o",
    instructions="You are helpful.",
    input="Hello"
)
text = response.output[0].content[0].text

适用场景

内置工具详解

Web Search 使用场景

• 获取实时信息（新闻、天气、股价）
• 查询最新文档和 API 变更
• 事实核查和信息验证

response = client.responses.create(
    model="gpt-4o",
    input="2024年诺贝尔物理学奖得主是谁？",
    tools=[{"type": "web_search"}]
)

Code Interpreter 使用场景

• 数学计算和数据分析
• 生成图表和可视化
• 处理上传的文件

response = client.responses.create(
    model="gpt-4o",
    input="计算 1 到 100 的质数之和",
    tools=[{"type": "code_interpreter"}]
)

File Search 使用场景

• 企业知识库问答
• 文档检索和总结
• 需要先创建 Vector Store

注意事项

1. 成本考虑：内置工具会产生额外费用
2. 延迟：使用工具会增加响应时间
3. 兼容性：第三方服务可能不支持此 API
4. 状态过期：previous_response_id 有时效限制

相关指南

• 02-OpenAI-Chat-Completions-API
• 09-错误处理与重试
• 16-流式输出实现详解

官方文档

• Responses API Guide: https://platform.openai.com/docs/guides/responses-vs-chat-completions
• API Reference: https://platform.openai.com/docs/api-reference/responses
• Migration Guide: https://platform.openai.com/docs/guides/migrating-from-chat-completions