Skip to main content

Qwen-ASR-Realtime Java SDK

Dokumen ini menjelaskan cara menggunakan DashScope Java SDK untuk memanggil model Real-time Speech Recognition (Qwen-ASR-Realtime).

Model Studio telah meluncurkan domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapura, yang memberikan performa unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Migrasi ke domain baru direkomendasikan:
  • Wilayah China (Beijing): migrasikan dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Wilayah Singapura: migrasikan dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} harus diganti dengan Workspace ID Anda yang sebenarnya. Domain yang ada tetap berfungsi seperti sebelumnya.

Prasyarat

  1. Instal SDK dan pastikan versi DashScope SDK adalah 2.22.5 atau lebih baru.
  2. Dapatkan dan konfigurasikan Kunci API.
  3. Pelajari WebSocket API.

Mulai Cepat

Kode contoh membaca your_audio_file.pcm (PCM16, 16 kHz, mono). Jika Anda hanya memiliki format seperti MP3/WAV, Anda dapat mengonversinya dengan ffmpeg:
ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm
Java
import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.sound.sampled.LineUnavailableException;
import java.io.File;
import java.io.FileInputStream;
import java.util.Base64;
import java.util.Collections;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.atomic.AtomicReference;

public class Qwen3AsrRealtimeUsage {
    private static final Logger log = LoggerFactory.getLogger(Qwen3AsrRealtimeUsage.class);
    private static final int AUDIO_CHUNK_SIZE = 1024; // Audio chunk size in bytes
    private static final int SLEEP_INTERVAL_MS = 30;  // Sleep interval in milliseconds

    public static void main(String[] args) throws InterruptedException, LineUnavailableException {
        CountDownLatch finishLatch = new CountDownLatch(1);

        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/model-studio/get-api-key
                // 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:.apikey("sk-xxx")
                .apikey(System.getenv("DASHSCOPE_API_KEY"))
                .build();

        OmniRealtimeConversation conversation = null;
        final AtomicReference<OmniRealtimeConversation> conversationRef = new AtomicReference<>(null);
        conversation = new OmniRealtimeConversation(param, new OmniRealtimeCallback() {
            @Override
            public void onOpen() {
                System.out.println("connection opened");
            }
            @Override
            public void onEvent(JsonObject message) {
                String type = message.get("type").getAsString();
                switch(type) {
                    case "session.created":
                        System.out.println("start session: " + message.get("session").getAsJsonObject().get("id").getAsString());
                        break;
                    case "conversation.item.input_audio_transcription.completed":
                        System.out.println("transcription: " + message.get("transcript").getAsString());
                        finishLatch.countDown();
                        break;
                    case "input_audio_buffer.speech_started":
                        System.out.println("======VAD Speech Start======");
                        break;
                    case "input_audio_buffer.speech_stopped":
                        System.out.println("======VAD Speech Stop======");
                        break;
                    case "conversation.item.input_audio_transcription.text":
                        System.out.println("transcription: " + message.get("text").getAsString() + message.get("stash").getAsString());
                        break;
                    default:
                        break;
                }
            }
            @Override
            public void onClose(int code, String reason) {
                System.out.println("connection closed code: " + code + ", reason: " + reason);
            }
        });
        conversationRef.set(conversation);
        try {
            conversation.connect();
        } catch (NoApiKeyException e) {
            throw new RuntimeException(e);
        }

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

        OmniRealtimeConfig config = OmniRealtimeConfig.builder()
                .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
                .transcriptionConfig(transcriptionParam)
                .build();
        conversation.updateSession(config);

        String filePath = "your_audio_file.pcm";
        File audioFile = new File(filePath);
        if (!audioFile.exists()) {
            log.error("Audio file not found: {}", filePath);
            return;
        }

        try (FileInputStream audioInputStream = new FileInputStream(audioFile)) {
            byte[] audioBuffer = new byte[AUDIO_CHUNK_SIZE];
            int bytesRead;
            int totalBytesRead = 0;

            log.info("Starting to send audio data from: {}", filePath);

            // Read and send audio data in chunks
            while ((bytesRead = audioInputStream.read(audioBuffer)) != -1) {
                totalBytesRead += bytesRead;
                byte[] chunk = new byte[bytesRead];
                System.arraycopy(audioBuffer, 0, chunk, 0, bytesRead);
                String audioB64 = Base64.getEncoder().encodeToString(chunk);
                // Send audio chunk to conversation
                conversation.appendAudio(audioB64);

                // Add small delay to simulate real-time audio streaming
                Thread.sleep(SLEEP_INTERVAL_MS);
            }

            log.info("Finished sending audio data. Total bytes sent: {}", totalBytesRead);

        } catch (Exception e) {
            log.error("Error sending audio from file: {}", filePath, e);
        }

        //send session.finish and wait for finish and close
        conversation.endSession();
        log.info("task finished");

        System.exit(0);
    }
}
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

