Skip to main content

Panduan akses WebSocket

Layanan pengenalan ucapan real-time Qwen-ASR-Realtime menggunakan protokol WebSocket untuk menerima aliran audio real-time dan mentranskripsikannya secara real-time. Layanan ini mendukung alur interaksi mode VAD dan mode Manual.

Panduan pengguna: Untuk pengenalan model dan rekomendasi pemilihan, lihat Pengenalan ucapan; untuk contoh kode, lihat Pengenalan ucapan real-time.

Titik akhir API

URL WebSocket tetap sebagai berikut. Model yang akan dipanggil ditentukan melalui parameter kueri model (ganti <model_name> dengan model sebenarnya):
  • Singapore
  • China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>Saat memanggil, ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya.
Alibaba Cloud Model Studio menyediakan domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapore, memberikan performa yang lebih unggul dan stabilitas yang lebih tinggi untuk permintaan inferensi. Migrasi ke domain baru direkomendasikan:
  • Wilayah China (Beijing): bermigrasi dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Wilayah Singapore: bermigrasi dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya. Domain yang ada saat ini tetap berfungsi.
URL harus menggunakan protokol wss://. Otorisasi diatur dalam header permintaan (lihat Request headers), dan model ditentukan melalui parameter kueri model pada URL.

Request headers

Tambahkan informasi berikut ke header permintaan:

Parameter

Tipe

Wajib

Deskripsi

Authorization

string

Ya

Token autentikasi, dalam format Bearer <your_api_key>; ganti <your_api_key> dengan API Key Anda yang sebenarnya.

user-agent

string

Tidak

Identifier klien yang membantu server melacak sumber permintaan.

X-DashScope-WorkSpace

string

Tidak

Workspace ID Alibaba Cloud Model Studio.

X-DashScope-DataInspection

string

Tidak

Apakah fitur pemeriksaan kepatuhan data diaktifkan. Secara default, tidak diteruskan atau diatur ke enable. Jangan aktifkan kecuali diperlukan.

Otorisasi diverifikasi selama handshake WebSocket. Jika API Key tidak valid atau tidak disertakan, handshake gagal dan error HTTP 401/403 dikembalikan.

Alur interaksi

Untuk detail tentang event klien dan server, lihat Event klien dan Event server. Dua mode interaksi didukung:
  • Mode VAD (default): Server secara otomatis mendeteksi awal dan akhir ucapan (segmentasi ujaran), sehingga cocok untuk skenario seperti percakapan real-time dan transkripsi rapat.
  • Mode Manual: Klien mengontrol segmentasi ujaran, cocok untuk skenario di mana klien dapat menentukan batas ujaran secara jelas, seperti mengirim pesan suara di aplikasi obrolan.
Model tidak mengembalikan stempel waktu tingkat kalimat atau tingkat kata untuk teks transkripsi. Waktu mulai dan berakhirnya ucapan dalam event VAD menggambarkan batas aktivitas suara; lihat event terkait untuk deskripsi bidang.

Mode VAD (default)

Nilai default server untuk silence_duration_ms adalah 800; untuk skenario yang memerlukan segmentasi ujaran cepat, seperti percakapan dan obrolan, 400 dapat digunakan sebagai referensi. Nilai default server untuk threshold adalah 0.2. Untuk konfigurasi lengkap, lihat Event klien. Server secara otomatis mendeteksi awal dan akhir ucapan (segmentasi ujaran). Pengembang hanya perlu terus mengirim aliran audio, dan server secara otomatis mengembalikan hasil pengenalan akhir ketika mendeteksi bahwa sebuah ujaran telah berakhir. Mode ini cocok untuk skenario seperti percakapan real-time dan transkripsi rapat. Untuk mengaktifkan: Konfigurasikan parameter session.turn_detection dari event session.update klien.
image
  • Klien menambahkan audio ke buffer dengan mengirim event input_audio_buffer.append.
  • Server mengembalikan event input_audio_buffer.speech_started ketika mendeteksi ucapan. Catatan: Jika klien belum menerima event ini dan langsung mengirim session.finish untuk mengakhiri sesi, server akan langsung mengembalikan event session.finished, setelah itu klien harus memutuskan koneksi sendiri.
  • Klien terus mengirim event input_audio_buffer.append untuk mengirimkan audio.
  • Setelah semua audio dikirimkan, klien mengirim event session.finish untuk memberi tahu server mengakhiri sesi saat ini.
    Dalam mode VAD, setelah semua audio dikirim, Anda harus mengirim event session.finish sebelum menutup koneksi. Jika klien menutup koneksi WebSocket secara langsung tanpa mengirim event ini, server akan membuang item in_progress saat ini, dan event seperti conversation.item.input_audio_transcription.completed tidak akan tiba. Kami menyarankan mengirim {"type":"session.finish"} sebelum memanggil ws.Close(), dan menutup koneksi hanya setelah menerima event session.finished.
  • Server mengembalikan event input_audio_buffer.speech_stopped ketika mendeteksi akhir ucapan.
  • Server mengembalikan event input_audio_buffer.committed.
  • Server mengembalikan event conversation.item.created.
  • Server mengembalikan event conversation.item.input_audio_transcription.text, yang berisi hasil pengenalan ucapan real-time.
  • Server mengembalikan event conversation.item.input_audio_transcription.completed, yang berisi hasil pengenalan ucapan final.
  • Server mengembalikan event session.finished untuk memberi tahu klien bahwa pengenalan telah selesai; pada saat itu, klien harus memutuskan koneksi sendiri.

