全部產品
Search
文件中心

Alibaba Cloud Model Studio:語音合成最佳實務

更新時間:Nov 13, 2026

介紹語音合成的文字提交、音訊處理、連線與並行資源管理,以及效能評估與問題診斷的最佳實務。

文字提交與任務控制

使用複製音色或設計音色時,合成模型須與建立音色時指定的目標模型一致。音色建立要求請參閱音色複製或音色設計。

文字分段與傳送時序

Qwen-Audio-TTS、CosyVoice 透過 WebSocket 接入時,收到 task-started 後再依序傳送文字片段。伺服器自動分句:完整語句立即合成,不完整語句暫存,直到語句完整或收到 finish-task 時再合成。

分段輸入時,過長的傳送間隔會增加合成總耗時;若上一段音訊已播放完畢、下一段文字尚未送達,也會造成播放停頓。單次文字長度、累計長度與傳送間隔限制,請參閱 Qwen-Audio-TTS 用戶端事件或 CosyVoice 用戶端事件。

說明使用 SSML 時須一次提交完整的 SSML 文字,不支援分段輸入。支援的模型、音色與介面請參閱 SSML 與 LaTeX。

任務完成與取消

透過 WebSocket 原始協定呼叫 Qwen-Audio-TTS、CosyVoice 時,文字傳送完畢後,傳送 finish-task 通知伺服器結束輸入,並持續接收音訊,直到收到 task-finished。省略結束通知可能導致音訊資料不完整。

需要中斷本輪合成時,使用取消任務功能;伺服器結束任務並傳回 task-finished。各 SDK 與原始協定的用法及適用條件請參閱取消任務。

音訊接收與播放

音訊接收與儲存

Qwen-Audio-TTS、CosyVoice 依接入方式傳回不同形式的音訊:

  • HTTP 非串流輸出:從 output.audio.url 取得完整音訊檔案。URL 有效期為 24 小時,須及時下載儲存;到期後可重新合成。
  • HTTP SSE 串流輸出:output.audio.data 為 Base64 編碼的音訊片段,依接收順序解碼並附加至同一檔案。傳回欄位請參閱 Qwen-Audio-TTS HTTP API與 CosyVoice HTTP API。
  • WebSocket 原始協定:透過 binary 通道接收音訊,文字事件傳遞句子等資訊。互動流程請參閱 Qwen-Audio-TTS WebSocket API與 CosyVoice WebSocket API。

音訊格式與播放器相容性

儲存完整音訊檔案時,請求中的音訊格式須與副檔名一致,並確認播放器支援對應格式與取樣率。串流播放異常時,可先將音訊流儲存為完整檔案:若檔案也無法播放,檢查格式與播放器;若檔案正常,則檢查播放實作是否支援串流音訊,例如 ffmpeg、pyaudio、AudioFormat、MediaSource 等。

串流傳回 WAV 時,檔頭可能無法反映最終音訊長度。如需準確的時長資訊,可將 format 設為 pcm,接收完整音訊後加入包含實際長度的 WAV 檔頭。

回呼與播放排程

即時合成的回呼在 WebSocket 執行緒執行,阻塞性業務邏輯會影響音訊接收。可將音訊寫入獨立緩衝區,在其他執行緒處理。播放停頓時,也須檢查文字傳送速度與網路穩定性;網路波動可能導致音訊傳輸中斷或延遲。

連線與並行資源管理

連線重用與任務隔離

透過原始 WebSocket 協定呼叫 Qwen-Audio-TTS、CosyVoice 時,同一連線可依序處理多輪合成。收到本輪 task-finished 後,必須使用新的 task_id 傳送 run-task,再按該系列的流程傳送文字;取消任務後也依此流程重用連線。

對於 Qwen-Audio-TTS、CosyVoice,任務結束後閒置 60 秒會自動中斷連線。長時間閒置後的呼叫應按重新建立連線的情況評估。

使用 Python SDK 的 client.audio.tts.connect 時,工作階段在任務結束或取消後預設關閉底層連線。需要重用連線時,可先透過 client.ws_connection() 建立共用連線,再以 connection= 傳入工作階段;由呼叫端透過 WsConnection.close 關閉共用連線。

驗證身分與隔離範圍

API Key 僅在 WebSocket 建立連線的交握階段透過 Authorization 請求標頭驗證,後續 run-task 訊息不攜帶 API Key。重用連線期間,修改參數或全域設定中的 API Key 不會改變該連線的驗證身分,可能導致身分、額度或計費歸屬與預期不一致。

Java SDK

Java 為不同 API Key 建立獨立物件集區,同一集區始終使用相同的 API Key。Qwen-Audio-TTS/CosyVoice 每次借出物件後都應呼叫 updateParamAndCallback,但該方法不會為已有連線重新驗證。

