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

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

前期準備

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

快速開始

請訪問github下載範例程式碼。我們提供了三種調用方式的範例程式碼：

音頻對話樣本：麥克風採集即時音頻輸入，開啟VAD 模式（自動檢測語音起止），支援語音打斷。
enableTurnDetection 參數需設為 true。
推薦您使用耳機播放音頻，避免回聲觸發語音打斷。
音視訊交談樣本：麥克風和網路攝影機採集即時音視頻輸入，開啟VAD 模式（自動檢測語音起止），支援語音打斷。
enableTurnDetection 參數需設為 true。
推薦您使用耳機播放音頻，避免回聲觸發語音打斷。
本地調用：本地音頻和圖片作為輸入，開啟Manual 模式（手動控制發送節奏）。
enableTurnDetection 參數需設為 false。

請求參數

下述請求參數可以通過OmniRealtimeParam對象的鏈式方法或setter配置、之後作為參數傳入OmniRealtimeConversation的構造方法完成配置。

參數

類型

說明

model

String

Qwen-Omni 即時模型的名稱。參見模型列表。

url

String

調用地址：

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

下述請求參數可以通過OmniRealtimeConfig對象的鏈式方法或setter配置、之後作為參數傳入updateSession介面完成配置。

參數	類型	說明
modalities	List<OmniRealtimeModality>	模型輸出模態設定，支援設定[OmniRealtimeModality.TEXT]（僅輸出文本）或[OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO]（輸出音頻和文本）。
voice	String	模型產生音訊音色，支援的音色參見音色列表。預設音色： Qwen3-Omni-Flash-Realtime：“Cherry”， Qwen-Omni-Turbo-Realtime：“Chelsie”
inputAudioFormat	OmniRealtimeAudioFormat	使用者輸入音訊格式，當前僅支援設定為PCM_16000HZ_MONO_16BIT。
outputAudioFormat	OmniRealtimeAudioFormat	模型輸出音訊格式，當前僅支援設定為PCM_24000HZ_MONO_16BIT。
smooth_output	Boolean	僅Qwen3-Omni-Flash-Realtime系列版本支援設定。 true：獲得口語化的回複 false：獲得更書面化、正式的回複但可能會因為存在難以朗讀的內容而導致效果不好。 null：預設值，模型自動選擇口語化或書面化的回複風格說明 `smoothOutput`需要通過`OmniRealtimeConfig`執行個體的`parameters`方法進行設定： `OmniRealtimeConfig config = OmniRealtimeConfig.builder() .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT)) .voice("Chelsie") .enableInputAudioTranscription(true) .InputAudioTranscription("gummy-realtime-v1") .parameters(new HashMap<String, Object>() {{ put("smooth_output", true); }}) .build();`
instructions	String	系統訊息，用於設定模型的目標或角色。例如：你是某五星級酒店的AI客服專員，請準確且友好地解答客戶關於房型、設施、價格、預訂政策的諮詢。請始終以專業和樂於助人的態度回應，杜絕提供未經證實或超出酒店服務涵蓋範圍的資訊。說明 `instructions`需要通過`OmniRealtimeConfig`執行個體的`parameters`方法進行設定： OmniRealtimeConfig config = OmniRealtimeConfig.builder() .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT)) .voice("Cherry") .enableTurnDetection(true) .enableInputAudioTranscription(true) .InputAudioTranscription("gummy-realtime-v1") .parameters(new HashMap<String, Object>() {{ put("instructions","你是某五星級酒店的AI客服專員，請準確且友好地解答客戶關於房型、設施、價格、預訂政策的諮詢。請始終以專業和樂於助人的態度回應，杜絕提供未經證實或超出酒店服務涵蓋範圍的資訊。"); }}) .build();
enableInputAudioTranscription	Boolean	是否開啟輸入音訊語音辨識。
InputAudioTranscription	String	用於輸入音頻轉錄的語音辨識模型，當前僅支援設定為"gummy-realtime-v1"
enableTurnDetection	Boolean	是否開啟語音活動檢測(VAD)，如果關閉後，由使用者手動提交音頻建立omni回複。
turnDetectionType	String	服務端VAD類型，目前固定為"server_vad"。
turnDetectionThreshold	Float	VAD檢測閾值。建議在嘈雜的環境中增加，在安靜的環境中降低。取值越接近-1，噪音被判定為語音的機率越大。取值越接近1，噪音被判定為語音的機率越小。預設為 0.2, 參數範圍：[-1.0, 1.0]。
turnDetectionSilenceDurationMs	Integer	檢測語音停止的靜音期間，超過此值後會觸發模型響應。預設值為800，參數範圍[200, 6000]。

關鍵介面

OmniRealtimeConversation類

