全部產品
Search
文件中心

Alibaba Cloud Model Studio:Qwen-Audio-Realtime WebRTC 接入

更新時間:Nov 16, 2026

Qwen-Audio-Realtime WebRTC 接入

WebRTC 使用媒體軌道傳輸音訊,使用 DataChannel 傳輸模型事件和文本。Web 端可使用瀏覽器原生 API,其他端可使用支援標準 WebRTC 的庫。百鍊不提供專用 WebRTC SDK。

本文提供本模型的 WebRTC 接入流程和完整的瀏覽器端示例。

適用範圍

本文面向 Qwen-Audio-Realtime。現有接入說明覆蓋:qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash。示例模型為 qwen-audio-3.1-realtime-plus。

  • 使用所選地域和業務空間對應的 API Key 與 Workspace ID。
  • 北京域名:{WorkspaceId}.cn-beijing.maas.aliyuncs.com;新加坡域名:{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com。
  • 長期 API Key 由服務端保管,不放入瀏覽器或移動端應用。臨時 API Key 的生成方式和權限說明參見生成臨時 API Key。

瀏覽器採集音訊時使用安全上下文;使用麥克風時申請麥克風權限。接收音訊時應處理瀏覽器自動播放限制。

鑒權與 SDP 交換

瀏覽器向業務 AppServer 提交 Offer SDP。AppServer 使用 API Key 轉發以下請求,並將 Answer SDP 原樣返回瀏覽器;長期 API Key 不進入前端。

  • 方法:POST
POSThttps://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus
POSThttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus

  • 請求頭:Authorization: Bearer <API_KEY>、Content-Type: application/sdp
  • 請求體:Offer SDP 字串。
  • 成功響應:HTTP 200,正文為 Answer SDP;失敗返回 4xx。

WebRTC 在 SDP 交換時鑒權,不需要先申請 AOQ Token。下文示例中的 /api/realtime/sdp 是業務 AppServer 的自建介面,需要實現上述轉發,不是百鍊提供的 URL。

整體流程

WebRTC 接入時序圖
  1. 業務 AppServer 準備 API Key 和目標模型參數。
  2. 用戶端建立連接對象並註冊回調。
  3. 配置媒體方向及 DataChannel,暫不掛載上行媒體軌道。
  4. 透過 AppServer 交換 SDP,等待連接及事件通道就緒。
  5. 按模型協議完成配置,收到確認後掛載所需上行媒體軌道。
  6. 完成交互後停止採集、關閉連接並釋放資源。

說明

  • 音訊透過 WebRTC 媒體軌道傳輸;應用負責獲取本地音訊軌道、綁定遠端播放器,並按目標模型的事件定義收發 DataChannel 消息。

  • WebRTC 的鑒權在 SDP 交換時完成,無需先獲取 AOQ Token。瀏覽器透過業務 AppServer 完成鑒權請求與 SDP 轉發,避免將長期 API Key 放入前端代碼。

  • 連接成功表示傳輸通道已建立,不代表模型已完成初始化。本頁使用 qwen-audio-3.1-realtime-plus 時,發送 session.update 並收到 session.updated 後,再開啓所需的上行媒體。

完整示例

以下是瀏覽器端的完整示例。先按鑒權與 SDP 交換實現業務 AppServer 的 /api/realtime/sdp 介面,再從業務 AppServer 的同源地址打開此 HTML 頁面;協議、主機和端口須一致。例如,頁面和 /api/realtime/sdp 均由 http://localhost:3000 提供。服務端負責保存 API Key 並轉發 SDP,不要將長期 API Key 放在頁面中。點擊“开始”建立連接;結束交互時點擊“结束”釋放資源。本示例每次建立一條連接;需要再次使用時請重新加載頁面。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>WebRTC 接入示例</title>
</head>
<body>
<button id="start-session" type="button">开始</button>
<button id="end-session" type="button">结束</button>
<script>
const pc = new RTCPeerConnection({ iceServers: [ ] });

const channels = new Set();
const senders = new Map();
const remoteAudio = document.createElement("audio");
remoteAudio.controls = true; // 自动播放被阻止时,用户可手动播放。
remoteAudio.autoplay = true;
document.body.appendChild(remoteAudio);

let localStream = null;
let eventChannel = null;
let stopped = false;
let started = false;
let sessionCreated = false;
let updateSent = false;
let modelReady = false;
let mediaStarted = false;
const requestController = new AbortController();
const media = {
  sendAudio: true,
  receiveAudio: true,
};

function mediaDirection(send, receive) {
  if (send && receive) return "sendrecv";
  if (send) return "sendonly";
  if (receive) return "recvonly";
  return "inactive";
}

async function configureMedia() {
  // 保留 m=audio;具体方向组合须由目标服务支持。
  const transceiver = pc.addTransceiver("audio", {
    direction: mediaDirection(media.sendAudio, media.receiveAudio),
  });
  if (media.sendAudio) senders.set("audio", transceiver.sender);
  if (!media.sendAudio) return;
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: true,
    video: false,
  });
  // 用户可能在权限弹窗期间结束通话。
  if (stopped) {
    stream.getTracks().forEach(track => track.stop());
    throw new Error("会话已结束");
  }
  localStream = stream;
  // 此时 sender.track 仍为空,不向模型发送采集数据。
}
// bindDataChannel 的完整实现见“Data 通道发送和接收事件”。
pc.ondatachannel = ({ channel }) => bindDataChannel(channel);
const clientChannel = pc.createDataChannel("oai-events");
bindDataChannel(clientChannel);
pc.onconnectionstatechange = () => {
  console.log("WebRTC 状态:", pc.connectionState);
  if (pc.connectionState === "connected") {
    tryInitializeModel();
  } else if (["failed", "disconnected", "closed"].includes(pc.connectionState)) {
    // 本示例选择结束连接;业务可按需要设计断线恢复策略。
    endSession();
  }
};