Python SDK

Python 應在建立集區前設定 dashscope.api_key。集區初始化時建立的連線沿用交握時的 API Key,borrow_synthesizer 不提供 API Key 參數。SpeechSynthesizerObjectPool 是程序內單例,多 API Key 應按程序隔離。

並行與資源規劃

物件集區保留合成物件及其 WebSocket 連線,減少重複建立物件、TCP/TLS 交握和通訊協定升級的開銷。支援的模型系列與 SDK 如下:

  • Qwen-Audio-TTS、CosyVoice:Python、Java 物件集區。

根據預期同時執行的任務數和伺服器規格設定資源集區。模型限流按主帳號統計,RAM 使用者、工作空間和 API Key 共用主帳號的額度;各模型的呼叫頻率和並行限制請參見限流。

物件集區容量可從峰值並行數的 1.5~2 倍開始設定,並根據實際負載調整。 Python 集區內的物件全部借出後,仍可能建立額外物件;這些物件在使用時需要建立新連線。

伺服器設定參考

以下為僅執行相應語音合成服務時的阿里雲伺服器參考設定。單機並行數指同一時間執行的合成任務數,可根據實際負載調整設定。

表中的「連線集區設定」同時作為 DASHSCOPE_CONNECTION_POOL_SIZE、DASHSCOPE_MAXIMUM_ASYNC_REQUESTS 和 DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST 的參考值,即三項均設為 2000;物件集區容量使用對應範例的環境變數設定。

系列阿里雲伺服器規格單機並行數物件集區容量連線集區設定

CosyVoice

4 vCPU / 8 GiB

100

500

2000

CosyVoice

8 vCPU / 16 GiB

150

500

2000

CosyVoice

16 vCPU / 32 GiB

200

500

2000

Java 資源集區參數

SDK 環境變數應在 Java 程序啟動前設定。下列前 3 項是 SDK 設定,後面的物件集區容量變數由範例程式碼自訂:

環境變數預設值說明

DASHSCOPE_CONNECTION_POOL_SIZE

32

底層 OkHttp 閒置連線集區的設定。

DASHSCOPE_MAXIMUM_ASYNC_REQUESTS

32

底層非同步請求排程的最大請求數。

DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST

32

底層非同步請求排程的單主機最大請求數。

COSYVOICE_OBJECTPOOL_SIZE

500

本文 Qwen-Audio-TTS/CosyVoice Java 範例的物件集區容量,對應 maxTotal 和 maxIdle,不是 SDK 內建參數。

本文 Java 範例將 maxIdle 和 maxTotal 設為相同值,減少閒置物件銷毀後再次建立的開銷。銷毀物件時應關閉其連線。達到 maxTotal 後,新的借用請求將等待可用物件。

物件生命週期

設定 API Key 和接入位址後,建立共用物件集區,供業務任務借用。

Java SDK

  1. 呼叫 borrowObject 借用物件。對於 Qwen-Audio-TTS/CosyVoice,每次借出後都須呼叫 updateParamAndCallback(param, callback) 設定本次任務的參數與回呼。
  2. Qwen-Audio-TTS/CosyVoice 使用 call 或 streamingCall 執行合成。
  3. 任務正常完成後,呼叫 returnObject 歸還物件;未完成或失敗時,使用 invalidateObject 廢棄物件,並由工廠關閉連線,不得直接歸還。
  4. 所有任務結束後,呼叫物件集區的 close(),釋放集區資源。

Java 中,若 maxIdle 小於 maxTotal,物件歸還時超出閒置容量的物件會被銷毀。如果工廠的 destroyObject 沒有關閉 WebSocket,連線可能在物件銷毀後仍保持開啟。

Python SDK

  1. 呼叫 borrow_synthesizer 借用物件,傳入模型、音色、格式與回呼。
  2. 呼叫 call 或 streaming_call 執行合成。
  3. 任務正常完成後,呼叫 return_synthesizer 歸還物件;未完成或失敗時,呼叫物件的 close(),不得直接歸還。
  4. 所有任務結束後,呼叫 shutdown(),釋放集區資源。

用戶端異常中斷任務後,服務端可能仍認為上一輪任務正在執行。此時重用連線傳送新的 run-task 會造成協定順序錯誤(Invalid action('run-task')! Please follow the protocol!)。應關閉連線並廢棄該物件,再建立新連線執行後續任務。

頻繁建立合成物件而未關閉舊連線,會使連線數持續增長,增加伺服器資源開銷。檢查任務結束後是否正確歸還物件,以及不再使用的連線是否關閉。

物件集區呼叫範例

  • 取得 API Key並設定 DASHSCOPE_API_KEY,使用與呼叫地區對應的 API Key。
  • 將範例中的 {WorkspaceId} 取代為對應地區的業務空間 ID,並按地區設定 WebSocket 位址。

