跳到主要内容

Realtime API

AISIX AI 网关在 GET /v1/realtime 通过 WebSocket 转发 OpenAI Realtime API。网关会在接受连接前完成客户端认证、模型别名解析、访问控制和限流策略检查，然后在客户端与服务提供方之间双向转发事件。

本指南将演示如何通过网关连接 Realtime 客户端，并说明该端点的关键会话行为。

前提条件​

开始前请准备：

  • 一个可处理代理请求的 AISIX 网关。
  • 一个可访问目标模型别名的调用方 API Key。
  • 一个由支持 OpenAI Realtime 协议的服务提供方支持的模型别名。

导出服务器端示例使用的网关连接和请求值：

# AISIX_PROXY 使用 http 或 https，末尾不含斜杠，也不包含端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="realtime-prod"

目前支持兼容 OpenAI 的服务提供方（适配器为 openai，包括自定义 api_base 部署）和 Azure OpenAI（适配器为 azure-openai，使用 /openai/realtime 和 api-key 认证）。Gemini Live 和 Bedrock 使用不同的实时事件协议，不通过该端点提供。

连接客户端​

通过 model 查询参数选择模型。服务端客户端使用标准请求头认证：

import WebSocket from "ws";

const realtimeUrl = new URL("/v1/realtime", process.env.AISIX_PROXY);
realtimeUrl.protocol = realtimeUrl.protocol === "https:" ? "wss:" : "ws:";
realtimeUrl.searchParams.set("model", process.env.AISIX_MODEL);

const ws = new WebSocket(realtimeUrl, {
  headers: { Authorization: `Bearer ${process.env.AISIX_API_KEY}` },
});

浏览器客户端无法设置 WebSocket 请求头。可以像 OpenAI 浏览器示例一样，把调用方 API Key 作为 subprotocol 项传入。网关会回显 realtime subprotocol：

const aisixProxy = "YOUR_AISIX_GATEWAY_ORIGIN";
const aisixApiKey = "YOUR_CALLER_API_KEY";
const aisixModel = "realtime-prod";

const realtimeUrl = new URL("/v1/realtime", aisixProxy);
realtimeUrl.protocol = realtimeUrl.protocol === "https:" ? "wss:" : "ws:";
realtimeUrl.searchParams.set("model", aisixModel);

const ws = new WebSocket(realtimeUrl, [
  "realtime",
  `openai-insecure-api-key.${aisixApiKey}`,
]);

连接建立后，可以像直接连接服务提供方一样收发 Realtime 事件。AISIX 转发 session.update、音频 buffer、response.create 和服务端事件等事件时不会改变其结构。

AISIX 唯一会改写的值是 session 对象中的模型名称。session.created 和 session.updated 事件中的模型名称是客户端连接时使用的模型别名，而不是服务提供方自身的模型 ID。客户端把该别名通过 session.update 发回时，会在转发到上游前被转换回服务提供方的模型 ID，因此客户端可以直接回传收到的 session 对象。

认证与策略​

认证、模型访问检查、客户端 IP 限制、预算和限流会在 WebSocket upgrade 完成前执行。任何检查失败都会在 HTTP 握手阶段被拒绝（401、403 或 429），客户端会看到连接建立失败。

会话期间，已配置的安全护栏会扫描双向文本事件。被阻断的事件会产生 OpenAI 风格的 error 事件，随后连接关闭。

用量跟踪​

网关会从服务提供方的 response.done 事件中提取用量信息；转录会话还会从转录完成事件中提取用量。每个会话会记录一个聚合用量事件，包括缓存 Token 数。会话总 Token 会计入基于 Token 的限流。

会话限制​

AISIX 会对两个方向的事件间隔应用空闲上限。系统依次从直接模型的 stream_timeout、该模型的 timeout，以及部署级 upstream.stream_timeout_ms 或 upstream.timeout_ms 默认值解析此上限。部署默认上限为 6000 秒。静默时间超过解析后截止时间的会话将以代码 1001 和原因 idle timeout 关闭。

要让某个模型不受部署级兜底值影响，请设置 timeout: 0，并确保该模型未设置非零 stream_timeout。部署运维人员也可以将两个上游超时默认值均设置为 0。有关完整优先级规则，请参阅超时之间的关系。上游连接失败会以代码 1011 关闭会话；模型开启冷却后，这类失败会计入模型冷却。

下一步​

你已经通过网关连接了 Realtime 客户端。接下来可阅读语音与音频，了解非 Realtime 音频端点。