🧠 OpenAI 下一代智能体与多模态 API 完整开发者指南

Responses API、GPT-5 推理、函数调用、结构化输出与多模态功能深度教程

---

引言：从聊天到智能体的演进

在人工智能应用开发领域，一场深刻的范式转变正在发生。
我们正在从传统的“请求/响应”模式（以 Chat Completions API 为代表）迁移到一种“默认即智能体”（agentic by default）的全新框架。

这一转变的核心是 Responses API 的推出。它不仅仅是一个新的端点，而是一种全新的 API 原语（API Primitive），为未来的智能体生态奠定了基础。

Responses API 是一个统一的、“面向未来”的（future-proof）基础架构，集成了：

• GPT-5 等模型的推理能力
• 网页搜索等内置工具
• 自定义函数调用
• 有保证的结构化输出
• 原生的多模态（视觉、音频、图像生成）支持

---

第一部分：新基础 — 掌握 Responses API

1.1 架构变革：从 Chat 到 Responses

功能	Chat Completions API（旧）	Responses API（新）
端点	/v1/chat/completions	/v1/responses
系统提示	messages: [{"role": "system", ...}]	instructions: "..."
用户输入	messages: [{"role": "user", ...}]	input: "..." 或 input: [...]
对话状态	手动管理 messages 数组	previous_response_id 或 context
响应字段	choices.message	output 数组（含 output_text）
结构化输出	response_format	text.format
多模态	支持有限	原生支持文本 + 图像

---

1.2 请求结构：更清晰的职责分离

旧方法 (Chat Completions)
系统与用户提示混合在 messages 数组中。

新方法 (Responses)

• 系统提示使用 instructions
• 用户输入使用 input
• input 可为字符串或消息数组（兼容旧结构）

---

1.3 状态管理：对话链与缓存优化

旧模型中，开发者需手动维护整个消息历史，导致高成本与复杂性。

Responses API 新机制：

• 使用 previous_response_id 引用上一个响应。
• 服务器端自动加载上下文与缓存。
• 可使用 store: true 持久化状态（工具与推理上下文）。

示例：Python 状态链调用

from openai import OpenAI
client = OpenAI()

# 第一次请求
response = client.responses.create(
    model="gpt-4o-mini",
    input="给我讲个笑话"
)
print(response.output_text)

# 第二次请求（引用上一个响应）
second_response = client.responses.create(
    model="gpt-4o-mini",
    previous_response_id=response.id,
    input=[{"role": "user", "content": "解释一下为什么这个笑话好笑。"}]
)
print(second_response.output_text)

优势：

• 成本下降（缓存利用率提升 40%-80%）
• 状态管理自动化
• “默认即智能体”设计理念落地

---

第二部分：控制新思维 — GPT-5 推理与新参数

GPT-5 引入了新的推理控制逻辑：
从“随机性”转向“计算资源分配”。

旧参数如 temperature、top_p 已不再适用，取而代之的是：

控制目标	旧参数（GPT-4）	新参数（GPT-5）
创造性 / 随机性	temperature, top_p	❌（不支持）
思考深度	无	reasoning.effort
输出简洁度	提示控制	text.verbosity
输出长度	max_tokens	max_output_tokens

---

2.1 推理深度：reasoning.effort

选项	说明
minimal	极快响应，适合确定性任务
low	快速、低消耗（接近 GPT-4.1）
medium	默认值，平衡速度与深度
high	深度推理，适用于复杂任务

---

2.2 输出详略：text.verbosity

选项	输出特征
low	简洁精炼
medium	平衡默认
high	详细冗长，适合教学或文档

可组合控制，例如：

深度推理但简短回答 → reasoning.effort: "high", text.verbosity: "low"

---

第三部分：构建智能体工作流 — 工具、函数与结构化数据

3.1 三步函数调用机制

步骤 1：定义工具（Tools）

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "获取城市天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    }
]

