Skip to main content
即時多模態

Java SDK

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

前期準備

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

快速開始

請訪問github下載範例程式碼。我們提供了三種調用方式的範例程式碼：
  1. 音頻對話樣本：麥克風採集即時音頻輸入，開啟VAD 模式（自動檢測語音起止），支援語音打斷。
    enableTurnDetection 參數需設為 true。
    推薦您使用耳機播放音頻，避免回聲觸發語音打斷。
  2. 音視訊交談樣本：麥克風和網路攝影機採集即時音視頻輸入，開啟VAD 模式（自動檢測語音起止），支援語音打斷。
    enableTurnDetection 參數需設為 true。
    推薦您使用耳機播放音頻，避免回聲觸發語音打斷。
  3. 本地調用：本地音頻和圖片作為輸入，開啟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介面完成配置。
參數類型說明
modalitiesList<OmniRealtimeModality>模型輸出模態設定，支援設定[OmniRealtimeModality.TEXT]（僅輸出文本）或[OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO]（輸出音頻和文本）。
voiceString模型產生音訊音色，支援的音色參見音色列表。預設音色：
  • Qwen3-Omni-Flash-Realtime：“Cherry”，
  • Qwen-Omni-Turbo-Realtime：“Chelsie”
inputAudioFormatOmniRealtimeAudioFormat使用者輸入音訊格式，當前僅支援設定為PCM_16000HZ_MONO_16BIT。
outputAudioFormatOmniRealtimeAudioFormat模型輸出音訊格式，當前僅支援設定為PCM_24000HZ_MONO_16BIT。
smooth_outputBoolean僅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();
instructionsString系統訊息，用於設定模型的目標或角色。例如：你是某五星級酒店的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();
enableInputAudioTranscriptionBoolean是否開啟輸入音訊語音辨識。
InputAudioTranscriptionString用於輸入音頻轉錄的語音辨識模型，當前僅支援設定為"gummy-realtime-v1"
enableTurnDetectionBoolean是否開啟語音活動檢測(VAD)，如果關閉後，由使用者手動提交音頻建立omni回複。
turnDetectionTypeString服務端VAD類型，目前固定為"server_vad"。
turnDetectionThresholdFloatVAD檢測閾值。建議在嘈雜的環境中增加， 在安靜的環境中降低。
  • 取值越接近-1，噪音被判定為語音的機率越大。
  • 取值越接近1，噪音被判定為語音的機率越小。
預設為 0.2, 參數範圍：[-1.0, 1.0]。
turnDetectionSilenceDurationMsInteger檢測語音停止的靜音期間，超過此值後會觸發模型響應。預設值為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"，用戶端必須提交音頻緩衝區才能建立使用者訊息項。
注意⚠️：
  1. 如果 input_audio_transcription為會話配置了音頻轉錄，系統會轉錄音頻。
  2. 提交輸入音頻緩衝區不會從模型建立響應。
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模型轉錄。
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
  • 概述
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多