[!WARNING] 该项目未处于积极维护状态，且与 OpenAI 实时 API 的最新正式发布版本不一致。此仓库中的代码仅作为官方库支持推出前的参考材料保留。有关新解决方案，请参阅适用于所有 OpenAI 库（Python、JS、Java、Go、.NET、Ruby）的官方库支持。

Azure OpenAI GPT-4o 音频和 /realtime：公开预览文档

欢迎使用基于 gpt-4o-realtime-preview 模型的 Azure OpenAI /realtime 公开预览版！本仓库提供了关于 /realtime 的文档、独立库以及示例代码——这些内容既适用于 Azure OpenAI，也适用于标准 OpenAI v1 端点的使用场景。

概述：什么是 /realtime？

本次预览引入了针对 gpt-4o-realtime-preview 模型系列的新 /realtime API 端点。/realtime 具有以下特点：

• 支持低延迟的“语音输入、语音输出”式对话交互
• 可处理文本消息、函数工具调用以及其他来自 /chat/completions 等端点的功能
• 非常适合客服代理、智能助手、翻译等需要与用户进行高效互动的应用场景

/realtime 基于 WebSockets API 构建，以实现终端用户与模型之间的完全异步流式通信。它被设计用于在受信任的中间服务环境中运行，该服务负责管理与终端用户的连接以及与模型端点的连接；/realtime 并非设计用于直接从不受信任的终端设备上使用，而诸如音频数据的捕获和渲染等设备相关细节也不在 /realtime API 的范围内。

从总体架构上看，基于 /realtime 构建的应用体验大致如下（请注意，如前所述，用户交互本身并不属于 API 的一部分）：

sequenceDiagram
  actor User as 终端用户
  participant MiddleTier as /realtime 主机
  participant AOAI as Azure OpenAI
  User->>MiddleTier: 开始交互
  MiddleTier->>MiddleTier: 认证/验证用户
  MiddleTier--)User: 音频信息
  User--)MiddleTier: 
  MiddleTier--)User: 文本信息
  User--)MiddleTier: 
  MiddleTier--)User: 控制信息
  User--)MiddleTier: 
  MiddleTier->>AOAI: 连接到 /realtime
  MiddleTier->>AOAI: 配置会话
  AOAI->>MiddleTier: 会话开始
  MiddleTier--)AOAI: 发送/接收 WS 命令
  AOAI--)MiddleTier: 
  AOAI--)MiddleTier: 创建/开始对话响应
  AOAI--)MiddleTier: （在响应中）创建/开始/添加/完成项目
  AOAI--)MiddleTier: （在项目中）创建/流式传输/完成内容部分

请注意，/realtime 处于 公开预览 阶段。API 变更、代码更新以及偶尔的服务中断均有可能发生。

如何开始使用

• 在 eastus2 或 swedencentral 区域创建一个 Azure OpenAI 资源
• 将 gpt-4o-realtime-preview 模型（版本为 2024-10-01）部署到上述支持的资源之一
• 使用附带的示例之一来体验 /realtime 的实际效果

连接与认证 /realtime

/realtime API 需要一个位于支持区域内的现有 Azure OpenAI 资源端点。完整的请求 URI 可通过以下步骤拼接而成：

