Skip to main content
即時多模態

Python SDK

本文介紹 DashScope Python SDK 調用 Qwen-Omni 即時模型 時的關鍵介面與請求參數。

前期準備

您的 SDK 版本需要不低於1.23.9。請先閱讀即時多模態互動流程。

快速開始

請訪問GitHub下載範例程式碼。我們提供了三種調用方式的範例程式碼：
  1. 音頻對話樣本：麥克風採集即時音頻輸入，開啟VAD 模式（自動檢測語音起止），支援語音打斷。
    enable_turn_detection參數需設為 True。
    推薦您使用耳機播放音頻，避免回聲觸發語音打斷。
  2. 音視訊交談樣本：麥克風和網路攝影機採集即時音視頻輸入，開啟VAD 模式（自動檢測語音起止），支援語音打斷。
    enable_turn_detection參數需設為 True。
    推薦您使用耳機播放音頻，避免回聲觸發語音打斷。
  3. 本地調用：本地音頻和圖片作為輸入，開啟Manual 模式（手動控制發送節奏）。
    enable_turn_detection參數需設為 False。

請求參數

下述請求參數可以通過OmniRealtimeConversation的構造方法（init）進行設定。

參數

類型

說明

model

str

Qwen-Omni系列模型名稱。參見模型列表。

url

str

調用地址：

  • 新加坡地區：wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime

  • 北京地區：wss://dashscope.aliyuncs.com/api-ws/v1/realtime

下述請求參數可以通過update_session介面配置。
參數類型說明
output_modalitieslist[MultiModality]模型輸出模態設定，支援設定[MultiModality.TEXT]（僅輸出文本）或[MultiModality.TEXT, MultiModality.AUDIO]（輸出音頻和文本）。
voicestr模型產生音訊音色，支援的音色參見音色列表。預設音色：
  • Qwen3-Omni-Flash-Realtime: "Cherry"
  • Qwen-Omni-Turbo-Realtime: "Chelsie"
input_audio_formatAudioFormat使用者輸入音訊格式，當前僅支援設定為PCM_16000HZ_MONO_16BIT。
output_audio_formatAudioFormat模型輸出音訊格式，當前僅支援設定為PCM_24000HZ_MONO_16BIT。
smooth_outputbool僅Qwen3-Omni-Flash-Realtime系列版本支援設定。
  • True：獲得口語化的回複
  • False：獲得更書面化、正式的回複
    但可能會因為存在難以朗讀的內容而導致效果不好。
  • None：模型自動選擇口語化或書面化的回複風格
instructionsstr系統訊息，用於設定模型的目標或角色。例如：你是某五星級酒店的AI客服專員，請準確且友好地解答客戶關於房型、設施、價格、預訂政策的諮詢。請始終以專業和樂於助人的態度回應，杜絕提供未經證實或超出酒店服務涵蓋範圍的資訊。
enable_input_audio_transcriptionbool是否開啟輸入音訊語音辨識。
input_audio_transcription_modelstr用於輸入音頻轉錄的語音辨識模型，當前僅支援設定為"gummy-realtime-v1"。
turn_detection_typestr服務端VAD類型，目前固定為"server_vad"。
turn_detection_thresholdfloatVAD檢測閾值。建議在嘈雜的環境中增加， 在安靜的環境中降低。
  • 取值越接近-1，噪音被判定為語音的機率越大。
  • 取值越接近1，噪音被判定為語音的機率越小。
預設為 0.2, 參數範圍：[-1.0, 1.0]。
turn_detection_silence_duration_msint檢測語音停止的靜音期間，超過此值後會觸發模型響應。預設值為800，參數範圍[200, 6000]。

關鍵介面

OmniRealtimeConversation類

OmniRealtimeConversation通過from dashscope.audio.qwen_omni import OmniRealtimeConversation方法引入。
方法簽名服務端響應事件（通過回調下發）說明
def connect(self,) -> None
session.created
會話已建立
session.updated
會話配置已更新
和服務端建立串連。
def update_session(self,
                       output_modalities: list[MultiModality],
                       voice: str,
                       input_audio_format: AudioFormat = AudioFormat.
                       PCM_16000HZ_MONO_16BIT,
                       output_audio_format: AudioFormat = AudioFormat.
                       PCM_24000HZ_MONO_16BIT,
                       enable_input_audio_transcription: bool = True,
                       input_audio_transcription_model: str = None,
                       enable_turn_detection: bool = True,
                       turn_detection_type: str = 'server_vad',
                       prefix_padding_ms: int = 300,
                       turn_detection_threshold: float = 0.2,
                       turn_detection_silence_duration_ms: int = 800,
                       turn_detection_param: dict = None,
                       smooth_output: bool = True
                       **kwargs) -> None
