Qwen-Audio-Realtime WebSocket 接入
用戶指南:即時語音對話(Qwen-Audio-Realtime)。用戶端事件和服務端事件的詳細說明,請參見用戶端事件和服務端事件。
適用模型:qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash。
重要阿里雲百鍊為華北2(北京)、新加坡地域推出了業務空間專屬域名,能夠為推理請求提供卓越的性能和更高的穩定性,建議遷移至新域名:
- 華北2(北京)地域:從
dashscope.aliyuncs.com遷移至{WorkspaceId}.cn-beijing.maas.aliyuncs.com - 新加坡地域:從
dashscope-intl.aliyuncs.com遷移至{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId}需要替換為真實的Workspace ID。現有域名仍可正常使用。
介面地址
WebSocket URL 固定如下,透過查詢參數 model 指定要呼叫的模型名稱(將 <model_name> 替換為實際的模型):
華北2(北京)
wss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>呼叫時請將{WorkspaceId}替換為真實的Workspace ID。
新加坡
wss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>呼叫時請將{WorkspaceId}替換為真實的Workspace ID。
重要URL 必須使用 wss:// 協議。Authorization 在請求頭中設置,模型透過 URL 查詢參數 model 指定。
請求頭
請求頭中需添加如下資訊:
參數 | 類型 | 是否必選 | 說明 |
|---|---|---|---|
Authorization | string | 是 | 鑒權令牌,格式為 |
user-agent | string | 否 | 用戶端標識,便於服務端追蹤來源。 |
X-DashScope-WorkSpace | string | 否 | 阿里雲百鍊業務空間 ID。 |
重要Authorization 鑒權在 WebSocket 握手階段驗證。如果 API Key 無效或缺失,握手將失敗並返回 HTTP 401/403 錯誤。長期 API Key 應保存在服務端,不放入瀏覽器或移動端應用。臨時 API Key 的生成方式和權限說明參見生成臨時 API Key。
通用 WebSocket 接入資料還列有資料合規檢查配置請求頭 X-DashScope-DataInspection,按模型要求使用。qwen-audio-3.1-realtime-plus 的示例使用了 x-dashscope-dataInspection: disable。
核心概念
- Session(會話):一次 WebSocket 連接對應一個會話,會話內維護配置和對話上下文。
- Conversation Item(對話項):對話中的每條消息,按鏈表順序組織。
- Response(響應):一次模型推理產生的輸出,包含一個或多個輸出項,輸出項可以是助手消息,也可以是函數呼叫。
- Function Call(函數呼叫):模型請求用戶端執行工具函數時產生的輸出項。用戶端執行完成後透過
function_call_output寫回結果,再用response.create觸發下一輪推理。 - Turn Detection(輪次檢測):控制何時觸發推理。
交互模式
Qwen-Audio Realtime API 支援三種交互模式,透過 session.update 事件中的 session.turn_detection 配置。自動檢測模式設置對象內的 type,push-to-talk 模式將整個 turn_detection 欄位設為 null:
模式 | session.turn_detection 的值 | 描述 | 適用場景 |
|---|---|---|---|
server_vad | 對象, | 服務端 VAD 檢測語音起止,自動觸發推理。 | 免提對話、語音助手 |
智能語義輪次 | 對象, | 融合聲學感知與語義理解判斷輪次邊界,而非僅依賴人聲信號。無語義的聲音(如”嗯”、”啊”)不會觸發對話輪或打斷模型播報。 | 低延遲自然對話、高質量打斷 |
push-to-talk |
| 用戶端手動提交音訊、手動觸發推理。 | 按鍵說話、精確控制 |
交互流程
用戶端事件和服務端事件的詳細說明,請參見用戶端事件和服務端事件。
server_vad 模式
服務端對傳入的音訊進行語音活動檢測,檢測到語音結束後自動觸發推理。
啓用方式:配置 session.update 事件的 turn_detection.type 為 server_vad。
一輪完整對話
下圖展示了 server_vad 模式下的典型交互時序:
按時間順序,用戶端與服務端的交互流程如下:
- 用戶端建立 WebSocket 連接,服務端返回
session.created事件。 - 用戶端發送
session.update配置會話參數,服務端返回session.updated。 - 用戶端持續發送
input_audio_buffer.append追加音訊資料。 - 服務端檢測到語音開始,返回
input_audio_buffer.speech_started,同時流式返回 ASR 轉寫增量conversation.item.input_audio_transcription.delta。 - 服務端檢測到語音結束,返回
input_audio_buffer.speech_stopped、input_audio_buffer.committed和conversation.item.created。 - 服務端自動生成響應,流式返回文本和音訊增量(
response.audio_transcript.delta、response.audio.delta),最終返回response.done。
用戶打斷
模型播報期間,若 VAD 檢測到用戶開始說話,服務端會取消當前響應(返回 response.done,狀態為 cancelled),隨後開始新一輪語音輸入和響應。下圖展示了用戶打斷的交互時序:
smart_turn / smart_turn_v2 模式
融合聲學感知與語義理解檢測語音結束,可過濾回應語、背景音等無意義聲音。無語義的聲音透過 conversation.item.ambient_audio_transcription.delta 事件透傳,不觸發對話輪。
啓用方式:配置 session.update 事件的 turn_detection.type 為 smart_turn 或 smart_turn_v2。
smart_turn_v2(推薦使用):在 smart_turn 基礎上增強對話上下文理解,更好地判斷多人場景中的交互意圖。減少旁人說話或無關插話造成的誤回覆、誤打斷。
一輪完整對話
下圖展示了 smart_turn / smart_turn_v2 模式下的典型交互時序:
與 server_vad 模式的主要區別:
- 無語義聲音(“嗯”、“啊”等)不會觸發推理,而是透過
ambient_audio_transcription事件返回。 - 已判定有效的語音可能被撤回(
input_audio_buffer.speech_stopped返回reason=turn_invalid),此時不觸發推理。 - 在等待用戶下一輪輸入時,用戶端可顯式發送
response.create觸發推理。
用戶打斷
與 server_vad 模式的打斷處理基本一致。下圖展示了用戶打斷的交互時序:
無效輪次
已判定有效的語音可能被撤回(input_audio_buffer.speech_stopped 返回 reason=turn_invalid),此時不觸發推理,用戶端應繼續發送音訊等待下一輪有效語音。下圖展示了無效輪次的交互時序:
說話人增強配置流程
在 smart_turn / smart_turn_v2 模式下,首次 session.update 中傳入 voiceprint_audio_urls 時,服務端將異步執行聲紋註冊(加載目標說話人音訊特徵),並透過事件通知註冊進度。聲紋註冊失敗不阻塞正常對話流程。
按時間順序,聲紋註冊的交互流程如下:
-
用戶端建立 WebSocket 連接,服務端返回
session.created。 -
用戶端發送首次
session.update,在turn_detection.voiceprint_audio_urls中傳入聲紋音訊 URL。 -
服務端立即異步啓動聲紋註冊,在
session.updated返回之前先推送voiceprint_audio_list.in_progress事件,攜帶本次註冊任務的唯一標識item_id。 -
服務端返回
session.updated,確認會話配置已生效。 -
聲紋註冊完成後,服務端推送終態事件(
item_id與步驟 3 一致):- 註冊成功:
voiceprint_audio_list.completed。 - 註冊失敗:
voiceprint_audio_list.failed,附帶reason欄位說明失敗原因(如音訊 URL 無法下載)。
- 註冊成功:
說明voiceprint_audio_urls 僅在第一次 session.update 時生效,後續傳入該欄位將被忽略。
push-to-talk 模式
用戶端手動控制音訊提交和推理觸發,適用於按鍵說話場景。
啓用方式:配置 session.update 事件的 turn_detection 為 null。
一輪完整對話
下圖展示了 push-to-talk 模式下的典型交互時序:
按時間順序,用戶端與服務端的交互流程如下:
- 用戶端持續發送
input_audio_buffer.append追加音訊資料。 - 用戶說完話後,用戶端發送
input_audio_buffer.commit提交緩衝區。 - 用戶端發送
response.create手動觸發推理。 - 服務端生成響應,流式返回文本和音訊。
用戶打斷
用戶端發送 response.cancel 取消當前響應,服務端返回 response.done(狀態為 cancelled,原因為 client_cancelled)。下圖展示了用戶打斷的交互時序:
各模式操作約束
操作 | push-to-talk | server_vad | smart_turn / smart_turn_v2 |
|---|---|---|---|
session.update | IDLE 時全部可改;非 IDLE 時部分受限 | IDLE 時全部可改;非 IDLE 時部分受限 | IDLE 時全部可改;非 IDLE 时部分受限 |
input_audio_buffer.append | 允许 | 允许 | 允许 |
input_audio_buffer.commit | 允许 | 忽略 | 忽略 |
input_audio_buffer.clear | 允许 | 忽略 | 忽略 |
response.create | 允许(需先透過 | 當前無響應正在生成時允許;有響應正在生成時不允許重復觸發 | 等待用戶下一輪輸入時允許;當前處於一個 turn 內時(收到 |
response.cancel | 允许(推理中) | 允許(推理中) | 允許(推理中) |
conversation.item.create/delete/retrieve | 允许 | 允许 | 允许 |
說明turn_detection 和 input_audio_format 僅在首次發送音訊之前(IDLE 狀態)允許修改。
錯誤處理
握手失敗時,核對域名、地域、業務空間、API Key、模型名稱及模型開通狀態與權限。完整錯誤資訊請參見錯誤碼。
類型 | 行為 | 示例 |
|---|---|---|
用戶端錯誤( | 連接保持,僅通知 | 參數不合法、狀態不允許、item_id 重復 |
服務端錯誤( | 連接終止 | LLM 連接失敗、存儲故障 |