Qwen-Omni-Realtime WebRTC 接入
WebRTC 使用媒體軌道傳輸音訊與視訊,使用 DataChannel 傳輸模型事件和文本。Web 端可使用瀏覽器原生 API,其他端可使用支援標準 WebRTC 的庫。百鍊不提供專用 WebRTC SDK。
本文提供本模型的 WebRTC 接入流程和完整的瀏覽器端示例。
適用範圍
本文面向 Qwen-Omni-Realtime。現有接入說明覆蓋:qwen3.8-omni-flash-realtime、qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime。示例模型為 qwen3.8-omni-flash-realtime。
- 使用所選地域和業務空間對應的 API Key 與 Workspace ID。
- 新加坡域名:
{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
https://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-omni-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。
整體流程
- 業務 AppServer 準備 API Key 和目標模型參數。
- 用戶端建立連接對象並註冊回調。
- 配置媒體方向及 DataChannel,暫不掛載上行媒體軌道。
- 透過 AppServer 交換 SDP,等待連接及事件通道就緒。
- 按模型協議完成配置,收到確認後掛載所需上行媒體軌道。
- 完成交互後停止採集、關閉連接並釋放資源。
說明
-
音訊與視訊透過 WebRTC 媒體軌道傳輸;應用負責獲取本地媒體軌道、綁定遠端播放器,並按目標模型的事件定義收發 DataChannel 消息。
-
WebRTC 的鑒權在 SDP 交換時完成,無需先獲取 AOQ Token。瀏覽器透過業務 AppServer 完成鑒權請求與 SDP 轉發,避免將長期 API Key 放入前端代碼。
-
連接成功表示傳輸通道已建立,不代表模型已完成初始化。本頁使用
qwen3.8-omni-flash-realtime時,發送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,
sendVideo: false,
};
function mediaDirection(send, receive) {
if (send && receive) return "sendrecv";
if (send) return "sendonly";
if (receive) return "recvonly";
return "inactive";
}
async function configureMedia() {
for (const kind of ["audio", "video"]) {
const send = kind === "audio" ? media.sendAudio : media.sendVideo;
const receive = kind === "audio" ? media.receiveAudio : false;
// 保留 m=audio;具体方向组合须由目标服务支持。
if (kind === "audio" || send || receive) {
const transceiver = pc.addTransceiver(kind, {
direction: mediaDirection(send, receive),
});
if (send) senders.set(kind, transceiver.sender);
}
}
if (!media.sendAudio && !media.sendVideo) return;
const stream = await navigator.mediaDevices.getUserMedia({
audio: media.sendAudio,
video: media.sendVideo ? {
width: { ideal: 640 }, height: { ideal: 480 },
frameRate: { ideal: 2, max: 2 },
} : 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 ? ["text", "audio"] : ["text"],
"voice": "Tina",
"turn_detection": { "type": "server_vad" },
},
});
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-Type | application/sdp |
Authorization | Bearer <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-Omni-Realtime | 語音輸入時開啓 | 需要語音回覆時開啓 | 需要視覺輸入時開啓 | 不支援開啓 |
該表描述業務需要的媒體方向,不承諾所有方向組合都可單獨協商。實際配置以目標模型和當前服務端協商能力為準。
準備媒體但延後上行
在建立 Offer 前預先協商所需媒體方向。對需要等待初始化確認的模型,先保留發送能力而不掛載真實採集軌道;模型就緒後再透過對應 sender 的 replaceTrack 等操作開始發送。接收媒體的處理邏輯可以提前註冊。
音訊發送、音訊接收和視訊發送應分別按需配置,不要把打開麥克風、播放音訊和模型初始化合併為一個操作。
媒體配置示例
下面以雙向語音、可選視訊上行為例。media 的三個開關分別控制音訊發送、音訊接收和視訊發送。addTransceiver 預先協商方向,採集到的軌道先保存在本地,直到模型就緒後再掛載到 sender。
代碼見完整示例。
視訊分辨率和幀率按目標模型要求設置;需要將本地預覽與上行幀率分離時,可參考最佳實踐中的 Canvas 降幀實現。
建立事件通道
在建立 Offer 前建立 DataChannel,使 SDP 包含資料通道協商。用戶端建立通道及服務端建立通道的處理方式參見Data 通道發送和接收事件。
DataChannel 負責發送模型初始化、文本和控制事件,並接收模型結果、狀態和錯誤。媒體軌道負責音訊與視訊傳輸。
完整示例在建立 Offer 前建立用戶端事件通道,並註冊服務端通道回調。
4. 建立連接
按以下順序完成建連:
- 呼叫
createOffer和setLocalDescription。 - 按服務端支援的 ICE 方式完成候選資訊收集;本示例等待 ICE 收集完成後發送本地 SDP。
- 將本地 SDP 發送到業務 AppServer,由 AppServer 攜帶 API Key 請求百鍊 SDP 交換介面。
- 檢查 HTTP 狀態,成功後以返回的 Answer SDP 呼叫
setRemoteDescription。 - 等待連接狀態成功,並確認用於發送模型事件的 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。
本模型事件定義見用戶端事件和服務端事件。媒體傳輸和可用模式按本頁說明處理。
Qwen-Omni-Realtime 使用 WebRTC 時,僅支援 VAD 模式,不支援 Manual 模式。音訊透過音訊軌道傳輸,不發送 input_audio_buffer.append;畫面透過視訊軌道傳輸,不發送 input_image_buffer.append。
模型事件示例
說明音訊與視訊透過媒體軌道傳輸,不使用 WebSocket 的媒體發送事件。
以下示例演示 qwen3.8-omni-flash-realtime 的 session.created → session.update → session.updated 流程。配置欄位以本模型事件參考為準。收到 session.updated 確認配置完成後,再掛載上行媒體軌道。
代碼見完整示例。
對於示例型號 qwen3.8-omni-flash-realtime,啓用音訊輸出時可透過 response.audio.done 瞭解模型的音訊生成狀態;該事件不表示用戶端的音訊已播放完畢。
開始媒體收發
滿足模型就緒條件後,掛載需要上行的音訊、視訊軌道。透過遠端軌道回調處理模型輸出,並持續解析 DataChannel 返回的事件。
-
音訊透過 RTP 媒體軌道傳輸,無需發送
input_audio_buffer.append。 -
畫面透過視訊軌道傳輸;當前 WebRTC 接入不支援
input_image_buffer.append。 -
文本、狀態、控制和錯誤透過 DataChannel 處理。
完整示例透過 startSendingMedia() 掛載上行軌道,透過 ontrack 處理接收到的媒體。
6. 結束交互並釋放資源
不再使用連接時,由用戶端業務層停止應用持有的本地採集軌道,關閉 DataChannel 和 RTCPeerConnection,釋放播放器等資源並清理業務狀態。
連接失敗或異常斷開時,撤銷模型就緒狀態。重新建立連接後按目標模型協議初始化,避免沿用上一條連接的會話狀態。
完整示例中的 endSession() 負責釋放連接和媒體資源。
在用戶點擊結束按鈕或頁面退出時呼叫 endSession()。如果業務額外啓用了最佳實踐中的 Canvas 降幀或錄制,還需取消動畫循環、停止 Canvas 媒體軌道及 MediaRecorder。
Data 通道發送和接收事件
用戶端透過 WebRTC DataChannel 發送和接收模型事件。發送前確認通道處於 open 狀態,使用 send 發送序列化後的模型事件;接收時在對應通道的 message 回調中解析消息,並處理服務端建立的事件通道。
發送事件的名稱、欄位、參數和呼叫時機遵循目標模型的用戶端事件定義;收到消息後的解析方式、狀態變更、結果和錯誤處理遵循該模型的服務端事件定義。初始化事件根據模型要求按需發送,後續文本和控制事件按照業務需要發送。
Data 通道代碼示例
同一個綁定函數處理用戶端建立和服務端建立的通道;它只負責收發與 JSON 解析,模型語義交給第 5 節的 handleModelEvent。sendModelEvent 可用於發送模型定義的初始化、文本或控制事件,但應在對應模型允許的時機呼叫。
完整示例中的 sendModelEvent() 和 bindDataChannel() 負責發送和接收事件。
完整示例中,開始按鈕呼叫 startSession(),結束按鈕呼叫 endSession()。這兩個函數為本文示例函數,不是 WebRTC 內置 API。
Qwen-Omni-Realtime 事件定義
| 模型/應用 | 用戶端事件定義(發送) | 服務端事件定義(接收) |
|---|---|---|
| Qwen-Omni-Realtime | 用戶端事件 | 服務端事件 |
模型事件的發送與接收還應遵循以下規則:
-
使用事件的
type欄位識別模型事件,關聯標識按本模型事件參考處理。 -
模型要求的初始化確認、輸入提交、響應取消和任務結束等操作,均在 Data 通道中按對應協議處理;它們屬於模型交互語義,與斷開傳輸連接是不同操作。
-
音訊與視訊資料透過媒體軌道傳輸。引用模型事件文檔時,媒體封裝和可用交互模式仍遵循本文的接入方式,不直接套用 WebSocket 的媒體發送方式。