Alibaba Cloud Model Studio:Sintesis suara real-time

Go

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"strings"
	"time"

	"github.com/google/uuid"
	"github.com/gorilla/websocket"
)

const (
	// Berikut ini adalah konfigurasi untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Konfigurasi bervariasi berdasarkan wilayah.
	wsURL      = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference"
	outputFile = "output.mp3"
)

func main() {
	// API Key berbeda antara wilayah Singapura dan Beijing. Dapatkan API Key Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
	// Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan API Key Model Studio China Anda: apiKey := "sk-xxx"
	apiKey := os.Getenv("DASHSCOPE_API_KEY")

	// Hapus file output
	os.Remove(outputFile)
	os.Create(outputFile)

	// Hubungkan ke WebSocket
	header := make(http.Header)
	header.Add("X-DashScope-DataInspection", "enable")
	header.Add("Authorization", fmt.Sprintf("bearer %s", apiKey))

	conn, resp, err := websocket.DefaultDialer.Dial(wsURL, header)
	if err != nil {
		if resp != nil {
			fmt.Printf("Koneksi gagal, kode status HTTP: %d\n", resp.StatusCode)
		}
		fmt.Println("Koneksi gagal:", err)
		return
	}
	defer conn.Close()

	// Hasilkan ID tugas
	taskID := uuid.New().String()
	fmt.Printf("ID tugas yang dihasilkan: %s\n", taskID)

	// Mengirim event run-task
	runTaskCmd := map[string]interface{}{
		"header": map[string]interface{}{
			"action":    "run-task",
			"task_id":   taskID,
			"streaming": "duplex",
		},
		"payload": map[string]interface{}{
			"task_group": "audio",
			"task":       "tts",
			"function":   "SpeechSynthesizer",
			"model":      "qwen-audio-3.0-tts-flash",
			"parameters": map[string]interface{}{
				"text_type":   "PlainText",
				"voice":       "longanhuan_v3.6",
				"format":      "mp3",
				"sample_rate": 22050,
				"volume":      50,
				"rate":        1,
				"pitch":       1,
				// Jika enable_ssml diatur ke true, hanya satu event continue-task yang dapat dikirim; jika tidak, error "Text request limit violated, expected 1." akan dikembalikan
				"enable_ssml": false,
			},
			"input": map[string]interface{}{},
		},
	}

	runTaskJSON, _ := json.Marshal(runTaskCmd)
	fmt.Printf("Mengirim event run-task: %s\n", string(runTaskJSON))

	err = conn.WriteMessage(websocket.TextMessage, runTaskJSON)
	if err != nil {
		fmt.Println("Gagal mengirim run-task:", err)
		return
	}

	textSent := false

	// Proses pesan
	for {
		messageType, message, err := conn.ReadMessage()
		if err != nil {
			fmt.Println("Gagal membaca pesan:", err)
			break
		}

		// Proses pesan biner
		if messageType == websocket.BinaryMessage {
			fmt.Printf("Menerima pesan biner, panjang: %d\n", len(message))
			file, _ := os.OpenFile(outputFile, os.O_APPEND|os.O_WRONLY|os.O_CREATE, 0644)
			file.Write(message)
			file.Close()
			continue
		}

		// Proses pesan teks
		messageStr := string(message)
		fmt.Printf("Menerima pesan teks: %s\n", strings.ReplaceAll(messageStr, "\n", ""))

		// Uraikan JSON untuk mendapatkan jenis event
		var msgMap map[string]interface{}
		if json.Unmarshal(message, &msgMap) == nil {
			if header, ok := msgMap["header"].(map[string]interface{}); ok {
				if event, ok := header["event"].(string); ok {
					fmt.Printf("Jenis event: %s\n", event)

					switch event {
					case "task-started":
						fmt.Println("=== Menerima event task-started ===")

						if !textSent {
							// Mengirim event continue-task

							texts := []string{"Before my bed, moonlight shines bright, I suspect it's frost upon the ground.", "I raise my eyes to gaze at the bright moon, then bow my head, thinking of home."}

							for _, text := range texts {
								continueTaskCmd := map[string]interface{}{
									"header": map[string]interface{}{
										"action":    "continue-task",
										"task_id":   taskID,
										"streaming": "duplex",
									},
									"payload": map[string]interface{}{
										"input": map[string]interface{}{
											"text": text,
										},
									},
								}

								continueTaskJSON, _ := json.Marshal(continueTaskCmd)
								fmt.Printf("Mengirim event continue-task: %s\n", string(continueTaskJSON))

								err = conn.WriteMessage(websocket.TextMessage, continueTaskJSON)
								if err != nil {
									fmt.Println("Gagal mengirim continue-task:", err)
									return
								}
							}

							textSent = true

							// Tunda sebelum mengirim finish-task
							time.Sleep(500 * time.Millisecond)

							// Mengirim event finish-task
							finishTaskCmd := map[string]interface{}{
								"header": map[string]interface{}{
									"action":    "finish-task",
									"task_id":   taskID,
									"streaming": "duplex",
								},
								"payload": map[string]interface{}{
									"input": map[string]interface{}{},
								},
							}

							finishTaskJSON, _ := json.Marshal(finishTaskCmd)
							fmt.Printf("Mengirim event finish-task: %s\n", string(finishTaskJSON))

							err = conn.WriteMessage(websocket.TextMessage, finishTaskJSON)
							if err != nil {
								fmt.Println("Gagal mengirim finish-task:", err)
								return
							}
						}

					case "task-finished":
						fmt.Println("=== Tugas selesai ===")
						return

					case "task-failed":
						fmt.Println("=== Tugas gagal ===")
						if header["error_message"] != nil {
							fmt.Printf("Pesan error: %s\n", header["error_message"])
						}
						return

					case "result-generated":
						fmt.Println("Menerima event result-generated")
					}
				}
			}
		}
	}
}

C#

using System.Net.WebSockets;
using System.Text;
using System.Text.Json;

class Program {
    // API Key berbeda antara wilayah Singapura dan Beijing. Dapatkan API Key Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan API Key Model Studio China Anda: private static readonly string ApiKey = "sk-xxx"
    private static readonly string ApiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY") ?? throw new InvalidOperationException("Variabel lingkungan DASHSCOPE_API_KEY belum diatur.");

    // Berikut ini adalah konfigurasi untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Konfigurasi bervariasi berdasarkan wilayah.
    private const string WebSocketUrl = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference";
    // Jalur file output
    private const string OutputFilePath = "output.mp3";

    // Klien WebSocket
    private static ClientWebSocket _webSocket = new ClientWebSocket();
    // Sumber token pembatalan
    private static CancellationTokenSource _cancellationTokenSource = new CancellationTokenSource();
    // ID tugas
    private static string? _taskId;
    // Apakah tugas telah dimulai
    private static TaskCompletionSource<bool> _taskStartedTcs = new TaskCompletionSource<bool>();

    static async Task Main(string[] args) {
        try {
            // Hapus file output
            ClearOutputFile(OutputFilePath);

            // Hubungkan ke layanan WebSocket
            await ConnectToWebSocketAsync(WebSocketUrl);

            // Mulai tugas penerima pesan
            Task receiveTask = ReceiveMessagesAsync();

            // Kirim event run-task
            _taskId = GenerateTaskId();
            await SendRunTaskCommandAsync(_taskId);

            // Tunggu event task-started
            await _taskStartedTcs.Task;

            // Kirim event continue-task
            string[] texts = {
                "Before my bed, moonlight shines bright,",
                "I suspect it\'s frost upon the ground.",
                "I raise my eyes to gaze at the bright moon,",
                "then bow my head, thinking of home."
            };
            foreach (string text in texts) {
                await SendContinueTaskCommandAsync(text);
            }

            // Kirim event finish-task
            await SendFinishTaskCommandAsync(_taskId);

            // Tunggu tugas penerima selesai
            await receiveTask;

            Console.WriteLine("Tugas selesai, koneksi ditutup.");
        } catch (OperationCanceledException) {
            Console.WriteLine("Tugas dibatalkan.");
        } catch (Exception ex) {
            Console.WriteLine($"Terjadi error: {ex.Message}");
        } finally {
            _cancellationTokenSource.Cancel();
            _webSocket.Dispose();
        }
    }

