全部產品
Search
文件中心

Alibaba Cloud Model Studio:Qwen-LiveTranslate-Realtime Java SDK

更新時間:Nov 19, 2026

本文檔介紹如何使用 DashScope Java SDK 呼叫即時音訊與視訊翻譯(Qwen-LiveTranslate-Realtime)模型。

連接與鑒權參見 WebSocket 接入;事件欄位與 JSON 示例參見用戶端事件和服務端事件。

前提條件

  1. 安裝SDK,確保DashScope SDK版本不低於2.22.5。
  2. 擷取API Key。
  3. 瞭解即時語音/音視頻翻譯-千問。

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

  • 華北2(北京)地區:從 wss://dashscope.aliyuncs.com 遷移至 wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區:從 wss://dashscope-intl.aliyuncs.com 遷移至 wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

其中 {WorkspaceId} 為您的業務空間 ID,可在阿里雲百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。

快速開始

以下樣本展示如何從麥克風即時錄音並進行翻譯。

麥克風即時翻譯範例程式碼

WebSocketwss://WorkspaceId.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime
WebSocketwss://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime

import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;

import javax.sound.sampled.*;
import java.util.*;
import java.util.concurrent.atomic.AtomicBoolean;

/**
 * 即時音視頻翻譯模型麥克風樣本
 */
public class Main {
    private static final int INPUT_CHUNK_SIZE = 3200;   // 100ms 的 16kHz 16bit 單聲道音頻
    private static final int OUTPUT_CHUNK_SIZE = 4800;  // 100ms 的 24kHz 16bit 單聲道音頻
    private static final AtomicBoolean running = new AtomicBoolean(true);
    private static SourceDataLine speaker;  // 擴音器

    public static void main(String[] args) throws InterruptedException {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            System.err.println("請設定環境變數 DASHSCOPE_API_KEY");
            System.exit(1);
        }

        // 建立串連參數
        OmniRealtimeParam param = OmniRealtimeParam.builder()
                .model("qwen3.5-livetranslate-flash-realtime")
                .url("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime")
                .apikey(apiKey)
                .build();

        // 建立回調處理
        OmniRealtimeCallback callback = new OmniRealtimeCallback() {
            @Override
            public void onOpen() {
                System.out.println("[串連已建立]");
            }

            @Override
            public void onEvent(JsonObject message) {
                String type = message.get("type").getAsString();
                switch (type) {
                    case "input_audio_buffer.speech_started":
                        System.out.println("====== 檢測到語音輸入 ======");
                        break;
                    case "input_audio_buffer.speech_stopped":
                        System.out.println("====== 語音輸入結束 ======");
                        break;
                    case "conversation.item.input_audio_transcription.completed":
                        String originalText = message.get("transcript").getAsString();
                        System.out.println("[原文] " + originalText);
                        break;
                    case "response.audio_transcript.done":
                        String translatedText = message.get("transcript").getAsString();
                        System.out.println("[翻譯結果] " + translatedText);
                        break;
                    case "response.audio.delta":
                        // 解碼並播放翻譯後的音頻
                        String audioB64 = message.get("delta").getAsString();
                        byte[] audioBytes = Base64.getDecoder().decode(audioB64);
                        if (speaker != null) {
                            speaker.write(audioBytes, 0, audioBytes.length);
                        }
                        break;
                    case "error":
                        JsonObject error = message.get("error").getAsJsonObject();
                        System.err.println("[錯誤] " + error.get("message").getAsString());
                        break;
                }
            }

            @Override
            public void onClose(int code, String reason) {
                System.out.println("[串連已關閉] code: " + code + ", reason: " + reason);
            }
        };

        // 建立會話
        OmniRealtimeConversation conversation = new OmniRealtimeConversation(param, callback);

        try {
            // 初始化擴音器(用於播放翻譯後的語音)
            AudioFormat speakerFormat = new AudioFormat(24000, 16, 1, true, false);
            DataLine.Info speakerInfo = new DataLine.Info(SourceDataLine.class, speakerFormat);
            speaker = (SourceDataLine) AudioSystem.getLine(speakerInfo);
            speaker.open(speakerFormat, OUTPUT_CHUNK_SIZE * 4);
            speaker.start();

            // 初始化麥克風(用於採集語音輸入)
            AudioFormat micFormat = new AudioFormat(16000, 16, 1, true, false);
            DataLine.Info micInfo = new DataLine.Info(TargetDataLine.class, micFormat);
            if (!AudioSystem.isLineSupported(micInfo)) {
                System.err.println("麥克風不可用");
                System.exit(1);
            }
            TargetDataLine microphone = (TargetDataLine) AudioSystem.getLine(micInfo);
            microphone.open(micFormat);
            microphone.start();

            // 串連服務端
            conversation.connect();

            // 配置翻譯參數
            Map<String, Object> phrases = new HashMap<>();
            phrases.put("人工智慧", "Artificial Intelligence");
            phrases.put("機器學習", "Machine Learning");

            OmniRealtimeConfig config = OmniRealtimeConfig.builder()
                    .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
                    .voice("Tina")
                    .inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT)
                    .outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
                    .InputAudioTranscription("qwen3-asr-flash-realtime")
                    .translationConfig(OmniRealtimeTranslationParam.builder()
                            .language("en")
                            .corpus(OmniRealtimeTranslationParam.Corpus.builder()
                                    .phrases(phrases)
                                    .build())
                            .build())
                    .build();

