全部產品
Search
文件中心

Alibaba Cloud Model Studio:Qwen-Omni-Realtime AOQ 接入

更新時間:Nov 16, 2026

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。

POSThttps://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen3.8-omni-flash-realtime

export 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,接入域名中的 WorkspaceId 固定為 token-plan。

Content-Type

application/json

指定消息類型

Authorization

Bearer <YOUR_API_KEY>

填寫API Key

x-dashscope-rtc-transport

moq

指定使用 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 接入點地址。

port

Relay 接入點端口。

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);

整體流程

AOQ 接入時序圖
  1. 用戶端透過業務 AppServer 獲取連接憑證。
  2. 建立 SDK 引擎並註冊回調。
  3. 配置媒體和 Data 軌道,關閉上行媒體發送。
  4. 建立 AOQ 連接,等待連接成功。
  5. 按模型協議完成配置,收到確認後開啓所需媒體發送。
  6. 完成交互後斷開連接並釋放資源。

說明

  • 音訊與視訊媒體資料由 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 配置
aoqTokenForClienttoken
sidsid
clientRelayCertFingerprintcertFingerprint
clientRelayEndpointsrelayEndpoints,按結構轉換各接入點
extraInfo 中的 workspaceIdHashworkspaceIdHash

新建連接時獲取新的連接憑證。同一連接內能否復用會話或啓動下一輪任務,由目標模型協議決定。

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 表示用戶端接收的軌道:

場景publishTrackssubscribeTracks
語音對話Audio、DataAudio、Data
帶畫面輸入的語音對話Audio、Video、DataAudio、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

AoqClientSdk-release.aar

libPluginOpus.zip

2026-10-27

  1. 支援從外部輸入 H.264 視訊。
  2. 優化性能。
  3. 修復已知的穩定性問題。

iOS

AoqClientSdk.framework.zip

AoqScreenShare.framework.zip

PluginOpus.framework.zip

HarmonyOS

AoqClientSdk.har

libPluginOpus.zip

Windows

AoqClientSdk-windows-x64.zip

macOS

AoqClientSdk.framework.zip

PluginOpus.framework.zip

Electron

aoq-electron-sdk-1.4.0-59463182.tgz

也可以透過 npm 安裝:

npm install aoq-electron-sdk@1.4.0-59463182

Linux

x86_64: AoqClientSdk.zip

arm64: AoqClientSdk.zip

v1.3.0Android2026-09-18
  1. 新增屏幕共享能力。

  2. 廢棄 bitcode。

  3. 支援遠程加載 .so 庫。

  4. 支援從外部設置編碼幀最大值。

  5. 將預設編解碼器調整為 Opus。

  6. 優化性能。

  7. 修復已知的穩定性問題。

iOS
HarmonyOS
WindowsAoqClientSdk-windows-x64.zip
macOS
Electron
也可以透過 npm 安裝:npm install aoq-electron-sdk@1.3.0-58586345
Linux
v1.2.2iOSAoqClientSdk.framework.zip2026-09-09
  1. 修復 iOS 通話被系統或第三方語音通話打斷後,在中斷結束時無法恢復通話的問題。

  2. 優化 iOS 通話起始階段的回聲抑制效果。

v1.2.0Android 2026-08-17
  1. 新增macOS平台支援

  2. 新增Windows平台支援

  3. 新增Electron平台支援

  4. Linux平台同時支援Python和C++介面

  5. 新增音量檢測功能

  6. 優化性能

  7. 修复已知的稳定性问题

iOS
HarmonyOS
Windows
macOS
Electron
也可以透過npm安裝:npm install aoq-electron-sdk@1.2.0-57407598
Linux
v1.1.0Android 2026-07-31
  1. 支援ASR模型

  2. 支援TTS模型

  3. 支援多模態交互套件

  4. 新增支援Linux平台

  5. 優化性能

  6. 解決已知的穩定性問題

iOS
HarmonyOS
LinuxAoqClientSdk.zip
v1.0.1Android 2026-07-09
  1. 支援AOQ協議接入模型/應用

  2. 支援音訊與視訊編解碼參數

  3. 支援音訊與視訊設備採集及播放

  4. 支援自定義外部輸入音訊採集

  5. 支援自定義外部輸入視訊採集

  6. 支援自定義外部輸入視訊編碼

  7. 支援控制媒體流的發送

iOS
HarmonyOS

重要AOQ使用音訊插件的方式加載Opus編解碼器,如果需要Opus編解碼時需要下載Opus插件並加載到工程內。

事件參考

場景教程