步骤 2：模型请求调用工具
模型返回 tool_calls 对象，例如：

{
  "tool_calls": [
    {
      "id": "call_abc123",
      "name": "get_current_weather",
      "arguments": {"location": "San Francisco"}
    }
  ]
}

步骤 3：执行函数并返回结果

messages.append({
    "tool_call_id": "call_abc123",
    "role": "tool",
    "name": "get_current_weather",
    "content": '{"temperature": "72", "unit": "fahrenheit"}'
})

---

3.2 内置工具支持

工具	功能
web_search_preview	网页搜索
code_interpreter	运行代码
file_search	文件检索
computer_use	计算机控制

---

3.3 结构化输出（Structured Output）

区别于旧的 JSON 格式化输出：

模式	类型	特性
JSON 模式	json_object	确保有效 JSON，但不保证结构
结构化输出	json_schema	严格模式校验 + 完整字段验证

示例：使用 JSON Schema 强制结构化

"text": {
  "format": {
    "type": "json_schema",
    "name": "research_paper_extraction",
    "schema": {
      "type": "object",
      "properties": {
        "title": {"type": "string"},
        "authors": {"type": "array", "items": {"type": "string"}},
        "abstract": {"type": "string"},
        "keywords": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["title", "authors", "abstract", "keywords"],
      "additionalProperties": false
    },
    "strict": true
  }
}

---

第四部分：多模态 API — 视觉与图像生成

4.1 视觉输入（Vision）

支持传递多张图像，三种方式：

• image_url
• Base64 编码
• file_id（文件上传后引用）

参数：detail

选项	说明
low	低分辨率，低成本
high	高分辨率，理解更准确
auto	模型自动决定

限制：

• 最大 50MB
• 最多 500 张图像
• 格式：PNG, JPG, WEBP, GIF（非动画）

---

4.2 图像生成（DALL·E 3 与 GPT-Image-1）

参数	GPT-Image-1	DALL·E 3
size	1024x1024, 1536x1024 等	1024x1024, 1792x1024 等
quality	low/medium/high	standard / hd
style	不适用	vivid / natural
多张图像	支持	不支持

---

第五部分：多模态 API — 音频（语音识别与语音合成）

5.1 语音转文本（Speech-to-Text）

模型	功能
gpt-4o-transcribe	转录音频为原语言
whisper-1	翻译成英语
gpt-4o-transcribe-diarize	自动标注说话人

示例：

from openai import OpenAI
client = OpenAI()
audio = open("/path/to/audio.mp3", "rb")

result = client.audio.transcriptions.create(
  model="gpt-4o-transcribe",
  file=audio
)
print(result.text)

---

5.2 文本转语音（Text-to-Speech）

模型	特点
gpt-4o-mini-tts	可提示语气、情感
tts-1	低延迟
tts-1-hd	高保真

支持声音：alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer 等。

import OpenAI from "openai";
const openai = new OpenAI();

const mp3 = await openai.audio.speech.create({
  model: "gpt-4o-mini-tts",
  voice: "coral",
  input: "Hello, world!",
  instructions: "Speak in a cheerful and positive tone."
});

---

语音智能体架构

架构	流程	特点
链式 (Chained)	语音→文本→文本→语音	控制性强，延迟高
语音到语音 (Speech-to-Speech)	单模型实时音频输入输出	自然流畅，低延迟

---

🧩 结论：智能体的时代已来临

一个完整的智能体应用现在可通过 单一的 Responses API 构建：

1. 语音输入：gpt-4o-transcribe 转录
2. 视觉理解：gpt-4v 分析图像
3. 推理决策：gpt-5 高效思考
4. 调用函数：get_current_weather 获取实时信息
5. 状态引用：通过 previous_response_id 管理上下文
6. 语音输出：gpt-4o-mini-tts 输出自然语音

简单聊天机器人的时代已经结束。
智能体的时代已经到来。
现在，就开始构建吧。