Skip to main content

Praktik terbaik sintesis suara

Terapkan praktik terbaik sintesis suara untuk pengiriman teks, pemrosesan audio, pengelolaan koneksi dan sumber daya konkurensi, evaluasi kinerja, serta pemecahan masalah.

Pengiriman teks dan kontrol tugas

Untuk suara hasil kloning atau desain, model sintesis harus sama dengan model target yang ditentukan saat suara dibuat. Lihat Kloning suara atau Desain suara untuk persyaratan pembuatan suara.

Segmentasi dan waktu pengiriman teks

Untuk Qwen-Audio-TTS dan CosyVoice melalui WebSocket, tunggu task-started sebelum mengirim segmen teks secara berurutan. Server memisahkan kalimat secara otomatis: kalimat lengkap langsung disintesis, sedangkan kalimat yang belum lengkap disimpan sampai lengkap atau sampai finish-task diterima. Jeda pengiriman yang panjang menambah waktu total sintesis. Pemutaran juga dapat tersendat jika audio sebelumnya selesai sebelum teks berikutnya tiba. Lihat Peristiwa klien Qwen-Audio-TTS atau Peristiwa klien CosyVoice untuk batas panjang per segmen, panjang kumulatif, dan interval pengiriman.
Kirim teks SSML lengkap sekaligus. SSML tidak mendukung input tersegmentasi. Model, suara, dan antarmuka yang didukung dijelaskan dalam SSML dan LaTeX.

Penyelesaian dan pembatalan tugas

Saat memanggil Qwen-Audio-TTS atau CosyVoice melalui protokol WebSocket langsung, setelah seluruh teks dikirim, kirim finish-task untuk mengakhiri input dan terus terima audio hingga task-finished. Tanpa pemberitahuan akhir input, audio dapat tidak lengkap. Untuk menghentikan sintesis saat ini, gunakan pembatalan tugas. Server mengakhiri tugas dan mengembalikan task-finished. Lihat Membatalkan tugas untuk penggunaan SDK dan protokol langsung serta ketentuan penerapannya.

Penerimaan dan pemutaran audio

Penerimaan dan penyimpanan audio

Qwen-Audio-TTS dan CosyVoice mengembalikan audio dalam bentuk berbeda sesuai antarmuka:
  • Output HTTP non-streaming: Unduh berkas audio lengkap dari output.audio.url. URL berlaku selama 24 jam. Simpan sebelum kedaluwarsa; setelah itu audio dapat disintesis ulang.
  • Output HTTP SSE: output.audio.data berisi segmen audio yang dikodekan Base64. Dekode sesuai urutan penerimaan dan tambahkan ke berkas yang sama. Lihat HTTP API Qwen-Audio-TTS dan HTTP API CosyVoice untuk bidang respons.
  • Protokol WebSocket langsung: Terima audio melalui kanal binary. Peristiwa teks membawa informasi kalimat dan metadata lain. Lihat WebSocket API Qwen-Audio-TTS dan WebSocket API CosyVoice untuk alur interaksi.

Kompatibilitas format audio dan pemutar

Saat menyimpan berkas lengkap, samakan ekstensi berkas dengan format audio yang diminta dan pastikan pemutar mendukung format serta laju sampelnya. Untuk masalah pemutaran streaming, simpan aliran sebagai berkas lengkap terlebih dahulu. Jika berkas tidak dapat diputar, periksa format dan pemutar. Jika berkas dapat diputar, periksa dukungan streaming pada implementasi pemutaran, seperti ffmpeg, pyaudio, AudioFormat, atau MediaSource. Header WAV streaming mungkin tidak mencerminkan panjang akhir audio. Jika durasi yang akurat diperlukan, atur format ke pcm, terima seluruh audio, lalu tambahkan header WAV yang berisi panjang sebenarnya.

Penjadwalan callback dan pemutaran

Callback sintesis real-time berjalan pada thread WebSocket. Logika bisnis yang memblokir dapat menunda penerimaan audio. Tulis audio ke buffer terpisah dan proses pada thread lain. Jika pemutaran tersendat, periksa juga kecepatan pengiriman teks dan kestabilan jaringan; fluktuasi jaringan dapat mengganggu atau menunda pengiriman audio.