1. 安全的 WebSocket 协议 (wss://)
2. 您的 Azure OpenAI 资源端点主机名，例如 my-aoai-resource.openai.azure.com
3. /openai/realtime API 路径
4. 用于指定支持 API 版本的 api-version 查询字符串参数——初始版本为 2024-10-01-preview
5. 包含您 gpt-4o-realtime-preview 模型部署名称的 deployment 查询字符串参数

综合以上步骤，一个完整的 /realtime 请求 URI 示例可能如下所示：

wss://my-eastus2-openai-resource.openai.azure.com/openai/realtime?api-version=2024-10-01-preview&deployment=gpt-4o-realtime-preview-1001

认证方式如下：

• 使用 Microsoft Entra：/realtime 支持基于令牌的身份验证，需配合已启用托管标识的适当配置的 Azure OpenAI 服务资源使用。请在 Authorization 头中使用 Bearer 令牌来应用获取到的认证令牌。
• 使用 API 密钥：可以通过两种方式提供 API 密钥：
  1. 在握手前的连接中使用 api-key 连接头（注意：浏览器环境不支持此方法）
  2. 在请求 URI 中使用 api-key 查询字符串参数（注意：使用 https/wss 时，查询字符串参数会被加密）

API 核心概念

• 调用者建立与 /realtime 的连接后，将启动一个新的 会话
• 可以对 会话 进行配置，以自定义输入和输出音频行为、语音活动检测行为以及其他共享设置
• 会话 会自动创建一个默认的 对话
  • 注意：未来可能会支持同时进行多个对话——但目前尚不可用
• 对话 会持续积累输入信号，直到由调用者直接发出命令或根据语音活动自动检测轮次来启动一次 响应
• 每个 响应 由一个或多个 项目 组成，这些项目可以封装消息、函数调用和其他信息
• 消息 项目 包含 内容部分，允许在一个项目中同时表示多种模态（文本、音频等）
• 会话 负责管理调用者的输入处理（例如用户音频）以及通用的输出/生成处理
• 每次调用者发起的 response.create 操作都可以根据需要覆盖部分输出行为
• 由服务器创建的 项目 以及消息中的 内容部分 可以异步并行地填充，例如同时接收音频、文本和函数信息（轮询方式）

API 详情

一旦与 /realtime 的 WebSocket 连接会话建立并完成身份验证后，功能交互便通过发送和接收 WebSocket 消息来进行。为避免与用于推理的承载内容的“消息”概念产生歧义，这些消息在此被称为“命令”。每个命令都采用 JSON 对象的形式。命令可以并行发送和接收，应用程序通常应以并发和异步的方式处理它们。

有关请求和响应命令的完整、结构化描述，请参阅 realtime-openapi3.yml。与其他公测阶段的内容一样，请注意协议细节可能会发生变更。

会话配置与轮次处理模式

在新建立的 /realtime 会话中，调用方发送的第一个命令通常是 session.update 负载。该命令控制广泛的输入和输出行为，而后续的输出和响应生成部分则可以通过 response.create 属性进行覆盖（如果需要）。

其中一个关键的会话级设置是 turn_detection，它控制调用方与模型之间的数据流处理方式：

• server_vad 会使用语音活动检测器 (VAD) 组件评估传入的用户音频（通过 input_audio_buffer.append 发送），并在检测到语音结束时自动利用该音频启动适用对话的响应生成。在指定 server_vad 检测模式时，可以配置 VAD 的静音检测。
• none 则依赖于调用方发起的 input_audio_buffer.commit 和 response.create 命令来推进对话并生成输出。这对于按住说话的应用程序或具有外部音频流控制的情况（例如调用方侧的 VAD 组件）非常有用。请注意，在 server_vad 模式下，这些手动信号仍然可以用来补充由 VAD 触发的响应生成。

用户输入音频的转录可通过 input_audio_transcription 属性启用；在此配置中指定转录模型（whisper-1）将启用 conversation.item.audio_transcription.completed 事件的传递。

以下是一个配置了包括工具在内的多个会话方面的 session.update 示例。请注意，所有会话参数都是可选的；并非所有内容都需要配置！

{
  "type": "session.update",
  "session": {
    "voice": "alloy",
    "instructions": "根据用户的输入，必要时调用提供的工具。",
    "input_audio_format": "pcm16",
    "input_audio_transcription": {
      "model": "whisper-1"
    },
    "turn_detection": {
      "threshold": 0.4,
      "silence_duration_ms": 600,
      "type": "server_vad"
    },
    "tools": [
      {
        "type": "function",
        "name": "get_weather_for_location",
        "description": "获取某个地点的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市和州，例如旧金山, 加利福尼亚州"
            },
            "unit": {
              "type": "string",
              "enum": [
                "c",
                "f"
              ]
            }
          },
          "required": [
            "location",
            "unit"
          ]
        }
      }
    ]
  }
}

命令概览

