Qwen-Omni-Realtime AOQ 接入
AOQ 將音訊與視訊媒體與模型事件分軌傳輸。SDK 負責媒體採集、編解碼、傳輸和播放;應用透過 Data 軌發送模型事件並處理回覆。本頁使用 Qwen-Omni-Realtime 的媒體方向和事件協議。
適用範圍
本文面向 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 只保存在服務端,不放入瀏覽器或移動端應用。
-
使用麥克風采集音訊或使用攝像頭採集畫面時,按平台要求申請相應權限。
-
從 SDK 下載獲取對應平台的 SDK。
鑒權與連接憑證
說明如需預先取得 Token,或瞭解完整的鑒權流程,請參見建連鑒權詳解。
由業務 AppServer 發起以下請求。請先配置 API Key 到環境變量。在下方請求地址選擇地域,並填寫業務空間 ID。clientIp 選填,不填時使用請求網關的 IP。
https://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtimeexport ENDPOINT="{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com"
curl -X POST \
"https://${ENDPOINT}/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime" \
-H "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-H "x-dashscope-rtc-transport: moq" \
-d '{}'
如需指定用戶端公網 IP,將請求體中的 -d '{}' 替換為 -d '{"clientIp":"<客户端公网 IP>"}'。
參數說明
配置項 | 值 | 說明 |
|---|---|---|
endpoint | 根據業務情況選擇接入域名 | 指定對應的接入域名,詳情請參見選擇地域、服務部署範圍和接入域名。如果使用Token Plan,接入域名中的 |
Content-Type |
| 指定消息類型 |
Authorization |
| 填寫API Key |
x-dashscope-rtc-transport |
| 指定使用 AOQ 協議 |
clientIp | 用戶端真實公網 IP | 選填。不填寫時,預設使用請求百鍊網關的 IP;填寫後以 clientIp 為準。服務 會根據用戶端 IP 分配最佳的 Relay 接入點 |
響應示例
{
"sid": "1d06b55683db49bba67a407902f62d02:1782706970:69aecdc5...",
"aoqTokenForClient": "ecc1a46015d5496ca4ff7a48281eb739",
"clientRelayEndpoints": [{"endpoint": "121.199.XX.XX", "port": 8443, "route_index": 0}],
"clientRelayCertFingerprint": "sha256/99843495...",
"sidExpiresInSecs": 7200,
"extraInfo": {"workspaceIdHash": "2021b6f98cea4cff"}
}
響應參數說明
欄位 | 說明 |
|---|---|
sid | 會話唯一標識 |
aoqTokenForClient | 用戶端連接令牌,傳給 SDK 的 token 欄位 |
clientRelayEndpoints | Relay 接入點陣列。響應示例中的陣列元素包含以下欄位: 屬性 endpoint Relay 接入點地址。 portRelay 接入點端口。 route_index下方 iOS 示例在該欄位缺省時使用陣列下標。 |
clientRelayCertFingerprint | Relay TLS 證書指紋 |
sidExpiresInSecs | 會話過期時間(秒) |
extraInfo | 附加資訊。 屬性 workspaceIdHash 工作區 ID 哈希。 |
AOQ Client SDK 連接示例
說明clientIp 為請求體中的選填欄位。不填寫時,預設使用請求百鍊網關的 IP 作為用戶端 IP;填寫後則以指定的 clientIp 為準。建議由業務 AppServer 獲取用戶端真實 IP 後填入,以獲得最佳的 Relay 接入點。
let resp = try JSONDecoder().decode(AllocateResponse.self, from: responseData)
let config = AoqConnectConfig()
config.token = resp.aoqTokenForClient
config.sid = resp.sid
config.certFingerprint = resp.clientRelayCertFingerprint
config.relayEndpoints = resp.clientRelayEndpoints.enumerated().map { index, item in
let ep = AoqRelayEndpoint()
// route_index 缺省时按数组下标兜底
ep.routeIndex = item.routeIndex ?? index
ep.endpoint = item.endpoint
ep.port = item.port
return ep
}
config.workspaceIdHash = resp.extraInfo?.workspaceIdHash ?? ""
let audioTrack = AoqTrackParam()
audioTrack.trackType = .audio
let dataTrack = AoqTrackParam()
dataTrack.trackType = .data
config.publishTracks = [audioTrack, dataTrack]
config.subscribeTracks = [audioTrack, dataTrack]
engine.connect(config)
JSONObject obj = new JSONObject(responseText);
AoqClientEngine.AoqConnectConfig cfg = new AoqClientEngine.AoqConnectConfig();
cfg.token = obj.optString("aoqTokenForClient", "");
cfg.sid = obj.optString("sid", "");
cfg.certFingerprint = obj.optString("clientRelayCertFingerprint", "");
JSONArray arr = obj.optJSONArray("clientRelayEndpoints");
if (arr != null) {
for (int i = 0; i < arr.length(); i++) {
JSONObject o = arr.optJSONObject(i);
AoqClientEngine.AoqRelayEndpoint ep = new AoqClientEngine.AoqRelayEndpoint();
// route_index 缺省时按数组下标兜底
ep.routeIndex = o.has("route_index") ? o.optInt("route_index", i) : i;
ep.endpoint = o.optString("endpoint", "");
ep.port = o.optInt("port", 0);
cfg.relayEndpoints.add(ep);
}
}
JSONObject ext = obj.optJSONObject("extraInfo");
cfg.workspaceIdHash = ext != null ? ext.optString("workspaceIdHash", "") : "";
AoqClientEngine.AoqTrackParam audio = new AoqClientEngine.AoqTrackParam();
audio.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeAudio;
AoqClientEngine.AoqTrackParam data = new AoqClientEngine.AoqTrackParam();
data.trackType = AoqClientEngine.AoqTrackType.AoqTrackTypeData;
cfg.publishTracks.add(audio);
cfg.publishTracks.add(data);
cfg.subscribeTracks.add(audio);
cfg.subscribeTracks.add(data);
engine.connect(cfg);
const obj = JSON.parse(responseText) as Record<string, Object | undefined>;
const cfg: AoqConnectConfig = {
token: String(obj['aoqTokenForClient'] ?? ''),
sid: String(obj['sid'] ?? ''),
certFingerprint: String(obj['clientRelayCertFingerprint'] ?? ''),
// route_index 缺省时按数组下标兜底
relayEndpoints: (obj['clientRelayEndpoints'] as Array<any>).map((item, index) => ({
routeIndex: Number(item['route_index'] ?? index),
endpoint: String(item['endpoint'] ?? ''),
port: Number(item['port'] ?? 0)
})),
workspaceIdHash: String((obj['extraInfo'] as any)?.['workspaceIdHash'] ?? ''),
publishTracks: [
{ trackType: AoqTrackType.AoqTrackTypeAudio },
{ trackType: AoqTrackType.AoqTrackTypeData }
],
subscribeTracks: [
{ trackType: AoqTrackType.AoqTrackTypeAudio },
{ trackType: AoqTrackType.AoqTrackTypeData }
]
};
engine.connect(cfg);
整體流程
- 用戶端透過業務 AppServer 獲取連接憑證。
- 建立 SDK 引擎並註冊回調。
- 配置媒體和 Data 軌道,關閉上行媒體發送。
- 建立 AOQ 連接,等待連接成功。
- 按模型協議完成配置,收到確認後開啓所需媒體發送。
- 完成交互後斷開連接並釋放資源。
說明
-
音訊與視訊媒體資料由 AOQ SDK 接管,負責採集、處理、發送、接收和播放;Data 資料需要呼叫方遵循目標模型的事件定義進行發送和接收。
-
連接成功表示與模型的傳輸通道已建立,用戶端應在模型初始化完成後再開啓所需的上行媒體。對於本頁示例型號
qwen3.8-omni-flash-realtime,發送session.update後需等待session.updated,再開啓媒體發送。
1. 獲取連接憑證
用戶端向業務 AppServer 請求憑證。AppServer 使用本模型的 Realtime 建連地址,並攜帶 API Key 和 x-dashscope-rtc-transport: moq 請求網關。完整地址、請求和欄位說明見 Token 鑒權。
將響應映射到 AoqConnectConfig:
| 網關響應 | SDK 配置 |
|---|---|
aoqTokenForClient | token |
sid | sid |
clientRelayCertFingerprint | certFingerprint |
clientRelayEndpoints | relayEndpoints,按結構轉換各接入點 |
extraInfo 中的 workspaceIdHash | workspaceIdHash |
新建連接時獲取新的連接憑證。同一連接內能否復用會話或啓動下一輪任務,由目標模型協議決定。
2. 初始化 SDK 並註冊回調
建立引擎並註冊連接狀態、Data 消息和錯誤回調。以 iOS Swift 為例:
let createConfig = AoqCreateConfig()
createConfig.workDir = workDir
createConfig.enableDumpAudio = false
engine = AoqClientEngine.createEngine(createConfig, delegate: self)
實現 AoqEngineDelegate,在 onConnectionStatusChange 中維護連接狀態,在 onDataMsg 中解析目標模型事件,在 onError 中處理 SDK 錯誤。模型返回的錯誤事件也需要在 Data 消息處理邏輯中單獨處理。SDK 介面及錯誤說明請參見 各平台 SDK和功能參考。
3. 配置 SDK
選擇四個媒體方向
以下“推”和“拉”均以用戶端為視角。按業務實際使用的輸入、輸出模態配置,不需要的方向不添加媒體軌道。
| 方向 | 配置內容 | 典型用途 |
|---|---|---|
| 推音訊 | 發佈 Audio 軌,設置音訊編碼器,配置內置或外部採集 | 語音對話 |
| 拉音訊 | 訂閱 Audio 軌,設置音訊解碼器,配置播放器或外部播放 | 語音回覆 |
| 推視訊 | 發佈 Video 軌,配置攝像頭或外部視訊輸入及編碼參數 | 向支援視覺輸入的模型發送畫面 |
| 拉視訊 | 本模型不支援視訊輸出 | 不配置視訊訂閱 |
Data 軌獨立於這四個方向:發佈 Data 軌用於發送模型事件,訂閱 Data 軌用於接收回覆。純文本輸入或輸出也需要 Data 軌。
本模型的媒體方向
下表列出本模型的媒體方向。模型範圍見適用範圍,其他接入方式參見Qwen-Omni-Realtime。
| 模型/應用 | 推音訊 | 拉音訊 | 推視訊 | 拉視訊 |
|---|---|---|---|---|
| Qwen-Omni-Realtime | 語音輸入時開啓 | 需要語音回覆時開啓 | 需要視覺輸入時開啓 | 不支援開啓 |
配置媒體參數和軌道
音訊上行和下行應分別配置:上行使用 setAudioEncoderConfig,下行使用 setAudioDecoderConfig。這些參數用於網絡傳輸,網關會將音訊轉換為模型所需的格式。傳輸編碼配置與模型事件中的音訊格式參數應分別按 SDK 和目標模型的要求設置。
按方向啓動 startAudioCapture、startAudioPlayer 或 startVideoCapture。自定義輸入輸出見下文高階能力。
publishTracks 表示用戶端發送的軌道,subscribeTracks 表示用戶端接收的軌道:
| 場景 | publishTracks | subscribeTracks |
|---|---|---|
| 語音對話 | Audio、Data | Audio、Data |
| 帶畫面輸入的語音對話 | Audio、Video、Data | Audio、Data |
在建連前關閉上行媒體發送,避免模型尚未就緒時收到輸入:
engine.enableSendMediaStream(.audio, enable: false)
engine.enableSendMediaStream(.video, enable: false)
採集、發佈軌道和允許發送是不同的操作。關閉發送不等於停止本地採集,也不影響 Data 軌事件收發。未添加的軌道不會因開啓發送而自動建立。
4. 建立連接
將憑證與軌道配置填入 AoqConnectConfig,呼叫:
engine.connect(connectConfig)
等待 onConnectionStatusChange 返回 .connected,再進入模型初始化流程。connect 呼叫返回不等於連接成功。
5. 按模型協議交互並收發媒體
發送和解析模型事件
用戶端透過 Data 軌發送事件。以下為 iOS Swift 代碼片段,其他介面詳見 iOS SDK 參考:
// eventJSON 由目标模型的客户端事件协议构造。
let msg = AoqDataMsg()
msg.data = eventJSON.data(using: .utf8)!
engine.send(msg)
在 onDataMsg 中解析回覆。本模型透過 type 欄位標識事件類型。完整欄位、參數及結束條件應遵循目標模型文檔。
就緒後開啓所需媒體
滿足當前模型、當前會話或任務的就緒條件後,僅開啓已配置的上行方向。例如,需要語音輸入時呼叫:
engine.enableSendMediaStream(.audio, enable: true)
需要視訊輸入時再開啓 .video。
音訊與視訊透過對應媒體軌道傳輸;模型事件和文本透過 Data 軌傳輸。例如,Omni 的 AOQ 接入無需使用 input_audio_buffer.append 或 input_image_buffer.append 重復發送媒體。下行音訊由已配置的播放器或外部播放邏輯處理。
6. 結束交互並釋放資源
不再使用連接時,由用戶端業務層呼叫AOQ SDK 的斷開連接和釋放資源介面:
engine.disconnect()
AoqClientEngine.destroy()
異常斷開後清理業務層就緒狀態,按連接狀態管理處理後續連接;重新建連後按模型協議重新初始化。
Data 通道發送和接收事件
用戶端透過 AOQ SDK 的 Data 軌發送和接收模型事件。連接時需要發佈和訂閱 Data 軌;發送時將模型事件序列化後放入 AoqDataMsg,並呼叫所用平台的 Data 發送介面;接收時在 onDataMsg 回調中解析消息。介面詳見各平台 SDK。
發送事件的名稱、欄位、參數和呼叫時機遵循目標模型的用戶端事件定義;收到消息後的解析方式、狀態變更、結果和錯誤處理遵循該模型的服務端事件定義。初始化事件根據模型要求按需發送,後續文本和控制事件按照業務需要發送。
| 模型/應用 | 用戶端事件定義(發送) | 服務端事件定義(接收) |
|---|---|---|
| Qwen-Omni-Realtime | 用戶端事件 | 服務端事件 |
模型事件的發送與接收還應遵循以下規則:
-
使用事件的
type欄位識別模型事件,關聯標識按本模型事件參考處理。 -
模型要求的初始化確認、輸入提交、響應取消和任務結束等操作,均在 Data 通道中按對應協議處理;它們屬於模型交互語義,與斷開傳輸連接是不同操作。
-
結束前按本模型事件說明完成輸入提交和結果接收;需要完整播放時,處理完本地待播音訊再釋放連接。
-
音訊與視訊資料透過媒體軌道傳輸。引用模型事件文檔時,媒體封裝和可用交互模式仍遵循本文的接入方式,不直接套用 WebSocket 的媒體發送方式。
高階能力
| 能力 | 使用場景 | 文檔 |
|---|---|---|
| 獨立控制音訊與視訊發送 | 等待模型就緒、暫停上行、按需開啓視訊 | 媒體流發送管理 |
| 音訊設備與處理 | 編解碼、揚聲器、文件混音、音訊幀回調 | 音訊常用功能 |
| 外部音訊輸入 | 使用業務側音訊源 | 自定義音訊採集 |
| 外部音訊輸出 | 由業務側處理或播放輸出音訊 | 自定義音訊播放 |
| 視訊採集與輸入 | 攝像頭及業務側畫面輸入 | 視訊常用功能、自定義視訊輸入 |
媒體發送控制只控制媒體傳輸。模型響應取消、輪次提交等行為仍需使用目標模型的事件協議。
會話配置示例
說明以下示例適用於 qwen3.8-omni-flash-realtime。音訊與視訊透過媒體軌道傳輸,不使用 WebSocket 的媒體發送事件。
{
"type": "session.update",
"session": {
"modalities": [
"text",
"audio"
],
"voice": "Tina",
"turn_detection": {
"type": "server_vad"
}
}
}
AOQ SDK 下載
以下版本更新說明描述 AOQ SDK 的通用能力,本模型的媒體支援範圍見上方本模型的媒體方向。
| 版本 | 平台 | 下載 | 更新日期 | 更新說明 |
|---|---|---|---|---|
v1.4.0 | Android | 2026-10-27 |
| |
iOS | ||||
HarmonyOS | ||||
Windows | ||||
macOS | ||||
Electron | aoq-electron-sdk-1.4.0-59463182.tgz 也可以透過 npm 安裝:
| |||
Linux |
| |||
| v1.3.0 | Android | 2026-09-18 |
| |
| iOS | ||||
| HarmonyOS | ||||
| Windows | AoqClientSdk-windows-x64.zip | |||
| macOS | ||||
| Electron | 也可以透過 npm 安裝: npm install aoq-electron-sdk@1.3.0-58586345 | |||
| Linux | x86_64: AoqClientSdk.zip arm64: AoqClientSdk.zip | |||
| v1.2.2 | iOS | AoqClientSdk.framework.zip | 2026-09-09 |
|
| v1.2.0 | Android | 2026-08-17 |
| |
| iOS | ||||
| HarmonyOS | ||||
| Windows | ||||
| macOS | ||||
| Electron | 也可以透過npm安裝: npm install aoq-electron-sdk@1.2.0-57407598 | |||
| Linux | x86_64:AoqClientSdk.zip arm64:AoqClientSdk.zip | |||
| v1.1.0 | Android | 2026-07-31 |
| |
| iOS | ||||
| HarmonyOS | ||||
| Linux | AoqClientSdk.zip | |||
| v1.0.1 | Android | 2026-07-09 |
| |
| iOS | ||||
| HarmonyOS |
重要AOQ使用音訊插件的方式加載Opus編解碼器,如果需要Opus編解碼時需要下載Opus插件並加載到工程內。