Parameter permintaan

  • Parameter berikut diatur melalui metode berantai dari 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/model-studio/get-api-key
                    // 若没有配置环境变量,请用百炼API Key将下行替换为:.apikey("sk-xxx")
                    .apikey(System.getenv("DASHSCOPE_API_KEY"))
                    .build();
    

    Parameter

    Tipe

    Wajib

    Deskripsi

    model

    String

    Ya

    Nama model yang digunakan.

    url

    String

    Ya

    Alamat layanan pengenalan ucapan:

    • Wilayah China (Beijing): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime. Saat melakukan panggilan, ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya.

    • Wilayah Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime. Saat melakukan panggilan, ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya.

    apikey

    String

    Tidak

    Kunci API yang akan dikonfigurasi.

  • Parameter berikut diatur melalui metode berantai dari 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();
    

    Parameter

    Tipe

    Wajib

    Deskripsi

    modalities

    List<OmniRealtimeModality>

    Ya

    Modalitas output model, ditetapkan tetap ke [OmniRealtimeModality.TEXT].

    enableTurnDetection

    boolean

    Tidak

    Apakah mengaktifkan deteksi aktivitas suara (VAD) sisi server. Saat dinonaktifkan, Anda harus memanggil metode commit() secara manual untuk memicu pengenalan.

    Nilai default: true.

    Nilai yang valid:

    • true: Aktifkan

    • false: Nonaktifkan

    turnDetectionType

    String

    Tidak

    Jenis VAD sisi server, ditetapkan tetap sebagai server_vad.

    turnDetectionThreshold

    float

    Tidak

    Ambang batas deteksi VAD. Kami menyarankan mengatur nilai ini ke 0.0.

    Nilai default: 0.5.

    Rentang nilai: [-1, 1].

    Ambang batas yang lebih rendah meningkatkan sensitivitas VAD dan dapat salah mengklasifikasikan kebisingan latar belakang sebagai ucapan. Ambang batas yang lebih tinggi mengurangi sensitivitas, yang membantu mengurangi pemicuan palsu di lingkungan yang bising.

    turnDetectionSilenceDurationMs

    int

    Tidak

    Ambang batas deteksi pemenggalan kalimat VAD (ms). Diam yang berlangsung lebih lama dari ambang batas ini dianggap sebagai akhir ujaran. Kami menyarankan mengatur nilai ini ke 400.

    Nilai default: 800.

    Rentang nilai: [200, 6000].

    Nilai yang lebih rendah (misalnya 300 ms) memungkinkan model merespons lebih cepat, tetapi dapat menyebabkan pemenggalan kalimat yang tidak wajar pada jeda alami. Nilai yang lebih tinggi (misalnya 1200 ms) lebih baik menangani jeda dalam kalimat panjang, tetapi meningkatkan latensi respons keseluruhan.

    transcriptionConfig

    OmniRealtimeTranscriptionParam

    Tidak

    Konfigurasi terkait pengenalan ucapan.

  • Parameter berikut diatur melalui metode setter dari OmniRealtimeTranscriptionParam.
    OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
            transcriptionParam.setLanguage("zh");
            transcriptionParam.setInputSampleRate(16000);
            transcriptionParam.setInputAudioFormat("pcm");
    

    Parameter

    Tipe

    Wajib

    Deskripsi

    language

    String

    Tidak

    Bahasa sumber audio.

    • zh: Tionghoa (Mandarin, dialek Sichuan, dialek Minnan, dialek Wu)

    • yue: Kanton

    • en: Inggris

    • ja: Jepang

    • de: Jerman

    • ko: Korea

    • ru: Rusia

    • fr: Prancis

    • pt: Portugis

    • ar: Arab

    • it: Italia

    • es: Spanyol

    • hi: Hindi

    • id: Indonesia

    • th: Thai

    • tr: Turki

    • uk: Ukraina

    • vi: Vietnam

    • cs: Ceko

    • da: Denmark

    • fil: Filipino

    • fi: Finlandia

    • is: Islandia

    • ms: Melayu

    • no: Norwegia

    • pl: Polandia

    • sv: Swedia

    inputSampleRate

    int

    Tidak

    Laju sampling audio (Hz). Mendukung 16000 dan 8000.

    Nilai default: 16000.

    Saat diatur ke 8000, server terlebih dahulu melakukan upsampling audio ke 16000 Hz sebelum pengenalan, yang dapat menimbulkan sedikit latensi. Disarankan hanya saat audio sumber adalah 8000 Hz (misalnya saluran telepon).

    inputAudioFormat

    String

    Tidak

    Format audio. Mendukung pcm dan opus.

    Nilai default: pcm.