完整的参数详情请参阅 realtime-openapi3.yml。

请求：从调用方发送到 /realtime 端点的命令

type	描述
会话配置
session.update	配置对话会话的连接级行为，例如共享音频输入的处理方式和通用的响应生成特性。此命令通常在连接后立即发送，但也可在会话中的任何时间点发送，以便在当前响应（如果正在进行中）完成后重新配置行为。
输入音频
input_audio_buffer.append	将音频数据追加到共享的用户输入缓冲区。在 server_vad 的 turn_detection 模式下，这些音频只有在检测到语音结束时才会被处理；而在其他 turn_detection 配置下，则需手动发送 response.create 命令才能触发处理。
input_audio_buffer.clear	清空当前的音频输入缓冲区。请注意，这不会影响正在处理中的响应。
input_audio_buffer.commit	将用户输入缓冲区的当前状态提交给已订阅的对话，作为下一次响应的信息。
项目管理	用于建立对话历史或将非音频项目信息纳入对话
conversation.item.create	在对话中插入一条新条目，可选择根据 previous_item_id 进行定位。这可以提供来自用户的新的非音频输入（如文本消息）、工具响应，或来自其他交互的历史信息，以形成生成之前的对话历史。
conversation.item.delete	从现有对话中移除一条条目。
conversation.item.truncate	手动缩短消息中的文本和/或音频内容，这在模型以超实时速度生成大量额外数据，随后因中断而被跳过的情况下可能很有用。
响应管理
response.create	启动对未处理对话输入的模型处理，标志着调用方逻辑轮次的结束。在 server_vad 的 turn_detection 模式下，语音结束时会自动触发响应生成；但在其他情况下（文本输入、工具响应、none 模式等），必须调用 response.create 命令来表明对话应继续。注意：在响应工具调用时，应在模型发出确认所有工具调用及其他消息均已提供的 response.done 命令之后，再调用 response.create。
response.cancel	取消正在进行中的响应。

响应：由 /realtime 端点发送给调用方的命令

type	描述
session.created	在连接成功建立后立即发送。提供一个特定于连接的 ID，可用于调试或日志记录。
session.updated	作为对 session.update 事件的响应发送，反映会话配置所做的更改。
调用方项目确认
conversation.item.created	确认一个新的对话项目已被插入到对话中。
conversation.item.deleted	确认一个现有的对话项目已从对话中移除。
conversation.item.truncated	确认对话中的一个现有项目已被截断。
响应流程
response.created	通知某个对话的新响应已开始。此命令会捕获输入状态，并开始生成新的项目。在 response.done 表示响应结束之前，响应可能会通过 response.output_item.added 创建项目，然后通过 *delta* 命令逐步填充内容。
response.done	通知某个对话的响应生成已完成。
rate_limits.updated	在 response.done 之后立即发送，提供当前的速率限制信息，反映刚刚完成的响应消耗后的更新状态。
响应中的项目流
response.output_item.added	通知一个新的、由服务器生成的对话项目 正在创建中；随后将通过增量的 add_content 消息逐步填充内容，最后以 response.output_item.done 命令表示该项目的创建已完成。
response.output_item.done	通知一个新的对话项目已成功添加到对话中。对于模型生成的消息，这之前会有 response.output_item.added 和 *delta* 命令，分别用于开始和填充新项目。
响应项目内的内容流
response.content_part.added	通知在正在进行的响应中，对话项目内正在创建一个新的内容部分。在 response_content_part_done 到达之前，内容将通过相应的 *delta* 命令逐步提供。
response.content_part.done	表示新创建的内容部分已完成，不再接收进一步的增量更新。
response.audio.delta	提供模型生成的二进制音频数据内容部分的增量更新。
response.audio.done	表示音频内容部分的增量更新已完成。
response.audio_transcript.delta	提供与模型生成的输出音频相关的音频转录的增量更新。
response.audio_transcript.done	表示输出音频的音频转录的增量更新已完成。
response.text.delta	提供对话消息项目中文本内容部分的增量更新。
response.text.done	表示文本内容部分的增量更新已完成。
response.function_call_arguments.delta	提供对话项目中表示的函数调用参数的增量更新。
response.function_call_arguments.done	表示函数调用参数的增量更新已完成，累积的参数现在可以完全使用。
用户输入音频
input_audio_buffer.speech_started	当使用配置的语音活动检测时，此命令通知在输入音频缓冲区中已检测到用户语音的开始，具体位置为某个音频采样索引。
input_audio_buffer.speech_stopped	当使用配置的语音活动检测时，此命令通知在输入音频缓冲区中已检测到用户语音的结束，具体位置为某个音频采样索引。如果已配置，则会自动触发响应生成。
conversation.item.input_audio_transcription.completed	通知用户输入音频缓冲区的补充转录现已可用。此行为必须通过 session.update 中的 input_audio_transcription 属性进行启用。
conversation.item_input_audio_transcription.failed	通知输入音频转录失败。
input_audio_buffer_committed	确认当前用户音频输入缓冲区的状态已提交至已订阅的对话。
input_audio_buffer_cleared	确认待处理的用户音频输入缓冲区已被清空。
其他
error	表示在处理会话数据时出现了问题。包含一个提供详细信息的 error 消息。

