PaddleSpeech 在线流式 TTS 服务引擎(tts_engine)深度解析:从 Python 动态图推理到分块流式合成
PaddleSpeech 在线流式 TTS 服务引擎(tts_engine)深度解析:从 Python 动态图推理到分块流式合成
PaddleSpeech 的流式语音合成(Streaming TTS)服务由 paddlespeech/server/engine/tts/online/python/tts_engine.py 这一引擎模块承担,它被 docs/source/api/paddlespeech.server.engine.tts.online.python.tts_engine.rst 作为 API 文档入口引用。该模块定义了 TTSServerExecutor、TTSEngine 与 PaddleTTSConnectionHandler 三个核心类,完成从文本前端(Frontend)到声学模型(AM)再到声码器(Vocoder)的流式推理全链路,并通过 HTTP / WebSocket 对外提供音频分片输出。读完本文,你将掌握流式 TTS 服务的模块划分、配置项语义、分块(chunk)与去填充(depadding)原理,以及如何启动服务并用客户端验证。
一、模块定位与整体架构
1.1 引擎在整个服务架构中的位置
PaddleSpeech 的服务端采用「引擎池 + 路由」结构:服务启动时根据配置中的 engine_list 加载对应引擎实例,paddlespeech/server/engine/base_engine.py 定义了所有引擎的抽象基类 BaseEngine(基于 Singleton 元类),提供 init、run、postprocess 等标准接口。流式 TTS 引擎 TTSEngine 即继承自 BaseEngine,其实现文件位于:
- paddlespeech/server/engine/tts/online/python/tts_engine.py(本文主体,Python 动态图推理)
paddlespeech/server/engine/tts/online/onnx/(onnxruntime 推理版本,tts_online-onnx引擎)
网络协议层由 paddlespeech/server/ws/tts_api.py 提供:WebSocket 端点 /paddlespeech/tts/streaming 会根据 tts_engine.engine_type 动态选择加载 python.tts_engine 或 onnx.tts_engine 中的 PaddleTTSConnectionHandler,随后将收到的文本逐包交给 handler 处理,并把生成器 yield 出来的每一段 base64 音频实时回传客户端。
┌─────────────────────────────┐
│ paddlespeech_server start │
└─────────────┬───────────────┘
▼
┌──────────────────┐ ┌───────────────────────────────────────────┐
│ engine_pool │──────▶│ TTSEngine (BaseEngine 子类) │
└──────────────────┘ │ ├─ TTSServerExecutor(TTSExecutor) │
▲ │ │ ├─ frontend (zh/en) │
│ │ │ ├─ am_inference + am_mu/am_std │
┌─────────┴─────────┐ │ │ └─ voc_inference + voc_mu/voc_std │
│ ws/tts_api.py │ │ └─ PaddleTTSConnectionHandler │
│ /tts/streaming │ │ ├─ infer()(流式生成器) │
└─────────┬─────────┘ │ └─ run()(后处理 + base64) │
▼ └───────────────────────────────────────────┘
客户端(HTTP/WebSocket)
1.2 模块的三个核心类
| 类 | 职责 |
|---|---|
TTSServerExecutor |
继承自 paddlespeech/cli/tts/infer.py 的 TTSExecutor,负责模型资源下载、加载 AM/Voc 权重与统计量、初始化前端,构建推理用封装模型 |
TTSEngine |
服务引擎,读取 YAML 配置、校验模型组合与 chunk 参数、设置 device,持有 executor 并暴露 sample_rate、am_block/am_pad、voc_block/voc_pad 等流式参数 |
PaddleTTSConnectionHandler |
每次连接/会话的处理器,实现 infer() 流式推理生成器与 run() 后处理(float32→PCM16→base64),并统计首包响应时间与 RTF |
模块对外通过 __all__ = ['TTSEngine', 'PaddleTTSConnectionHandler'] 暴露两个公共符号(TTSServerExecutor 供引擎内部使用)。
二、配置解析:tts_online_application.yaml
流式 TTS 服务的完整配置见 paddlespeech/server/conf/tts_online_application.yaml(demo 使用的副本位于 demos/streaming_tts_server/conf/tts_online_application.yaml)。
2.1 服务级配置
host: 0.0.0.0
port: 8092
protocol: 'http' # 可选 'websocket'、'http'
engine_list: ['tts_online-onnx'] # 可选 'tts_online'、'tts_online-onnx'
engine_list中条目的命名格式为<speech task>_<engine type>,其中tts_online对应本文介绍的 Python 动态图引擎,tts_online-onnx对应 ONNX Runtime 推理引擎(推理速度更快)。protocol决定服务以 HTTP 还是 WebSocket 方式对外提供接口;WebSocket 场景下由 paddlespeech/server/ws/tts_api.py 的/paddlespeech/tts/streaming端点承载。- 若在容器中启动服务后客户端访问 IP 不可达,可尝试将
host改为本机实际 IP。
2.2 tts_online(Python 动态图引擎)配置
tts_online:
# 声学模型,可选 ['fastspeech2_csmsc', 'fastspeech2_cnndecoder_csmsc']
am: 'fastspeech2_csmsc'
am_config:
am_ckpt:
am_stat:
phones_dict:
tones_dict:
speaker_dict:
spk_id: 0
# 声码器,可选 ['mb_melgan_csmsc', 'hifigan_csmsc']
voc: 'mb_melgan_csmsc'
voc_config:
voc_ckpt:
voc_stat:
# 其它参数
lang: 'zh'
device: 'cpu' # 或 'gpu:id'
am_block: 72
am_pad: 12
voc_block: 36
voc_pad: 14
各字段说明:
| 参数 | 含义 |
|---|---|
am / voc |
声学模型与声码器标识。fastspeech2_cnndecoder_csmsc 支持流式 AM 推理;mb_melgan_csmsc 与 hifigan_csmsc 均支持流式 Voc 推理 |
am_config/am_ckpt/am_stat、voc_config/voc_ckpt/voc_stat |
若留空则使用 CommonTaskResource 自动下载的预训练模型;若指定则使用本地文件(此时 phones_dict 必填) |
phones_dict |
音素字典,声学模型前端的必要输入 |
lang |
语言,zh 使用 paddlespeech.t2s.frontend.zh_frontend.Frontend,en 使用 paddlespeech.t2s.frontend.en_frontend.English |
device |
推理设备,cpu 或 gpu:id;不配置时回退到 paddle.get_device() |
am_block / am_pad |
流式 AM 推理的 chunk 有效帧数与前后填充帧数。仅对 fastspeech2_cnndecoder_csmsc 生效 |
voc_block / voc_pad |
流式 Voc 推理的 chunk 有效帧数与前后填充帧数 |
2.3 关键约束与断言
在 TTSEngine.init() 中,配置会经过三重校验(对应 tts_engine.py):
- 模型组合断言:
am必须是fastspeech2_csmsc或fastspeech2_cnndecoder_csmsc,voc必须是hifigan_csmsc或mb_melgan_csmsc,否则启动报错。 - chunk 参数断言:
voc_block与voc_pad必须大于 0。 - 采样率一致性断言:
self.executor.am_config.fs必须等于self.executor.voc_config.fs,并以此作为服务对外输出的sample_rate。
同时,self.voc_upsample = self.executor.voc_config.n_shift(默认 300),表示每帧 mel 上采样到 300 个采样点,用于后续去填充时的帧-采样换算。
三、TTSServerExecutor:模型与资源初始化
TTSServerExecutor 在构造时创建 CommonTaskResource(task='tts', model_format='dynamic', inference_mode='online'),用于管理预训练模型资源。其核心方法如下。
3.1 get_model_info:加载 AM/Voc 模型与统计量
model_class = self.task_resource.get_model_class(model_name)
if field == "am":
odim = self.am_config.n_mels
model = model_class(idim=self.vocab_size, odim=odim, **self.am_config["model"])
model.set_state_dict(paddle.load(ckpt)["main_params"])
elif field == "voc":
model = model_class(**self.voc_config["generator_params"])
model.set_state_dict(paddle.load(ckpt)["generator_params"])
model.remove_weight_norm()
...
model_mu, model_std = np.load(stat) # 归一化统计量
return model, model_mu, model_std
要点:
- AM 侧从配置读取
n_mels作为输出维度,从phones_dict得到vocab_size作为输入维度;权重取自 checkpoint 的main_params。 - Voc 侧使用
generator_params构造生成器,加载generator_params权重并调用remove_weight_norm()去掉权重归一化(推理阶段不再需要)。 stat文件同时包含mu(均值)与std(标准差),二者会被包装成paddle.Tensor返回,作为 Z-Score 归一化器的参数。
3.2 _init_from_path:完整初始化流程
def _init_from_path(self, am='fastspeech2_csmsc', am_config=None, am_ckpt=None,
am_stat=None, phones_dict=None, tones_dict=None,
speaker_dict=None, voc='mb_melgan_csmsc', voc_config=None,
voc_ckpt=None, voc_stat=None, lang='zh'):
初始化逻辑(tts_engine.py):
- 幂等保护:若
am_inference与voc_inference已存在则直接返回,避免重复加载。 - AM 资源:若
am_ckpt/am_config/am_stat/phones_dict任一为空,则走预训练下载分支(use_pretrained_am=True),否则使用用户指定的本地文件路径;模型 tag 为am + '-' + lang。 - Voc 资源:同样的下载/本地判断逻辑,模型 tag 为
voc + '-' + lang。 - 读取配置与字典:将 AM/Voc 的 YAML 配置解析为
CfgNode,读取phones_dict得到vocab_size。 - 初始化前端:
zh语言用Frontend(支持phone_vocab_path与tone_vocab_path),en语言用English(仅phone_vocab_path)。 - 构建 AM 推理封装:模型名取
am[:am.rindex('_')](如fastspeech2_csmsc→fastspeech2);若为fastspeech2_cnndecoder则直接使用底层模型(其推理在 handler 中按 encoder/decoder/postnet 分步执行),否则用ZScore归一化器 +*_inference封装类构建self.am_inference。 - 构建 Voc 推理封装:
ZScore+*_inference封装类得到self.voc_inference。
四、TTSEngine:服务引擎与流式参数
class TTSEngine(BaseEngine):
def init(self, config: dict) -> bool:
self.executor = TTSServerExecutor()
self.config = config
self.lang = self.config.lang
self.engine_type = "online"
...
self.sample_rate = self.executor.am_config.fs
self.am_block = self.config.am_block
self.am_pad = self.config.am_pad
self.voc_block = self.config.voc_block
self.voc_pad = self.config.voc_pad
self.am_upsample = 1
self.voc_upsample = self.executor.voc_config.n_shift
初始化成功后打印 Initialize TTS server engine successfully on device: %s.,失败则记录日志并返回 False。其中 am_upsample = 1(AM 帧不额外上采样),voc_upsample = n_shift(通常 300)两个上采样倍数会被传给 PaddleTTSConnectionHandler,用于把 mel 帧数换算成音频采样点数。
五、PaddleTTSConnectionHandler:流式推理的核心实现
5.1 构造与参数传递
class PaddleTTSConnectionHandler:
def __init__(self, tts_engine):
self.tts_engine = tts_engine
self.executor = self.tts_engine.executor
self.config = self.tts_engine.config
self.am_block = self.tts_engine.am_block
...
该 handler 在 WebSocket 端点收到 signal == 'start' 时由 paddlespeech/server/ws/tts_api.py 创建,每次会话一个实例,与每个连接的生命周期绑定。
5.2 depadding:流式推理的误差消除
def depadding(self, data, chunk_num, chunk_id, block, pad, upsample):
front_pad = min(chunk_id * block, pad)
if chunk_id == 0: # 首块:保留前半段
data = data[:block * upsample]
elif chunk_id == chunk_num - 1: # 末块:去掉前填充
data = data[front_pad * upsample:]
else: # 中间块:去掉前后填充
data = data[front_pad * upsample:(front_pad + block) * upsample]
return data
由于分块推理时每个 chunk 前后都会额外带上 pad 帧上下文(用于抵消边界效应),合成结果中必须把这些填充帧对应的音频剪掉,才能无缝拼接出与整句推理一致的结果。首块、中间块、末块三种情况分别按 block * upsample 与 front_pad * upsample 进行裁剪,其中 upsample 是 mel 帧到采样点的放大倍数(AM 侧为 1,Voc 侧为 n_shift)。
5.3 infer:两条流式推理路径
infer() 是一个被 @paddle.no_grad() 装饰的生成器,其流程如下:
- 文本前端:
zh用frontend.get_input_ids(text, merge_sentences=False, get_tone_ids=False)得到phone_ids;en类似但不含 tone。前端耗时记录到self.frontend_time。 - 逐句循环:对每个句子的音素序列执行 AM→Voc 的流式合成,
first_flag标记首个音频块以统计首包延迟。
路径 A:fastspeech2_csmsc(整体 AM + 流式 Voc)
mel = self.executor.am_inference(part_phone_ids) # 整句合成 mel
mel_chunks = get_chunks(mel, self.voc_block, self.voc_pad, "voc")
for i, mel_chunk in enumerate(mel_chunks):
sub_wav = self.executor.voc_inference(mel_chunk) # 分块 voc 推理
sub_wav = self.depadding(sub_wav, voc_chunk_num, i,
self.voc_block, self.voc_pad, self.voc_upsample)
yield sub_wav
这里 AM 一次性合成整句 mel,只有声码器做流式分块,因此该模式不支持流式 AM,am_block/am_pad 对它无效。
路径 B:fastspeech2_cnndecoder_csmsc(AM、Voc 双流式)
orig_hs = self.executor.am_inference.encoder_infer(part_phone_ids) # encoder 一次前向
mel_len = orig_hs.shape[1]
voc_chunk_num = math.ceil(mel_len / self.voc_block)
hss = get_chunks(orig_hs, self.am_block, self.am_pad, "am") # 对 encoder 输出分块
for i, hs in enumerate(hss):
before_outs = self.executor.am_inference.decoder(hs) # 逐块 decoder
after_outs = before_outs + self.executor.am_inference.postnet(
before_outs.transpose((0, 2, 1))).transpose((0, 2, 1)) # postnet 残差
normalized_mel = after_outs[0]
sub_mel = denorm(normalized_mel, self.executor.am_mu, self.executor.am_std)
sub_mel = self.depadding(sub_mel, am_chunk_num, i,
self.am_block, self.am_pad, self.am_upsample)
mel_streaming = np.concatenate((mel_streaming, sub_mel), axis=0) # 累积 mel 流
while (mel_streaming.shape[0] >= end and voc_chunk_id < voc_chunk_num):
voc_chunk = mel_streaming[start:end, :]
sub_wav = self.executor.voc_inference(voc_chunk)
sub_wav = self.depadding(sub_wav, voc_chunk_num, voc_chunk_id,
self.voc_block, self.voc_pad, self.voc_upsample)
yield sub_wav
voc_chunk_id += 1
start = max(0, voc_chunk_id * self.voc_block - self.voc_pad)
end = min((voc_chunk_id + 1) * self.voc_block + self.voc_pad, mel_len)
该模式将 encoder 一次性前向(hidden states 不含填充),随后 decoder + postnet 按 am_block 分块流式产出 mel 帧;denorm(data * std + mean,定义于 paddlespeech/server/utils/util.py)将归一化后的 mel 还原为真实值。累积的 mel_streaming 一旦达到 voc_block + voc_pad 的窗口长度,就触发一轮流式 Voc 推理并 yield 一段音频,实现 AM 与 Voc 两级流水线式的低延迟输出。
5.4 get_chunks 与窗口滑动
分块工具函数 get_chunks 也在 paddlespeech/server/utils/util.py 中:
def get_chunks(data, block_size, pad_size, step):
if block_size == -1:
return [data] # 不分块
data_len = data.shape[1] if step == "am" else data.shape[0]
chunks = []
n = math.ceil(data_len / block_size)
for i in range(n):
start = max(0, i * block_size - pad_size)
end = min((i + 1) * block_size + pad_size, data_len)
...
return chunks
每个 chunk 的窗口为 [i*block - pad, (i+1)*block + pad),相邻 chunk 之间有 2*pad 的重叠区域,这正是流式推理消除边界误差的来源。step 参数区分 AM(按时间维 shape[1] 切分)与 Voc(按 mel 帧维 shape[0] 切分)。
5.5 run:后处理与指标统计
def run(self, sentence, spk_id=0):
wav_list = []
for wav in self.infer(text=sentence, lang=self.config.lang,
am=self.config.am, spk_id=spk_id):
wav = float2pcm(wav) # float32 -> int16
wav_bytes = wav.tobytes()
wav_base64 = base64.b64encode(wav_bytes).decode('utf8')
wav_list.append(wav)
yield wav_base64
...
logger.info(f"The durations of audio is: {duration} s")
logger.info(f"first response time: {self.first_response_time} s")
logger.info(f"final response time: {self.final_response_time} s")
logger.info(f"RTF: {self.final_response_time / duration}")
float2pcm位于 paddlespeech/server/utils/audio_process.py,将范围在 [-1, 1] 的 float32 音频缩放到 int16 PCM,并通过base64.b64encode编码后逐块yield,WebSocket 端收到后以{"status": 1, "audio": <base64>}逐包下发,最后以{"status": 2}标记合成完成。- 指标统计:
first_response_time(首包响应时间,从前端开始到首个 Voc 输出)、final_response_time(整句完成时间)、RTF(Real-Time Factor,合成耗时/音频时长)。服务端日志可用count_engine(见 paddlespeech/server/utils/util.py)批量统计平均首包、平均尾包与平均 RTF。
六、流式 chunk 参数的工程调优
chunk 参数直接决定延迟与音质的平衡,仓库文档与配置注释给出的经验值如下:
| 参数 | 推荐值 | 说明 |
|---|---|---|
am_block |
72 | 流式 AM 每次推理的有效帧数(仅 fastspeech2_cnndecoder 生效) |
am_pad |
12 | 流式 AM 前后填充帧数;am_pad=12 时流式合成音频与非流式一致 |
voc_block |
36 | 流式 Voc 每次推理的有效 mel 帧数 |
voc_pad(mb_melgan) |
14 | 与非流式一致;最小可设 7(听感正常),小于 7 会出现听感异常 |
voc_pad(hifigan) |
19 | 与非流式一致;设为 14 听感正常 |
调参原则:block 越小、pad 越小,首包延迟越低,但过小的 pad 会引入拼接误差与音质劣化;反之则音质更接近整句推理但延迟上升。Voc 模型的 pad 计算方法可参考配置注释中提到的 AIStudio 教程思路(PaddleSpeech 流式声码器 Pad 计算)。此外,voc_upsample 应与 voc 配置中的 n_shift 一致(默认 300),保证去填充的采样点换算正确。
七、服务启动与客户端调用
7.1 启动服务
命令行方式(推荐):
paddlespeech_server start --config_file ./conf/tts_online_application.yaml
其中 --config_file 默认为 ./conf/tts_online_application.yaml,--log_file 默认为 ./log/paddlespeech.log。启动成功后日志会出现 Uvicorn running on http://0.0.0.0:8092,并伴随若干次 warm-up 的首包响应时间输出。
Python API 方式:
from paddlespeech.server.bin.paddlespeech_server import ServerExecutor
server_executor = ServerExecutor()
server_executor(config_file="./conf/tts_online_application.yaml",
log_file="./log/paddlespeech.log")
7.2 客户端调用
HTTP 协议:
paddlespeech_client tts_online --server_ip 127.0.0.1 --port 8092 --protocol http --input "您好,欢迎使用百度飞桨语音合成服务。" --output output.wav
WebSocket 协议:
paddlespeech_client tts_online --server_ip 127.0.0.1 --port 8092 --protocol websocket --input "您好,欢迎使用百度飞桨语音合成服务。" --output output.wav
客户端常用参数:--server_ip(默认 127.0.0.1)、--port(默认 8092)、--protocol(可选 http/websocket,默认 http)、--input(待合成文本)、--output(输出音频文件)。若 127.0.0.1 不可访问,应使用实际服务 IP。完整的服务端/客户端使用步骤还可参考 demos/streaming_tts_server/README_cn.md。
八、测试验证与实现佐证
仓库在 tests/unit/server/online/tts/check_server/ 提供了流式 TTS 服务的自动化验证脚本 test.sh:
- 遍历
tts_online引擎在fastspeech2_cnndecoder_csmsc/fastspeech2_csmsc×mb_melgan_csmsc/hifigan_csmsc四种 AM/Voc 组合下的 HTTP 服务启动与客户端合成; - 再通过修改配置中的
protocol为 websocket,重复四组组合的 WebSocket 验证; - 启动阶段以
Uvicorn running on http://判断服务就绪,以Failed to warm up on tts engine.或AssertionError判断启动失败;HTTP 侧以200 OK计数、WebSocket 侧以Complete the synthesis of the audio streams计数判定测试通过。
该测试脚本使用的客户端命令与配置亦与本文第 2、7 节描述的字段一一对应,可作为引擎行为正确性的直接验证依据。
九、小结
paddlespeech.server.engine.tts.online.python.tts_engine 是 PaddleSpeech 流式语音合成服务的 Python 动态图实现核心:TTSServerExecutor 负责模型与前端装配,TTSEngine 负责配置校验与流式参数提取,PaddleTTSConnectionHandler 通过 get_chunks 分块、depadding 去填充、生成器逐块输出,实现了「文本→音素→mel→PCM16→base64」的低延迟流式链路,并配套首包响应时间与 RTF 指标。理解该模块的 chunk 窗口与去填充机制,是调优流式 TTS 延迟-音质平衡、以及为线上服务选型 tts_online / tts_online-onnx 引擎的前提。