function waitForIceComplete() {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => finish(new Error("ICE 收集超时")), 15000);
    function finish(error) {
      clearTimeout(timer);
      pc.removeEventListener("icegatheringstatechange", check);
      requestController.signal.removeEventListener("abort", cancel);
      error ? reject(error) : resolve();
    }
    function check() {
      if (pc.iceGatheringState === "complete") finish();
    }
    function cancel() { finish(new Error("会话已结束")); }
    pc.addEventListener("icegatheringstatechange", check);
    requestController.signal.addEventListener("abort", cancel, { once: true });
    if (stopped) cancel();
    else check();
  });
}

function normalizeAnswerSdp(sdp) {
  return String(sdp).trim().replace(/\r?\n/g, "\r\n") + "\r\n";
}

async function startSession() {
  if (started || stopped) return;
  started = true;
  try {
    await configureMedia();
    if (stopped) return;
    const offer = await pc.createOffer();
    await pc.setLocalDescription(offer);
    await waitForIceComplete();

    // 这是业务自行实现的同源接口,不是百炼官方接口。
    // AppServer 为目标模型转发 SDP,附带 API Key,并原样返回 Answer SDP。
    const response = await fetch("/api/realtime/sdp", {
      method: "POST",
      headers: { "Content-Type": "application/sdp" },
      body: pc.localDescription.sdp,
      signal: requestController.signal,
    });
    if (!response.ok) {
      throw new Error(`SDP 交换失败:${response.status} ${await response.text()}`);
    }
    const answerSdp = normalizeAnswerSdp(await response.text());
    if (stopped) return;
    await pc.setRemoteDescription({ type: "answer", sdp: answerSdp });
    // 后续由 connectionstatechange、DataChannel 和模型事件驱动。
  } catch (error) {
    if (!stopped) console.error("建连失败:", error);
    endSession();
  }
}
function tryInitializeModel() {
  if (stopped || updateSent || !sessionCreated ||
      pc.connectionState !== "connected" ||
      eventChannel?.readyState !== "open") return;
  sendModelEvent({
    event_id: `event_${crypto.randomUUID()}`,
    type: "session.update",
    session: {
      "modalities": media.receiveAudio ? ["audio", "text"] : ["text"],
      "voice": "longanqian_v3.1",
    },
  });
  updateSent = true;
}