    private static void ClearOutputFile(string filePath) {
        if (File.Exists(filePath)) {
            File.WriteAllText(filePath, string.Empty);
            Console.WriteLine("File output dihapus.");
        } else {
            Console.WriteLine("File output tidak ada, tidak perlu dihapus.");
        }
    }

    private static async Task ConnectToWebSocketAsync(string url) {
        var uri = new Uri(url);
        if (_webSocket.State == WebSocketState.Connecting || _webSocket.State == WebSocketState.Open) {
            return;
        }

        // Atur header koneksi WebSocket
        _webSocket.Options.SetRequestHeader("Authorization", $"bearer {ApiKey}");
        _webSocket.Options.SetRequestHeader("X-DashScope-DataInspection", "enable");

        try {
            await _webSocket.ConnectAsync(uri, _cancellationTokenSource.Token);
            Console.WriteLine("Berhasil terhubung ke layanan WebSocket.");
        } catch (OperationCanceledException) {
            Console.WriteLine("Koneksi WebSocket dibatalkan.");
        } catch (Exception ex) {
            Console.WriteLine($"Koneksi WebSocket gagal: {ex.Message}");
            throw;
        }
    }

    private static async Task SendRunTaskCommandAsync(string taskId) {
        var command = CreateCommand("run-task", taskId, "duplex", new {
            task_group = "audio",
            task = "tts",
            function = "SpeechSynthesizer",
            model = "qwen-audio-3.0-tts-flash",
            parameters = new
            {
                text_type = "PlainText",
                voice = "longanhuan_v3.6",
                format = "mp3",
                sample_rate = 22050,
                volume = 50,
                rate = 1,
                pitch = 1,
                // Jika enable_ssml diatur ke true, hanya satu event continue-task yang dapat dikirim; jika tidak, error "Text request limit violated, expected 1." akan dikembalikan
                enable_ssml = false
            },
            input = new { }
        });

        await SendJsonMessageAsync(command);
        Console.WriteLine("Event run-task dikirim.");
    }

    private static async Task SendContinueTaskCommandAsync(string text) {
        if (_taskId == null) {
            throw new InvalidOperationException("ID tugas belum diinisialisasi.");
        }

        var command = CreateCommand("continue-task", _taskId, "duplex", new {
            input = new {
                text
            }
        });

        await SendJsonMessageAsync(command);
        Console.WriteLine("Event continue-task dikirim.");
    }

    private static async Task SendFinishTaskCommandAsync(string taskId) {
        var command = CreateCommand("finish-task", taskId, "duplex", new {
            input = new { }
        });

        await SendJsonMessageAsync(command);
        Console.WriteLine("Event finish-task dikirim.");
    }

    private static async Task SendJsonMessageAsync(string message) {
        var buffer = Encoding.UTF8.GetBytes(message);
        try {
            await _webSocket.SendAsync(new ArraySegment<byte>(buffer), WebSocketMessageType.Text, true, _cancellationTokenSource.Token);
        } catch (OperationCanceledException) {
            Console.WriteLine("Pengiriman pesan dibatalkan.");
        }
    }

    private static async Task ReceiveMessagesAsync() {
        while (_webSocket.State == WebSocketState.Open) {
            var response = await ReceiveMessageAsync();
            if (response != null) {
                var eventStr = response.RootElement.GetProperty("header").GetProperty("event").GetString();
                switch (eventStr) {
                    case "task-started":
                        Console.WriteLine("Tugas dimulai.");
                        _taskStartedTcs.TrySetResult(true);
                        break;
                    case "task-finished":
                        Console.WriteLine("Tugas selesai.");
                        _cancellationTokenSource.Cancel();
                        break;
                    case "task-failed":
                        Console.WriteLine("Tugas gagal: " + response.RootElement.GetProperty("header").GetProperty("error_message").GetString());
                        _cancellationTokenSource.Cancel();
                        break;
                    default:
                        // result-generated dapat ditangani di sini
                        break;
                }
            }
        }
    }

    private static async Task<JsonDocument?> ReceiveMessageAsync() {
        var buffer = new byte[1024 * 4];
        var segment = new ArraySegment<byte>(buffer);

        try {
            WebSocketReceiveResult result = await _webSocket.ReceiveAsync(segment, _cancellationTokenSource.Token);

            if (result.MessageType == WebSocketMessageType.Close) {
                await _webSocket.CloseAsync(WebSocketCloseStatus.NormalClosure, "Closing", _cancellationTokenSource.Token);
                return null;
            }

            if (result.MessageType == WebSocketMessageType.Binary) {
                // Proses data biner
                Console.WriteLine("Menerima data biner...");

                // Simpan data biner ke file
                using (var fileStream = new FileStream(OutputFilePath, FileMode.Append)) {
                    fileStream.Write(buffer, 0, result.Count);
                }

                return null;
            }

            string message = Encoding.UTF8.GetString(buffer, 0, result.Count);
            return JsonDocument.Parse(message);
        } catch (OperationCanceledException) {
            Console.WriteLine("Penerimaan pesan dibatalkan.");
            return null;
        }
    }

    private static string GenerateTaskId() {
        return Guid.NewGuid().ToString("N").Substring(0, 32);
    }

    private static string CreateCommand(string action, string taskId, string streaming, object payload) {
        var command = new {
            header = new {
                action,
                task_id = taskId,
                streaming
            },
            payload
        };

        return JsonSerializer.Serialize(command);
    }
}

PHP

Struktur direktori kode contoh:

my-php-project/

├── composer.json

├── vendor/

└── index.php

Isi composer.json (sesuaikan versi dependensi sesuai kebutuhan):

