Skip to main content

Panduan akses WebSocket

Topik ini menjelaskan titik akhir API, header permintaan, dan alur interaksi untuk mengakses layanan pengenalan ucapan real-time Qwen-Audio-3.1-ASR-Flash-Message melalui koneksi WebSocket.

Titik akhir API

Titik akhir API WebSocket adalah sebagai berikut. Anda harus menggunakan protokol wss://:
  • Singapore
  • China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceSaat memanggil API, ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapore. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru berikut:
  • China (Beijing): dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Header permintaan

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 Kunci API Anda yang sebenarnya.

user-agent

string

Tidak

Identifier klien yang membantu server melacak sumber permintaan.

X-DashScope-WorkSpace

string

Tidak

ID ruang kerja Alibaba Cloud Model Studio.

X-DashScope-DataInspection

string

Tidak

Menentukan apakah pemeriksaan kepatuhan data diaktifkan. Secara default, parameter ini tidak dikirim atau diatur ke enable. Jangan aktifkan parameter ini kecuali diperlukan.

Authorization diverifikasi selama handshake WebSocket. Jika Kunci API tidak valid atau tidak ada, handshake gagal dan mengembalikan error HTTP 401 atau 403.

Alur interaksi

Untuk deskripsi mendetail tentang event klien dan event server, lihat Event klien dan Event server.
Urutan interaksi pengenalan ucapan WebSocket
Alur interaksi antara klien dan server secara kronologis adalah sebagai berikut:
  1. Membuat koneksi: Klien membuat koneksi WebSocket dengan server.
  2. Memulai task: Klien mengirim perintah run-task untuk memulai task dan menerima event task-started dari server, yang menandakan bahwa task telah berhasil dimulai dan Anda dapat melanjutkan ke langkah-langkah berikutnya.
  3. Mengirim aliran audio: Klien mulai mengirim audio biner (harus mono) dan secara terus-menerus menerima event result-generated dari server. Event ini berisi hasil pengenalan ucapan.
  4. Memberi tahu server untuk mengakhiri task: Klien mengirim perintah finish-task untuk memberi tahu server agar mengakhiri task dan terus menerima event result-generated dari server.
  5. Task selesai: Klien menerima event task-finished dari server, yang menandakan bahwa task telah selesai.
  6. Menutup koneksi: Klien menutup koneksi WebSocket.

Contoh pemanggilan

Contoh berikut menggunakan qwen-audio-3.1-asr-flash-message. Dapatkan API Key dan Base URL di konsol, lalu konfigurasikan variabel lingkungan DASHSCOPE_API_KEY dan DASHSCOPE_BASE_URL masing-masing. Unduh audio contoh dan simpan sebagai asr_example.wav. Audio tersebut adalah file WAV yang dikodekan dalam 16 kHz, mono, PCM 16-bit.
  • Java
  • Python
  • Go
  • Node.js
  • C#
  • PHP
Sebelum menjalankan contoh, instal 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.ByteBuffer;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.UUID;
import java.util.concurrent.atomic.AtomicBoolean;

public class FunASRRealtimeClient {

    private static final String API_KEY = System.getenv("DASHSCOPE_API_KEY");
    private static final String URL = "wss://" + URI.create(System.getenv("DASHSCOPE_BASE_URL")).getHost() + "/api-ws/v1/inference";
    private static final String AUDIO_FILE = "asr_example.wav"; // Replace with the path to your audio file
    private static final String MODEL = "qwen-audio-3.1-asr-flash-message";

    // Generate a 32-character random ID
    private static final String TASK_ID = UUID.randomUUID().toString().replace("-", "").substring(0, 32);

    private static final AtomicBoolean taskStarted = new AtomicBoolean(false);
    private static WebSocketClient client;

    public static void main(String[] args) throws Exception {
        client = new WebSocketClient(new URI(URL)) {
            @Override
            public void onOpen(ServerHandshake handshake) {
                System.out.println("Connected to server");
                sendRunTask();
            }

            @Override
            public void onMessage(String data) {
                JSONObject message = new JSONObject(data);
                String event = message.getJSONObject("header").getString("event");
                switch (event) {
                    case "task-started":
                        System.out.println("Task started");
                        taskStarted.set(true);
                        new Thread(FunASRRealtimeClient::sendAudioStream).start();
                        break;
                    case "result-generated":
                        JSONObject payload = message.getJSONObject("payload");
                        String text = payload.getJSONObject("output").getJSONObject("sentence").getString("text");
                        System.out.println("Recognition result: " + text);
                        if (payload.has("usage")) {
                            System.out.println("Audio duration (seconds): " + payload.getJSONObject("usage").get("duration"));
                        }
                        break;
                    case "task-finished":
                        System.out.println("Task finished");
                        close();
                        break;
                    case "task-failed":
                        String errMsg = message.getJSONObject("header").optString("error_message");
                        System.err.println("Task failed: " + errMsg);
                        close();
                        break;
                    default:
                        System.out.println("Unknown event: " + event);
                }
            }

            @Override
            public void onClose(int code, String reason, boolean remote) {
                if (!taskStarted.get()) {
                    System.err.println("Task not started, closing connection");
                }
            }

            @Override
            public void onError(Exception ex) {
                System.err.println("WebSocket error: " + ex.getMessage());
            }
        };
        client.addHeader("Authorization", "bearer " + API_KEY);
        client.connectBlocking();
    }

    // Send the run-task instruction
    private static void sendRunTask() {
        JSONObject runTask = new JSONObject()
                .put("header", new JSONObject()
                        .put("action", "run-task")
                        .put("task_id", TASK_ID)
                        .put("streaming", "duplex"))
                .put("payload", new JSONObject()
                        .put("task_group", "audio")
                        .put("task", "asr")
                        .put("function", "recognition")
                        .put("model", MODEL)
                        .put("parameters", new JSONObject()
                                .put("sample_rate", 16000)
                                .put("format", "wav"))
                        .put("input", new JSONObject()));
        client.send(runTask.toString());
    }

    // Send the audio stream (send one binary chunk every 100ms)
    private static void sendAudioStream() {
        int chunkSize = 3200; // 100ms @ 16kHz 16bit mono
        try {
            byte[] audio = Files.readAllBytes(Paths.get(AUDIO_FILE));
            int offset = 0;
            while (offset < audio.length) {
                int end = Math.min(offset + chunkSize, audio.length);
                byte[] chunk = new byte[end - offset];
                System.arraycopy(audio, offset, chunk, 0, end - offset);
                client.send(ByteBuffer.wrap(chunk));
                offset = end;
                Thread.sleep(100);
            }
            System.out.println("Audio stream ended");
            sendFinishTask();
        } catch (Exception e) {
            System.err.println("Error reading audio file: " + e.getMessage());
            client.close();
        }
    }

    // Send the finish-task instruction
    private static void sendFinishTask() {
        JSONObject finishTask = new JSONObject()
                .put("header", new JSONObject()
                        .put("action", "finish-task")
                        .put("task_id", TASK_ID)
                        .put("streaming", "duplex"))
                .put("payload", new JSONObject()
                        .put("input", new JSONObject()));
        client.send(finishTask.toString());
    }
}

SDK yang tersedia