OmniRealtimeConversation通過import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;方法引入。

方法簽名	服務端響應事件（通過回調下發）	說明
`public void connect() throws NoApiKeyException, InterruptedException`	session.created 會話已建立 session.updated 會話配置已更新	和服務端建立串連。
`public void updateSession(OmniRealtimeConfig config)`	session.updated 會話配置已更新	更新本次會話互動的預設配置。參數配置請參考《請求參數》章節。在您建立連結，服務端會及時返回用於此會話的預設輸出輸入配置。如果您需要更新預設會話配置，我們也推薦您總是在建立連結後即刻調用此介面。服務端在收到session.update事件後，會進行參數校正，如果參數不合法則返回錯誤，否則更新服務端側的會話配置。
`public void appendAudio(String audioBase64)`	無	將base64編碼後的音頻資料片段追加到雲端輸入音頻緩衝區。音頻緩衝區是你可以寫入並稍後提交的臨時儲存。開啟"turn_detection"，音頻緩衝區用於檢測語音，伺服器決定何時提交。關閉"turn_detection"，用戶端可以選擇每個事件中放置多少音頻量，最多放置 15 MiB。例如，從用戶端串流較小的資料區塊可以讓 VAD 響應更迅速。
`public void appendVideo(String videoBase64)`	無	將base64編碼後的圖片資料添加到雲端視頻緩衝區。圖片資料可以是本地的圖片，或從視頻流即時採集的圖片資料。目前對圖片輸入有以下限制：圖片格式需要為JPG或JPEG，建議傳入的圖片解析度為480P或720P，最大1080P；單張圖片大小不大於500KB（Base64編碼前）；圖片資料需要經過Base64編碼；建議您以 1張/秒的頻率向服務端發送圖片；
`public void clearAppendedAudio()`	input_audio_buffer.cleared 清空服務端收到的音頻	刪除當前雲端緩衝區的音頻。
`public void commit()`	input_audio_buffer.committed 伺服器收到提交的音頻	提交之前通過append添加到雲端緩衝區的音視頻，如果輸入的音頻緩衝區為空白將產生錯誤。開啟"turn_detection"，用戶端不需要發送此事件，伺服器會自動認可音頻緩衝區。關閉"turn_detection"，用戶端必須提交音頻緩衝區才能建立使用者訊息項。注意⚠️：如果 input_audio_transcription為會話配置了音頻轉錄，系統會轉錄音頻。提交輸入音頻緩衝區不會從模型建立響應。
`public void createResponse(String instructions, List<OmniRealtimeModality> modalities)`	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 mesasge 的文本或音頻內容流式輸出完成 response.output_item.done Assistant mesasge 的整個輸出項串流完成 response.done 響應完成	指示伺服器建立模型響應。開啟"turn_detection"模式下配置會話時，伺服器會自動建立模型響應。
`public void cancelResponse()`	無	取消進行中的響應。如果沒有任何響應可供取消，伺服器將以一個錯誤進行響應。
`public void close()`	無	終止任務，並關閉串連。
`public String getSessionId()`	無	擷取當前任務的session_id。
`public String getResponseId()`	無	擷取最近一次response的response_id。
`public long getFirstTextDelay()`	無	擷取最近一次response的首包文本延遲。
`public long getFirstAudioDelay()`	無	擷取最近一次response的音頻文本延遲。

回調介面（OmniRealtimeCallback）

服務端會通過回調的方式，將服務端響應事件和資料返回給用戶端。您需要實現回調方法，處理服務端返回的資訊或者資料。

通過import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;引入。

方法	參數	傳回值	描述
`public void onOpen()`	無	無	當和服務端建立串連完成後，該方法立刻被回調。
`public abstract void onEvent(JsonObject message)`	message：服務端響應事件。	無	包括對介面調用的回複響應和模型產生的文本和音頻。具體可以參考：服務端事件
`public abstract void onClose(int code, String reason)`	code：關閉websokcet的狀態代碼。 reason：關閉websocket的關閉資訊。	無	當服務已經關閉串連後進行回調。

常見問題

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

omni-realtime模型的輸入將音頻作為時間軸，圖片會按照發送的時間，插入到音頻中。您可以在音頻時間軸的任意時刻添加圖片。

在即時互動情境下，您可以在任意時刻開啟或關閉視頻輸入。

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

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

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

目前turn_detection開啟後只支援server_vad模式：

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

注意，在開啟"turn_detection"時，依舊可以通過commit和create_response主動觸發回複，通過response_cancel主動打斷。

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

omni是端到端的多模態大模型，文本輸出是對輸入的回答，因此不會直接產生輸入音訊轉錄。需要接入其他ASR模型轉錄。