介紹語音合成的文字提交、音訊處理、連線與並行資源管理,以及效能評估與問題診斷的最佳實務。
文字提交與任務控制
使用複製音色或設計音色時,合成模型須與建立音色時指定的目標模型一致。音色建立要求請參閱音色複製或音色設計。
文字分段與傳送時序
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 設定,後面的物件集區容量變數由範例程式碼自訂:
| 環境變數 | 預設值 | 說明 |
|---|---|---|
| 32 | 底層 OkHttp 閒置連線集區的設定。 |
| 32 | 底層非同步請求排程的最大請求數。 |
| 32 | 底層非同步請求排程的單主機最大請求數。 |
| 500 | 本文 Qwen-Audio-TTS/CosyVoice Java 範例的物件集區容量,對應 |
本文 Java 範例將 maxIdle 和 maxTotal 設為相同值,減少閒置物件銷毀後再次建立的開銷。銷毀物件時應關閉其連線。達到 maxTotal 後,新的借用請求將等待可用物件。
物件生命週期
設定 API Key 和接入位址後,建立共用物件集區,供業務任務借用。
Java SDK
- 呼叫
borrowObject借用物件。對於 Qwen-Audio-TTS/CosyVoice,每次借出後都須呼叫updateParamAndCallback(param, callback)設定本次任務的參數與回呼。 - Qwen-Audio-TTS/CosyVoice 使用
call或streamingCall執行合成。 - 任務正常完成後,呼叫
returnObject歸還物件;未完成或失敗時,使用invalidateObject廢棄物件,並由工廠關閉連線,不得直接歸還。 - 所有任務結束後,呼叫物件集區的
close(),釋放集區資源。
Java 中,若 maxIdle 小於 maxTotal,物件歸還時超出閒置容量的物件會被銷毀。如果工廠的 destroyObject 沒有關閉 WebSocket,連線可能在物件銷毀後仍保持開啟。
Python SDK
- 呼叫
borrow_synthesizer借用物件,傳入模型、音色、格式與回呼。 - 呼叫
call或streaming_call執行合成。 - 任務正常完成後,呼叫
return_synthesizer歸還物件;未完成或失敗時,呼叫物件的close(),不得直接歸還。 - 所有任務結束後,呼叫
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 限制同一集區同時借出的物件數。
核對帳號限流額度;需要提高額度時,按限流中的流程申請。 根據實際負載調整伺服器設定或增加機器數。
網路頻寬與伺服器負載
檢查網路頻寬是否達到上限,以及實際並行數是否過高,再根據業務負載調整並行數或伺服器設定。