Skip to main content

Qwen-Omni-Realtime WebSocket 接入

Qwen-Omni-Realtime WebSocket 接入

適用範圍

本文面向 Qwen-Omni-Realtime。示例模型為 qwen3.8-omni-flash-realtime,qwen3.5-omni-plus-realtime、qwen3.5-omni-flash-realtime 的配置參見事件參考。歷史型號 qwen3-omni-flash-realtime-2025-09-15 的參數參見 Python SDK。
  • 使用所選地域和業務空間對應的 API Key 與 Workspace ID。
  • 新加坡域名:{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com。
  • 長期 API Key 保存在服務端,不放入瀏覽器或移動端應用。

地址與鑒權

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

qwen3.8-omni-flash-realtime 必須使用業務空間專屬域名。舊型號可繼續使用原域名:北京為 wss://dashscope.aliyuncs.com,新加坡為 wss://dashscope-intl.aliyuncs.com。詳情參見 Python SDK。 在 WebSocket 握手請求頭中設置 Authorization: Bearer <API_KEY>。替換業務空間 ID 和實際模型名稱;不要把長期 API Key 放入瀏覽器或移動端。 可選的 user-agent 請求頭用於標識用戶端。通用 WebSocket 接入資料還列有 X-DashScope-WorkSpace(業務空間 ID)和 X-DashScope-DataInspection(資料合規檢查配置),這兩個請求頭按模型要求使用。 臨時 API Key 的生成方式和權限說明參見生成臨時 API Key。 以下業務空間位址以 qwen3.5-omni-plus-realtime 為例。
  • 華北2(北京) wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime
  • 新加坡 wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.5-omni-plus-realtime
將 {WorkspaceId} 替換為所選地域的業務空間 ID。

會話配置

建立連接並收到 session.created 後發送 session.update。收到 session.updated 確認後再發送輸入;錯誤透過 error 事件處理。 以下示例對應 qwen3.8-omni-flash-realtime,其他版本使用各自事件參考中的配置,不混用欄位層級。
{
  "type": "session.update",
  "session": {
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "Tina",
    "turn_detection": {
      "type": "server_vad"
    }
  }
}

輸入、結果與結束

音訊透過 input_audio_buffer.append 發送;輸入格式、提交條件和圖像輸入限制見用戶端事件。處理服務端事件中的結果、狀態和錯誤,不將連接建立視為業務請求已完成。 自動輪次與 Manual 模式、Function Calling 和 MCP 的時序見交互流程。接收完所需結果後關閉 WebSocket 連接。

交互流程

VAD 模式

將用戶端事件事件的session.turn_detection.type 設為"server_vad"以啓用 VAD 模式。在 VAD 模式下,服務端對傳入的音訊進行語音活動檢測,並在檢測到作出響應。此模式適用於用戶端到服務器始終發送音訊的情況,也是當前的預設模式。
server_vad
  • 服務端在檢測到語音開始時發送input_audio_buffer.speech_started 事件。
  • 用戶端隨時可以選擇透過發送 input_audio_buffer.append 事件將音訊追加到緩衝區。
  • 服務端在檢測到語音結束時發送input_audio_buffer.speech_stopped事件。
  • 服務端透過發送 input_audio_buffer.committed 事件來提交輸入音訊緩衝區。
  • 服務端發送 conversation.item.created 事件,其中包含從音訊緩衝區建立的用戶消息項。

Function Calling 流程

在 VAD 模式下,當服務端生成的響應需要用戶端執行 Function Calling 工具時,遵循以下交互流程:
image.svg
  • 服務端在檢測到語音結束並生成響應時,識別到需要呼叫工具。
  • 服務端發送 response.function_call_arguments.delta 事件,包含工具呼叫參數的增量資料。
  • 服務端發送 response.function_call_arguments.done 事件,表示工具呼叫參數傳遞完成。
  • 用戶端執行工具呼叫並獲取結果。
  • 用戶端透過 conversation.item.create 事件發送工具呼叫結果。
  • 用戶端發送 response.create 事件,觸發服務端基於工具呼叫結果生成響應。

Manual 模式

將用戶端事件事件的session.turn_detection 設為 null 以啓用 Manual 模式。此模式下,用戶端透過顯式發送input_audio_buffer.commit 和response.create事件請求服務器響應。適用於按下即說場景,如聊天軟件中的發送語音。
manual
  • 用戶端可以透過發送 input_audio_buffer.append 事件將音訊追加到緩衝區。
  • 用戶端透過發送 input_audio_buffer.commit事件來提交輸入音訊緩衝區。 該提交會在對話中建立一個新的用戶消息項。
  • 服務器透過發送 input_audio_buffer.committed事件進行響應。
  • 用戶端發送 response.create 事件,觸發模型生成最終響應。
  • 服務器透過發送 conversation.item.created事件進行響應。

Function Calling 流程

image.svg
在 Manual 模式下,當服務端生成的響應需要用戶端執行 Function Calling 工具時,遵循以下交互流程:
  • 用戶端發送 response.create 事件後,服務端生成響應並識別到需要呼叫工具。
  • 服務端發送 response.function_call_arguments.delta 事件,包含工具呼叫參數的增量資料。
  • 服務端發送 response.function_call_arguments.done 事件,表示工具呼叫參數傳遞完成。
  • 用戶端執行工具呼叫並獲取結果。
  • 用戶端透過 conversation.item.create 事件發送工具呼叫結果。
  • 用戶端發送 response.create 事件,觸發模型生成最終響應。
  • 服務端基於工具呼叫結果生成響應,並透過 response.audio.delta 或 response.text.delta 事件返回給用戶端。

MCP 工具呼叫

以下流程適用於 Qwen3.8-Omni-Flash-Realtime,可與上述 VAD 或 Manual 模式配合使用。 Function Calling 與 MCP 可以在同一會話的 session.tools 中配置,不能同時啓用聯網搜索(enable_search)。百鍊不額外收取 MCP 工具呼叫費,模型推理仍按模型價格計費。 MCP 由服務端執行工具,前述 Function Calling 流程則由用戶端執行工具,兩者的結果回傳方式不同。

工具發現

用戶端透過 session.update 配置 MCP 服務後,由 Realtime 服務異步發現工具,交互流程如下:
MCP 工具發現時序圖
本節時序圖中,opt 表示滿足條件時執行,alt 表示按條件選擇不同分支,par 表示並行處理。
  • session.updated 僅表示 MCP 配置已接受,不表示工具已經可用。
  • mcp_list_tools.in_progress 可能早於 session.updated 到達。
  • 用戶端可以在工具發現完成前繼續發送音訊或 response.create;但只有發現完成後的 Response 才能使用對應 MCP 工具。
  • 工具發現成功時,服務端先發送包含最終工具列表的 conversation.item.created,再發送 mcp_list_tools.completed。
  • 工具發現失敗時,服務端先發送包含 error 的 conversation.item.created,再發送 mcp_list_tools.failed。

MCP 呼叫與續答

模型選擇 MCP 工具後,由 Realtime 服務執行工具呼叫;需要審批時,用戶端先回覆審批結果。交互流程如下:
MCP 工具呼叫、審批與續答時序圖
審批拒絕或超時會直接觸發 response.mcp_call.failed,不執行工具,也不會經過 response.mcp_call.in_progress。無需審批或審批透過時,典型事件順序如下:
response.output_item.added(mcp_call)
→ response.mcp_call_arguments.delta
→ response.mcp_call_arguments.done
→ 可选:conversation.item.created(mcp_approval_request)
→ 可选:conversation.item.create(mcp_approval_response)
→ response.mcp_call.in_progress
→ response.mcp_call.completed 或 response.mcp_call.failed
→ response.output_item.done(最终 mcp_call)
→ response.done(父 Response)
服務端會在同一父 Response 的全部 MCP item 進入終態後發送 response.done。其中 response.output 已包含最終 mcp_call 快照:成功項為 completed 並包含 output;失敗項為 failed 並包含 error。 如果需要模型基於 MCP 結果繼續生成回答,用戶端應在收到父 response.done 後發送一次不附帶 MCP 結果的 response.create。 參見用戶端 MCP 工具配置、審批回覆、MCP 服務端事件和MCP 對話項。

使用限制

以下為每個會話的 MCP 預設約束:
項目預設值
MCP 服務數8
MCP 工具數128
工具發現超時30 秒
審批超時60 秒
工具執行超時30 秒
單次上游響應大小2 MB
累計工具結果大小8 MB
累計工具呼叫數256

錯誤處理

握手失敗時,核對域名、地域、業務空間、API Key、模型名稱及模型開通狀態與權限。連接建立後,根據 error 事件定位問題,並參見錯誤碼。保留事件 ID 便於排查,不以無響應判定協議不支援。

SDK 與參考