Pengelolaan koneksi dan sumber daya konkurensi

Penggunaan ulang koneksi dan isolasi tugas

Saat memanggil Qwen-Audio-TTS atau CosyVoice melalui protokol WebSocket langsung, satu koneksi dapat menangani beberapa tugas secara berurutan. Setelah menerima task-finished, kirim run-task dengan task_id baru, lalu kirim teks sesuai alur keluarga model tersebut. Gunakan urutan yang sama setelah pembatalan. Untuk Qwen-Audio-TTS, CosyVoice, koneksi ditutup setelah 60 detik idle seusai tugas. Nilai panggilan setelah idle lama sebagai koneksi baru. Dengan client.audio.tts.connect pada Python SDK, sesi secara default menutup koneksi dasarnya saat tugas selesai atau dibatalkan. Untuk memakai ulang koneksi, buat koneksi bersama dengan client.ws_connection() dan teruskan melalui connection=. Pemanggil menutup koneksi bersama menggunakan WsConnection.close.

Identitas koneksi dan batas isolasi

Kunci API dikirim melalui header Authorization hanya saat handshake WebSocket. Pesan run-task berikutnya tidak menyertakannya. Mengubah kunci pada parameter atau konfigurasi global tidak mengubah identitas koneksi yang sudah ada, sehingga identitas, penggunaan kuota, atau biaya dapat dibebankan secara berbeda dari yang diharapkan.
  • Java SDK
  • Python SDK
Di Java, buat pool independen untuk setiap kunci API dan gunakan kunci yang sama dalam satu pool. Untuk Qwen-Audio-TTS/CosyVoice, panggil updateParamAndCallback setiap kali objek dipinjam. Metode ini tidak mengautentikasi ulang koneksi yang sudah ada.

Perencanaan konkurensi dan sumber daya

Pool menyimpan objek sintesis dan koneksi WebSocket untuk mengurangi pembuatan objek, handshake TCP/TLS, dan upgrade protokol. Seri model dan SDK berikut mendukung pool objek:
  • Qwen-Audio-TTS, CosyVoice: pool objek Python dan Java.
Atur pool sumber daya sesuai jumlah tugas simultan yang diperkirakan dan spesifikasi server. Batas model dihitung per akun Alibaba Cloud dan digunakan bersama oleh pengguna RAM, workspace, dan kunci API dalam akun tersebut. Untuk batas frekuensi dan konkurensi model, lihat Batas laju. Mulai dengan kapasitas pool sebesar 1,5–2 kali konkurensi puncak, lalu sesuaikan dengan beban aktual. Pool Python dapat membuat objek tambahan saat semua objek dipinjam. Objek tambahan ini memerlukan koneksi baru ketika digunakan.
  • Referensi konfigurasi server
  • Parameter pool sumber daya Java
Konfigurasi server Alibaba Cloud berikut merupakan referensi ketika hanya layanan sintesis yang ditunjukkan yang dijalankan. Konkurensi per server berarti tugas sintesis simultan. Sesuaikan konfigurasi dengan beban aktual.Pengaturan pool koneksi pada tabel menjadi nilai referensi untuk ketiga variabel: DASHSCOPE_CONNECTION_POOL_SIZE, DASHSCOPE_MAXIMUM_ASYNC_REQUESTS, dan DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST. Untuk konfigurasi referensi ini, atur ketiganya ke 2000. Atur kapasitas pool objek melalui variabel lingkungan pada contoh yang sesuai.
SeriServer Alibaba CloudTugas simultanKapasitas pool objekPengaturan pool koneksi
CosyVoice4 vCPU / 8 GiB1005002000
CosyVoice8 vCPU / 16 GiB1505002000
CosyVoice16 vCPU / 32 GiB2005002000

Siklus hidup objek