故障排除与常见问题解答

最佳实践和预期模式正在迅速发展，本节中涉及的主题可能会很快过时。

我发送了音频，但没有收到服务返回的任何命令

• 确保输入音频格式与 session.update 命令中提供的格式一致（默认为 24KHz、16 位单声道 PCM）；如果格式不匹配，音频将被解码为“噪声”，而不会被解释为输入。
• 如果使用 none 的 turn_detection 模式（较新协议版本中为 null），请确保根据需要发送 input_audio_buffer.commit 和/或 response.create 命令。

工具调用无法正常工作或无响应

由于单个响应可能包含多个工具调用，因此工具调用与响应之间引入了一定的状态性：

• 调用方可以在收到该工具调用的 item_added 消息之后的任何时间添加工具调用输出项目 tool_call。
• 一旦当前响应的所有项目都已生成，模型的 response.done 命令将会到达，其中 output 字段会引用所有工具调用及其他属于该响应的项目。
• 此时（即所有传入的工具调用均已解决之后），调用方可以发送一个新的 response.create 命令。
• 在前一响应的配对 response.done 命令到达之前就发送 response.create 命令（例如，在 response.function_call_arguments.done 或 response.output_item.done 之后立即发送），可能会导致意外行为和竞态条件。
• 如果不发送任何 response.create 命令，对话可能无法继续推进。

使用音频文件作为输入时，我看到许多响应，或者我的响应会卡住

当使用比实时快得多的长音频输入时——例如来自带有自然停顿的音频文件——服务器的语音活动检测可能会连续触发大量响应，从而导致响应变得不可靠。在这种情况下，强烈建议在 session.update 中禁用语音活动检测（"turn_detection": { "type": "none" }，在较新协议版本中为 "turn_detection": null），并在所有音频传输完毕后手动调用 response.create。

关于库支持的长期计划是什么？

最简短的回答是：许多细节仍有待确定。

• .NET（https://github.com/openai/openai-dotnet）：现已提供对 /realtime 的预览支持，自 2.1.0-beta.1 版本开始。该预览版 SDK 的实现仍将持续开发、优化和调整——预计在各个预览版本之间会出现一定数量的破坏性变更。
• Python 和 JavaScript：正如 Realtime 公告中的“接下来的计划”部分 所述，官方库支持（通过 https://github.com/openai/openai-python 和 https://github.com/openai/openai-node）将在稍后推出。具体的时间表和细节将在后续进一步公布，但我们预计未来将实现对 /realtime 与其他客户端功能，如 /chat/completions 的统一支持。在此期间，本仓库提供了独立的库（兼容标准 OpenAI 和 Azure OpenAI），并附有示例，未来将继续扩展和改进。
• Java 和 Go：关于客户端库支持的讨论正在进行中，我们希望很快能分享更多进展。

aoai-realtime-audio-sdk 快速上手指南

