Skip to main content

Panduan akses WebSocket

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

Titik akhir

URL WebSocket bersifat tetap:
  • Singapore
  • China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceGanti {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:
ParameterTypeRequiredDescription
AuthorizationstringYesToken autentikasi dalam format Bearer <your_api_key>. Ganti <your_api_key> dengan Kunci API Anda yang sebenarnya.
user-agentstringNoIdentifier client yang membantu server melacak sumber permintaan.
X-DashScope-WorkSpacestringNoAlibaba Cloud Model Studio ID ruang kerja.
X-DashScope-DataInspectionstringNoApakah inspeksi kepatuhan data diaktifkan. Parameter ini secara default diabaikan 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 client dan event server, lihat Event client dan Event server.
Diagram urutan interaksi pengenalan ucapan WebSocket
Secara kronologis, alur interaksi antara client dan server adalah sebagai berikut:
  1. Membuat koneksi: Client membuat koneksi WebSocket ke server.
  2. Memulai task: Client mengirim instruksi run-task untuk memulai task dan menerima event task-started dari server. Event ini mengonfirmasi bahwa task telah dimulai dan Anda dapat melanjutkan ke langkah berikutnya.
  3. Mengirim aliran audio: Client mulai mengirim audio biner (harus mono) dan secara bersamaan menerima aliran event result-generated dari server. Setiap event berisi hasil pengenalan ucapan.
  4. Memberi tahu server untuk mengakhiri task: Client mengirim instruksi finish-task untuk memberi sinyal ke server agar mengakhiri task dan terus menerima event result-generated dari server.
  5. Mengakhiri task: Client menerima event task-finished dari server, yang menandakan bahwa task telah berakhir.
  6. Menutup koneksi: Client menutup koneksi WebSocket.

Contoh

Contoh berikut menggunakan qwen-audio-3.1-asr-flash-streaming. Dapatkan API Key dan Base URL di konsol, lalu atur masing-masing sebagai variabel lingkungan DASHSCOPE_API_KEY dan DASHSCOPE_BASE_URL. Unduh audio contoh dan simpan sebagai asr_example.wav. Audio tersebut merupakan file WAV dengan pengodean 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-streaming";

    // 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