Skip to main content

AOQ 接入

本文介紹通過 AOQ Client SDK 接入 Realtime API 的通用流程：獲取連接憑證、初始化 SDK、配置媒體方向、建立連接、按目標模型協議交互，以及釋放資源。

AOQ 將音視頻媒體與模型事件分軌傳輸。SDK 負責媒體採集、編解碼、傳輸和播放；應用通過 Data 軌發送模型事件並處理回復。接入不同模型時，需要分別選擇媒體方向和模型事件協議。

前提條件

  • 已完成接入概覽中的準備工作，並確認目標模型、地域和 AOQ 支持範圍。
  • 已從 SDK 下載導入對應平台 SDK；使用 Opus 時，導入對應插件。
  • 業務 AppServer 已實現 Token 鑒權。API Key 保存在 AppServer，客戶端使用臨時連接憑證。
僅在需要採集時申請麥克風或攝像頭權限。例如，語音合成不需要這兩項權限。

整體流程

AOQ 接入時序圖
  1. 客戶端通過業務 AppServer 獲取連接憑證。
  2. 創建 SDK 引擎並註冊回調。
  3. 配置媒體和 Data 軌道，關閉上行媒體發送。
  4. 建立 AOQ 連接，等待連接成功。
  5. 按模型協議完成配置，收到確認後開啓所需媒體發送。
  6. 完成交互後斷開連接並釋放資源。
  • 音視頻媒體數據由 AOQ SDK 接管，負責採集、處理、發送、接收和播放；Data 數據需要調用方遵循目標模型的事件定義進行發送和接收。
  • 連接成功表示與模型的傳輸通道已建立。如果業務需要配置音色等前置操作，應先完成模型配置，再啟動媒體發送。例如，Realtime 模型需要等待 session.updated，Inference 模型需要等待 task-started。因此，客戶端應在模型初始化成功後，才能開啟所需的上行媒體。

1. 獲取連接憑證

客戶端向業務 AppServer 請求憑證。AppServer 根據目標模型選擇 Realtime 或 Inference 建連地址，並攜帶 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 接口及錯誤說明請參見 AOQ 客戶端 SDK。

3. 配置 SDK

選擇四個媒體方向

以下“推”和“拉”均以客戶端為視角。按業務實際使用的輸入、輸出模態配置，不需要的方向不添加媒體軌道。
方向配置內容典型用途
推音頻發佈 Audio 軌，設置音頻編碼器，配置內置或外部採集語音識別、語音對話、語音翻譯
拉音頻訂閱 Audio 軌，設置音頻解碼器，配置播放器或外部播放語音合成、語音回復
推視頻發佈 Video 軌，配置攝像頭或外部視頻輸入及編碼參數向支持視覺輸入的模型發送畫面
拉視頻僅當目標模型/應用明確支持視頻輸出時配置訂閱及接收處理以目標模型/應用文檔為準
Data 軌獨立於這四個方向：發佈 Data 軌用於發送模型事件，訂閱 Data 軌用於接收回復。純文本輸入或輸出也需要 Data 軌。

各模型如何選擇

下表是典型場景的媒體配置建議。具體模型及版本的支持範圍以 Realtime API 概述和模型文檔為準。
模型/應用推音頻拉音頻推視頻拉視頻
Qwen-Omni-Realtime語音輸入時開啓需要語音回復時開啓需要視覺輸入時開啓不支持開啓
Qwen-Audio-Realtime語音對話時開啓需要語音回復時開啓不支持開啓不支持開啓
Qwen-Audio-TTS、CosyVoice不支持開啓開啓不支持開啓不支持開啓
Qwen-Audio-ASR-Streaming、Qwen-Audio-ASR-Message開啓不支持開啓不支持開啓不支持開啓
Fun-ASR-Realtime開啓不支持開啓不支持開啓不支持開啓
Qwen-LiveTranslate-Realtime語音輸入時開啓需要語音譯文時開啓按所選版本及場景配置不支持開啓
multimodal-dialog按應用輸入配置按應用輸出配置按應用能力配置僅在應用明確支持時配置

配置媒體參數和軌道