Mode Manual

Klien mengontrol segmentasi ujaran. Klien perlu mengirim audio untuk satu ujaran lengkap, lalu mengirim event input_audio_buffer.commit untuk memberi tahu server. Mode ini cocok untuk skenario di mana klien dapat menentukan batas ujaran secara jelas, seperti mengirim pesan suara di aplikasi obrolan. Untuk mengaktifkan: Atur session.turn_detection dari event session.update klien ke null.
image
  • Klien menambahkan audio ke buffer dengan mengirim event input_audio_buffer.append.
  • Klien mengirimkan buffer audio input dengan mengirim event input_audio_buffer.commit. Commit ini membuat item pesan pengguna baru dalam percakapan.
  • Klien mengirim event session.finish untuk memberi tahu server mengakhiri sesi saat ini.
  • Server mengembalikan event input_audio_buffer.committed sebagai respons.
  • Server mengembalikan event conversation.item.input_audio_transcription.text, yang berisi hasil pengenalan ucapan real-time.
  • Server mengembalikan event conversation.item.input_audio_transcription.completed, yang berisi hasil pengenalan ucapan final.
  • Server mengembalikan event session.finished untuk memberi tahu klien bahwa pengenalan telah selesai; pada saat itu, klien harus memutuskan koneksi sendiri.

Contoh pemanggilan

Contoh berikut menggunakan qwen3-asr-flash-realtime. Dapatkan API Key dan Base URL di konsol, lalu konfigurasikan masing-masing sebagai variabel lingkungan DASHSCOPE_API_KEY dan DASHSCOPE_BASE_URL. Unduh audio contoh dan simpan sebagai asr_example.wav. Audio tersebut adalah file WAV yang dikodekan dalam 16 kHz, mono, PCM 16-bit.
Kode contoh membaca asr_example.pcm (PCM16, 16 kHz, mono). Jika Anda hanya memiliki file dalam format seperti MP3/WAV, gunakan ffmpeg untuk mengonversinya:
ffmpeg -i asr_example.wav -ar 16000 -ac 1 -f s16le asr_example.pcm
Saat menggunakan mode non-VAD (Manual), kami menyarankan agar durasi kumulatif audio yang dikirim dalam satu sesi tidak melebihi 60 detik.
  • Java
  • Python
  • Go
  • Node.js
  • C#
  • PHP
Sebelum menjalankan contoh, pastikan Anda telah menginstal dependensi Java-WebSocket:
Maven
<dependency>
    <groupId>org.java-websocket</groupId>
    <artifactId>Java-WebSocket</artifactId>
    <version>1.5.6</version>
</dependency>
<dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20240303</version>
</dependency>
import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;
import org.json.JSONObject;

import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;
import java.util.concurrent.atomic.AtomicBoolean;
import java.util.logging.*;

public class QwenASRRealtimeClient {

    private static final Logger logger = Logger.getLogger(QwenASRRealtimeClient.class.getName());
    private static final String API_KEY = System.getenv("DASHSCOPE_API_KEY");
    private static final String MODEL = "qwen3-asr-flash-realtime";

    // 控制是否使用 VAD 模式
    private static final boolean enableServerVad = true;

    private static final AtomicBoolean isRunning = new AtomicBoolean(true);
    private static WebSocketClient client;