async function handleModelEvent(event, channel) {
  if (stopped) return;
  if (event.type === "session.created") {
    sessionCreated = true;
    eventChannel = channel; // 沿收到会话事件的通道发送配置。
    tryInitializeModel();
  } else if (event.type === "session.updated" && updateSent) {
    modelReady = true;
    await startSendingMedia();
  } else if (event.type === "error") {
    console.error("模型错误:", event.error);
    endSession();
  } else {
    // 按所选模型定义展示文本、转录或响应状态;音频从媒体轨道接收。
    console.log("模型事件:", event);
  }
}
async function startSendingMedia() {
  if (stopped || !modelReady || mediaStarted) return;
  mediaStarted = true;

  for (const track of localStream?.getTracks() ?? []) {

    if (stopped) return;
    const sender = senders.get(track.kind);
    if (sender) await sender.replaceTrack(track);
  }
}

// 在 startSession() 前注册。无 streams 的轨道也能正确接收。
const remoteAudioStream = new MediaStream();
pc.ontrack = ({ track }) => {
  if (stopped) return;
  if (track.kind === "audio" && media.receiveAudio) {
    remoteAudioStream.addTrack(track);
    remoteAudio.srcObject = remoteAudioStream;
    remoteAudio.play().catch(() => {
      console.info("自动播放受限,请点击音频控件播放");
    });
  }
};
function endSession() {
  if (stopped) return;
  stopped = true;
  modelReady = false;
  sessionCreated = false;
  updateSent = false;
  mediaStarted = false;
  requestController.abort(); // 取消未完成的 SDP 请求/ICE 等待。
  localStream?.getTracks().forEach(track => track.stop());
  localStream = null;
  channels.forEach(channel => channel.close());
  channels.clear();
  eventChannel = null;
  pc.close();
  senders.clear();
  remoteAudioStream.getTracks().forEach(track => track.stop());
  remoteAudio.pause();
  remoteAudio.srcObject = null;
  remoteAudio.remove();
}
function sendModelEvent(event, channel = eventChannel) {
  if (stopped || pc.connectionState !== "connected" ||
      channel?.readyState !== "open") {
    throw new Error("Data 通道尚不可用");
  }
  channel.send(JSON.stringify(event));
}

function bindDataChannel(channel) {
  channels.add(channel);
  channel.onopen = () => {
    if (stopped) return;
    console.log("DataChannel 已打开:", channel.label);
    tryInitializeModel();
  };
  channel.onmessage = ({ data }) => {
    if (stopped) return;
    let event;
    try { event = JSON.parse(data); }
    catch (error) {
      console.warn("无法解析模型事件:", error);
      return;
    }
    if (!event || typeof event !== "object") return;
    handleModelEvent(event, channel).catch(error => {
      if (!stopped) console.error("模型事件处理失败:", error);
      endSession();
    });
  };
  channel.onerror = error => console.error("DataChannel 错误:", error);
  channel.onclose = () => {
    channels.delete(channel);
    if (channel === eventChannel) endSession();
  };
  if (channel.readyState === "open") channel.onopen();
}

document.getElementById("start-session").addEventListener("click", startSession);
document.getElementById("end-session").addEventListener("click", endSession);
</script>
</body>
</html>

1. 準備鑒權和連接參數

業務 AppServer 根據目標模型、地域和業務空間配置 SDP 交換請求。標準 Realtime 建連參數如下;應用專屬接入參數以對應最佳實踐為準。

配置項值
方法POST
地址https://{endpoint}/api/v1/webrtc/realtime?model={model_name}
Content-Typeapplication/sdp
AuthorizationBearer <API_KEY>
請求體Offer SDP
成功響應Answer SDP

完整地域、地址和鑒權說明見鑒權與 SDP 交換。業務 AppServer 的介面由業務自行實現,不屬於百鍊 SDK API。

2. 初始化連接對象並註冊回調

Web 端建立 RTCPeerConnection,其他端執行對應庫的初始化操作。建立連接前註冊以下處理邏輯:

  • 連接狀態變化:判斷連接是否成功,以及失敗或斷開。

  • DataChannel 建立、打開、消息和關閉:承載模型事件。

  • 遠端媒體軌道:接收並播放音訊,或處理目標應用支援的其他媒體。

