如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

在 WebRTC 中使用 WARP

使用 WARP 降低 GPT-Live 和 Realtime API 的连接延迟。

使用 WebRTC 精简往返协议(WARP)可以缩短启动 GPT-Live 或 Realtime API 语音会话所需的时间。WARP 将三项传输优化(DTLS 1.3、SPED 和 SNAP)与预先协商的数据通道结合起来,减少建立连接所需的网络往返次数。

您也可以单独使用这些优化。即使无法使用完整的 WARP,启用客户端支持的功能也能降低连接延迟。同时启用所有功能即可使用完整的 WARP 握手流程。

WARP、SPED 和 SNAP 都是 IETF 互联网草案,其规范和客户端支持情况可能会发生变化。

GPT-Live 和 Realtime API 使用相同的 WebRTC 优化。无论应用服务器使用哪种编程语言,您都可以在浏览器或原生客户端中配置这些优化。创建会话时,这两个 API 传递已协商的数据通道 ID 的方式有所不同。

在原生客户端中启用 WARP

要使用完整的 WARP,请通过现场试验启用传输优化,并预先协商数据通道。您也可以单独执行其中任一步骤。

启用现场试验

当前版本的 libwebrtc 包含 WARP 优化。如果您的原生客户端使用兼容的 libwebrtc 构建版本,请启用以下现场试验:

WebRTC-ForceDtls13/Enabled/
WebRTC-Sctp-Snap/Enabled/
WebRTC-IceHandshakeDtls/Enabled/

这三项试验依次启用 DTLS 1.3、SNAP 和 SPED。只需添加与所需优化对应的试验项。

某些集成要求将所选试验项合并为一个字符串:

WebRTC-ForceDtls13/Enabled/WebRTC-Sctp-Snap/Enabled/WebRTC-IceHandshakeDtls/Enabled/

请在创建对等连接工厂之前初始化现场试验。封装库可能只提供针对特定优化的配置选项。例如,使用 webrtc-sys 0.3.51 时,可以在对等连接工厂上启用 SPED,并通过连接配置启用 SNAP:

use webrtc_sys::peer_connection::ffi::{
    ContinualGatheringPolicy, IceTransportsType, RtcConfiguration,
};
use webrtc_sys::peer_connection_factory::ffi::create_peer_connection_factory_with_options;

// The wrapper enables SPED on the factory; SNAP is an immutable connection option.
let factory = create_peer_connection_factory_with_options(false, true);
let configuration = RtcConfiguration {
    ice_servers: vec![],
    continual_gathering_policy: ContinualGatheringPolicy::GatherOnce,
    ice_transport_type: IceTransportsType::All,
    enable_sctp_snap: true,
};

如果您使用封装了 libwebrtc 的 SDK(例如原生 LiveKit SDK),请通过该 SDK 的 WebRTC 配置或初始化选项传入相同的现场试验字符串。如果 SDK 未提供现场试验配置选项,请在 SDK 创建对等连接工厂之前初始化底层 libwebrtc 实例,或升级到支持此配置的封装库版本。

预先协商数据通道

请在客户端和信令请求中使用相同的通道 ID。即使尚未启用全部三项传输优化,以下步骤也适用于原生客户端和浏览器:

  1. 在生成 SDP 提议之前创建数据通道,将 negotiated 设为 true,并将 id 设为可用的通道 ID,例如 4。通道标签可以是任意字符串。
  2. 将 SDP 提议和通道 ID 发送到应用服务器,然后按下文中相应 API 的步骤操作。

连接到 GPT-Live

先按照 GPT-Live WebRTC 快速入门指南进行设置。让服务器将通道 ID 作为 transport.dcid 字段的值写入 POST /v1/live/sessions 的 JSON 请求体。保持 transport.type 为 webrtc,并将 transport.sdp 设为客户端的 SDP 提议。

如果创建通道时指定了 id: 4,请将以下 JSON 请求体发送到 POST /v1/live/sessions。将 <SDP offer> 替换为客户端实际生成的 SDP 提议:

{
  "session": {
    "model": "gpt-live-1"
  },
  "transport": {
    "type": "webrtc",
    "sdp": "<SDP offer>",
    "dcid": 4
  }
}

transport.dcid 字段用于启用预先协商的数据通道。使用标准数据通道时,请省略此字段。请勿将 dcid 作为 URL 查询参数发送。与下文的 Realtime API 连接流程不同,GPT-Live 会拒绝带有查询参数的请求。

将返回的 transport.sdp 设为远端应答,收到 session.started 后再发送应用指令。HTTP 请求会启动会话,请勿在数据通道上发送 session.start。

如果您的 SDK 未提供 transport.dcid 字段,请沿用 GPT-Live 快速入门指南中的标准数据通道配置。您仍可单独启用客户端支持的各项传输优化。

连接到 Realtime API

使用统一的 WebRTC 连接流程。让服务器通过 dcid 查询参数传递通道 ID,以此方式调用 /v1/realtime/calls。如果创建通道时指定了 id: 4,请使用 POST /v1/realtime/calls?dcid=4,并在多部分请求体中沿用相同的 SDP 和会话配置。

将返回的 SDP 设为远端应答。使用标准数据通道时,请省略 dcid。下文的完整示例展示了这两种配置。

在浏览器中启用 WARP

Chrome、Edge 和其他基于 Chromium 的浏览器内置了 libwebrtc,但网页无法配置其现场试验。请先启用浏览器支持的传输功能,再根据所用 API,按照与原生客户端相同的信令流程预先协商数据通道。

启用可用功能和源试用

源试用允许已注册的网站启用浏览器的实验性功能。请确认各项 WARP 功能的支持情况:

  • DTLS 1.3: Chrome 支持 DTLS 1.3,无需启用源试用。
  • SNAP: Chrome 151 至 156 版通过源试用支持 SNAP。如果您使用 Edge,请确认当前版本是否提供 SNAP 源试用,并注册以获取 Edge 签发的令牌。
  • SPED: 目前没有浏览器提供 SPED 源试用。您可以稍后再查看支持情况。要使用完整的 WARP,浏览器必须默认启用 SPED,或者您必须能够控制浏览器的启动参数并自行启用所需的现场试验。

启用 SNAP 源试用不会启用 SPED 或完整的 WARP。如果浏览器未提供 SPED,您仍可使用 DTLS 1.3 和 SNAP 源试用,通过这两项优化降低连接延迟。

查看您的浏览器提供的源试用:

按以下步骤启用 SNAP 源试用:

  1. 打开浏览器的源试用页面,找到 WebRTC Data Channel: SCTP Negotiation Acceleration Protocol (SNAP)。

  2. 选择注册并输入应用的源,例如 https://example.com。

  3. 将签发的令牌添加到页面的 <head> 中,放在创建 RTCPeerConnection 的脚本之前:

    <meta http-equiv="origin-trial" content="YOUR_ORIGIN_TRIAL_TOKEN" />
  4. 重新加载页面。在 Chrome 中打开开发者工具,选择应用,然后确认 WebRtcSctpSnap 出现在源试用下。

您也可以通过 HTTP 响应标头提供令牌:

Origin-Trial: YOUR_ORIGIN_TRIAL_TOKEN

源试用令牌仅适用于指定的功能、签发令牌的浏览器和注册的源。SNAP 令牌不能启用 SPED,Chrome 令牌也不能在 Edge 中启用该试用。Firefox、Safari、iOS 上的浏览器以及较旧的 Chromium 构建版本可能支持标准 WebRTC,但不支持完整的 WARP。

预先协商浏览器的数据通道

按照上文的步骤设置数据通道,然后按照 GPT-Live 或 Realtime API 的说明发送相同的通道 ID。预先协商数据通道无需启用源试用,即使无法使用完整的 WARP,也可以缩短等待服务器事件的时间。

通过统一接口建立连接