    public static void main(String[] args) throws Exception {
        initLogger();

        String baseUrl = "wss://" + URI.create(System.getenv("DASHSCOPE_BASE_URL")).getHost() + "/api-ws/v1/realtime";
        String url = baseUrl + "?model=" + MODEL;
        logger.info("Connecting to server: " + url);

        client = new WebSocketClient(new URI(url)) {
            @Override
            public void onOpen(ServerHandshake handshake) {
                logger.info("Connected to server.");
                sendSessionUpdate();
            }

            @Override
            public void onMessage(String message) {
                try {
                    JSONObject data = new JSONObject(message);
                    String eventType = data.optString("type");

                    logger.info("Received event: " + data.toString(2));

                    // 最终识别结果在 transcription.completed 事件中
                    if ("conversation.item.input_audio_transcription.completed".equals(eventType)) {
                        logger.info("Final transcript: " + data.optString("transcript"));
                    }

                    // 收到结束事件 → 停止发送线程并关闭连接
                    if ("session.finished".equals(eventType)) {
                        logger.info("Closing WebSocket connection after session finished...");

                        isRunning.set(false); // 停止发送音频线程
                        if (this.isOpen()) {
                            this.close(1000, "ASR finished");
                        }
                    }
                } catch (Exception e) {
                    logger.severe("Failed to parse message: " + message);
                }
            }

            @Override
            public void onClose(int code, String reason, boolean remote) {
                logger.info("Connection closed: " + code + " - " + reason);
            }

            @Override
            public void onError(Exception ex) {
                logger.severe("Error: " + ex.getMessage());
            }
        };

        // 添加请求头
        client.addHeader("Authorization", "Bearer " + API_KEY);
        client.addHeader("OpenAI-Beta", "realtime=v1");

        client.connectBlocking(); // 阻塞直到连接建立

        // 替换为待识别的音频文件路径
        String localAudioPath = "asr_example.pcm";
        Thread audioThread = new Thread(() -> {
            try {
                sendAudio(localAudioPath);
            } catch (Exception e) {
                logger.severe("Audio sending thread error: " + e.getMessage());
            }
        });
        audioThread.start();
    }

    /** 会话更新事件(开启/关闭 VAD) */
    private static void sendSessionUpdate() {
        JSONObject eventNoVad = new JSONObject()
                .put("event_id", "event_123")
                .put("type", "session.update")
                .put("session", new JSONObject()
                        .put("modalities", new String[]{"text"})
                        .put("input_audio_format", "pcm")
                        .put("sample_rate", 16000)
                        // .put("input_audio_transcription", new JSONObject()
                        //         .put("language", "zh"))
                        .put("turn_detection", JSONObject.NULL) // 手动模式
                );

        JSONObject eventVad = new JSONObject()
                .put("event_id", "event_123")
                .put("type", "session.update")
                .put("session", new JSONObject()
                        .put("modalities", new String[]{"text"})
                        .put("input_audio_format", "pcm")
                        .put("sample_rate", 16000)
                        // .put("input_audio_transcription", new JSONObject()
                        //         .put("language", "zh"))
                        .put("turn_detection", new JSONObject()
                                .put("type", "server_vad")
                                .put("threshold", 0.2)
                                .put("silence_duration_ms", 400))
                );

        if (enableServerVad) {
            logger.info("Sending event (VAD):\n" + eventVad.toString(2));
            client.send(eventVad.toString());
        } else {
            logger.info("Sending event (Manual):\n" + eventNoVad.toString(2));
            client.send(eventNoVad.toString());
        }
    }

    /** 发送音频文件流 */
    private static void sendAudio(String localAudioPath) throws Exception {
        Thread.sleep(3000); // 等会话准备
        byte[] allBytes = Files.readAllBytes(Paths.get(localAudioPath));
        logger.info("文件读取开始");

        int offset = 0;
        while (isRunning.get() && offset < allBytes.length) {
            int chunkSize = Math.min(3200, allBytes.length - offset);
            byte[] chunk = new byte[chunkSize];
            System.arraycopy(allBytes, offset, chunk, 0, chunkSize);
            offset += chunkSize;

            if (client != null && client.isOpen()) {
                String encoded = Base64.getEncoder().encodeToString(chunk);
                JSONObject eventd = new JSONObject()
                        .put("event_id", "event_" + System.currentTimeMillis())
                        .put("type", "input_audio_buffer.append")
                        .put("audio", encoded);

                client.send(eventd.toString());
                logger.info("Sending audio event: " + eventd.getString("event_id"));
            } else {
                break; // 避免在断开后继续发送
            }

            Thread.sleep(100); // 模拟实时发送
        }

        logger.info("文件读取完毕");

        if (client != null && client.isOpen()) {
            // 非 VAD 模式下需要 commit
            if (!enableServerVad) {
                JSONObject commitEvent = new JSONObject()
                        .put("event_id", "event_789")
                        .put("type", "input_audio_buffer.commit");
                client.send(commitEvent.toString());
                logger.info("Sent commit event for manual mode.");
            }

            JSONObject finishEvent = new JSONObject()
                    .put("event_id", "event_987")
                    .put("type", "session.finish");
            client.send(finishEvent.toString());
            logger.info("Sent finish event.");
        }
    }

    /** 初始化日志 */
    private static void initLogger() {
        logger.setLevel(Level.ALL);
        Logger rootLogger = Logger.getLogger("");
        for (Handler h : rootLogger.getHandlers()) {
            rootLogger.removeHandler(h);
        }

        Handler consoleHandler = new ConsoleHandler();
        consoleHandler.setLevel(Level.ALL);
        consoleHandler.setFormatter(new SimpleFormatter());
        logger.addHandler(consoleHandler);
    }
}

SDK yang tersedia