使用Python SDK調用Qwen-Omni即時多模態介面-大模型服務平台百鍊-阿里雲

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

前期準備

您的 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

調用地址：

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

下述請求參數可以通過update_session介面配置。

參數	類型	說明
output_modalities	list[MultiModality]	模型輸出模態設定，支援設定[MultiModality.TEXT]（僅輸出文本）或[MultiModality.TEXT, MultiModality.AUDIO]（輸出音頻和文本）。
voice	str	模型產生音訊音色，支援的音色參見音色列表。預設音色： `Qwen3-Omni-Flash-Realtime`: `"Cherry"` `Qwen-Omni-Turbo-Realtime`: `"Chelsie"`
input_audio_format	AudioFormat	使用者輸入音訊格式，當前僅支援設定為PCM_16000HZ_MONO_16BIT。
output_audio_format	AudioFormat	模型輸出音訊格式，當前僅支援設定為PCM_24000HZ_MONO_16BIT。
smooth_output	bool	僅Qwen3-Omni-Flash-Realtime系列版本支援設定。 True：獲得口語化的回複 False：獲得更書面化、正式的回複但可能會因為存在難以朗讀的內容而導致效果不好。 None：模型自動選擇口語化或書面化的回複風格
instructions	str	系統訊息，用於設定模型的目標或角色。例如：你是某五星級酒店的AI客服專員，請準確且友好地解答客戶關於房型、設施、價格、預訂政策的諮詢。請始終以專業和樂於助人的態度回應，杜絕提供未經證實或超出酒店服務涵蓋範圍的資訊。
enable_input_audio_transcription	bool	是否開啟輸入音訊語音辨識。
input_audio_transcription_model	str	用於輸入音頻轉錄的語音辨識模型，當前僅支援設定為"gummy-realtime-v1"。
turn_detection_type	str	服務端VAD類型，目前固定為"server_vad"。
turn_detection_threshold	float	VAD檢測閾值。建議在嘈雜的環境中增加，在安靜的環境中降低。取值越接近-1，噪音被判定為語音的機率越大。取值越接近1，噪音被判定為語音的機率越小。預設為 0.2, 參數範圍：[-1.0, 1.0]。
turn_detection_silence_duration_ms	int	檢測語音停止的靜音期間，超過此值後會觸發模型響應。預設值為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"，用戶端必須提交音頻緩衝區才能建立使用者訊息項。注意⚠️：如果 input_audio_transcription為會話配置了音頻轉錄，系統會轉錄音頻。提交輸入音頻緩衝區不會從模型建立響應。
`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模型轉錄。