Java SDK

  • Qwen-Audio-TTS、CosyVoice:DashScope Java SDK 2.16.6 及以上版本。

Java 範例還需要 Apache Commons Pool 2,可透過 Maven 或 Gradle 設定相依套件:

<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>
dependencies {
    implementation 'com.alibaba:dashscope-sdk-java:2.23.2'
    implementation 'org.apache.commons:commons-pool2:2.12.0'
}

Python SDK

Qwen-Audio-TTS、CosyVoice 的物件集區需要 DashScope Python SDK 1.25.2 及以上版本:

pip install "dashscope>=1.25.2"

以下範例使用 qwen-audio-3.1-tts-flash 和 longanhuan_v3.1,並行執行 3 次合成。使用 CosyVoice 時,可將模型和音色分別改為 cosyvoice-v3-flash 和 longanyang;其他模型選擇與音色要求參見即時語音合成。

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("你好,欢迎使用阿里云百炼。");
            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();
        }
    }
}
import os
import threading
from concurrent.futures import ThreadPoolExecutor
import dashscope
from dashscope.audio.tts_v2 import SpeechSynthesizerObjectPool, ResultCallback, AudioFormat

dashscope.api_key = os.environ["DASHSCOPE_API_KEY"]
dashscope.base_websocket_api_url = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference"
pool = SpeechSynthesizerObjectPool(max_size=3)

def synthesize(index):
    done = threading.Event()
    errors = []
    with open(f"output_{index}.mp3", "wb") as audio:
        class Callback(ResultCallback):
            def on_data(self, data: bytes):
                audio.write(data)

            def on_complete(self):
                done.set()

            def on_error(self, message):
                errors.append(message)
                done.set()

        synthesizer = pool.borrow_synthesizer(
            model="qwen-audio-3.1-tts-flash",
            voice="longanhuan_v3.1",
            format=AudioFormat.MP3_24000HZ_MONO_256KBPS,
            callback=Callback(),
        )
        successful = False
        try:
            synthesizer.streaming_call("你好,欢迎使用阿里云百炼。")
            synthesizer.streaming_complete(60000)
            if not done.wait(60):
                raise TimeoutError("Synthesis timed out")
            if errors:
                raise RuntimeError(errors[0])
            successful = True
        finally:
            if successful:
                pool.return_synthesizer(synthesizer)
            else:
                synthesizer.close()

try:
    with ThreadPoolExecutor(max_workers=3) as executor:
        list(executor.map(synthesize, range(3)))
finally:
    pool.shutdown()

效能評估與問題診斷

連線預熱與啟動恢復

Python 物件集區初始化時會建立連線;Java GenericObjectPool 按需建立物件,首次合成時才建立連線,因此 Java 連線預熱需要實際執行合成請求。

服務啟動或網路恢復後先執行預熱呼叫,逐步提高並行數。效能測試前,可按目標並行數持續預熱(例如 1~2 分鐘),待連線穩定重用後再收集資料。 逐步提高並行數可避免同時建立大量 WebSocket 連線造成阻塞。

延遲與即時率評估

首次呼叫包含 WebSocket 建立連線的開銷,應與重用連線後的首包延遲和任務總耗時分別統計。也可透過即時率(RTF,合成總耗時 / 音訊時長)評估合成速度。

SDK 端首包延遲包含建立連線和網路傳輸等耗時,不等同於純模型推論耗時。Qwen-Audio-TTS/CosyVoice 的 Python 物件可透過 get_first_package_delay() 取得首包延遲,並透過 get_last_request_id() 取得請求 ID,用於關聯請求記錄。Java 物件透過 getLastRequestId() 取得請求 ID。

物件集區借用等待與逾時

Java 物件集區達到 maxTotal 後,借用操作會等待可用物件。檢查集區容量、物件歸還及連線關閉情況,避免任務因等待物件而增加耗時。

請求尖峰與限流

服務啟動、網路中斷或大量服務端錯誤後,集中重連可能使任務積壓;連線恢復後,積壓任務同時提交又會形成呼叫尖峰,並可能觸發帳號限流。

檢查尖峰前是否出現網路異常或大量服務端錯誤,例如 Requests rate limit exceeded, please try again later.。 控制啟動和恢復階段的並行數。Java 可透過物件集區的 maxTotal 限制同一集區同時借出的物件數。

核對帳號限流額度;需要提高額度時,按限流中的流程申請。 根據實際負載調整伺服器設定或增加機器數。

網路頻寬與伺服器負載

檢查網路頻寬是否達到上限,以及實際並行數是否過高,再根據業務負載調整並行數或伺服器設定。