全部產品
Search
文件中心

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

更新時間:Nov 16, 2026

Qwen-LiveTranslate-Realtime WebRTC 接入

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

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

適用範圍

本文面向 Qwen-LiveTranslate-Realtime。現有指南列有 qwen3.8-livetranslate-flash-realtime 和 qwen3.5-livetranslate-flash-realtime,兩者的配置和事件欄位不同,詳見用戶端事件。本文示例使用 qwen3.8-livetranslate-flash-realtime。

  • 使用所選地域和業務空間對應的 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=qwen3.8-livetranslate-flash-realtime
POSThttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-livetranslate-flash-realtime

  • 請求頭: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 放入前端代碼。

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

完整示例

以下是瀏覽器端的完整示例。先按鑒權與 SDP 交換實現業務 AppServer 的 /api/realtime/sdp 介面,再從業務 AppServer 的同源地址打開此 HTML 頁面;協議、主機和端口須一致。例如,頁面和 /api/realtime/sdp 均由 http://localhost:3000 提供。服務端負責保存 API Key 並轉發 SDP,不要將長期 API Key 放在頁面中。點擊“结束输入”發送 session.finish,等待 session.finished 並播放完剩餘譯音後,再點擊“译音播放完成后断开”。建連中或需要提前退出時,可點擊“取消并断开”;此操作會立即關閉連接,可能丟失尚未返回的翻譯或未播放的譯音。本示例每次建立一條連接;需要再次使用時請重新加載頁面。

<!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="finish-input" type="button" disabled>结束输入</button>
<button id="end-session" type="button" disabled>译音播放完成后断开</button>
<button id="cancel-session" type="button" disabled>取消并断开</button>
<p id="session-status" role="status" aria-live="polite">点击“开始翻译”建立连接。</p>
<script>
const startSessionButton = document.getElementById("start-session");
const finishInputButton = document.getElementById("finish-input");
const endSessionButton = document.getElementById("end-session");
const cancelSessionButton = document.getElementById("cancel-session");
const sessionStatus = document.getElementById("session-status");
let translationFinished = false;
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;
let finishRequested = 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: media.sendAudio,
    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: {
      "output_modalities": media.receiveAudio ? ["text", "audio"] : ["text"],
      "audio": {
        "input": {
          "turn_detection": {
            "type": "speaker_detection",
            "threshold": 0.5,
          },
        },
      },
      ...(media.receiveAudio ? {
        "voice": "Tina",
      } : {}),
      "translation": {
        "language": "en",
      },
    },
  });
  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();
    if (!finishRequested && !stopped) {
      finishInputButton.disabled = false;
      sessionStatus.textContent = "模型已就绪,可以开始说话。";
    }
  } else if (event.type === "session.finished") {
    translationFinished = true;
    finishInputButton.disabled = true;
    endSessionButton.disabled = false;
    sessionStatus.textContent = "翻译已完成,请等待剩余译音播放完毕后断开。";
    console.log("翻译处理已结束,请等待剩余译音播放完成后释放资源");
  } 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("自动播放受限,请点击音频控件播放");
    });
  }
};
async function finishTranslation() {
  if (stopped || !modelReady || finishRequested) return;
  finishRequested = true;
  try {
    localStream?.getAudioTracks().forEach(track => track.stop());
    const sender = senders.get("audio");
    if (sender) await sender.replaceTrack(null);
    sendModelEvent({ type: "session.finish" });
  } catch (error) {
    finishRequested = false;
    throw error;
  }
}
function endSession() {
  if (stopped) return;
  stopped = true;
  finishInputButton.disabled = true;
  endSessionButton.disabled = true;
  cancelSessionButton.disabled = true;
  sessionStatus.textContent = "连接已关闭;如需再次翻译,请重新加载页面。";
  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();
}

startSessionButton.addEventListener("click", () => {
  startSessionButton.disabled = true;
  cancelSessionButton.disabled = false;
  sessionStatus.textContent = "正在建立连接……";
  startSession();
});
finishInputButton.addEventListener("click", () => {
  finishInputButton.disabled = true;
  sessionStatus.textContent = "正在结束输入……";
  finishTranslation().then(() => {
    if (!translationFinished && !stopped) {
      sessionStatus.textContent = "已结束输入,正在等待翻译完成。";
    }
  }).catch(error => {
    if (!stopped) {
      finishInputButton.disabled = false;
      sessionStatus.textContent = "结束输入失败,请重试。";
    }
    console.error("结束输入失败:", error);
  });
});
endSessionButton.addEventListener("click", endSession);
cancelSessionButton.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 建立、打開、消息和關閉:承載模型事件。

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

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

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

完整示例使用 finishRequested 避免重復發送結束事件。

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

3. 配置媒體方向和 DataChannel

選擇媒體方向

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

方向配置內容
推音訊協商音訊發送能力,準備麥克風或外部音訊軌道;模型就緒後掛載
拉音訊協商音訊接收能力,在遠端軌道回調中綁定音訊播放
推視訊按所選版本及場景支援範圍協商視訊發送能力,準備攝像頭或外部視訊軌道

例如,輸入語音時配置音訊上行;需要語音譯文時配置音訊下行。Offer SDP 需要包含音訊媒體段 m=audio;不能僅因業務無需播放音訊就刪除該媒體段。

本模型的媒體方向

模型/應用推音訊拉音訊推視訊拉視訊
Qwen-LiveTranslate-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 的媒體發送事件。

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

以下配置將語音翻譯為英語,使用 Tina 音色。

代碼見完整示例。

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

開始媒體收發

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

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

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

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

6. 結束交互並釋放資源

對於示例模型 qwen3.8-livetranslate-flash-realtime,完成音訊輸入後,停止採集和音訊上行,透過 DataChannel 發送 session.finish。繼續接收尾句原文、譯文和譯音,等待 session.finished。該事件表示模型翻譯處理完成,不代表用戶端的剩餘譯音已播放完畢;如需完整播放,播放完成後再呼叫 endSession() 釋放資源。

完整示例中的 finishTranslation() 使用建立的音訊軌道和 DataChannel。如果輸入來自文件或業務緩衝區,需先完成已緩衝音訊的發送,再結束輸入。

finishTranslation() 的實現見完整示例。

endSession() 僅釋放連接和媒體資源,不發送結束事件。

完成模型交互後,由用戶端業務層停止應用持有的本地採集軌道,關閉 DataChannel 和 RTCPeerConnection,釋放播放器等資源並清理業務狀態。

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

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

完成模型交互並處理剩餘譯音後呼叫 endSession()。如果業務額外使用錄制,還需停止 MediaRecorder。

Data 通道發送和接收事件

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

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

Data 通道代碼示例

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

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

完整示例中,開始翻譯時呼叫 startSession(),結束輸入時呼叫 finishTranslation(),完成翻譯和播放收尾後呼叫 endSession()。這些函數為本文示例函數,不是 WebRTC 內置 API。

Qwen-LiveTranslate-Realtime 事件定義

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

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

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

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

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

事件參考