Referensi API

Kelas OmniRealtimeConversation

OmniRealtimeConversation diimpor melalui import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;.
Tanda tangan metodeEvent respons server (dikirim melalui callback)Deskripsi
public OmniRealtimeConversation(OmniRealtimeParam param, OmniRealtimeCallback callback)
Tidak adaKonstruktor.
public void connect() throws NoApiKeyException, InterruptedException
session.created
Sesi dibuat
session.updated
Konfigurasi sesi diperbarui
Membuat koneksi dengan server.
public void updateSession(OmniRealtimeConfig config)
session.updated
Konfigurasi sesi diperbarui
Digunakan untuk memperbarui konfigurasi sesi. Disarankan memanggil metode ini terlebih dahulu setelah koneksi terbentuk untuk menerapkan pengaturan. Jika metode ini tidak dipanggil, sistem menggunakan konfigurasi default. Hanya parameter yang tercantum dalam parameter permintaan yang perlu dipertimbangkan.
public void appendAudio(String audioBase64)
Tidak adaMenambahkan potongan data audio yang dienkode Base64 ke buffer audio input di sisi cloud.
  • Saat enableTurnDetection dalam parameter permintaan diatur ke true, buffer audio digunakan untuk deteksi ucapan, dan server yang menentukan kapan melakukan commit.
  • Saat enableTurnDetection dalam parameter permintaan diatur ke false, klien dapat memilih berapa banyak audio yang ditempatkan dalam setiap event, hingga 15 MiB. Misalnya, streaming potongan yang lebih kecil dari klien memungkinkan VAD merespons lebih cepat.
public void commit()
input_audio_buffer.committed
Server menerima audio yang di-commit
Melakukan commit pada audio dan video yang sebelumnya ditambahkan ke buffer sisi cloud melalui append. Jika buffer audio input kosong, akan terjadi error.Skenario nonaktif: Saat enableTurnDetection dalam parameter permintaan diatur ke true.
public void endSession() throws InterruptedException
session.finished
Server menyelesaikan pengenalan ucapan dan mengakhiri sesi.
Memberi tahu server untuk mengakhiri sesi. Setelah menerima notifikasi akhir sesi, server akan menyelesaikan pengenalan ucapan akhir.Kapan harus dipanggil:
  • Dalam mode VAD (default), panggil metode ini setelah semua audio terkirim
  • Dalam mode Manual, panggil metode ini setelah memanggil metode commit
endSessionAsync adalah versi asinkron dari endSession; keduanya identik secara fungsional.
public void close()
Tidak adaMenghentikan tugas dan menutup koneksi.
public String getSessionId()
Tidak adaMendapatkan session_id dari tugas saat ini.
public String getResponseId()
Tidak adaMendapatkan response_id dari respons terbaru.

Antarmuka callback (OmniRealtimeCallback)

Server mengembalikan event respons server dan data ke klien melalui callback. Perluas kelas ini dan implementasikan metode yang sesuai untuk menangani event server. Impor melalui import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;.
Tanda tangan metodeParameterDeskripsi
public void onOpen()
Tidak adaDipicu saat koneksi WebSocket berhasil dibuat.
public abstract void onEvent(JsonObject message)
message: Event serverDipicu saat event server diterima.
public abstract void onClose(int code, String reason)
code: kode statusreason: Informasi log yang dihasilkan saat koneksi WebSocket ditutupDipicu saat koneksi WebSocket ditutup.