{
    "require": {
        "react/event-loop": "^1.3",
        "react/socket": "^1.11",
        "react/stream": "^1.2",
        "react/http": "^1.1",
        "ratchet/pawl": "^0.4"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Isi index.php:

<?php

require __DIR__ . '/vendor/autoload.php';

use Ratchet\Client\Connector;
use React\EventLoop\Loop;
use React\Socket\Connector as SocketConnector;

// API Key berbeda antara wilayah Singapura dan Beijing. Dapatkan API Key Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan API Key Model Studio China Anda: $api_key = "sk-xxx"
$api_key = getenv("DASHSCOPE_API_KEY");
// Berikut ini adalah konfigurasi untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Konfigurasi bervariasi berdasarkan wilayah.
$websocket_url = 'wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'; // URL server WebSocket
$output_file = 'output.mp3'; // Jalur file output

$loop = Loop::get();

if (file_exists($output_file)) {
    // Hapus isi file
    file_put_contents($output_file, '');
}

// Buat konektor kustom
$socketConnector = new SocketConnector($loop, [
    'tcp' => [
        'bindto' => '0.0.0.0:0',
    ],
    'tls' => [
        'verify_peer' => false,
        'verify_peer_name' => false,
    ],
]);

$connector = new Connector($loop, $socketConnector);

$headers = [
    'Authorization' => 'bearer ' . $api_key,
    'X-DashScope-DataInspection' => 'enable'
];

$connector($websocket_url, [], $headers)->then(function ($conn) use ($loop, $output_file) {
    echo "Terhubung ke server WebSocket\n";

    // Hasilkan ID tugas
    $taskId = generateTaskId();

    // Kirim event run-task
    sendRunTaskMessage($conn, $taskId);

    // Definisikan fungsi untuk mengirim event continue-task
    $sendContinueTask = function() use ($conn, $loop, $taskId) {
        // Teks yang akan dikirim
        $texts = ["Before my bed, moonlight shines bright,", "I suspect it\'s frost upon the ground.", "I raise my eyes to gaze at the bright moon,", "then bow my head, thinking of home."];
        $continueTaskCount = 0;
        foreach ($texts as $text) {
            $continueTaskMessage = json_encode([
                "header" => [
                    "action" => "continue-task",
                    "task_id" => $taskId,
                    "streaming" => "duplex"
                ],
                "payload" => [
                    "input" => [
                        "text" => $text
                    ]
                ]
            ]);
            echo "Mengirim event continue-task: " . $continueTaskMessage . "\n";
            $conn->send($continueTaskMessage);
            $continueTaskCount++;
        }
        echo "Jumlah event continue-task yang dikirim: " . $continueTaskCount . "\n";

        // Kirim event finish-task
        sendFinishTaskMessage($conn, $taskId);
    };

    // Bendera apakah event task-started telah diterima
    $taskStarted = false;

    // Dengarkan pesan
    $conn->on('message', function($msg) use ($conn, $sendContinueTask, $loop, &$taskStarted, $taskId, $output_file) {
        if ($msg->isBinary()) {
            // Tulis data biner ke file lokal
            file_put_contents($output_file, $msg->getPayload(), FILE_APPEND);
        } else {
            // Proses pesan non-biner
            $response = json_decode($msg, true);

            if (isset($response['header']['event'])) {
                handleEvent($conn, $response, $sendContinueTask, $loop, $taskId, $taskStarted);
            } else {
                echo "Format pesan tidak dikenal\n";
            }
        }
    });

    // Dengarkan penutupan koneksi
    $conn->on('close', function($code = null, $reason = null) {
        echo "Koneksi ditutup\n";
        if ($code !== null) {
            echo "Kode penutupan: " . $code . "\n";
        }
        if ($reason !== null) {
            echo "Alasan penutupan: " . $reason . "\n";
        }
    });
}, function ($e) {
    echo "Gagal terhubung: {$e->getMessage()}\n";
});

$loop->run();

/**
 * Hasilkan ID tugas
 * @return string
 */
function generateTaskId(): string {
    return bin2hex(random_bytes(16));
}

/**
 * Kirim event run-task
 * @param $conn
 * @param $taskId
 */
function sendRunTaskMessage($conn, $taskId) {
    $runTaskMessage = json_encode([
        "header" => [
            "action" => "run-task",
            "task_id" => $taskId,
            "streaming" => "duplex"
        ],
        "payload" => [
            "task_group" => "audio",
            "task" => "tts",
            "function" => "SpeechSynthesizer",
            "model" => "qwen-audio-3.0-tts-flash",
            "parameters" => [
                "text_type" => "PlainText",
                "voice" => "longanhuan_v3.6",
                "format" => "mp3",
                "sample_rate" => 22050,
                "volume" => 50,
                "rate" => 1,
                "pitch" => 1,
                // Jika enable_ssml diatur ke true, hanya satu event continue-task yang dapat dikirim; jika tidak, error "Text request limit violated, expected 1." akan dikembalikan
                "enable_ssml" => false
            ],
            "input" => (object) []
        ]
    ]);
    echo "Mengirim event run-task: " . $runTaskMessage . "\n";
    $conn->send($runTaskMessage);
    echo "Event run-task dikirim\n";
}

/**
 * Baca file audio
 * @param string $filePath
 * @return bool|string
 */
function readAudioFile(string $filePath) {
    $voiceData = file_get_contents($filePath);
    if ($voiceData === false) {
        echo "Gagal membaca file audio\n";
    }
    return $voiceData;
}

/**
 * Pisahkan data audio
 * @param string $data
 * @param int $chunkSize
 * @return array
 */
function splitAudioData(string $data, int $chunkSize): array {
    return str_split($data, $chunkSize);
}

/**
 * Kirim event finish-task
 * @param $conn
 * @param $taskId
 */
function sendFinishTaskMessage($conn, $taskId) {
    $finishTaskMessage = json_encode([
        "header" => [
            "action" => "finish-task",
            "task_id" => $taskId,
            "streaming" => "duplex"
        ],
        "payload" => [
            "input" => (object) []
        ]
    ]);
    echo "Mengirim event finish-task: " . $finishTaskMessage . "\n";
    $conn->send($finishTaskMessage);
    echo "Event finish-task dikirim\n";
}

/**
 * Tangani event
 * @param $conn
 * @param $response
 * @param $sendContinueTask
 * @param $loop
 * @param $taskId
 * @param $taskStarted
 */
function handleEvent($conn, $response, $sendContinueTask, $loop, $taskId, &$taskStarted) {
    switch ($response['header']['event']) {
        case 'task-started':
            echo "Tugas dimulai, mengirim event continue-task...\n";
            $taskStarted = true;
            // Kirim event continue-task
            $sendContinueTask();
            break;
        case 'result-generated':
            // Menerima event result-generated
            break;
        case 'task-finished':
            echo "Tugas selesai\n";
            $conn->close();
            break;
        case 'task-failed':
            echo "Tugas gagal\n";
            echo "Kode error: " . $response['header']['error_code'] . "\n";
            echo "Pesan error: " . $response['header']['error_message'] . "\n";
            $conn->close();
            break;
        case 'error':
            echo "Error: " . $response['payload']['message'] . "\n";
            break;
        default:
            echo "Event tidak dikenal: " . $response['header']['event'] . "\n";
            break;
    }

    // Jika tugas selesai, tutup koneksi
    if ($response['header']['event'] == 'task-finished') {
        // Tunggu 1 detik untuk memastikan semua data telah dikirim
        $loop->addTimer(1, function() use ($conn) {
            $conn->close();
            echo "Klien menutup koneksi\n";
        });
    }

    // Jika event task-started belum diterima, tutup koneksi
    if (!$taskStarted && in_array($response['header']['event'], ['task-failed', 'error'])) {
        $conn->close();
    }
}

Node.js

Instal dependensi yang diperlukan:

npm install ws
npm install uuid

Kode contoh:

const WebSocket = require('ws');
const fs = require('fs');
const uuid = require('uuid').v4;

// API Key berbeda antara wilayah Singapura dan Beijing. Dapatkan API Key Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan API Key Model Studio China Anda: const apiKey = "sk-xxx"
const apiKey = process.env.DASHSCOPE_API_KEY;
// Berikut ini adalah konfigurasi untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Konfigurasi bervariasi berdasarkan wilayah.
const url = 'wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference';
// Jalur file output
const outputFilePath = 'output.mp3';

// Hapus file output
fs.writeFileSync(outputFilePath, '');

// Buat klien WebSocket
const ws = new WebSocket(url, {
  headers: {
    Authorization: `bearer ${apiKey}`,
    'X-DashScope-DataInspection': 'enable'
  }
});

let taskStarted = false;
let taskId = uuid();

ws.on('open', () => {
  console.log('Terhubung ke server WebSocket');

  // Kirim event run-task
  const runTaskMessage = JSON.stringify({
    header: {
      action: 'run-task',
      task_id: taskId,
      streaming: 'duplex'
    },
    payload: {
      task_group: 'audio',
      task: 'tts',
      function: 'SpeechSynthesizer',
      model: 'qwen-audio-3.0-tts-flash',
      parameters: {
        text_type: 'PlainText',
        voice: 'longanhuan_v3.6', // Suara
        format: 'mp3', // Format audio
        sample_rate: 22050, // Laju sampel
        volume: 50, // Volume
        rate: 1, // Laju bicara
        pitch: 1, // Pitch
        enable_ssml: false // Apakah SSML diaktifkan. Jika enable_ssml diatur ke true, hanya satu event continue-task yang dapat dikirim; jika tidak, error "Text request limit violated, expected 1." akan dikembalikan
      },
      input: {}
    }
  });
  ws.send(runTaskMessage);
  console.log('Pesan run-task dikirim');
});

const fileStream = fs.createWriteStream(outputFilePath, { flags: 'a' });
ws.on('message', (data, isBinary) => {
  if (isBinary) {
    // Tulis data biner ke file
    fileStream.write(data);
  } else {
    const message = JSON.parse(data);

    switch (message.header.event) {
      case 'task-started':
        taskStarted = true;
        console.log('Tugas dimulai');
        // Kirim event continue-task
        sendContinueTasks(ws);
        break;
      case 'task-finished':
        console.log('Tugas selesai');
        ws.close();
        fileStream.end(() => {
          console.log('Aliran file ditutup');
        });
        break;
      case 'task-failed':
        console.error('Tugas gagal: ', message.header.error_message);
        ws.close();
        fileStream.end(() => {
          console.log('Aliran file ditutup');
        });
        break;
      default:
        // result-generated dapat ditangani di sini
        break;
    }
  }
});

function sendContinueTasks(ws) {
  const texts = [
    'Before my bed, moonlight shines bright,',
    'I suspect it is frost upon the ground.',
    'I raise my eyes to gaze at the bright moon,',
    'then bow my head, thinking of home.'
  ];

  texts.forEach((text, index) => {
    setTimeout(() => {
      if (taskStarted) {
        const continueTaskMessage = JSON.stringify({
          header: {
            action: 'continue-task',
            task_id: taskId,
            streaming: 'duplex'
          },
          payload: {
            input: {
              text: text
            }
          }
        });
        ws.send(continueTaskMessage);
        console.log(`continue-task dikirim, teks: ${text}`);
      }
    }, index * 1000); // Kirim satu per detik
  });

  // Kirim event finish-task
  setTimeout(() => {
    if (taskStarted) {
      const finishTaskMessage = JSON.stringify({
        header: {
          action: 'finish-task',
          task_id: taskId,
          streaming: 'duplex'
        },
        payload: {
          input: {}
        }
      });
      ws.send(finishTaskMessage);
      console.log('finish-task dikirim');
    }
  }, texts.length * 1000 + 1000); // Kirim 1 detik setelah semua event continue-task dikirim
}

ws.on('close', () => {
  console.log('Terputus dari server WebSocket');
});

Java

Kami merekomendasikan penggunaan SDK Java DashScope untuk pengembangan. Lihat SDK Java.

Berikut adalah contoh koneksi langsung WebSocket Java. Impor dependensi berikut sebelum menjalankan:

• Java-WebSocket
• jackson-databind

Gunakan Maven atau Gradle untuk mengelola dependensi:

<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 lainnya dihilangkan
dependencies {
  // WebSocket Client
  implementation 'org.java-websocket:Java-WebSocket:1.5.3'
  // JSON Processing
  implementation 'com.fasterxml.jackson.core:jackson-databind:2.13.0'
}
// Kode lainnya dihilangkan

Kode Java:

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("Koneksi berhasil");

        // Kirim event run-task
        // Jika enable_ssml diatur ke true, hanya satu event continue-task yang dapat dikirim; jika tidak, error "Text request limit violated, expected 1." akan dikembalikan
        String runTaskCommand = "{ \"header\": { \"action\": \"run-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"task_group\": \"audio\", \"task\": \"tts\", \"function\": \"SpeechSynthesizer\", \"model\": \"qwen-audio-3.0-tts-flash\", \"parameters\": { \"text_type\": \"PlainText\", \"voice\": \"longanhuan_v3.6\", \"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("Menerima pesan dari server: " + message);
        try {
            // Uraikan pesan JSON
            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("Menerima event task-started dari server");

                        List<String> texts = Arrays.asList(
                                "Before my bed, moonlight shines bright,I suspect it\'s frost upon the ground.",
                                "I raise my eyes to gaze at the bright moon,then bow my head, thinking of home."
                        );

                        for (String text : texts) {
                            // Kirim event continue-task
                            sendContinueTask(text);
                        }

                        // Kirim event finish-task
                        sendFinishTask();
                    } else if ("task-finished".equals(event)) {
                        System.out.println("Menerima event task-finished dari server");
                        taskFinished = true;
                        closeConnection();
                    } else if ("task-failed".equals(event)) {
                        System.out.println("Tugas gagal: " + message);
                        closeConnection();
                    }
                }
            }
        } catch (Exception e) {
            System.err.println("Terjadi exception: " + e.getMessage());
        }
    }

    @Override
    public void onMessage(ByteBuffer message) {
        System.out.println("Menerima data audio biner ukuran: " + message.remaining());

        try (FileOutputStream fos = new FileOutputStream(outputFile, true)) {
            byte[] buffer = new byte[message.remaining()];
            message.get(buffer);
            fos.write(buffer);
            System.out.println("Data audio ditulis ke file lokal " + outputFile);
        } catch (IOException e) {
            System.err.println("Gagal menulis data audio ke file lokal: " + e.getMessage());
        }
    }

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

    @Override
    public void onError(Exception ex) {
        System.err.println("Error: " + 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 berbeda antara wilayah Singapura dan Beijing. Dapatkan API Key Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
            // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan API Key Model Studio China Anda: String apiKey = "sk-xxx"
            String apiKey = System.getenv("DASHSCOPE_API_KEY");
            if (apiKey == null || apiKey.isEmpty()) {
                System.err.println("Harap atur variabel lingkungan DASHSCOPE_API_KEY");
                return;
            }

            Map<String, String> headers = new HashMap<>();
            headers.put("Authorization", "bearer " + apiKey);
            // Berikut ini adalah konfigurasi untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Konfigurasi bervariasi berdasarkan wilayah.
            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("Gagal terhubung ke layanan WebSocket: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Python

Kami merekomendasikan penggunaan SDK Python DashScope untuk pengembangan. Lihat SDK Python.

Berikut adalah contoh koneksi langsung WebSocket Python. Instal dependensi berikut sebelum menjalankan:

pip uninstall websocket-client
pip uninstall websocket
pip install websocket-client

import websocket
import json
import uuid
import os
import time

class TTSClient:
    def __init__(self, api_key, uri):
        """
    Inisialisasi instans TTSClient

    Parameter:
        api_key (str): Kunci API untuk otentikasi
        uri (str): URL layanan WebSocket
    """
        self.api_key = api_key  # Ganti dengan Kunci API Anda
        self.uri = uri  # Ganti dengan URL WebSocket Anda
        self.task_id = str(uuid.uuid4())  # Hasilkan ID tugas unik
        self.output_file = f"output_{int(time.time())}.mp3"  # Jalur file audio keluaran
        self.ws = None  # Instans WebSocketApp
        self.task_started = False  # Apakah task-started telah diterima
        self.task_finished = False  # Apakah task-finished / task-failed telah diterima

    def on_open(self, ws):
        """
    Callback ketika koneksi WebSocket terbentuk
    Mengirim event run-task untuk memulai tugas sintesis suara
    """
        print("WebSocket connected")

        # Buat event run-task
        run_task_cmd = {
            "header": {
                "action": "run-task",
                "task_id": self.task_id,
                "streaming": "duplex"
            },
            "payload": {
                "task_group": "audio",
                "task": "tts",
                "function": "SpeechSynthesizer",
                "model": "qwen-audio-3.0-tts-flash",
                "parameters": {
                    "text_type": "PlainText",
                    "voice": "longanhuan_v3.6",
                    "format": "mp3",
                    "sample_rate": 22050,
                    "volume": 50,
                    "rate": 1,
                    "pitch": 1,
                    # Jika enable_ssml diatur ke true, hanya satu event continue-task yang dapat dikirim; jika tidak, kesalahan akan dikembalikan
                    "enable_ssml": False
                },
                "input": {}
            }
        }

        # Kirim event run-task
        ws.send(json.dumps(run_task_cmd))
        print("Sent run-task event")

    def on_message(self, ws, message):
        """
    Callback ketika pesan diterima
    Menangani pesan teks dan biner secara berbeda
    """
        if isinstance(message, str):
            # Tangani pesan teks JSON
            try:
                msg_json = json.loads(message)
                print(f"Received JSON message: {msg_json}")

                if "header" in msg_json:
                    header = msg_json["header"]

                    if "event" in header:
                        event = header["event"]

                        if event == "task-started":
                            print("Task started")
                            self.task_started = True

                            # Kirim event continue-task
                            texts = [
                                "Before my bed, moonlight shines bright,I suspect it\'s frost upon the ground.",
                                "I raise my eyes to gaze at the bright moon,then bow my head, thinking of home."
                            ]

                            for text in texts:
                                self.send_continue_task(text)

                            # Kirim finish-task setelah semua event continue-task dikirim
                            self.send_finish_task()

                        elif event == "task-finished":
                            print("Task completed")
                            self.task_finished = True
                            self.close(ws)

                        elif event == "task-failed":
                            error_msg = msg_json.get("error_message", "Unknown error")
                            print(f"Task failed: {error_msg}")
                            self.task_finished = True
                            self.close(ws)

            except json.JSONDecodeError as e:
                print(f"JSON parsing failed: {e}")
        else:
            # Tangani pesan biner (data audio)
            print(f"Received binary message, size: {len(message)} bytes")
            with open(self.output_file, "ab") as f:
                f.write(message)
            print(f"Audio data written to local file {self.output_file}")

    def on_error(self, ws, error):
        """Callback ketika terjadi kesalahan"""
        print(f"WebSocket error: {error}")

    def on_close(self, ws, close_status_code, close_msg):
        """Callback ketika koneksi ditutup"""
        print(f"WebSocket closed: {close_msg} ({close_status_code})")

    def send_continue_task(self, text):
        """Kirim event continue-task dengan konten teks yang akan disintesis"""
        cmd = {
            "header": {
                "action": "continue-task",
                "task_id": self.task_id,
                "streaming": "duplex"
            },
            "payload": {
                "input": {
                    "text": text
                }
            }
        }

        self.ws.send(json.dumps(cmd))
        print(f"Sent continue-task event, text content: {text}")

    def send_finish_task(self):
        """Kirim event finish-task untuk mengakhiri tugas sintesis suara"""
        cmd = {
            "header": {
                "action": "finish-task",
                "task_id": self.task_id,
                "streaming": "duplex"
            },
            "payload": {
                "input": {}
            }
        }

        self.ws.send(json.dumps(cmd))
        print("Sent finish-task event")

    def close(self, ws):
        """Tutup secara aktif koneksi"""
        if ws and ws.sock and ws.sock.connected:
            ws.close()
            print("Connection closed actively")

    def run(self):
        """Mulai klien WebSocket"""
        # Atur header permintaan (otentikasi)
        header = {
            "Authorization": f"bearer {self.api_key}",
            "X-DashScope-DataInspection": "enable"
        }

        # Buat instans WebSocketApp
        self.ws = websocket.WebSocketApp(
            self.uri,
            header=header,
            on_open=self.on_open,
            on_message=self.on_message,
            on_error=self.on_error,
            on_close=self.on_close
        )

        print("Listening for WebSocket messages...")
        self.ws.run_forever()  # Mulai pendengar koneksi persisten

# Contoh penggunaan
if __name__ == "__main__":
    # Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    # Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikutnya dengan Kunci API Model Studio China Anda: API_KEY = "sk-xxx"
    API_KEY = os.environ.get("DASHSCOPE_API_KEY")
    # Berikut ini adalah konfigurasi untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi berdasarkan wilayah.
    SERVER_URI = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference"  # Ganti dengan URL WebSocket Anda

    client = TTSClient(API_KEY, SERVER_URI)
    client.run()

SDK Python

SDK Python menggunakan SpeechSynthesizerObjectPool untuk mengelola dan menggunakan kembali objek SpeechSynthesizer.

Pool membuat sejumlah instance SpeechSynthesizer dan membentuk koneksi WebSocket saat inisialisasi. Saat Anda meminjam objek, objek tersebut siap mengirim permintaan segera, sehingga mengurangi latensi paket pertama. Setelah objek dikembalikan, koneksi tetap aktif untuk tugas berikutnya.

Langkah implementasi

1. Instal dependensi: Instal dependensi DashScope (pip install -U dashscope).

2. Buat dan konfigurasikan pool objek

   Atur ukuran pool menjadi 1,5–2 kali konkurensi puncak, dan jangan melebihi batas QPS akun Anda.

   Buat pool singleton global (pembentukan koneksi saat inisialisasi memakan waktu):

from dashscope.audio.tts_v2 import SpeechSynthesizerObjectPool

synthesizer_object_pool = SpeechSynthesizerObjectPool(max_size=20)
import dashscope
// Berikut adalah konfigurasi untuk wilayah China (Beijing). Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi berdasarkan wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

3. Pinjam objek SpeechSynthesizer dari pool

   Jika jumlah objek yang belum dikembalikan melebihi kapasitas pool, sistem membuat objek tambahan.

   Objek tambahan ini harus membentuk koneksi baru dan tidak mendapat manfaat dari pooling.

speech_synthesizer = connectionPool.borrow_synthesizer(
    model='cosyvoice-v3-flash',
    voice='longanyang',
    seed=12382,
    callback=synthesizer_callback
)

4. Lakukan sintesis ucapan

   Panggil metode call atau streaming_call objek SpeechSynthesizer untuk mensintesis ucapan.

5. Kembalikan objek SpeechSynthesizer

   Kembalikan objek setelah tugas selesai agar tersedia untuk digunakan kembali.

   Jangan mengembalikan objek dengan tugas yang belum lengkap atau gagal.

connectionPool.return_synthesizer(speech_synthesizer)

Kode lengkap

// !/usr/bin/env python3
// Hak Cipta (C) Alibaba Group. Seluruh Hak Dilindungi.
// Lisensi MIT (https://opensource.org/licenses/MIT)

import os
import time
import threading

import dashscope
from dashscope.audio.tts_v2 import *

USE_CONNECTION_POOL = True
text_to_synthesize = [
    'Kalimat 1: Selamat datang di layanan sintesis ucapan Alibaba.',
    'Kalimat 2: Selamat datang di layanan sintesis ucapan Alibaba.',
    'Kalimat 3: Selamat datang di layanan sintesis ucapan Alibaba.',
]
connectionPool = None

def init_dashscope_api_key():
    '''
    Tetapkan Kunci API DashScope Anda. Informasi lebih lanjut:
    https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    '''
    // Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  // muat Kunci API dari variabel lingkungan DASHSCOPE_API_KEY
    else:
        dashscope.api_key = '<your-dashscope-api-key>'  // tetapkan Kunci API secara manual

def synthesis_text_to_speech_and_play_by_streaming_mode(text, task_id):
    global USE_CONNECTION_POOL, connectionPool
    '''
    Sintesis ucapan dengan teks yang diberikan dengan mode streaming, panggilan asinkron dan putar audio yang disintesis secara real-time.
    untuk informasi lebih lanjut, silakan merujuk ke https://www.alibabacloud.com/help/document_detail/2712523.html
    '''

    complete_event = threading.Event()

    // Definisikan callback untuk menangani hasil

    class Callback(ResultCallback):
        def on_open(self):
            // saat menggunakan pool objek, on_open akan dipanggil setelah tugas dimulai
            self.file = open(f'result_{task_id}.mp3', 'wb')
            print(f'[task_{task_id}] mulai')

        def on_complete(self):
            print(f'[task_{task_id}] tugas sintesis ucapan selesai berhasil.')
            complete_event.set()

        def on_error(self, message: str):
            print(f'[task_{task_id}] tugas sintesis ucapan gagal, {message}')

        def on_close(self):
            // saat menggunakan pool objek, on_open akan dipanggil setelah tugas selesai
            print(f'[task_{task_id}] selesai')

        def on_event(self, message):
            // print(f'terima pesan sintesis ucapan {message}')
            pass

        def on_data(self, data: bytes) -> None:
            // kirim ke pemutar
            // simpan audio ke file
            self.file.write(data)

    // Panggil callback synthesizer ucapan
    synthesizer_callback = Callback()

    // Inisialisasi synthesizer ucapan
    // Anda dapat menyesuaikan parameter sintesis, seperti suara, format, laju sampel atau parameter lainnya
    if USE_CONNECTION_POOL:
        speech_synthesizer = connectionPool.borrow_synthesizer(
            model='cosyvoice-v3-flash',
            voice='longanyang',
            seed=12382,
            callback=synthesizer_callback
        )
    else:
        speech_synthesizer = SpeechSynthesizer(model='cosyvoice-v3-flash',
                                               voice='longanyang',
                                               seed=12382,
                                               callback=synthesizer_callback)
    try:
        speech_synthesizer.call(text)
    except Exception as e:
        print(f'[task_{task_id}] tugas sintesis ucapan gagal, {e}')
        if USE_CONNECTION_POOL:
            // tutup koneksi synthesizer secara manual jika tugas gagal saat menggunakan pool koneksi.
            speech_synthesizer.close()
        return

    print('[task_{}] Teks yang disintesis: {}'.format(task_id, text))
    complete_event.wait()
    print('[task_{}][Metric] requestId: {}, latensi paket pertama ms: {}'.format(
        task_id,
        speech_synthesizer.get_last_request_id(),
        speech_synthesizer.get_first_package_delay()))
    if USE_CONNECTION_POOL:
        connectionPool.return_synthesizer(speech_synthesizer)

// fungsi utama
if __name__ == '__main__':
    // Anda harus mengatur dashscope.api_key dan base_websocket_api_url sebelum membuat SpeechSynthesizerObjectPool.
    // Pool membentuk koneksi WebSocket menggunakan dashscope.api_key global saat ini saat waktu inisialisasi.
    // Memodifikasi dashscope.api_key setelah pembuatan pool tidak akan memengaruhi koneksi yang ada di pool.
    // Berikut adalah konfigurasi untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi berdasarkan wilayah.
    dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'
    init_dashscope_api_key()

    if USE_CONNECTION_POOL:
        print('membuat pool koneksi')
        start_time = time.time() * 1000
        connectionPool = SpeechSynthesizerObjectPool(max_size=3)
        end_time = time.time() * 1000
        print('pool koneksi dibuat, biaya: {} ms'.format(end_time - start_time))

    task_thread_list = []
    for task_id in range(3):
        thread = threading.Thread(
            target=synthesis_text_to_speech_and_play_by_streaming_mode,
            args=(text_to_synthesize[task_id], task_id))
        task_thread_list.append(thread)

    for task_thread in task_thread_list:
        task_thread.start()

    for task_thread in task_thread_list:
        task_thread.join()

    if USE_CONNECTION_POOL:
        connectionPool.shutdown()

Manajemen sumber daya dan penanganan error

• Tugas berhasil: Setelah tugas sintesis selesai secara normal, panggil connectionPool.return_synthesizer(speech_synthesizer) untuk mengembalikan objek SpeechSynthesizer ke pool untuk digunakan kembali.

  PentingJangan mengembalikan objek SpeechSynthesizer dengan tugas yang belum lengkap atau gagal.

• Tugas gagal: Jika error internal SDK atau exception logika bisnis menyebabkan tugas dibatalkan, tutup koneksi WebSocket dasar: speech_synthesizer.close()

• Setelah semua tugas sintesis selesai, matikan pool: connectionPool.shutdown()

• Saat terjadi error TaskFailed di sisi server, tidak diperlukan penanganan tambahan.

SDK Java

SDK Java mencapai kinerja optimal melalui koordinasi pool koneksi bawaan dan pool objek kustom.

• Pool koneksi: Pool koneksi OkHttp3 yang terintegrasi dalam SDK mengelola dan menggunakan kembali koneksi WebSocket dasar, sehingga mengurangi overhead jabat tangan jaringan. Fitur ini diaktifkan secara default.
• Pool objek: Dibangun di atas commons-pool2, pool ini mempertahankan seperangkat objek SpeechSynthesizer yang telah terhubung sebelumnya. Meminjam dari pool menghilangkan latensi penyiapan koneksi, sehingga secara signifikan mengurangi latensi paket pertama.

Langkah implementasi

1. Tambahkan dependensi

   Tambahkan dashscope-sdk-java dan commons-pool2 ke konfigurasi dependensi proyek Anda berdasarkan alat build yang digunakan.

   Contoh Maven dan Gradle:

   Maven

   1. Buka file pom.xml proyek Maven Anda.
   2. Tambahkan dependensi berikut di dalam tag <dependencies>.

   <dependency>
       <groupId>com.alibaba</groupId>
       <artifactId>dashscope-sdk-java</artifactId>
       <!-- Ganti 'the-latest-version' dengan versi 2.16.9 atau lebih baru. Periksa versi yang tersedia di: https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java -->
       <version>the-latest-version</version>
   </dependency>
   
   <dependency>
       <groupId>org.apache.commons</groupId>
       <artifactId>commons-pool2</artifactId>
       <!-- Ganti 'the-latest-version' dengan versi terbaru. Periksa versi yang tersedia di: https://mvnrepository.com/artifact/org.apache.commons/commons-pool2 -->
       <version>the-latest-version</version>
   </dependency>
   

   1. Simpan file pom.xml.
   2. Jalankan perintah Maven seperti mvn clean install atau mvn compile untuk memperbarui dependensi proyek.

   Gradle

   1. Buka file build.gradle proyek Gradle Anda.
   2. Tambahkan dependensi berikut di dalam blok dependencies.

   dependencies {
       // Ganti 'the-latest-version' dengan versi 2.16.6 atau lebih baru. Periksa versi yang tersedia di: https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
       implementation group: 'com.alibaba', name: 'dashscope-sdk-java', version: 'the-latest-version'
   
       // Ganti 'the-latest-version' dengan versi terbaru. Periksa versi yang tersedia di: https://mvnrepository.com/artifact/org.apache.commons/commons-pool2
       implementation group: 'org.apache.commons', name: 'commons-pool2', version: 'the-latest-version'
   }
   

   3. Simpan file build.gradle.
   4. Di terminal, navigasi ke direktori root proyek dan jalankan perintah Gradle berikut untuk memperbarui dependensi.

   ./gradlew build --refresh-dependencies
   

   Di Windows, gunakan perintah berikut sebagai gantinya:

   gradlew build --refresh-dependencies
   

2. Konfigurasikan pool koneksi

   Konfigurasikan parameter kunci pool koneksi melalui variabel lingkungan:

   Variabel lingkungan	Deskripsi
   DASHSCOPE_CONNECTION_POOL_SIZE	Ukuran pool koneksi. Nilai yang direkomendasikan: minimal 2x konkurensi puncak. Default: 32.
   DASHSCOPE_MAXIMUM_ASYNC_REQUESTS	Jumlah maksimum permintaan asinkron. Nilai yang direkomendasikan: sama dengan DASHSCOPE_CONNECTION_POOL_SIZE. Default: 32.
   DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST	Jumlah maksimum permintaan asinkron per host. Nilai yang direkomendasikan: sama dengan DASHSCOPE_CONNECTION_POOL_SIZE. Default: 32.

3. Konfigurasikan pool objek

   Konfigurasikan ukuran pool objek melalui variabel lingkungan:

   Variabel lingkungan	Deskripsi
   COSYVOICE_OBJECTPOOL_SIZE	Ukuran pool objek. Nilai yang direkomendasikan: 1,5x-2x konkurensi puncak. Default: 500.

   Penting

   • Ukuran pool objek (COSYVOICE_OBJECTPOOL_SIZE) harus kurang dari atau sama dengan ukuran pool koneksi (DASHSCOPE_CONNECTION_POOL_SIZE). Jika tidak, saat pool objek meminta objek dan pool koneksi penuh, thread pemanggil akan memblokir sambil menunggu koneksi yang tersedia.
   • Ukuran pool objek tidak boleh melebihi batas QPS (queries per second) akun Anda.

   Buat pool objek dengan kode berikut:

class CosyvoiceObjectPool {
    // ... Kode lain dihilangkan di sini. Untuk contoh lengkap, lihat kode lengkap.
    public static GenericObjectPool<SpeechSynthesizer> getInstance() {
        lock.lock();
        if (synthesizerPool == null) {
            // Anda dapat mengatur ukuran pool objek di sini, atau mengaturnya di variabel lingkungan COSYVOICE_OBJECTPOOL_SIZE.
            // Disarankan untuk mengaturnya menjadi 1,5 hingga 2 kali koneksi konkuren maksimum server.
            int objectPoolSize = getObjectivePoolSize();
            SpeechSynthesizerObjectFactory speechSynthesizerObjectFactory =
                    new SpeechSynthesizerObjectFactory();
            GenericObjectPoolConfig<SpeechSynthesizer> config =
                    new GenericObjectPoolConfig<>();
            config.setMaxTotal(objectPoolSize);
            config.setMaxIdle(objectPoolSize);
            config.setMinIdle(objectPoolSize);
            synthesizerPool =
                    new GenericObjectPool<>(speechSynthesizerObjectFactory, config);
        }
        lock.unlock();
        return synthesizerPool;
    }
}

4. Pinjam objek SpeechSynthesizer dari pool

   Jika jumlah objek yang belum dikembalikan melebihi kapasitas maksimum pool, sistem membuat objek SpeechSynthesizer tambahan.

   Objek yang baru dibuat ini memerlukan inisialisasi ulang dan koneksi WebSocket baru, sehingga tidak mendapat manfaat dari pooling.

synthesizer = CosyvoiceObjectPool.getInstance().borrowObject();

5. Lakukan sintesis ucapan

   Setelah meminjam objek SpeechSynthesizer dari pool, panggil updateParamAndCallback(param, callback) untuk mengikat parameter dan callback untuk tugas saat ini, lalu panggil streamingCall atau call untuk mensintesis ucapan.

   Penting

   • Dalam skenario pool objek, updateParamAndCallback dipanggil beberapa kali (sekali setiap kali objek dipinjam, untuk mengatur callback dan parameter tingkat tugas seperti voice dan format). Kunci apiKey yang diteruskan dalam setiap panggilan harus tetap sama. updateParamAndCallback hanya memperbarui bidang lokal instance SpeechSynthesizer saat ini dan tidak membangun ulang koneksi WebSocket dasar. SDK menulis apiKey ke header Authorization hanya selama handshake WebSocket untuk autentikasi. Pesan tugas berikutnya (seperti run-task) tidak membawa apiKey. Selama koneksi yang digunakan kembali tidak terputus, meneruskan apiKey baru tidak akan dikirim ke server — permintaan masih menggunakan apiKey dari handshake awal, yang dapat menyebabkan atribusi identitas, kuota, atau penagihan berbeda dari yang diharapkan.
   • Untuk menggunakan beberapa Kunci API, pertahankan instance pool objek terpisah untuk setiap kunci.

6. Kembalikan objek SpeechSynthesizer

   Setelah tugas sintesis selesai, kembalikan objek SpeechSynthesizer agar tugas berikutnya dapat menggunakannya kembali.

   Jangan mengembalikan objek dengan tugas yang belum lengkap atau gagal.

CosyvoiceObjectPool.getInstance().returnObject(synthesizer);

Kode lengkap

import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisAudioFormat;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.pool2.BasePooledObjectFactory;
import org.apache.commons.pool2.PooledObject;
import org.apache.commons.pool2.impl.DefaultPooledObject;
import org.apache.commons.pool2.impl.GenericObjectPool;
import org.apache.commons.pool2.impl.GenericObjectPoolConfig;

import java.time.LocalDateTime;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.locks.Lock;

/**
 * Anda perlu menyertakan paket org.apache.commons.pool2 dan DashScope dalam proyek Anda.
 *
 * SDK DashScope versi 2.16.6 dan lebih baru dioptimalkan untuk skenario konkurensi tinggi.
 * Versi SDK DashScope sebelum 2.16.6 tidak direkomendasikan untuk penggunaan konkurensi tinggi.
 *
 *
 * Sebelum melakukan panggilan konkurensi tinggi ke layanan TTS,
 * harap konfigurasikan parameter pool koneksi melalui variabel lingkungan berikut.
 *
 * DASHSCOPE_MAXIMUM_ASYNC_REQUESTS
 * DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST
 * DASHSCOPE_CONNECTION_POOL_SIZE
 *
 */

class SpeechSynthesizerObjectFactory
        extends BasePooledObjectFactory<SpeechSynthesizer> {
    public SpeechSynthesizerObjectFactory() {
        super();
    }
    @Override
    public SpeechSynthesizer create() throws Exception {
        return new SpeechSynthesizer();
    }

    @Override
    public PooledObject<SpeechSynthesizer> wrap(SpeechSynthesizer obj) {
        return new DefaultPooledObject<>(obj);
    }
}

class CosyvoiceObjectPool {
    public static GenericObjectPool<SpeechSynthesizer> synthesizerPool;
    public static String COSYVOICE_OBJECTPOOL_SIZE_ENV = "COSYVOICE_OBJECTPOOL_SIZE";
    public static int DEFAULT_OBJECT_POOL_SIZE = 500;
    private static Lock lock = new java.util.concurrent.locks.ReentrantLock();
    public static int getObjectivePoolSize() {
        try {
            Integer n = Integer.parseInt(System.getenv(COSYVOICE_OBJECTPOOL_SIZE_ENV));
            System.out.println("Menggunakan Ukuran Pool Objek di Env: "+ n);
            return n;
        } catch (NumberFormatException e) {
            System.out.println("Menggunakan Ukuran Pool Objek Default: "+ DEFAULT_OBJECT_POOL_SIZE);
            return DEFAULT_OBJECT_POOL_SIZE;
        }
    }
    public static GenericObjectPool<SpeechSynthesizer> getInstance() {
        lock.lock();
        if (synthesizerPool == null) {
            // Anda dapat mengatur ukuran pool objek di sini atau di variabel lingkungan COSYVOICE_OBJECTPOOL_SIZE.
            // Disarankan untuk mengaturnya menjadi 1,5 hingga 2 kali koneksi konkuren maksimum server Anda.
            int objectPoolSize = getObjectivePoolSize();
            SpeechSynthesizerObjectFactory speechSynthesizerObjectFactory =
                    new SpeechSynthesizerObjectFactory();
            GenericObjectPoolConfig<SpeechSynthesizer> config =
                    new GenericObjectPoolConfig<>();
            config.setMaxTotal(objectPoolSize);
            config.setMaxIdle(objectPoolSize);
            config.setMinIdle(objectPoolSize);
            synthesizerPool =
                    new GenericObjectPool<>(speechSynthesizerObjectFactory, config);
        }
        lock.unlock();
        return synthesizerPool;
    }
}

class SynthesizeTaskWithCallback implements Runnable {
    String[] textArray;
    String requestId;
    long timeCost;
    public SynthesizeTaskWithCallback(String[] textArray) {
        this.textArray = textArray;
    }
    @Override
    public void run() {
        SpeechSynthesizer synthesizer = null;
        long startTime = System.currentTimeMillis();
        // jika menerima onError
        final boolean[] hasError = {false};
        try {
            class ReactCallback extends ResultCallback<SpeechSynthesisResult> {
                ReactCallback() {}

                @Override
                public void onEvent(SpeechSynthesisResult message) {
                    if (message.getAudioFrame() != null) {
                        try {
                            byte[] bytesArray = message.getAudioFrame().array();
                            System.out.println("Audio diterima, panjang aliran audio: " + bytesArray.length);
                        } catch (Exception e) {
                            throw new RuntimeException(e);
                        }
                    }
                }

                @Override
                public void onComplete() {}

                @Override
                public void onError(Exception e) {
                    System.out.println(e.getMessage());
                    e.printStackTrace();
                    hasError[0] = true;
                }
            }

            SpeechSynthesisParam param =
                    SpeechSynthesisParam.builder()
                            .model("cosyvoice-v3-flash")
                            .voice("longanyang")
                            // Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                            // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio China Anda: .apiKey("sk-xxx")
                            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                            .format(SpeechSynthesisAudioFormat
                                    .MP3_22050HZ_MONO_256KBPS) // Gunakan PCM atau MP3 untuk sintesis streaming
                            .build();

            try {
                synthesizer = CosyvoiceObjectPool.getInstance().borrowObject();
                // Catatan: Dalam skenario pool objek, apiKey yang diteruskan dalam beberapa panggilan updateParamAndCallback harus selalu sama. SDK tidak memperbarui apiKey untuk koneksi yang telah dibentuk, sehingga meneruskan apiKey yang berbeda tidak berpengaruh. Lihat catatan penting di langkah "Lakukan sintesis ucapan" di atas.
                synthesizer.updateParamAndCallback(param, new ReactCallback());
                for (String text : textArray) {
                    synthesizer.streamingCall(text);
                }
                Thread.sleep(20);
                synthesizer.streamingComplete(60000);
                requestId = synthesizer.getLastRequestId();
            } catch (Exception e) {
                System.out.println("Exception e: " + e.toString());
                hasError[0] = true;
            }
        } catch (Exception e) {
            hasError[0] = true;
            throw new RuntimeException(e);
        }
        if (synthesizer != null) {
            try {
                if (hasError[0] == true) {
                    // Jika terjadi exception, tutup koneksi dan batalkan objek di pool.
                    synthesizer.getDuplexApi().close(1000, "bye");
                    CosyvoiceObjectPool.getInstance().invalidateObject(synthesizer);
                } else {
                    // Jika tugas selesai secara normal, kembalikan objek ke pool.
                    CosyvoiceObjectPool.getInstance().returnObject(synthesizer);
                }
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
            long endTime = System.currentTimeMillis();
            timeCost = endTime - startTime;
            System.out.println("[Thread " + Thread.currentThread() + "] Tugas sintesis ucapan selesai. Biaya waktu: " + timeCost + " ms, RequestId " + requestId);
        }
    }
}

@Slf4j
public class SynthesizeTextToSpeechWithCallbackConcurrently {
    public static void checkoutEnv(String envName, int defaultSize) {
        if (System.getenv(envName) != null) {
            System.out.println("[PERIKSA ENV]: " + envName + " "
                    + System.getenv(envName));
        } else {
            System.out.println("[PERIKSA ENV]: " + envName
                    + " Menggunakan Default yaitu " + defaultSize);
        }
    }

    public static void main(String[] args)
            throws InterruptedException, NoApiKeyException {
        // Berikut adalah konfigurasi untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi bervariasi berdasarkan wilayah.
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference";
        // Periksa env pool koneksi
        checkoutEnv("DASHSCOPE_CONNECTION_POOL_SIZE", 32);
        checkoutEnv("DASHSCOPE_MAXIMUM_ASYNC_REQUESTS", 32);
        checkoutEnv("DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST", 32);
        checkoutEnv(CosyvoiceObjectPool.COSYVOICE_OBJECTPOOL_SIZE_ENV, CosyvoiceObjectPool.DEFAULT_OBJECT_POOL_SIZE);

        int runTimes = 3;
        // Buat pool objek SpeechSynthesis
        ExecutorService executorService = Executors.newFixedThreadPool(runTimes);

        for (int i = 0; i < runTimes; i++) {
            // Catat waktu pengiriman tugas
            LocalDateTime submissionTime = LocalDateTime.now();
            executorService.submit(new SynthesizeTaskWithCallback(new String[] {
                    "Before my bed, moonlight shines bright,", "I wonder if it is frost on the ground,", "I raise my eyes to gaze at the bright moon,", "then bow my head, thinking of home."}));
        }

        // Matikan ExecutorService dan tunggu semua tugas selesai
        executorService.shutdown();
        executorService.awaitTermination(1, TimeUnit.MINUTES);
        System.exit(0);
    }
}

Konfigurasi yang direkomendasikan

Konfigurasi berikut didasarkan pada hasil pengujian dari menjalankan hanya layanan sintesis ucapan Qwen-Audio-TTS/CosyVoice pada instance ECS Alibaba Cloud dengan spesifikasi yang ditentukan. Konkurensi berlebihan dapat meningkatkan latensi pemrosesan tugas.

"Konkurensi mesin tunggal" mengacu pada jumlah tugas sintesis Qwen-Audio-TTS/CosyVoice yang berjalan secara bersamaan, setara dengan jumlah thread pekerja.

Manajemen sumber daya dan penanganan error

• Tugas berhasil: Setelah tugas sintesis selesai secara normal, panggil metode GenericObjectPool.returnObject untuk mengembalikan objek SpeechSynthesizer ke pool untuk digunakan kembali.

  Dalam kode contoh, ini sesuai dengan CosyvoiceObjectPool.getInstance().returnObject(synthesizer).

  PentingJangan mengembalikan objek SpeechSynthesizer dengan tugas yang belum lengkap atau gagal.

• Tugas gagal: Jika error internal SDK atau exception logika bisnis menyebabkan tugas dibatalkan, lakukan hal berikut:

  1. Tutup koneksi WebSocket dasar.
  2. Batalkan objek di pool untuk mencegahnya digunakan kembali.

// Dalam kode saat ini, konten yang sesuai adalah sebagai berikut
// Tutup koneksi
synthesizer.getDuplexApi().close(1000, "bye");
// Batalkan synthesizer di pool objek saat terjadi exception
CosyvoiceObjectPool.getInstance().invalidateObject(synthesizer);

• Saat terjadi error TaskFailed di sisi server, tidak diperlukan penanganan tambahan.

Pemanasan dan pengukuran latensi

Saat mengevaluasi SDK Java DashScope untuk latensi dan kinerja konkurensi, jalankan operasi pemanasan yang cukup terlebih dahulu. Ini memastikan bahwa pengukuran mencerminkan kinerja keadaan stabil daripada overhead koneksi awal.

Mekanisme penggunaan kembali koneksi

SDK Java DashScope menggunakan pool koneksi singleton global untuk mengelola dan menggunakan kembali koneksi WebSocket secara efisien, sehingga mengurangi overhead pembuatan dan penghancuran koneksi yang sering untuk beban kerja konkurensi tinggi.

Cara kerja mekanisme ini:

• Pembuatan sesuai permintaan: SDK tidak membuat koneksi WebSocket sebelumnya saat startup. Koneksi dibentuk pada panggilan pertama.

• Penggunaan kembali berbatas waktu: Setelah permintaan selesai, koneksi tetap berada di pool hingga 60 detik untuk digunakan kembali.

  • Jika permintaan baru tiba dalam waktu 60 detik, koneksi yang ada digunakan kembali, sehingga menghindari overhead jabat tangan.
  • Jika koneksi menganggur lebih dari 60 detik, koneksi tersebut ditutup secara otomatis untuk membebaskan sumber daya.

Pentingnya pemanasan

Dalam skenario berikut, pool koneksi mungkin tidak memiliki koneksi aktif yang dapat digunakan kembali, sehingga memaksa pembuatan koneksi baru:

• Aplikasi baru saja dimulai dan belum melakukan panggilan apa pun.
• Layanan telah menganggur lebih dari 60 detik, dan koneksi di pool telah timeout serta ditutup.

Dalam skenario ini, permintaan pertama harus menyelesaikan jabat tangan WebSocket penuh (jabat tangan TCP, negosiasi TLS, peningkatan protokol), sehingga menghasilkan latensi yang jauh lebih tinggi daripada permintaan berikutnya yang menggunakan kembali koneksi. Tanpa pemanasan, hasil pengujian kinerja condong oleh overhead koneksi awal ini.

Latensi yang dilaporkan SDK vs. latensi paket pertama aktual

Latensi paket pertama yang dilaporkan oleh SDK (misalnya, nilai dari get_first_package_delay()) mencakup penyiapan koneksi WebSocket dan waktu transmisi jaringan, dan tidak sama dengan latensi paket pertama layanan model aktual.

Latensi paket pertama aktual adalah interval antara saat server menerima instruksi run-task dan saat server mengembalikan event result-generated pertama. Nilai ini dapat ditemukan di log sisi server.

Dalam skenario konkurensi tinggi, karena pembuatan koneksi simultan dan penjadwalan sumber daya, latensi yang dilaporkan SDK mungkin jauh lebih tinggi daripada latensi paket pertama sisi server aktual. Jika Anda mengamati latensi paket pertama yang dilaporkan SDK tinggi:

• Bandingkan dengan latensi paket pertama log sisi server (dari run-task ke result-generated pertama) untuk memeriksa apakah kinerja inferensi model normal.
• Gunakan mekanisme pool objek atau pool koneksi yang dijelaskan di atas untuk pemanasan. Ini menghilangkan overhead jabat tangan WebSocket, sehingga membawa latensi yang dilaporkan SDK lebih dekat ke latensi paket pertama aktual.

Praktik yang direkomendasikan

Untuk data kinerja yang andal, ikuti langkah pemanasan ini sebelum menjalankan pengujian beban atau mengumpulkan metrik latensi:

1. Simulasikan tingkat konkurensi target dan kirim sejumlah permintaan pemanasan terlebih dahulu (misalnya, pertahankan lalu lintas selama 1–2 menit) untuk sepenuhnya mengisi pool koneksi.
2. Konfirmasi bahwa pool koneksi telah membentuk dan mempertahankan koneksi aktif yang cukup sebelum memulai pengumpulan data kinerja formal.

Pemanasan yang tepat membawa pool koneksi SDK ke keadaan penggunaan kembali yang stabil, sehingga menghasilkan metrik latensi yang secara akurat mencerminkan kinerja keadaan stabil online.

Exception SDK Java umum