PaddleSpeech TTS 推理引擎源码解析:基于 Paddle Inference 的离线语音合成服务实现
PaddleSpeech TTS 推理引擎源码解析:基于 Paddle Inference 的离线语音合成服务实现
导读
本文以 PaddleSpeech 服务端 TTS 模块的 Paddle Inference 推理引擎(即 paddlespeech.server.engine.tts.paddleinference.tts_engine 模块)为绝对主体,深入讲解该引擎如何借助静态图模型(pdmodel/pdiparams)完成文本到语音的合成,并服务于 HTTP/REST 与 WebSocket 接口。读完本文,你将掌握 TTSServerExecutor、TTSEngine、PaddleTTSConnectionHandler 三个核心类的职责划分、tts_inference 配置项的完整含义,以及从请求进入、文本前端处理、声学模型推理、声码器合成到音频后处理(变采样率、调音量、变速、base64 编码)的完整调用链。
本文对应的 API 文档入口为 docs/source/api/paddlespeech.server.engine.tts.paddleinference.tts_engine.rst,该 RST 通过
automodule指令自动生成模块文档;本文以其背后的真实实现 tts_engine.py 为主线展开。
一、模块定位:离线 TTS 服务的 "inference" 引擎
在 PaddleSpeech 的服务端架构中,同一个语音任务可以有不同的引擎实现。TTS 任务在 engine_factory.py 中被区分出四种引擎类型:
tts_python:动态图(Python 前向)实现,便于调试;tts_inference:静态图 Paddle Inference 实现(本文主角),部署性能更优;tts_online/tts_online-onnx:流式(流式/Online)TTS 实现。
EngineFactory.get_engine("tts", "inference") 会懒加载并返回本模块的 TTSEngine(engine_factory.py):
elif engine_name == 'tts' and engine_type == 'inference':
from paddlespeech.server.engine.tts.paddleinference.tts_engine import TTSEngine
return TTSEngine()
因此本模块承载的是“离线(整句合成)TTS + Paddle Inference 静态模型推理”的服务端引擎。模块对外导出的核心符号为(tts_engine.py):
__all__ = ['TTSEngine', 'PaddleTTSConnectionHandler']
三个类按照“执行器 / 引擎 / 连接处理器”三层协作,职责如下表:
| 类 | 继承 | 职责 |
|---|---|---|
TTSServerExecutor |
TTSExecutor |
模型资源加载(_init_from_path)与推理(infer),内部持有前端(frontend)、AM/Vocoder 两个 predictor |
TTSEngine |
BaseEngine(Singleton) |
引擎级初始化入口 init(config),负责设备设置与执行器初始化 |
PaddleTTSConnectionHandler |
TTSServerExecutor |
处理每一次 TTS 请求,负责 run(推理+后处理)与 postprocess(音频变换与编码) |
二、模型资源与参数:静态图 TTS 的配置体系
2.1 tts_inference 完整配置说明
离线 TTS 推理引擎的配置位于服务端主配置 application.yaml。下面是该配置段的完整内容与逐项说明:
################### speech task: tts; engine_type: inference #######################
tts_inference:
# am (acoustic model) choices=['speedyspeech_csmsc', 'fastspeech2_csmsc']
am: 'fastspeech2_csmsc'
am_model: # the pdmodel file of your am static model (XX.pdmodel)
am_params: # the pdiparams file of your am static model (XX.pdipparams)
am_sample_rate: 24000
phones_dict:
tones_dict:
speaker_dict:
spk_id: 0
am_predictor_conf:
device: # set 'gpu:id' or 'cpu'
switch_ir_optim: True
glog_info: False # True -> print glog
summary: True # False -> do not show predictor config
# voc (vocoder) choices=['pwgan_csmsc', 'mb_melgan_csmsc','hifigan_csmsc']
voc: 'pwgan_csmsc'
voc_model: # the pdmodel file of your vocoder static model (XX.pdmodel)
voc_params: # the pdiparams file of your vocoder static model (XX.pdipparams)
voc_sample_rate: 24000
voc_predictor_conf:
device: # set 'gpu:id' or 'cpu'
switch_ir_optim: True
glog_info: False # True -> print glog
summary: True # False -> do not show predictor config
# others
lang: 'zh'
参数含义速查:
| 配置项 | 含义 | 默认/取值 |
|---|---|---|
am |
声学模型标签 | speedyspeech_csmsc、fastspeech2_csmsc 等 |
am_model / am_params |
声学模型静态模型文件 | *.pdmodel / *.pdiparams,留空则自动下载预训练模型 |
am_sample_rate |
声学模型输出采样率 | 24000 |
phones_dict |
音素字典 | 中文需配合 tones_dict |
tones_dict |
声调字典 | 仅 speedyspeech 需要 |
speaker_dict |
说话人字典 | 仅多说话人模型(如 aishell3/vctk)需要 |
spk_id |
说话人 ID | 0 |
voc |
声码器标签 | pwgan_csmsc、mb_melgan_csmsc、hifigan_csmsc |
voc_model / voc_params |
声码器静态模型文件 | *.pdmodel / *.pdiparams |
voc_sample_rate |
声码器输出采样率 | 24000 |
lang |
合成语言 | zh / en |
am_predictor_conf / voc_predictor_conf |
两个 Paddle Inference Predictor 的配置 | 见下文 |
2.2 predictor 配置与底层实现
am_predictor_conf 与 voc_predictor_conf 直接透传给 init_predictor(paddle_predictor.py):
def init_predictor(model_dir=None, model_file=None, params_file=None, predictor_conf=None):
...
# set device
if predictor_conf["device"]:
device = predictor_conf["device"]
else:
device = paddle.get_device()
if "gpu" in device:
gpu_id = device.split(":")[-1]
config.enable_use_gpu(1000, int(gpu_id))
# IR optim
if predictor_conf["switch_ir_optim"]:
config.switch_ir_optim()
# glog
if not predictor_conf["glog_info"]:
config.disable_glog_info()
# config summary
if predictor_conf["summary"]:
print(config.summary())
# memory optim
config.enable_memory_optim()
predictor = create_predictor(config)
return predictor
四个配置项的作用:
device:取值gpu:id或cpu。当包含gpu时通过config.enable_use_gpu(1000, int(gpu_id))开启 GPU,显存初始设为 1000MB;switch_ir_optim:是否开启 Paddle Inference 的 IR 计算图优化;glog_info:是否打印 Paddle Inference 底层 glog 日志(生产环境建议False);summary:是否打印 predictor 的配置摘要。
推理调用则由 run_model 完成(paddle_predictor.py):按输入名逐个 copy_from_cpu 拷贝数据、执行 predictor.run(),再按输出名 copy_to_cpu 取回结果列表。
2.3 模型资源的自动下载与本地指定
TTSServerExecutor._init_from_path 展示了“预训练模型自动下载”与“本地静态模型显式指定”两种加载路径:
- 当
am_model、am_params、phones_dict均为空时,use_pretrained_am=True,引擎通过CommonTaskResource(task='tts', model_format='static')按am + '-' + lang的标签(如fastspeech2_csmsc-zh)自动下载预训练静态模型,并从资源字典中解析model、params、phones_dict、sample_rate; - 反之则使用用户显式指定的本地文件,并通过
os.path.abspath归一化路径。
声码器部分(voc_tag = voc + '-' + lang)走完全相同的逻辑。加载完成后有一个关键断言(tts_engine.py):
assert (self.voc_sample_rate == self.am_sample_rate), \
"The sample rate of AM and Vocoder model are different, please check model."
即声学模型与声码器的采样率必须一致,否则拒绝初始化。
2.4 词表与前端初始化
加载词表时,引擎逐个统计音素、声调、说话人的数量(tts_engine.py):
phones_dict行数得到vocab_size(音素表大小);tones_dict存在时得到tone_size(声调表大小,仅speedyspeech使用);speaker_dict存在时得到spk_num(说话人数量,多说话人模型使用)。
随后按语言选择文本前端(tts_engine.py):
lang == 'zh':Frontend(phone_vocab_path=..., tone_vocab_path=...)(来自paddlespeech.t2s.frontend.zh_frontend);lang == 'en':English(phone_vocab_path=...)(来自paddlespeech.t2s.frontend.en_frontend)。
三、TTSEngine:服务端引擎的单例初始化流程
TTSEngine 继承自 BaseEngine。后者是服务端所有引擎的公共基类(base_engine.py),通过 pattern_singleton.Singleton 元类保证单例,并预留了 init、postprocess、run 三个抽象方法。
TTSEngine.init(config) 的完整流程(tts_engine.py):
- 创建执行器:实例化
TTSServerExecutor(),保存配置对象,标记self.engine_type = "inference"; - 设置设备:优先取
am_predictor_conf.device,其次voc_predictor_conf.device,兜底使用paddle.get_device(),随后paddle.set_device(self.device)。任一环节异常都会记录错误并返回False; - 加载模型:调用
self.executor._init_from_path(...),将配置中的am、am_model、am_params、am_sample_rate、phones_dict、tones_dict、speaker_dict、voc、voc_model、voc_params、voc_sample_rate、lang、am_predictor_conf、voc_predictor_conf全部透传; - 全部成功后在日志输出
Initialize TTS server engine successfully on device: %s.并返回True。
四、推理执行器:TTSServerExecutor.infer 的合成流水线
infer 方法(tts_engine.py)在 @paddle.no_grad() 下执行,是整个合成流水线的核心。其步骤为:
- 解析模型名:
am_name = am[:am.rindex('_')]取模型主体(如fastspeech2/speedyspeech),am_dataset = am[am.rindex('_') + 1:]取数据集后缀(如csmsc/aishell3/vctk); - 文本前端:
speedyspeech需要声调(get_tone_ids=True)。中文走self.frontend.get_input_ids(text, merge_sentences=False, get_tone_ids=...),英文走English.get_input_ids,均返回按句切分的phone_ids列表(必要时含tone_ids)。此段耗时计入self.frontend_time; - 逐句推理:对每个句子的
phone_ids:- AM(声学模型):
speedyspeech同时喂入phone_ids与tone_ids;fastspeech2类模型若数据集是aishell3/vctk(多说话人),额外喂入np.array([spk_id]),否则仅喂phone_ids。输出为梅尔谱mel; - Vocoder(声码器):将
mel喂入voc_predictor得到wav,转成 paddle tensor 并按句paddle.concat拼接为完整wav_all; - 两段耗时分别累计到
self.am_time与self.voc_time;
- AM(声学模型):
- 结果写入
self._outputs["wav"]。
从源码结构可以推断,离线推理引擎之所以按“句”循环,是因为文本前端 get_input_ids 会把长文本按标点切分为多个句子,逐句推理后拼接,以降低单次推理的显存/内存峰值。
五、连接处理器:PaddleTTSConnectionHandler 的请求处理链路
PaddleTTSConnectionHandler(tts_engine.py)每次请求都会在 REST API 层被创建(见 tts_api.py):
elif tts_engine.engine_type == "inference":
from paddlespeech.server.engine.tts.paddleinference.tts_engine import PaddleTTSConnectionHandler
...
connection_handler = PaddleTTSConnectionHandler(tts_engine)
lang, target_sample_rate, duration, wav_base64 = connection_handler.run(
text, spk_id, speed, volume, sample_rate, save_path)
构造函数直接引用引擎已初始化好的 frontend、am_predictor、voc_predictor,避免重复加载模型。
5.1 run:一次 TTS 请求的完整响应
run(sentence, spk_id=0, speed=1.0, volume=1.0, sample_rate=0, save_path=None) 的参数约定:
| 参数 | 类型 | 含义 | 校验范围 |
|---|---|---|---|
sentence |
str | 待合成文本 | 必填 |
spk_id |
int | 说话人 ID | 默认 0 |
speed |
float | 语速 | 0 < speed <= 3.0,默认 1.0 |
volume |
float | 音量(相对模型合成音频) | 0 < volume <= 3.0,默认 1.0 |
sample_rate |
int | 目标采样率,0 表示保持模型采样率 |
可选 0 / 16000 / 8000 |
save_path |
str | 保存路径,支持 wav/pcm |
默认 None |
run 内部依次执行推理与后处理,并统计多项指标(tts_engine.py):
infer_time:前端 + AM + Vocoder 的总推理耗时;duration:合成音频时长(len(wav) / am_sample_rate);rtf = infer_time / duration:实时率(Real-Time Factor),衡量合成速度;postprocess_time:后处理耗时(变速、调音量、变采样率、编码)。
最终返回 (lang, target_sample_rate, duration, wav_base64) 四元组。
5.2 postprocess:采样率、音量、速度与编码
postprocess(wav, original_fs, target_fs=0, volume=1.0, speed=1.0, audio_path=None) 按顺序执行四步音频处理(tts_engine.py):
- 采样率转换:
target_fs == 0或大于原始采样率时保持模型采样率,否则用librosa.resample降采样; - 音量调整:
wav_vol = wav_tar_fs * volume,直接按比例缩放采样点; - 变速:调用
change_speed(audio_process.py)。该函数优先使用soxbindings的sox.Transformer().tempo(speed_rate)实现高质量变速;若未安装soxbindings会尝试动态安装sox与soxbindings,失败则抛出ServerBaseException,提示需将speed设为 1.0。注意speed_rate == 1.0时直接返回原音频,speed_rate <= 0时抛出ValueError; - 编码与落盘:先用
soundfile将音频写入io.BytesIO并做 base64 编码,得到wav_base64;若指定audio_path,.wav直接用sf.write保存,.pcm则先按32767 / max(0.001, np.max(np.abs(wav)))归一化到 int16 再写入。
5.3 REST 请求层的参数校验
REST 接口 POST /paddlespeech/tts 在进入引擎前会做参数校验(tts_api.py):speed、volume 必须落在 (0, 3],sample_rate 只能是 0/16000/8000,save_path 必须以 pcm 或 wav 结尾,否则返回 SERVER_PARAM_ERR。请求体模型为 TTSRequest(request.py),其中 text 为必填字段,其余均有默认值。
一次典型的请求体示例如下(来自 request.py 的注释文档):
{
"text": "你好,欢迎使用百度飞桨语音合成服务。",
"spk_id": 0,
"speed": 1.0,
"volume": 1.0,
"sample_rate": 0,
"save_path": "./tts.wav"
}
响应体中包含 lang、spk_id、speed、volume、sample_rate(实际目标采样率)、duration(秒)、save_path 与 base64 编码的 audio 字段(tts_api.py)。
六、引擎预热(Warm-up):首次请求的延迟优化
Paddle Inference 的 predictor 在首次推理时存在图优化与显存/内存初始化开销,PaddleSpeech 通过预热机制降低首包延迟。warm_up 函数(engine_warmup.py)在服务启动阶段按 engine_and_type == "tts_inference" 分支导入本模块的 PaddleTTSConnectionHandler,并按语言选择预热句子:
zh:"您好,欢迎使用语音合成服务。"en:"Hello and welcome to the speech synthesis service."mix:"您好,欢迎使用TTS多语种服务。"
随后循环 warm_up_time(默认 3)次调用 connection_handler.infer(...) 并记录每次响应耗时。只有 tts_inference(以及 tts_python、tts_online 系列)等离线/在线类型会被预热;此机制从源码结构看旨在让 predictor 与前端在正式流量到达前完成初始化。
七、从配置到请求的完整链路回顾
将以上内容串联,一次“PaddleSpeech 离线 TTS 推理服务”的请求生命周期为:
- 服务启动时,
EngineFactory.get_engine('tts', 'inference')懒加载 tts_engine.py 并实例化TTSEngine(单例); TTSEngine.init(config)解析 application.yaml 中的tts_inference段,设置设备、加载/下载 AM 与 Vocoder 静态模型、初始化词表与文本前端;- 预热阶段按语言合成一句固定文本,完成 predictor 首次推理;
- 客户端
POST /paddlespeech/tts携带 TTSRequest 进入 tts_api.py,校验参数后创建PaddleTTSConnectionHandler; run→infer依次完成文本前端切句、AM(speedyspeech/fastspeech2)梅尔谱预测、Vocoder 波形合成、跨句拼接;postprocess完成采样率转换、音量缩放、sox 变速、wav/base64 编码与可选落盘;- 返回
lang / sample_rate / duration / audio(base64),由 REST 层组装 JSON 响应。
八、关键文件索引
- 模块 API 文档入口:docs/source/api/paddlespeech.server.engine.tts.paddleinference.tts_engine.rst
- 引擎核心实现:paddlespeech/server/engine/tts/paddleinference/tts_engine.py
- 引擎公共基类:paddlespeech/server/engine/base_engine.py
- 引擎工厂(
tts + inference映射):paddlespeech/server/engine/engine_factory.py - Paddle Inference 封装(
init_predictor/run_model):paddlespeech/server/utils/paddle_predictor.py tts_inference服务端配置:paddlespeech/server/conf/application.yaml- REST 接口与请求体模型:paddlespeech/server/restful/tts_api.py、paddlespeech/server/restful/request.py
- 引擎预热逻辑:paddlespeech/server/engine/engine_warmup.py
- 变速工具(sox 实现):paddlespeech/server/utils/audio_process.py