Atur kunci API dan endpoint, lalu buat pool objek yang digunakan bersama oleh tugas aplikasi.
  • Java SDK
  • Python SDK
  1. Pinjam objek dengan borrowObject. Untuk Qwen-Audio-TTS/CosyVoice, panggil updateParamAndCallback(param, callback) setiap kali objek dipinjam untuk mengatur parameter dan callback tugas.
  2. Jalankan sintesis Qwen-Audio-TTS/CosyVoice dengan call atau streamingCall.
  3. Setelah selesai normal, kembalikan objek dengan returnObject. Jika belum selesai atau gagal, buang dengan invalidateObject agar factory menutup koneksinya; jangan kembalikan langsung.
  4. Setelah semua tugas selesai, panggil close() pada pool untuk melepas sumber dayanya.
Di Java, jika maxIdle lebih kecil dari maxTotal, objek yang dikembalikan melebihi kapasitas idle akan dihancurkan. Jika destroyObject pada factory tidak menutup WebSocket, koneksi dapat tetap terbuka setelah objek dihancurkan.
Setelah error klien menginterupsi tugas, server mungkin masih menganggap tugas sebelumnya aktif. Menggunakan ulang koneksi untuk run-task baru akan menyebabkan error urutan protokol (Invalid action('run-task')! Please follow the protocol!). Tutup koneksi dan buang objek, lalu bangun koneksi baru untuk tugas berikutnya. Sering membuat objek sintesis tanpa menutup koneksi lama dapat terus menambah jumlah koneksi dan penggunaan sumber daya server. Periksa apakah objek dikembalikan setelah tugas selesai dan koneksi yang tidak dipakai sudah ditutup.

Contoh pool objek

  • Dapatkan kunci API dan atur DASHSCOPE_API_KEY. Gunakan kunci untuk wilayah yang dipanggil.
  • Ganti {WorkspaceId} dengan ID ruang kerja wilayah tersebut dan atur endpoint WebSocket-nya.
  • Java SDK
  • Python SDK
  • Qwen-Audio-TTS, CosyVoice: DashScope Java SDK 2.16.6 atau yang lebih baru.
Contoh Java juga memerlukan Apache Commons Pool 2. Konfigurasikan dependensi dengan Maven atau Gradle:
Maven
<dependencies>
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>dashscope-sdk-java</artifactId>
        <version>2.23.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-pool2</artifactId>
        <version>2.12.0</version>
    </dependency>
</dependencies>
Contoh menggunakan qwen-audio-3.1-tts-flash dan longanhuan_v3.1 untuk tiga tugas simultan. Untuk CosyVoice, ganti model dan suara menjadi cosyvoice-v3-flash dan longanyang. Untuk model lain dan persyaratan suara, lihat Sintesis ucapan real-time.
Java
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.utils.Constants;
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.io.FileOutputStream;
import java.nio.ByteBuffer;
import java.time.Duration;
import java.util.concurrent.*;
import java.util.concurrent.atomic.AtomicReference;

public class PooledTts {
    static class Factory extends BasePooledObjectFactory<SpeechSynthesizer> {
        public SpeechSynthesizer create() { return new SpeechSynthesizer(); }
        public PooledObject<SpeechSynthesizer> wrap(SpeechSynthesizer value) {
            return new DefaultPooledObject<>(value);
        }
        public void destroyObject(PooledObject<SpeechSynthesizer> value) {
            value.getObject().getDuplexApi().close(1000, "done");
        }
    }

    static void synthesize(GenericObjectPool<SpeechSynthesizer> pool, int index) throws Exception {
        SpeechSynthesizer synthesizer = pool.borrowObject();
        boolean successful = false;
        AtomicReference<Exception> error = new AtomicReference<>();
        try (FileOutputStream audio = new FileOutputStream("output_" + index + ".mp3")) {
            SpeechSynthesisParam param = SpeechSynthesisParam.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-audio-3.1-tts-flash")
                .voice("longanhuan_v3.1")
                .format(SpeechSynthesisAudioFormat.MP3_24000HZ_MONO_256KBPS)
                .build();
            synthesizer.updateParamAndCallback(param, new ResultCallback<SpeechSynthesisResult>() {
                public void onEvent(SpeechSynthesisResult result) {
                    ByteBuffer buffer = result.getAudioFrame();
                    if (buffer != null) {
                        byte[] bytes = new byte[buffer.remaining()];
                        buffer.get(bytes);
                        try { audio.write(bytes); }
                        catch (Exception e) { error.set(e); }
                    }
                }
                public void onComplete() {}
                public void onError(Exception e) { error.set(e); }
            });
            synthesizer.streamingCall("Hello, welcome to Alibaba Cloud Model Studio.");
            synthesizer.streamingComplete(60000);
            if (error.get() != null) { throw error.get(); }
            successful = true;
        } finally {
            if (successful) { pool.returnObject(synthesizer); }
            else { pool.invalidateObject(synthesizer); }
        }
    }

