Skip to main content

Panduan Integrasi WebSocket

Topik ini menjelaskan proses interaksi, alamat endpoint, dan header permintaan untuk mengakses layanan sintesis suara real-time CosyVoice melalui koneksi WebSocket.

Titik akhir

API WebSocket menggunakan protokol wss://, dengan alamat berikut:
  • Singapura
  • China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceSaat memanggil, ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya.

SDK yang tersedia

Alibaba Cloud Model Studio telah merilis domain khusus workspace untuk wilayah China (Beijing) dan Singapura, yang memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan bermigrasi ke domain baru:
  • Wilayah China (Beijing): bermigrasi dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Wilayah Singapura: bermigrasi dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Header permintaan

Tambahkan informasi berikut ke header permintaan:
ParameterTipeWajibDeskripsi
AuthorizationstringYaToken otentikasi dengan format Bearer <your_api_key>. Ganti <your_api_key> dengan API Key Anda yang sebenarnya.
user-agentstringTidakIdentifikasi klien, yang membantu server melacak sumber permintaan.
X-DashScope-WorkSpacestringTidakAlibaba Cloud Model Studio Workspace ID.
X-DashScope-DataInspectionstringTidakApakah akan mengaktifkan fitur pemeriksaan kepatuhan data. Secara default, parameter ini tidak dikirim atau diatur ke enable. Jangan aktifkan kecuali diperlukan.
Otorisasi diverifikasi selama handshake WebSocket. Jika API Key tidak valid atau tidak disertakan, handshake akan gagal dan error HTTP 401/403 dikembalikan.

Alur kerja interaksi

image
Untuk penjelasan rinci mengenai event klien dan event server, lihat Event klien dan Event server. Secara kronologis, alur interaksi antara klien dan server adalah sebagai berikut:
  1. Bangun koneksi: Klien membangun koneksi WebSocket dengan server.
  2. Mulai tugas: Klien mengirim event run-task untuk memulai tugas.
  3. Tunggu konfirmasi: Klien menerima event task-started yang dikembalikan oleh server, yang menunjukkan bahwa tugas telah berhasil dimulai dan langkah selanjutnya dapat dilanjutkan.
  4. Kirim teks yang akan disintesis: Klien mengirim satu atau lebih event continue-task yang berisi teks yang akan disintesis ke server secara berurutan. Setelah menerima kalimat lengkap, server mengembalikan event result-generated dan aliran audio (panjang teks memiliki batasan; untuk detailnya, lihat penjelasan bidang text pada event continue-task).
    Anda dapat mengirim event continue-task beberapa kali untuk mengirimkan segmen teks secara berurutan. Setelah menerima segmen teks, server secara otomatis membaginya menjadi kalimat:
    • Kalimat lengkap langsung disintesis, dan klien menerima audio yang dikembalikan oleh server
    • Kalimat yang belum lengkap di-cache hingga menjadi lengkap sebelum disintesis; server tidak mengembalikan audio selama sebuah kalimat belum lengkap
    Saat event finish-task dikirim, server memaksa sintesis semua konten yang di-cache.
  5. Terima audio: Terima aliran audio melalui saluran binary
  6. Beri tahu server untuk mengakhiri tugas: Setelah semua teks dikirim, klien mengirim event finish-task untuk memberi tahu server bahwa tugas akan diakhiri, dan terus menerima aliran audio yang dikembalikan oleh server. Langkah ini tidak boleh dilewati; jika tidak, data audio mungkin tidak lengkap.
  7. Tugas berakhir: Klien menerima event task-finished yang dikembalikan oleh server, yang menunjukkan bahwa tugas telah berakhir.
  8. Tutup koneksi: Klien menutup koneksi WebSocket.
Untuk meningkatkan utilisasi resource, kami merekomendasikan menggunakan kembali satu koneksi WebSocket untuk menangani beberapa tugas, alih-alih membangun koneksi baru untuk setiap tugas.
Dalam tugas sintesis yang sama, event run-task, semua event continue-task, dan finish-task harus menggunakan task_id yang sama. Hasilkan task_id baru setiap kali Anda memulai tugas baru (misalnya, gunakan UUID). Penggunaan nilai task_id yang berbeda akan menyebabkan audio tidak berurutan atau kegagalan tugas.

Contoh kode

Contoh berikut menggunakan pustaka WebSocket umum untuk mengirim event protokol secara langsung, dengan model cosyvoice-v3-flash dan suara longanyang. Pertama, dapatkan API Key dan atur variabel lingkungan DASHSCOPE_API_KEY, lalu ganti {WorkspaceId} dengan workspace ID wilayah terkait; saat menggunakan wilayah lain, ganti juga alamat API dan API Key.
  • Java
  • Python
  • Go
  • C#
  • PHP
  • Node.js
Kami merekomendasikan menggunakan Java DashScope SDK untuk pengembangan. Untuk informasi lebih lanjut, lihat SDK Java CosyVoice.Berikut adalah contoh koneksi langsung WebSocket Java. Sebelum menjalankannya, impor dependensi berikut:
  • Java-WebSocket
  • jackson-databind
