本文介紹 DashScope Python SDK 調用 Qwen-Omni 即時模型 時的關鍵介面與請求參數。
連接與鑒權參見 WebSocket 接入;事件欄位與 JSON 示例參見用戶端事件和服務端事件。
您的 SDK 版本需要不低於1.23.9。請先閱讀即時多模態互動流程。
請訪問GitHub下載範例程式碼。我們提供了三種調用方式的範例程式碼:
下述請求參數可以通過OmniRealtimeConversation的構造方法(init)進行設定。
下述請求參數可以通過update_session介面配置。
OmniRealtimeConversation通過
服務端會通過回調的方式,將服務端響應事件和資料返回給用戶端。您需要實現回調方法,處理服務端返回的資訊或者資料。
通過
前提條件
您的 SDK 版本需要不低於1.23.9。請先閱讀即時多模態互動流程。
快速開始
請訪問GitHub下載範例程式碼。我們提供了三種調用方式的範例程式碼:
-
音頻對話樣本:麥克風採集即時音頻輸入,開啟VAD 模式(自動檢測語音起止),支援語音打斷。
enable_turn_detection參數需設為 True。推薦您使用耳機播放音頻,避免回聲觸發語音打斷。
-
音視訊交談樣本:麥克風和網路攝影機採集即時音視頻輸入,開啟VAD 模式(自動檢測語音起止),支援語音打斷。
enable_turn_detection參數需設為 True。推薦您使用耳機播放音頻,避免回聲觸發語音打斷。
-
本地調用:本地音頻和圖片作為輸入,開啟Manual 模式(手動控制發送節奏)。
enable_turn_detection參數需設為 False。
請求參數
下述請求參數可以通過OmniRealtimeConversation的構造方法(init)進行設定。
參數 | 類型 | 說明 |
|---|---|---|
model | str | Qwen-Omni系列模型名稱。參見模型列表。 |
url | str | 調用地址:
|
| 參數 | 類型 | 說明 |
|---|---|---|
| output_modalities | list[MultiModality] | 模型輸出模態設定,支援設定[MultiModality.TEXT](僅輸出文本)或[MultiModality.TEXT, MultiModality.AUDIO](輸出音頻和文本)。 |
| voice | str | 模型產生音訊音色,支援的音色參見音色列表。預設音色:
|
| input_audio_format | AudioFormat | 使用者輸入音訊格式,當前僅支援設定為PCM_16000HZ_MONO_16BIT。 |
| output_audio_format | AudioFormat | 模型輸出音訊格式,當前僅支援設定為PCM_24000HZ_MONO_16BIT。 |
| smooth_output | bool | 僅 qwen3-omni-flash-realtime-2025-09-15 支援設定。
|
| instructions | str | 系統訊息,用於設定模型的目標或角色。例如:你是某五星級酒店的AI客服專員,請準確且友好地解答客戶關於房型、設施、價格、預訂政策的諮詢。請始終以專業和樂於助人的態度回應,杜絕提供未經證實或超出酒店服務涵蓋範圍的資訊。 |
| enable_input_audio_transcription | bool | 是否開啟輸入音訊語音辨識。 |
| input_audio_transcription_model | str | 用於輸入音頻轉錄的語音辨識模型,固定為 qwen3-asr-flash-realtime,不支援修改。 |
| turn_detection_type | str | 服務端VAD類型,目前固定為"server_vad"。 |
| turn_detection_threshold | float | VAD檢測閾值。建議在嘈雜的環境中增加, 在安靜的環境中降低。
|
| turn_detection_silence_duration_ms | int | 檢測語音停止的靜音期間,超過此值後會觸發模型響應。預設值為800,參數範圍[200, 6000]。 |
介面參考
OmniRealtimeConversation類
OmniRealtimeConversation通過from dashscope.audio.qwen_omni import OmniRealtimeConversation方法引入。
| 方法簽名 | 服務端響應事件(通過回調下發) | 說明 |
|---|---|---|
session.created會話已建立session.updated 會話配置已更新 | 和服務端建立串連。 | |
session.updated會話配置已更新 | 更新本次會話互動的預設配置。參數配置請參考《請求參數》章節。在您建立連結,服務端會及時返回用於此會話的預設輸出輸入配置。如果您需要更新預設會話配置,我們也推薦您總是在建立連結後即刻調用此介面。服務端在收到session.update事件後,會進行參數校正,如果參數不合法則返回錯誤,否則更新服務端側的會話配置。 | |
| 無 | 將base64編碼後的音頻資料片段追加到雲端輸入音頻緩衝區。 音頻緩衝區是你可以寫入並稍後提交的臨時儲存。
| |
| 無 | 將base64編碼後的圖片資料添加到雲端視頻緩衝區。圖片資料可以是本地的圖片,或從視頻流即時採集的圖片資料。目前對圖片輸入有以下限制:
| |
input_audio_buffer.cleared清空服務端收到的音頻 | 刪除當前雲端緩衝區的音頻。 | |
input_audio_buffer.committed服務端收到提交的音頻 | 提交之前通過append添加到雲端緩衝區的音視頻,如果輸入的音頻緩衝區為空白將產生錯誤。
| |
response.created服務端開始產生響應response.output_item.added 響應時有新的輸出內容conversation.item.created 對話項被建立response.content_part.added 新的輸出內容添加到assistant message 項response.audio_transcript.delta 增量產生的轉錄文字response.audio.delta 模型增量產生的音頻response.audio_transcript.done 完成文本轉錄response.audio.done 完成音頻產生response.content_part.done Assistant message 的文本或音頻內容流式輸出完成response.output_item.done Assistant message 的整個輸出項串流完成response.done 響應完成 | 指示服務端建立模型響應。開啟"turn_detection"模式下配置會話時,服務端會自動建立模型響應。 | |
| 無 | 取消進行中的響應。如果沒有任何響應可供取消,服務端將以一個錯誤進行響應。 | |
| 無 | 終止任務,並關閉串連。 | |
| 無 | 擷取當前任務的session_id。 | |
| 無 | 擷取最近一次response的response_id。 | |
| 無 | 擷取最近一次response的首包文本延遲。 | |
| 無 | 擷取最近一次response的首包音頻延遲。 |
回調介面(OmniRealtimeCallback)
服務端會通過回調的方式,將服務端響應事件和資料返回給用戶端。您需要實現回調方法,處理服務端返回的資訊或者資料。
通過from dashscope.audio.qwen_omni import OmniRealtimeCallback引入。
| 方法 | 參數 | 傳回值 | 描述 |
|---|---|---|---|
| 無 | 無 | 當和服務端建立串連完成後,該方法立刻被回調。 | |
| message:服務端響應事件。 | 無 | 包括對介面調用的回複響應和模型產生的文本和音頻。具體可以參考:服務端事件 | |
| close_status_code:關閉websocket的狀態代碼。close_msg:關閉websocket的關閉資訊。 | 無 | 當服務已經關閉串連後進行回調。 |