    public static void main(String[] args) throws Exception {
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
        GenericObjectPoolConfig<SpeechSynthesizer> config = new GenericObjectPoolConfig<>();
        int poolSize = Integer.parseInt(System.getenv().getOrDefault("COSYVOICE_OBJECTPOOL_SIZE", "500"));
        config.setMaxTotal(poolSize);
        config.setMaxIdle(poolSize);
        config.setMaxWait(Duration.ofSeconds(60));
        ExecutorService executor = Executors.newFixedThreadPool(3);
        try (GenericObjectPool<SpeechSynthesizer> pool = new GenericObjectPool<>(new Factory(), config)) {
            java.util.List<Future<?>> futures = new java.util.ArrayList<>();
            for (int i = 0; i < 3; i++) {
                final int index = i;
                futures.add(executor.submit(() -> {
                    try { synthesize(pool, index); }
                    catch (Exception e) { throw new RuntimeException(e); }
                }));
            }
            for (Future<?> future : futures) { future.get(); }
        } finally {
            executor.shutdownNow();
        }
    }
}

Evaluasi kinerja dan diagnosis

Pool Python membangun koneksi saat inisialisasi. Java GenericObjectPool membuat objek sesuai kebutuhan dan terhubung pada sintesis pertama. Karena itu, pemanasan koneksi Java memerlukan permintaan sintesis yang benar-benar dijalankan.Setelah startup atau pemulihan jaringan, jalankan pemanasan dan tingkatkan konkurensi secara bertahap. Sebelum pengujian kinerja, lakukan pemanasan pada konkurensi target, misalnya selama 1–2 menit, lalu kumpulkan pengukuran setelah koneksi digunakan kembali secara stabil. Menaikkan konkurensi secara bertahap menghindari pemblokiran akibat membangun banyak koneksi WebSocket sekaligus.
Panggilan pertama mencakup overhead pembuatan koneksi WebSocket. Ukur latensi audio pertama dan waktu totalnya secara terpisah dari panggilan yang menggunakan kembali koneksi. Faktor waktu nyata (RTF, total waktu sintesis / durasi audio) juga dapat digunakan untuk menilai kecepatan sintesis.Latensi audio pertama di sisi SDK mencakup pembuatan koneksi dan transmisi jaringan, sehingga bukan hanya waktu inferensi model. Untuk Qwen-Audio-TTS/CosyVoice, objek Python menyediakan get_first_package_delay() untuk latensi audio pertama dan get_last_request_id() untuk ID yang digunakan dalam korelasi log permintaan. Objek Java menyediakan getLastRequestId() untuk ID permintaan.
Pada maxTotal, peminjaman dari pool Java menunggu objek yang tersedia. Periksa kapasitas pool, pengembalian objek, dan penutupan koneksi untuk menghindari tambahan waktu tunggu objek.
Koneksi ulang massal saat startup, setelah gangguan jaringan, atau setelah banyak error server dapat menumpuk tugas. Setelah koneksi pulih, pengiriman tugas tersebut secara bersamaan dapat menyebabkan lonjakan dan memicu batas akun.Periksa masalah jaringan atau banyak error sebelum lonjakan, misalnya Requests rate limit exceeded, please try again later.. Kendalikan konkurensi saat startup dan pemulihan. Di Java, maxTotal membatasi jumlah objek yang dipinjam secara bersamaan dari pool yang sama.Periksa kuota akun. Untuk meminta peningkatan, ikuti prosedur pada Batas laju. Sesuaikan spesifikasi server atau tambah server sesuai beban aktual.
Periksa apakah bandwidth jaringan sudah mencapai batas atau konkurensi terlalu tinggi. Sesuaikan konkurensi atau spesifikasi server dengan beban kerja.