Kami merekomendasikan menggunakan Maven atau Gradle untuk mengelola dependensi. Konfigurasinya adalah sebagai berikut:
pom.xml
<dependencies>
    <!-- WebSocket Client -->
    <dependency>
        <groupId>org.java-websocket</groupId>
        <artifactId>Java-WebSocket</artifactId>
        <version>1.5.3</version>
    </dependency>

    <!-- JSON Processing -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.13.0</version>
    </dependency>
</dependencies>
Kode Java adalah sebagai berikut:
import com.fasterxml.jackson.databind.ObjectMapper;

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;

import java.io.FileOutputStream;
import java.io.IOException;
import java.net.URI;
import java.nio.ByteBuffer;
import java.util.*;

public class TTSWebSocketClient extends WebSocketClient {
    private final String taskId = UUID.randomUUID().toString();
    private final String outputFile = "output_" + System.currentTimeMillis() + ".mp3";
    private boolean taskFinished = false;

    public TTSWebSocketClient(URI serverUri, Map<String, String> headers) {
        super(serverUri, headers);
    }

    @Override
    public void onOpen(ServerHandshake serverHandshake) {
        System.out.println("连接成功");

        // 发送run-task事件
        // 如果enable_ssml设为true,只允许发送一次continue-task事件,否则会报错“Text request limit violated, expected 1.”
        String runTaskCommand = "{ \"header\": { \"action\": \"run-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"task_group\": \"audio\", \"task\": \"tts\", \"function\": \"SpeechSynthesizer\", \"model\": \"cosyvoice-v3-flash\", \"parameters\": { \"text_type\": \"PlainText\", \"voice\": \"longanyang\", \"format\": \"mp3\", \"sample_rate\": 22050, \"volume\": 50, \"rate\": 1, \"pitch\": 1, \"enable_ssml\": false }, \"input\": {} }}";
        send(runTaskCommand);
    }

    @Override
    public void onMessage(String message) {
        System.out.println("收到服务端返回的消息:" + message);
        try {
            // Parse JSON message
            Map<String, Object> messageMap = new ObjectMapper().readValue(message, Map.class);

            if (messageMap.containsKey("header")) {
                Map<String, Object> header = (Map<String, Object>) messageMap.get("header");

                if (header.containsKey("event")) {
                    String event = (String) header.get("event");

                    if ("task-started".equals(event)) {
                        System.out.println("收到服务端返回的task-started事件");

                        List<String> texts = Arrays.asList(
                                "床前明月光,疑是地上霜",
                                "举头望明月,低头思故乡"
                        );

                        for (String text : texts) {
                            // 发送continue-task事件
                            sendContinueTask(text);
                        }

                        // 发送finish-task事件
                        sendFinishTask();
                    } else if ("task-finished".equals(event)) {
                        System.out.println("收到服务端返回的task-finished事件");
                        taskFinished = true;
                        closeConnection();
                    } else if ("task-failed".equals(event)) {
                        System.out.println("任务失败:" + message);
                        closeConnection();
                    }
                }
            }
        } catch (Exception e) {
            System.err.println("出现异常:" + e.getMessage());
        }
    }

    @Override
    public void onMessage(ByteBuffer message) {
        System.out.println("收到的二进制音频数据大小为:" + message.remaining());

        try (FileOutputStream fos = new FileOutputStream(outputFile, true)) {
            byte[] buffer = new byte[message.remaining()];
            message.get(buffer);
            fos.write(buffer);
            System.out.println("音频数据已写入本地文件" + outputFile + "中");
        } catch (IOException e) {
            System.err.println("音频数据写入本地文件失败:" + e.getMessage());
        }
    }

    @Override
    public void onClose(int code, String reason, boolean remote) {
        System.out.println("连接关闭:" + reason + " (" + code + ")");
    }

    @Override
    public void onError(Exception ex) {
        System.err.println("报错:" + ex.getMessage());
        ex.printStackTrace();
    }

    private void sendContinueTask(String text) {
        String command = "{ \"header\": { \"action\": \"continue-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"input\": { \"text\": \"" + text + "\" } }}";
        send(command);
    }

    private void sendFinishTask() {
        String command = "{ \"header\": { \"action\": \"finish-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"input\": {} }}";
        send(command);
    }

    private void closeConnection() {
        if (!isClosed()) {
            close();
        }
    }

    public static void main(String[] args) {
        try {
            // 新加坡和北京地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key
            // 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:String apiKey = "sk-xxx"
            String apiKey = System.getenv("DASHSCOPE_API_KEY");
            if (apiKey == null || apiKey.isEmpty()) {
                System.err.println("请设置 DASHSCOPE_API_KEY 环境变量");
                return;
            }

            Map<String, String> headers = new HashMap<>();
            headers.put("Authorization", "bearer " + apiKey);
            // 以下为新加坡地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
            TTSWebSocketClient client = new TTSWebSocketClient(new URI("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference"), headers);

            client.connect();

            while (!client.isClosed() && !client.taskFinished) {
                Thread.sleep(1000);
            }
        } catch (Exception e) {
            System.err.println("连接WebSocket服务失败:" + e.getMessage());
            e.printStackTrace();
        }
    }
}