如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

在 WebRTC 中使用 WARP

使用 WARP 降低 GPT-Live 和 Realtime API 的連線延遲。

使用 WebRTC Abridged Roundtrip Protocol(WARP) 可縮短啟動 GPT-Live 或 Realtime API 語音工作階段所需的時間。WARP 結合三項傳輸最佳化功能(DTLS 1.3、SPED 和 SNAP),並搭配預先協商的資料通道,減少建立連線所需的網路往返次數。

這些最佳化功能也可以個別使用。即使無法使用完整的 WARP,啟用用戶端支援的功能仍可降低連線延遲。同時使用所有功能,即可進行完整的 WARP 交握。

WARP、SPED 和 SNAP 目前都是 IETF 網際網路草案,規格和用戶端的支援情況都可能變更。

GPT-Live 和 Realtime API 使用相同的 WebRTC 最佳化功能。無論應用程式伺服器使用哪種語言,都請在瀏覽器或原生用戶端設定這些功能。建立工作階段時,傳送已協商資料通道 ID 的方式會因 API 而異。

在原生用戶端啟用 WARP

若要使用完整的 WARP,請透過實驗設定(field trials)啟用傳輸最佳化功能,並預先協商資料通道。也可以單獨執行其中一個步驟。

啟用實驗設定

目前版本的 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 offer。建立通道時,將 negotiated 設為 true,並將 id 設為可用的通道 ID,例如 4。通道標籤可以是任意字串。
  2. 將 SDP offer 和通道 ID 傳送至應用程式伺服器,然後依照下方對應 API 的步驟操作。

連線至 GPT-Live

先依照 GPT-Live WebRTC 快速入門指南設定連線。讓伺服器將通道 ID 填入 transport.dcid 欄位,並將該欄位納入 POST /v1/live/sessions 的 JSON 請求本文。請將 transport.type 維持為 webrtc,並將 transport.sdp 維持為用戶端的 SDP offer。

如果建立通道時設定了 id: 4,請將以下 JSON 本文傳送至 POST /v1/live/sessions。請將 <SDP offer> 替換為用戶端實際產生的 SDP offer:

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

transport.dcid 欄位會啟用預先協商的通道。使用標準資料通道時,請省略此欄位。請勿以 URL 查詢參數傳送 dcid。GPT-Live 會拒絕查詢參數,這與下方的 Realtime API 流程不同。

將傳回的 transport.sdp 設為遠端 SDP answer,並等到收到 session.started 事件後,再傳送應用程式指令。HTTP 請求會啟動工作階段,請勿透過資料通道傳送 session.start。

如果 SDK 未提供 transport.dcid 欄位,請沿用 GPT-Live 快速入門指南中的標準資料通道設定。你仍可個別啟用用戶端支援的傳輸最佳化功能。

連線至 Realtime API

請使用統一的 WebRTC 連線流程。讓伺服器將通道 ID 填入 dcid 查詢參數,再呼叫 /v1/realtime/calls。如果建立通道時設定了 id: 4,請使用 POST /v1/realtime/calls?dcid=4,並在 multipart 請求本文中沿用相同的 SDP 和工作階段設定。

將傳回的 SDP 設為遠端 SDP answer。使用標準資料通道時,請省略 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. 選取註冊(Register),然後輸入應用程式的來源,例如 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 offer 和已協商的資料通道 ID 傳送至應用程式伺服器。伺服器接著將相同的 ID 填入 dcid 查詢參數,再呼叫 /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 統一介面。