            conversation.updateSession(config);

            // 註冊退出訊號處理
            Runtime.getRuntime().addShutdownHook(new Thread(() -> {
                System.out.println("\n[正在退出...]");
                running.set(false);
                microphone.stop();
                microphone.close();
                speaker.stop();
                speaker.close();
                try {
                    conversation.endSession();
                } catch (InterruptedException e) {
                    Thread.currentThread().interrupt();
                }
                conversation.close(1000, "使用者停止");
            }));

            System.out.println("[開始即時翻譯] 請對著麥克風說話,按 Ctrl+C 退出");

            // 持續採集麥克風音頻並發送
            byte[] buffer = new byte[INPUT_CHUNK_SIZE];
            while (running.get()) {
                int bytesRead = microphone.read(buffer, 0, buffer.length);
                if (bytesRead > 0) {
                    conversation.appendAudio(Base64.getEncoder().encodeToString(buffer));
                }
            }

        } catch (NoApiKeyException e) {
            System.err.println("API Key 錯誤: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("發生異常: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

請求參數

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

    點擊查看範例程式碼

    OmniRealtimeParam param = OmniRealtimeParam.builder()
            .model("qwen3.5-livetranslate-flash-realtime")
            // 以下為新加坡地區URL,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的URL不同。
            .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

    是

    指定要使用的模型名稱,推薦使用qwen3.5-livetranslate-flash-realtime。

    url

    String

    是

    即時翻譯服務地址:

    • 華北2(北京):wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime
    • 新加坡:wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime

    調用時請將{WorkspaceId}替換為真實的業務空間ID。

    apikey

    String

    否

    設定API Key。

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

    點擊查看範例程式碼

    // 設定翻譯熱詞
    Map<String, Object> phrases = new HashMap<>();
    phrases.put("人工智慧", "Artificial Intelligence");
    phrases.put("機器學習", "Machine Learning");
    
    OmniRealtimeConfig config = OmniRealtimeConfig.builder()
            .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
            .voice("Tina")
            .inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT)
            .outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
            .InputAudioTranscription("qwen3-asr-flash-realtime")
            .translationConfig(OmniRealtimeTranslationParam.builder()
                    .language("en")
                    .corpus(OmniRealtimeTranslationParam.Corpus.builder()
                            .phrases(phrases)
                            .build())
                    .build())
            .build();
    
    conversation.updateSession(config);
    

    參數

    類型

    是否必須

    說明

    modalities

    List<OmniRealtimeModality>

    否

    模型輸出模態。

    預設值:[OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT]。

    取值範圍:

    • [OmniRealtimeModality.TEXT]:僅輸出文本

    • [OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT]:輸出文本和音頻

    voice

    String

    是

    產生音訊音色。

    預設值:

    • Qwen3.5-LiveTranslate-Flash-Realtime預設音色為: Tina

    可選值:參見支援的音色。

    inputAudioFormat

    OmniRealtimeAudioFormat

    否

    輸入音頻格式。

    預設值:OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT。

    outputAudioFormat

    OmniRealtimeAudioFormat

    否

    輸出音頻格式。

    預設值:OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT。

    InputAudioTranscription

    String

    否

    輸入音頻轉錄模型。如需輸出原文轉錄,則必須設定此參數。

    可選值:qwen3-asr-flash-realtime。

    translationConfig

    OmniRealtimeTranslationParam

    否

    翻譯相關配置。

    enableTurnDetection

    boolean

    否

    是否啟用 VAD(語音活動檢測)。

    預設值:true,即啟用 VAD 模式,服務端自動檢測語音起止並自動觸發翻譯。

    設為false可切換為 Manual 模式,由用戶端通過commit()方法手動提交音頻。詳細參數說明參見turn_detection object (可選) 語音活動檢測(VAD,Voice Activity Detection)配置,用於控制語音起止的檢測方式: 設為設定物件(預設值):啟用 VAD 模式。服務端自動檢測語音起止,自動認可音頻緩衝區並觸發翻譯響應,用戶端無需發送input_audio_buffer.commit事件。 設為null:啟用 Manual 模式。由用戶端通過input_audio_buffer.commit事件手動提交音頻緩衝區,服務端收到後自動開始產生翻譯響應。 屬性 type string (可選) VAD 類型,固定為server_vad。 threshold float (可選) VAD 檢測靈敏度。值越低,越容易將微弱聲音(包括背景雜音)識別為語音;值越高,需要更清晰、音量更大的語音才能觸發。 取值範圍:[-1.0, 1.0],預設值為 0.2。 silence_duration_ms integer (可選) 語音結束後需保持靜音的最短時間長度(毫秒)。超過該時間長度後判定語音結束,服務端自動認可音頻緩衝區並觸發翻譯響應。 取值範圍:[200, 6000],預設值為 1000。。

    擴充會話參數

    部分會話參數沒有對應的 SDK 設定方法,可以透過 OmniRealtimeConfig.builder().parameters(Map) 傳入。Map 中的鍵會直接寫入 session。例如,啟用即時聲音複刻時,先建構以下參數:

    Map<String, Object> options = new HashMap<>();
    options.put("frequency", "once");
    
    Map<String, Object> parameters = new HashMap<>();
    parameters.put("enable_voice_clone", true);
    parameters.put("voice_clone_options", options);
    

    在既有設定建構鏈中,將音色設為 .voice("default"),並加入 .parameters(parameters)。保留原有語種和音訊設定,建構後呼叫 conversation.updateSession(config)。複刻頻率與音色的搭配請參見聲音複刻。

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

    點擊查看範例程式碼

    // 設定翻譯熱詞
    Map<String, Object> phrases = new HashMap<>();
    phrases.put("人工智慧", "Artificial Intelligence");  // 源語言詞: 目標語言翻譯
    phrases.put("機器學習", "Machine Learning");
    
    OmniRealtimeTranslationParam translationParam = OmniRealtimeTranslationParam.builder()
            .language("en")  // 翻譯目標語言代碼
            .corpus(OmniRealtimeTranslationParam.Corpus.builder()
                    .phrases(phrases)
                    .build())
            .build();
    

    參數

    類型

    是否必須

    說明

    language

    String

    否

    翻譯目標語言代碼。

    預設值:en。

    可選值:參見支援的語種。

    corpus

    OmniRealtimeTranslationParam.Corpus

    否

    熱詞配置,用於提升特定詞彙的翻譯準確性。

    corpus.phrases

    Map<String, Object>

    否

    熱詞映射表。key 為源語言詞彙,value 為目標語言對應翻譯。

    樣本:{"人工智慧": "Artificial Intelligence"}

介面參考

OmniRealtimeConversation類

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

方法簽名服務端響應事件(通過回調下發)說明
public OmniRealtimeConversation(OmniRealtimeParam param, OmniRealtimeCallback callback)

無

構造方法。

public void connect() throws NoApiKeyException, InterruptedException

服務端事件

會話已建立

服務端事件

會話配置已更新

和服務端建立串連。

public void updateSession(OmniRealtimeConfig config)

服務端事件

會話配置已更新

用於更新會話配置,建議在串連建立後首先調用該方法進行設定。若未調用該方法,系統將使用預設配置。只需關注OmniRealtimeConfig中涉及的參數。

public void appendAudio(String audioBase64)

無

將Base64編碼後的音頻資料片段追加到雲端輸入音頻緩衝區。服務端會自動檢測語音起止並觸發翻譯。

public void commit()

input_audio_buffer.committed

輸入音頻緩衝區已提交

Manual 模式下,提交之前通過appendAudio方法追加到雲端緩衝區的音頻,服務端收到後自動開始產生翻譯響應。VAD 模式下無需調用此方法,服務端會自動認可。

public void clearAppendedAudio()

input_audio_buffer.cleared

輸入音頻緩衝區已清空

清空當前雲端緩衝區中尚未提交的音頻資料。

public void endSession() throws InterruptedException

session.finished

服務端完成語音翻譯,結束會話

通知服務端結束會話,服務端收到會話結束通知後將完成最後的語音翻譯。

public void close(int code, String reason)

無

終止任務,並關閉串連。

public String getSessionId()

無

擷取當前任務的session_id。

public String getResponseId()

無

擷取最近一次response的response_id。

public long getFirstTextDelay()

無

擷取最近一次響應的首個文本延遲(毫秒)。

public long getFirstAudioDelay()

無

擷取最近一次響應的首個音頻延遲(毫秒)。

回調介面(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串連關閉時觸發。