⚠️ 重要提示：本项目目前不再积极维护，其代码状态与 OpenAI Realtime API 的最新通用版本不完全匹配。本仓库代码仅作为官方库支持到位之前的参考材料。对于新的解决方案，请使用 OpenAI 官方支持的库（Python, JS, Java, Go, .NET, Ruby）。以下指南基于 Azure OpenAI GPT-4o Audio /realtime 公共预览版文档整理。

环境准备

在开始之前，请确保满足以下系统和资源要求：

• Azure 区域：必须创建位于 eastus2 (美国东部 2) 或 swedencentral (瑞典中部) 区域的 Azure OpenAI 资源。
• 模型部署：在上述资源中部署 gpt-4o-realtime-preview 模型，版本需为 2024-10-01。
• 网络协议：支持 WebSocket (wss://) 连接。
• 开发环境：任意支持 HTTP/WebSocket 请求的编程语言或工具（如 Node.js, Python, Postman 等）。
• 认证方式：
  • Microsoft Entra ID (Bearer Token)
  • 或者 API Key

安装步骤

由于这是一个参考性质的 SDK 仓库，通常不需要通过包管理器安装特定的 "aoai-realtime-audio-sdk" 包。你可以通过克隆仓库获取示例代码，或直接根据 API 规范在你的项目中实现 WebSocket 连接。

获取示例代码：

git clone https://github.com/Azure-Samples/aoai-realtime-audio-sdk.git
cd aoai-realtime-audio-sdk

注：如果你使用官方 OpenAI 库进行新开发，请运行对应语言的安装命令，例如：

# Python 示例
pip install openai
# Node.js 示例
npm install openai

基本使用

1. 构建连接 URI

/realtime API 通过 WebSocket 连接。你需要构造如下格式的 URI：

wss://<你的资源名称>.openai.azure.com/openai/realtime?api-version=2024-10-01-preview&deployment=<你的部署名称>

示例 URI：

wss://my-eastus2-openai-resource.openai.azure.com/openai/realtime?api-version=2024-10-01-preview&deployment=gpt-4o-realtime-preview-1001

2. 认证连接

在建立 WebSocket 握手时，需选择以下一种认证方式：

• 方式 A：API Key (推荐用于测试) 在 URI 后追加 &api-key=<你的密钥> (WSS 加密传输是安全的)，或在非浏览器环境的预握手连接头中添加 api-key。
• 方式 B：Microsoft Entra Token 在 WebSocket 请求头中添加 Authorization: Bearer <你的访问令牌>。

3. 配置会话 (Session Update)

连接成功后，首先发送一个 session.update 命令来配置语音、指令和交互模式。

示例命令 (JSON)：

{
  "type": "session.update",
  "session": {
    "voice": "alloy",
    "instructions": "Call provided tools if appropriate for the user's input.",
    "input_audio_format": "pcm16",
    "input_audio_transcription": {
      "model": "whisper-1"
    },
    "turn_detection": {
      "threshold": 0.4,
      "silence_duration_ms": 600,
      "type": "server_vad"
    },
    "tools": [
      {
        "type": "function",
        "name": "get_weather_for_location",
        "description": "gets the weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["c", "f"]
            }
          },
          "required": ["location", "unit"]
        }
      }
    ]
  }
}

4. 发送音频与获取响应

• 发送音频：将用户音频数据分块发送，命令类型为 input_audio_buffer.append。
• 触发响应：
  • 如果配置了 server_vad (语音活动检测)，检测到说话结束时会自动触发响应。
  • 如果配置为 none 或发送文本，需手动发送 response.create 命令来触发模型生成。

手动触发响应示例：

{
  "type": "response.create"
}

5. 处理流式返回

服务端会通过 WebSocket 推送各种事件（Commands），你需要异步监听并处理：

• response.audio.delta: 包含生成的音频片段。
• response.text.delta: 包含生成的文本片段。
• conversation.item.audio_transcription.completed: 用户语音转写完成事件。

---

注意：由于处于公共预览阶段 (Public Preview)，API 细节、命令格式及服务稳定性可能会发生变化。生产环境请务必关注官方最新文档。