深入解析 OpenAI Realtime API 协议架构：从 Response 到 Conversation

在开发基于 OpenAI Realtime API 的低延迟语音应用时，开发者面对的最大挑战往往是其复杂的 WebSocket 事件流（Event Stream）。与传统的 Request-Response 模式不同，Realtime API 将一次对话拆解为了极细粒度的原子事件。

Connect Websocket

Realtime Session

理解 response、output_item、content_part 以及 conversation.item 之间的层级关系与语义区别，是正确处理流式数据、管理多模态状态以及维护对话上下文的关键。本文将对这些核心概念进行深度剖析。

一、 核心层级架构：从宏观到微观

Realtime API 的响应结构遵循一个严格的 1-to-N 嵌套层级。理解这一结构的最佳方式是从生命周期的角度审视一次生成过程。

1. Response (响应/生成轮次)

这是最高层级的容器，代表模型的一次“思考与生成”动作。

• 语义与作用：它是一个生命周期管理单元。
• 关键职责：
  • 计费统计：Token Usage 是在 Response 结束时 (response.done) 统一结算的。
  • 控制权：客户端可以通过 response.cancel 中断整个生成过程。
  • 状态同步：标记模型是否处于“忙碌”状态。

2. Output Item (输出项/消息单元)

这是 Response 内部的逻辑单元。一个 Response 可能包含多个 Output Item（例如：模型先说了一句话，紧接着调用了一个工具）。

• 语义与作用：它代表对话历史中的一个独立条目。
• 对应概念：对应传统 Chat API 中的 Message 对象。
• 关键属性：拥有独立的 id、role（如 assistant）和 type（如 message 或 function_call）。

3. Content Part (内容分块)

这是 Output Item 内部的模态容器。

• 语义与作用：它解决了多模态共存的问题。在一个 Message Item 中，可能同时包含音频 (audio) 和对应的转录文本 (text)。这两者就是同一个 Item 下的两个不同 Part。
• 关键职责：定义数据的类型（Mime-type 级别的区分）。

4. Output Text / Audio (数据流载体)

这是最底层的“墨水”。

• 语义与作用：它是依附于 Content Part 的实际载荷 (Payload)。
• 表现形式：以 delta 事件流的形式传输（如 response.text.delta 或 response.audio.delta）。

# 完整数据流示例

response.output_item.added
含义：准备回复一条消息。
数据：{ id: "item_001", type: "message" }
response.content_part.added
含义：这条消息的第 0 部分是文本。
数据：{ item_id: "item_001", content_index: 0, type: "text" }
response.output_text.delta (第 1 次)
含义：由于是流式，这是第一个字。
数据：{ item_id: "item_001", content_index: 0, delta: "你" }
response.output_text.delta (第 2 次 ... 第 N 次)
含义：后续的字。
数据：{ delta: "好" } ... { delta: "啊" }
response.output_text.done
含义：文本部分流结束了，确认最终文本。
数据：{ text: "你好啊" }
response.content_part.done
含义：第 0 部分内容块结束。
response.output_item.done
含义：整条消息结束。

二、 详解协议事件与数据流

为了在客户端精准还原模型的输出，我们需要区分以下几组容易混淆的事件：

1. 结构事件 vs. 内容事件

注意：output_text 是数据流事件，而 output_item 是结构事件。必须监听 output_text.delta 才能获取真正的文本内容。

2. 定位锚点：Understanding Indexes

在高并发的流式传输中，数据包是乱序或碎片化的。API 提供了两个索引用于精确定位数据包的归属：

• output_index：消息索引。表示当前数据属于 Response 中的第几个 Item。
  • 例：output_index=0 是助手回复的文本，output_index=1 是随后的函数调用。
• content_index：内容块索引。表示当前数据属于 Item 中的第几个 Part。
  • 例：在同一个 Item 中，content_index=0 可能是思考过程 (CoT)，content_index=1 是最终回答。

JSON 结构示意：

// Response
{
  "output": [
    // Output Item (output_index = 0)
    {
      "type": "message",
      "content": [
        // Content Part (content_index = 0) - 文本
        { "type": "text", "text": "Hello..." }, 
        // Content Part (content_index = 1) - 音频
        { "type": "audio", "audio": "base64..." }
      ]
    }
  ]
}

三、 生成视角与历史视角：Response vs. Conversation

在 Realtime API 中，Item 有两种存在形态，这经常导致开发者的困惑：response.output_item 和 conversation.item。

1. 核心区别

• response.output_item.* (生成视角)
  • 定义：正在“被制造”的产品。
  • 触发源：仅由模型生成 (Assistant Message / Function Call) 触发。
  • 状态：流式、动态、可能被中断或取消。
  • 用途：用于实时展示打字机效果、播放实时音频流。
• conversation.item.* (存储视角)
  • 定义：已经“入库”的档案。
  • 触发源：任何对对话历史的变动（用户语音输入、模型回复上屏、手动插入 System Prompt）。
  • 状态：持久化、作为上下文 Context。
  • 用途：用于维护完整的对话历史列表、上下文管理。

2. 生命周期流转

当模型进行回复时，这两个概念是首尾相连的：

1. 生成阶段：模型开始输出，触发 response.output_item.added。此时该 Item 处于“生成中”状态。
2. 流式传输：通过 response.output_text.delta 传输内容。
3. 归档阶段：Response 完成，该 Item 被确认为有效，正式成为 conversation.item 的一部分（API 通常会同步触发 conversation.item.created 事件，虽然它在逻辑上早已存在）。

总结

• Response 是产生内容的“工厂流程”。
• Output Item 是工厂流水线上的“产品”。
• Content Part 是产品的“组件”。
• Conversation 是存放最终成品的“仓库”。

在开发应用时，建议使用 conversation.item 事件来维护主聊天界面的数据源（因为它包含了用户和助手双方的消息），而使用 response.* 事件来处理实时的 UI 反馈（如波形动效、打字机滚动）。