> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/reference/realtime · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# Realtime 实时会话

除了「一问一答」式的 HTTP 流量，网关还支持**实时多模态会话**：客户端与上游之间建立一条长生命、双向、有状态的 WebSocket 连接，持续互发音频与事件（典型场景是语音对话）。这条路径与 HTTP 路径并行、互相独立。

入口：`GET /v1/realtime`（WebSocket 升级），说 **OpenAI Realtime** 客户端协议。

## 配置一个 Realtime 模型

和配普通模型一样在控制台建上游 + 模型，只是协议选 realtime 变体：

- **上游协议**选 `openai_realtime`（或 `dashscope_realtime`），基础 URL 填上游的 realtime WebSocket 端点。
- **模型**挂到该上游，填上游模型 ID。

客户端随后用访问密钥连 `ws(s)://<网关>/v1/realtime?model=<模型名>` 建立会话。

## 认证与准入

`/v1/realtime` 与 HTTP 数据面用**同一套认证**：访问密钥（`Authorization: Bearer`）+ Header ACL 规则照常生效。密钥组要放行该模型，会话才能建立。

## 会话作用域（与 HTTP 的区别）

一条 realtime 连接是一个**会话**，不是单个请求，因此它**不走**按请求起灭的那套中间件（每请求超时、并发、落盘、按请求统计）。会话级的治理（空闲/寿命限制、按轮计量）独立实现。要点：

- **桥接任务一会话一个**：网关连上上游 WebSocket 后，双向泵送帧。当前实现为**透传**——帧原样转发，不做协议翻译；网关旁路观测上游控制事件（`session.created` / `response.create` / `response.done`）以跟踪会话状态。
- **故障转移只在会话建立前**：连接建立阶段可在多个凭据候选间切换；一旦上游确认会话（`session.created`），上游已持有无法迁移的会话状态，此后**不再**允许换节点。
- **优雅关闭**：网关排空/关停时，对每个会话发送关闭帧，给足关闭握手的时间预算。

## 计费与日志（按轮）

一个会话里，每一**轮**（一次 `response.create` → `response.done` 往返）约等于一条请求：网关把它记进与 HTTP 请求**同一条**持久化统计与日志管线。

- **统计 / 账单**：每轮计入 `request_stats`，账单页按模型 join 定价——realtime 用量与 HTTP 用量在同一张统计/账单里按模型汇总。
- **日志**：每轮产生一条日志事件，进日志页与 Live SSE 流，可按访问密钥/模型查看。

> 因此 realtime 的成本是**按轮累计**的，计费口径与 HTTP 一致（按目标模型计价），见 [定价与计费](/zh-CN/howto/setup-pricing-and-billing.md)。

## 常见问题

**Q：realtime 能用负载均衡器吗？**
realtime 路由按模型解析到单个上游会话；多节点/多凭据的故障转移体现在**会话建立阶段**的凭据候选切换，而非 HTTP 那种按请求换节点。

**Q：realtime 会话会被请求超时切断吗？**
不会套用 HTTP 的每请求超时——realtime 是会话作用域，按会话的空闲/寿命限制治理。

**Q：realtime 支持协议互译吗？**
当前桥接是透传（帧原样转发）。客户端侧说 OpenAI Realtime 协议；上游需是同族 realtime 协议（`openai_realtime` / `dashscope_realtime`）。

**下一步**：[端点 · 认证 · 协议互通](/zh-CN/reference/endpoints.md) 看完整端点；[协议互通矩阵](/zh-CN/reference/protocol-matrix.md) 看协议清单；[定价与计费](/zh-CN/howto/setup-pricing-and-billing.md) 看计费口径。