完整示例在同一腳本中建立連接對象、狀態變量和回調。示例每次建立一條連接;結束後再次通話需重新建立這些對象。

連接對象和狀態變量見完整示例。

註冊消息監聽應早於模型初始化,避免遺漏服務端主動發送的會話事件。不要只監聽用戶端建立的通道:服務端會透過名為 txt 的通道推送事件,應處理 datachannel 回調。

3. 配置媒體方向和 DataChannel

選擇音訊方向

以下方向均以用戶端為視角。WebRTC 透過媒體收發器協商發送與接收能力:雙向為 sendrecv,僅發送為 sendonly,僅接收為 recvonly。最終可用能力還取決於服務端 SDP 應答及模型支援範圍。

方向配置內容
推音訊協商音訊發送能力,準備麥克風或外部音訊軌道;模型就緒後掛載
拉音訊協商音訊接收能力,在遠端軌道回調中綁定音訊播放

例如,語音對話一般使用雙向音訊。Offer SDP 需要包含音訊媒體段 m=audio;不能僅因業務無需播放音訊就刪除該媒體段。

本模型的媒體方向

模型/應用推音訊拉音訊推視訊拉視訊
Qwen-Audio-Realtime語音對話時開啓需要語音回覆時開啓不支援開啓不支援開啓

該表描述業務需要的媒體方向,不承諾所有方向組合都可單獨協商。實際配置以目標模型和當前服務端協商能力為準。

準備媒體但延後上行

在建立 Offer 前預先協商所需媒體方向。對需要等待初始化確認的模型,先保留發送能力而不掛載真實採集軌道;模型就緒後再透過對應 sender 的 replaceTrack 等操作開始發送。接收媒體的處理邏輯可以提前註冊。

音訊發送和接收應分別按需配置,不要把打開麥克風、播放音訊和模型初始化合併為一個操作。

媒體配置示例

下面以雙向語音為例。media 的兩個開關分別控制音訊發送和接收;addTransceiver 預先協商方向,採集到的軌道先保存在本地,直到模型就緒後再掛載到 sender。

代碼見完整示例。

建立事件通道

在建立 Offer 前建立 DataChannel,使 SDP 包含資料通道協商。用戶端建立通道及服務端建立通道的處理方式參見Data 通道發送和接收事件。

DataChannel 負責發送模型初始化、文本和控制事件,並接收模型結果、狀態和錯誤。媒體軌道負責音訊傳輸。

完整示例在建立 Offer 前建立用戶端事件通道,並註冊服務端通道回調。

4. 建立連接

按以下順序完成建連:

  1. 呼叫 createOffer 和 setLocalDescription。
  2. 按服務端支援的 ICE 方式完成候選資訊收集;本示例等待 ICE 收集完成後發送本地 SDP。
  3. 將本地 SDP 發送到業務 AppServer,由 AppServer 攜帶 API Key 請求百鍊 SDP 交換介面。
  4. 檢查 HTTP 狀態,成功後以返回的 Answer SDP 呼叫 setRemoteDescription。
  5. 等待連接狀態成功,並確認用於發送模型事件的 DataChannel 已打開。

SDP 交換成功或 setRemoteDescription 完成,只表示完成相應協商步驟,不能直接當作媒體連接已經成功。DataChannel 未處於 open 狀態時也不能發送模型事件。

建連代碼及狀態回調

監聽 connectionstatechange 判斷連接狀態,監聽 icegatheringstatechange 等待完整的本地 SDP。模型初始化還需要 DataChannel 的 open 和模型的就緒事件,不能僅依靠 SDP 交換完成判斷。

完整示例透過 startSession() 完成 SDP 交換,並透過連接狀態回調處理連接結果。

業務 AppServer 應按第 1 節的地址和請求頭轉發 Offer;示例介面約定返回純 SDP 文本。不要將含有 HTTP 響應頭、日誌或 JSON 包裝的內容直接傳給 setRemoteDescription。