音頻上行和下行應分別配置：上行使用 setAudioEncoderConfig，下行使用 setAudioDecoderConfig。這些參數用於網絡傳輸，網關會將音頻轉換為模型所需的格式。傳輸編碼配置與模型事件中的音頻格式參數應分別按 SDK 和目標模型的要求設置。 按方向啓動 startAudioCapture、startAudioPlayer 或 startVideoCapture。自定義輸入輸出見下文高階能力。 publishTracks 表示客戶端發送的軌道，subscribeTracks 表示客戶端接收的軌道：
場景publishTrackssubscribeTracks
語音對話Audio、DataAudio、Data
帶畫面輸入的語音對話Audio、Video、DataAudio、Data
語音識別Audio、DataData
語音合成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 示例： 
// eventJSON 由目标模型的客户端事件协议构造。
let msg = AoqDataMsg()
msg.data = eventJSON.data(using: .utf8)!
engine.send(msg)
在 onDataMsg 中解析回復。不要統一假定事件類型位於 type：Realtime 事件通常使用 type，Inference 服務端事件使用 header.event。完整字段、參數及結束條件應遵循目標模型文檔。

就緒後開啓所需媒體

滿足當前模型、當前會話或任務的就緒條件後，僅開啓已配置的上行方向。例如，需要語音輸入時調用： 
engine.enableSendMediaStream(.audio, enable: true)
需要視頻輸入時再開啓 .video。TTS 場景輸入文本，無需開啓上行音視頻。 音視頻通過對應媒體軌道傳輸；模型事件和文本通過 Data 軌傳輸。例如，Omni 的 AOQ 接入無需使用 input_audio_buffer.append 或 input_image_buffer.append 重復發送媒體。下行音頻由已配置的播放器或外部播放邏輯處理。

6. 結束交互並釋放資源

不再使用連接時，由客戶端業務層調用AOQ SDK 的斷開連接和釋放資源接口： 
engine.disconnect()
AoqClientEngine.destroy()
異常斷開後清理業務層就緒狀態，按連接狀態管理處理後續連接；重新建連後按模型協議重新初始化。

Data 通道發送和接收事件

客戶端通過AOQ SDK 的 Data 軌發送和接收模型事件。連接時需要發佈和訂閱 Data 軌；發送時將模型事件序列化後放入 AoqDataMsg，調用 engine.send(msg)；接收時在 onDataMsg 回調中解析消息。 發送事件的名稱、字段、參數和調用時機遵循目標模型的客戶端事件定義；收到消息後的解析方式、狀態變更、結果和錯誤處理遵循該模型的服務端事件定義。初始化事件根據模型要求按需發送，後續文本和控制事件按照業務需要發送。
模型/應用客戶端事件定義（發送）服務端事件定義（接收）
Qwen-Omni-Realtime客戶端事件服務端事件
Qwen-Audio-Realtime客戶端事件服務端事件
Qwen-Audio-TTS、CosyVoice客戶端事件服務端事件
Qwen-Audio-ASR-Streaming客戶端事件服務端事件
Qwen-Audio-ASR-Message客戶端事件服務端事件
Fun-ASR-Realtime客戶端事件服務端事件
Qwen-LiveTranslate-Realtime客戶端事件服務端事件
multimodal-dialog交互協議中的 Input Message交互協議中的 Output Message
多模態交互套件的雙向事件定義在同一篇交互協議中。請按實際接入的模型版本選擇事件定義，不同模型之間不共用一套固定事件。 模型事件的發送與接收還應遵循以下規則：
  • 按模型定義識別事件類型和關聯標識。例如，Realtime 事件通常使用 type；Inference 客戶端使用 header.action、服務端使用 header.event，通過 task_id 關聯任務。
  • 模型要求的初始化確認、輸入提交、響應取消和任務結束等操作，均在 Data 通道中按對應協議處理；它們屬於模型交互語義，與斷開傳輸連接是不同操作。
  • 例如，Inference 模型使用 finish-task 結束任務，並通過 task-finished 確認任務結束；如需完整結果，應在收到剩餘結果後再釋放連接，需要完整播放時還應處理完本地待播音頻。
  • 音視頻數據通過媒體軌道傳輸。引用模型事件文檔時，媒體封裝和可用交互模式仍遵循本文的接入方式，不直接套用 WebSocket 的媒體發送方式。

高階能力

能力使用場景文檔
獨立控制音視頻發送等待模型就緒、暫停上行、按需開啓視頻媒體流發送管理
音頻設備與處理編解碼、揚聲器、文件混音、音頻幀回調音頻常用功能
外部音頻輸入使用業務側音頻源自定義音頻採集
外部音頻輸出由業務側處理或播放輸出音頻自定義音頻播放
視頻採集與輸入攝像頭及業務側畫面輸入視頻常用功能、自定義視頻輸入
媒體發送控制只控制媒體傳輸。模型響應取消、輪次提交等行為仍需使用目標模型的事件協議。

最佳實踐