使用统一的 WebRTC 连接流程可以更快地连接到 Realtime API。浏览器将其 SDP 提议和已协商的数据通道 ID 发送到应用服务器。服务器通过 dcid 查询参数转发相同的 ID,以此方式调用 /v1/realtime/calls。

配置应用服务器

此应用服务器同时支持标准 WebRTC 和 WARP。标有 WARP only 的注释指出了 WARP 所需的 dcid 转发逻辑:

import express from "express";

const app = express();

// Parse raw SDP payloads posted from the browser
app.use(express.text({ type: ["application/sdp", "text/plain"] }));

const sessionConfig = JSON.stringify({
  type: "realtime",
  model: "gpt-realtime-2.1",
  audio: { output: { voice: "marin" } },
});

// An endpoint which creates a Realtime API session.
app.post("/session", async (req, res) => {
  const fd = new FormData();
  fd.set("sdp", req.body);
  fd.set("session", sessionConfig);

  const endpoint = new URL("https://api.openai.com/v1/realtime/calls");

  // WARP only: forward the negotiated data-channel ID to the Realtime API.
  if (typeof req.query.dcid === "string") {
    endpoint.searchParams.set("dcid", req.query.dcid);
  }

  try {
    const r = await fetch(endpoint, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
        "OpenAI-Safety-Identifier": "hashed-user-id",
      },
      body: fd,
    });
    // Send back the SDP we received from the OpenAI REST API
    const sdp = await r.text();
    res.set(
      "Content-Type",
      r.ok ? "application/sdp" : (r.headers.get("Content-Type") ?? "text/plain")
    );
    const location = r.headers.get("Location");
    if (location) res.set("Location", location);
    res.status(r.status).send(sdp);
  } catch (error) {
    console.error("Session creation error:", error);
    res.status(500).json({ error: "Failed to create session" });
  }
});

app.listen(3000);

从浏览器建立连接

启用浏览器支持的优化后,将 useWarp 设为 true。选择任意可用的数据通道 ID,并将相同的 ID 传给服务器。标有 WARP only 的注释指出了标准 WebRTC 无需使用的配置和信令:

// WARP only: set to true after enabling the supported WARP optimizations.
const useWarp = false;

// WARP only: choose any available data-channel ID.
const dataChannelId = 4;

// Create a peer connection
const pc = new RTCPeerConnection();

// Set up to play remote audio from the model
audioElement.current = document.createElement("audio");
audioElement.current.autoplay = true;
pc.ontrack = (e) => (audioElement.current.srcObject = e.streams[0]);

// Add local audio track for microphone input in the browser
const ms = await navigator.mediaDevices.getUserMedia({
  audio: true,
});
pc.addTrack(ms.getTracks()[0]);

// Set up the event channel using any channel label.
// WARP only: pre-negotiate the channel using the selected data-channel ID.
const dc = pc.createDataChannel(
  "events",
  useWarp ? { negotiated: true, id: dataChannelId } : undefined,
);

// Start the session using the Session Description Protocol (SDP)
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const endpoint = new URL("/session", window.location.origin);

// WARP only: include the matching data-channel ID in the session request.
if (useWarp) {
  endpoint.searchParams.set("dcid", String(dataChannelId));
}

const sdpResponse = await fetch(endpoint, {
  method: "POST",
  body: offer.sdp,
  headers: {
    "Content-Type": "application/sdp",
  },
});

const answer = {
  type: "answer",
  sdp: await sdpResponse.text(),
};
await pc.setRemoteDescription(answer);

使用不支持 WARP 的客户端

如果您的 WebRTC 客户端不使用 libwebrtc,请在 WebRTC 协议栈中添加与 WARP 兼容的传输优化,或采用该协议栈支持的其他方案。相关规范包括 WARP、SPED、SNAP、DTLS 1.3 和数据通道建立协议。

如果无法使用这些优化,请使用标准的 GPT-Live WebRTC 连接流程或 Realtime API 统一接口。