session.updated
會話配置已更新
更新本次會話互動的預設配置。參數配置請參考《請求參數》章節。在您建立連結，服務端會及時返回用於此會話的預設輸出輸入配置。如果您需要更新預設會話配置，我們也推薦您總是在建立連結後即刻調用此介面。服務端在收到session.update事件後，會進行參數校正，如果參數不合法則返回錯誤，否則更新服務端側的會話配置。
def append_audio(self, audio_b64: str) -> None
無將base64編碼後的音頻資料片段追加到雲端輸入音頻緩衝區。 音頻緩衝區是你可以寫入並稍後提交的臨時儲存。
  • 開啟"turn_detection"，音頻緩衝區用於檢測語音，服務端決定何時提交。
  • 關閉"turn_detection"，用戶端可以選擇每個事件中放置多少音頻量，最多放置 15 MiB。 例如，從用戶端串流較小的資料區塊可以讓 VAD 響應更迅速。
def append_video(self, video_b64: str) -> None
無將base64編碼後的圖片資料添加到雲端視頻緩衝區。圖片資料可以是本地的圖片，或從視頻流即時採集的圖片資料。目前對圖片輸入有以下限制：
  • 圖片格式需要為JPG或JPEG，建議傳入的圖片解析度為480P或720P， 最大1080P；
  • 單張圖片大小不大於500KB（Base64編碼前）；
  • 圖片資料需要經過Base64編碼；
  • 建議您以 1張/秒 的頻率向服務端發送圖片；
def clear_appended_audio(self, ) -> None
input_audio_buffer.cleared
清空服務端收到的音頻
刪除當前雲端緩衝區的音頻。
def commit(self, ) -> None
input_audio_buffer.committed
服務端收到提交的音頻
提交之前通過append添加到雲端緩衝區的音視頻，如果輸入的音頻緩衝區為空白將產生錯誤。
  • 開啟"turn_detection"，用戶端不需要發送此事件，服務端會自動認可音頻緩衝區。
  • 關閉"turn_detection"，用戶端必須提交音頻緩衝區才能建立使用者訊息項。
注意⚠️：
  1. 如果 input_audio_transcription為會話配置了音頻轉錄，系統會轉錄音頻。
  2. 提交輸入音頻緩衝區不會從模型建立響應。
def create_response(self,
        instructions: str = None,
        output_modalities: list[MultiModality] = None) -> None
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"模式下配置會話時，服務端會自動建立模型響應。
def cancel_response(self, ) -> None
無取消進行中的響應。如果沒有任何響應可供取消，服務端將以一個錯誤進行響應。
def close(self, ) -> None
無終止任務，並關閉串連。
def get_session_id(self) -> str
無擷取當前任務的session_id。
def get_last_response_id(self) -> str
無擷取最近一次response的response_id。
def get_last_first_text_delay(self)
無擷取最近一次response的首包文本延遲。
def get_last_first_audio_delay(self)
無擷取最近一次response的首包音頻延遲。

回調介面（OmniRealtimeCallback）

服務端會通過回調的方式，將服務端響應事件和資料返回給用戶端。您需要實現回調方法，處理服務端返回的資訊或者資料。 通過from dashscope.audio.qwen_omni import OmniRealtimeCallback引入。
方法參數傳回值描述
def on_open(self) -> None
無無當和服務端建立串連完成後，該方法立刻被回調。
def on_event(self, message: str) -> None
message：服務端響應事件。無包括對介面調用的回複響應和模型產生的文本和音頻。具體可以參考：服務端事件
def on_close(self, close_status_code, close_msg) -> None
close_status_code：關閉websocket的狀態代碼。close_msg：關閉websocket的關閉資訊。無當服務已經關閉串連後進行回調。

常見問題

Q：輸入的音頻和圖片要如何對齊？

Qwen-Omni即時模型的輸入將音頻作為時間軸，圖片會按照發送的時間，插入到音頻中。您可以在音頻時間軸的任意時刻添加圖片。 在即時互動情境下，您可以在任意時刻開啟或關閉視頻輸入。

Q：輸入圖片和音訊推薦頻率？

在即時互動情境，推薦按照1 fps或2 fps的幀率發送圖片，按照100ms一包的音頻發送音頻。

Q：turn_detection開關兩種模式的區別？

目前turn_detection開啟後只支援server_vad模式：
  • 開啟"turn_detection"：
    • 輸入狀態：雲端的VAD（語音事件監測）會根據輸入音頻判斷輸入的一句話結束，並且立刻自動調用Qwen-Omni的推理下發回複文本和語音。
    • 回複狀態：在此狀態下，音視頻可以繼續輸入，不需要在模型回複階段中斷。回複結束後會回到輸入狀態等待語音。
    • 打斷：如果在模型回複期間，如果檢測到使用者開始說話則會觸發打斷，服務會立刻停止這一次的回複並且轉換到輸入狀態。
  • 關閉"turn_detection"：
    • 使用者需要自己判斷一輪音視頻輸入的結束，並且手動通過commit和create_response觸發Qwen-Omni的推理，獲得回複。
    • 在模型回複狀態，需要停止音視頻的輸入。在模型回複結束後才可以繼續輸入下一輪音視頻。
    • 需要通過cancel_response介面打斷模型回複。
注意，在開啟"turn_detection"時，依舊可以通過commit和create_response主動觸發回複，通過cancel_response主動打斷。

Q：input_audio_transcription為何要選擇其他模型？

Qwen-Omni即時是端到端的多模態大模型，文本輸出是對輸入的回答，因此不會直接產生輸入音訊轉錄。需要接入其他ASR模型轉錄。
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
  • 概述
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多