5. 按模型協議交互並收發媒體

初始化模型

連接及事件通道可用後,按目標模型協議處理初始化。應用需要保存已收到的服務端初始化事件,並結合通道狀態推進流程,避免依賴回調到達的固定順序。

例如,使用 session.update 配置會話的模型,應按其協議構造事件,等待配置確認後再發送輸入。音色、輸出模態、VAD、採樣率等參數都應來自當前模型文檔。

session.created 表示會話建立,不能統一視為配置已生效。對於要求確認會話配置的模型,應等待 session.updated。

本模型事件定義見用戶端事件和服務端事件。媒體傳輸和可用模式按本頁說明處理。

模型事件示例

說明音訊透過媒體軌道傳輸,不使用 WebSocket 的媒體發送事件。

以下示例演示 qwen-audio-3.1-realtime-plus 的 session.created → session.update → session.updated 流程。配置欄位以本模型事件參考為準。收到 session.updated 確認配置完成後,再掛載上行媒體軌道。

代碼見完整示例。

對於示例型號 qwen-audio-3.1-realtime-plus,啓用音訊輸出時可透過 response.audio.done 瞭解模型的音訊生成狀態;該事件不表示用戶端的音訊已播放完畢。

開始媒體收發

滿足模型就緒條件後,掛載需要上行的音訊軌道。透過遠端軌道回調處理模型輸出,並持續解析 DataChannel 返回的事件。

  • 音訊透過 RTP 媒體軌道傳輸,無需發送 input_audio_buffer.append。

  • 文本、狀態、控制和錯誤透過 DataChannel 處理。

完整示例透過 startSendingMedia() 掛載上行軌道,透過 ontrack 處理接收到的媒體。

6. 結束交互並釋放資源

不再使用連接時,由用戶端業務層停止應用持有的本地採集軌道,關閉 DataChannel 和 RTCPeerConnection,釋放播放器等資源並清理業務狀態。

連接失敗或異常斷開時,撤銷模型就緒狀態。重新建立連接後按目標模型協議初始化,避免沿用上一條連接的會話狀態。

完整示例中的 endSession() 負責釋放連接和媒體資源。

在用戶點擊結束按鈕或頁面退出時呼叫 endSession()。

Data 通道發送和接收事件

用戶端透過 WebRTC DataChannel 發送和接收模型事件。發送前確認通道處於 open 狀態,使用 send 發送序列化後的模型事件;接收時在對應通道的 message 回調中解析消息,並處理服務端建立的事件通道。

發送事件的名稱、欄位、參數和呼叫時機遵循目標模型的用戶端事件定義;收到消息後的解析方式、狀態變更、結果和錯誤處理遵循該模型的服務端事件定義。初始化事件根據模型要求按需發送,後續文本和控制事件按照業務需要發送。

Data 通道代碼示例

同一個綁定函數處理用戶端建立和服務端建立的通道;它只負責收發與 JSON 解析,模型語義交給第 5 節的 handleModelEvent。sendModelEvent 可用於發送模型定義的初始化、文本或控制事件,但應在對應模型允許的時機呼叫。

完整示例中的 sendModelEvent() 和 bindDataChannel() 負責發送和接收事件。

完整示例中,開始按鈕呼叫 startSession(),結束按鈕呼叫 endSession()。這兩個函數為本文示例函數,不是 WebRTC 內置 API。

Qwen-Audio-Realtime 事件定義

模型/應用用戶端事件定義(發送)服務端事件定義(接收)
Qwen-Audio-Realtime用戶端事件服務端事件

模型事件的發送與接收還應遵循以下規則:

  • 使用事件的 type 欄位識別模型事件,關聯標識按本模型事件參考處理。

  • 模型要求的初始化確認、輸入提交、響應取消和任務結束等操作,均在 Data 通道中按對應協議處理;它們屬於模型交互語義,與斷開傳輸連接是不同操作。

  • 音訊資料透過媒體軌道傳輸。引用模型事件文檔時,媒體封裝和可用交互模式仍遵循本文的接入方式,不直接套用 WebSocket 的媒體發送方式。

事件參考