Java SDK

本文檔介紹如何使用 DashScope Java SDK 調用即時語音辨識（Qwen-ASR-Realtime）模型。

重要

阿里雲百鍊為華北2（北京）、新加坡地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議遷移至新網域名稱：

華北2（北京）地區：從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
新加坡地區：從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId}需要替換為真實的Workspace ID。現有網域名稱仍可正常使用。

使用者指南：模型介紹、功能特性和完整範例程式碼請參見即時語音辨識

前提條件

安裝SDK，確保DashScope SDK版本不低於2.22.5。
擷取API Key。
瞭解WebSocket API。

請求參數

以下參數通過OmniRealtimeParam的鏈式方法設定。

點擊查看範例程式碼

OmniRealtimeParam param = OmniRealtimeParam.builder()
                .model("qwen3-asr-flash-realtime")
                // 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
                .url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime")
                // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                // 若沒有配置環境變數，請用百鍊API Key將下行替換為：.apikey("sk-xxx")
                .apikey(System.getenv("DASHSCOPE_API_KEY"))
                .build();

參數	類型	是否必須	說明
`model`	`String`	是	指定要使用的模型名稱。
`url`	`String`	是	語音辨識服務地址：華北2（北京）地區：`wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime`。調用時請將`{WorkspaceId}`替換為真實的Workspace ID。新加坡地區：`wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime`。調用時請將`{WorkspaceId}`替換為真實的業務空間ID。
`apikey`	`String`	否	設定API Key。

以下參數通過OmniRealtimeConfig的鏈式方法設定。

點擊查看範例程式碼

OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
        transcriptionParam.setLanguage("zh");
        transcriptionParam.setInputSampleRate(16000);
        transcriptionParam.setInputAudioFormat("pcm");

OmniRealtimeConfig config = OmniRealtimeConfig.builder()
                .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
                .enableTurnDetection( true)
                .turnDetectionType("server_vad")
                .turnDetectionThreshold(0.0f)
                .turnDetectionSilenceDurationMs(400)
                .transcriptionConfig(transcriptionParam)
                .build();

參數	類型	是否必須	說明
`modalities`	`List<OmniRealtimeModality>`	是	模型輸出模態，固定為`[OmniRealtimeModality.TEXT]`。
`enableTurnDetection`	`boolean`	否	是否開啟服務端語音活動檢測（VAD）。關閉後，需手動調用`commit()`方法觸發識別。預設值：`true`。取值範圍： `true`：開啟 `false`：關閉
`turnDetectionType`	`String`	否	服務端VAD類型，固定為 `server_vad`。
`turnDetectionThreshold`	`float`	否	VAD檢測閾值。推薦將該值設為`0.0`。預設值：`0.2`。取值範圍：`[-1, 1]`。較低的閾值會提高 VAD 的靈敏度，可能將背景雜音誤判為語音。較高的閾值則降低靈敏度，有助於在嘈雜環境中減少誤觸發。
`turnDetectionSilenceDurationMs`	`int`	否	VAD斷句檢測閾值（ms）。靜音持續時間長度超過該閾值將被認為是語句結束。推薦將該值設為`400`。預設值：`800`。取值範圍：`[200, 6000]`。較低的值（如 300ms）可使模型更快響應，但可能導致在自然停頓處發生不合理的斷句。較高的值（如 1200ms）可更好地處理長句內的停頓，但會增加整體響應延遲。
`transcriptionConfig`	`OmniRealtimeTranscriptionParam`	否	語音辨識相關配置。

以下參數通過OmniRealtimeTranscriptionParam的setter方法設定。

點擊查看範例程式碼

OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
        transcriptionParam.setLanguage("zh");
        transcriptionParam.setInputSampleRate(16000);
        transcriptionParam.setInputAudioFormat("pcm");

參數	類型	是否必須	說明
`language`	`String`	否	音頻源語言。 zh：中文（普通話、四川話、閩南語、吳語） yue：粵語 en：英文 ja：日語 de：德語 ko：韓語 ru：俄語 fr：法語 pt：葡萄牙語 ar：阿拉伯語 it：意大利語 es：西班牙語 hi：印地語 id：印尼語 th：泰語 tr：土耳其語 uk：烏克蘭語 vi：越南語 cs：捷克語 da：丹麥語 fil：菲律賓語 fi：芬蘭語 is：冰島語 ms：馬來語 no：挪威語 pl：波蘭語 sv：瑞典語
`inputSampleRate`	`int`	否	音頻採樣率（Hz）。支援`16000`和`8000`。預設值：`16000`。設定為 `8000` 時，服務端會先升採樣到16000Hz再進行識別，可能引入微小延遲。建議僅在源音頻為8000Hz（如電話線路）時使用。
`inputAudioFormat`	`String`	否	音頻格式。支援`pcm`和`opus`。預設值：`pcm`。

關鍵介面

OmniRealtimeConversation類

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

方法簽名	服務端響應事件（通過回調下發）	說明
`public OmniRealtimeConversation(OmniRealtimeParam param, OmniRealtimeCallback callback)`	無	構造方法。
`public void connect() throws NoApiKeyException, InterruptedException`	session.created 會話已建立 session.updated 會話配置已更新	和服務端建立串連。
`public void updateSession(OmniRealtimeConfig config)`	session.updated 會話配置已更新	用於更新會話配置，建議在串連建立後首先調用該方法進行設定。若未調用該方法，系統將使用預設配置。只需關注請求參數中的涉及到的參數。
`public void appendAudio(String audioBase64)`	無	將Base64編碼後的音頻資料片段追加到雲端輸入音頻緩衝區。請求參數`enableTurnDetection`設為`true`，音頻緩衝區用於檢測語音，服務端決定何時提交。請求參數`enableTurnDetection`設為`false`，用戶端可以選擇每個事件中放置多少音頻量，最多放置 15 MiB。例如，從用戶端串流較小的資料區塊可以讓 VAD 響應更迅速。
`public void commit()`	input_audio_buffer.committed 服務端收到提交的音頻	提交之前通過append添加到雲端緩衝區的音視頻，如果輸入的音頻緩衝區為空白將產生錯誤。禁用情境：請求參數`enableTurnDetection`設為`true`時。
`public void endSession() throws InterruptedException`	session.finished 服務端完成語音辨識，結束會話	通知服務端結束會話，服務端收到會話結束通知後將完成最後的語音辨識。調用時機： VAD 模式（預設）下，發送完音頻後調用該方法 Manual 模式下，調用commit方法之後調用該方法 `endSessionAsync` 是 `endSession` 的非同步版本，兩者功能完全相同。
`public void close()`	無	終止任務，並關閉串連。
`public String getSessionId()`	無	擷取當前任務的session_id。
`public String getResponseId()`	無	擷取最近一次response的response_id。

回調介面（OmniRealtimeCallback）

服務端會通過回調的方式，將服務端響應事件和資料返回給用戶端。

繼承此類並實現相應方法以處理服務端事件。

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

方法簽名	參數	說明
`public void onOpen()`	無	WebSocket串連成功建立時觸發。
`public abstract void onEvent(JsonObject message)`	message：服務端事件	收到服務端事件時觸發。
`public abstract void onClose(int code, String reason)`	code：狀態代碼 reason：WebSocket串連關閉時的日誌資訊	WebSocket串連關閉時觸發。