企业官网建设流程全解析

• 人工智能
• 语音
• 音频

本指南以 PaddleSpeech 仓库中 examples/ljspeech/tts1 示例为骨架，系统讲解基于 LJSpeech-1.1 数据集从零训练TransformerTTS文本到语音（TTS）模型，并配合WaveFlow神经声码器完成语音合成的完整流程。读完本文，你将掌握 PaddleSpeech 多阶段脚本（stage）的运行机制、dump 特征目录结构、训练与合成脚本的全部命令行参数，以及 conf/default.yaml 中每个模型超参数的工程含义，可以直接复制命令在自己的环境下复现实验。

一、示例概览：tts1 解决什么问题

examples/ljspeech/tts1是 PaddleSpeech 为 LJSpeech（LJ Speech）英文单说话人数据集提供的 TransformerTTS 训练示例。TransformerTTS 是论文《Neural Speech Synthesis with Transformer Network》中提出的端到端 TTS 模型，它用 Transformer 的 encoder-decoder 结构把音素（phone）序列映射为Mel 频谱（mel-filterbank）序列，再交由声码器重建波形。在 PaddleSpeech 源码中，该模型实现于 paddlespeech/t2s/models/transformer_tts/transformer_tts.py，类的 docstring 明确注明了其论文出处（https://arxiv.org/pdf/1809.08895.pdf）。

整个示例目录包含以下核心文件：

其中BIN_DIR指向 paddlespeech/t2s/exps/transformer_tts，其下存放preprocess.py、normalize.py、train.py、synthesize.py、synthesize_e2e.py五个可执行入口，所有 shell 脚本最终都调用这些 Python 程序。

二、数据集准备：下载并解压 LJSpeech-1.1

本示例使用的数据集是LJSpeech-1.1（约 13,100 条英文语音片段，由一位女性朗读者录制，总时长约 24 小时，采样率 22050 Hz）。请从 LJSpeech 官方网站下载该数据集，并将其解压到~/datasets目录，最终目录结构应为：

~/datasets/LJSpeech-1.1/

注意：local/preprocess.sh中写死了数据根目录为~/datasets/LJSpeech-1.1/（见 examples/ljspeech/tts1/local/preprocess.sh 中的--rootdir=~/datasets/LJSpeech-1.1/），因此请按此约定放置数据，避免路径不匹配。

LJSpeech 目录内的文本标注文件采用|分隔的元数据格式，形如utt_id|转录文本|规范化文本。在 paddlespeech/t2s/exps/transformer_tts/preprocess.py 的get_lj_sentences函数中可以看到解析逻辑：按行split('|')取第一列作为 utterance id（并按前两位字符提取说话人，本数据集中均为LJ），取最后一列作为原始文本，再调用英文前端English的phoneticize方法把文本转成音素序列。这说明预处理的输入并不直接使用音频，而是「元数据行 + 前端音素化」的组合。

三、一键运行：理解 run.sh 的 stage 机制

准备好数据集后，在examples/ljspeech/tts1目录下执行：

./run.sh

该命令会依次完成四件事：

1. source path：加载 path.sh，设置MAIN_ROOT（仓库根目录）、BIN_DIR（paddlespeech/t2s/exps/transformer_tts）以及PYTHONPATH，使后续脚本能找到库代码。
2. preprocess the dataset：提取特征、统计并归一化数据。
3. train the model：训练 TransformerTTS 模型。
4. synthesize wavs：分别从metadata.jsonl和文本文件合成波形。

run.sh 通过stage与stop_stage两个变量控制执行范围，并借助utils/parse_options.sh解析命令行参数。若只想运行其中某个阶段，把stage设为stop-stage即可，例如只做数据预处理：

./run.sh --stage 0 --stop-stage 0

各 stage 与 run.sh 中脚本片段的对应关系如下：

run.sh 顶部的默认变量（均可被命令行覆盖）：

gpus=0,1 # 使用的 GPU 编号 stage=0 stop_stage=100 # 默认跑完全部阶段 conf_path=conf/default.yaml # 配置文件 train_output_path=exp/default # 训练输出目录 ckpt_name=snapshot_iter_403.pdz # 用于合成的 checkpoint 文件名

从源码看，local/train.sh内部写死了--ngpu=2，因此默认脚本按双卡训练设计；如果只有单卡，建议修改gpus与--ngpu保持一致。

四、数据预处理：dump 目录结构与 metadata.jsonl

预处理由 local/preprocess.sh 完成，其等价命令为：

./local/preprocess.sh ${conf_path}

脚本内部包含三个子阶段：

1. 提取特征：调用preprocess.py，参数为--dataset=ljspeech、--rootdir=~/datasets/LJSpeech-1.1/、--dumpdir=dump、--config-path=conf/default.yaml、--num-cpu=8。特征提取基于配置中的fs / n_fft / win_length / n_shift / n_mels等参数计算 80 维 Log-Mel FBank（源码中对应 paddlespeech/t2s/datasets/get_feats.py 的LogMelFBank类）。
2. 统计特征：调用utils/compute_statistics.py，对dump/train/raw/metadata.jsonl中speech字段计算均值与标准差，输出dump/train/speech_stats.npy。
3. 归一化：对 train/dev/test 三部分分别调用normalize.py，其中dev 和 test 必须复用 train 的统计量（--speech-stats=dump/train/speech_stats.npy），并生成phone_id_map.txt（音素到 id 映射）与speaker_id_map.txt（说话人到 id 映射）。

预处理完成后，当前目录下会生成dump文件夹，结构如下：

dump ├── dev │ ├── norm │ └── raw ├── phone_id_map.txt ├── speaker_id_map.txt ├── test │ ├── norm │ └── raw └── train ├── norm ├── raw └── speech_stats.npy

• 数据被划分为train、dev、test三部分；每个部分含raw（原始特征）与norm（归一化后特征）两个子目录。
• 归一化使用的统计量来自训练集，即dump/train/speech_stats.npy。
• 每个子目录中都有一个metadata.jsonl，它是一份表格式文件，逐行记录每条 utterance 的音素序列（phones）、文本长度（text_lengths）、语音长度（speech_lengths）、语音特征路径、说话人（speaker）以及 utterance id。

训练与合成阶段都直接消费这份 metadata：在 paddlespeech/t2s/exps/transformer_tts/train.py 中，训练数据通过jsonlines.open(args.train_metadata)读入，并用DataTable按text / text_lengths / speech / speech_lengths四个字段组织，其中speech字段通过np.load转换器按路径加载.npy特征文件。

五、模型训练：train.py 与超参数详解

训练入口由 local/train.sh 调用：

CUDA_VISIBLE_DEVICES=${gpus} ./local/train.sh ${conf_path} ${train_output_path}

其实际执行的 Python 命令（以双卡为例）：

python3 ${BIN_DIR}/train.py \ --train-metadata=dump/train/norm/metadata.jsonl \ --dev-metadata=dump/dev/norm/metadata.jsonl \ --config=${conf_path} \ --output-dir=${train_output_path} \ --ngpu=2 \ --phones-dict=dump/phone_id_map.txt

5.1 train.py 完整参数

usage: train.py [-h] [--config CONFIG] [--train-metadata TRAIN_METADATA] [--dev-metadata DEV_METADATA] [--output-dir OUTPUT_DIR] [--ngpu NGPU] [--phones-dict PHONES_DICT] Train a TransformerTTS model with LJSpeech TTS dataset. optional arguments: -h, --help show this help message and exit --config CONFIG TransformerTTS config file. --train-metadata TRAIN_METADATA training data. --dev-metadata DEV_METADATA dev data. --output-dir OUTPUT_DIR output dir. --ngpu NGPU if ngpu == 0, use cpu. --phones-dict PHONES_DICT phone vocabulary file.

各参数要点：

1. --config：YAML 格式配置文件，覆盖默认超参数，即 conf/default.yaml。
2. --train-metadata/--dev-metadata：应指向dump目录下train、dev的norm子目录中的metadata.jsonl。
3. --output-dir：实验输出目录，checkpoint 保存在该目录下的checkpoints/中。
4. --ngpu：使用的 GPU 数量，为 0 时使用 CPU。
5. --phones-dict：音素词汇表文件路径（即预处理生成的dump/phone_id_map.txt）。

5.2 从源码理解 train.py 的训练管线

阅读 paddlespeech/t2s/exps/transformer_tts/train.py 可以发现几个关键实现事实：

• 设备选择：ngpu > 0且 Paddle 编译支持 CUDA/NPU 时选择对应设备，否则回退 CPU；world_size > 1时调用paddle.distributed.init_parallel_env()初始化并行环境。
• 随机种子：seed_everything(config.seed)在分布式训练中保证多进程一致。
• 词表大小：从phones_dict文件按行读取得到音素列表，vocab_size = len(phn_id)，作为模型的idim；输出维度odim = config.n_mels（本示例为 80）。
• 模型构建：TransformerTTS(idim=vocab_size, odim=odim, **config["model"])，即 config 中model段的所有键值对都会作为模型构造参数传入。
• 数据加载：使用DistributedBatchSampler+transformer_single_spk_batch_fncollate 函数；num_workers与batch_size均来自 config。
• 训练扩展：每 epoch 执行一次 dev 集评估（TransformerTTSEvaluator），每 iteration 写一次 VisualDL 日志，并通过Snapshot(max_size=config.num_snapshots)保存快照（即checkpoints/下的.pdz文件）。
• 多卡分发：--ngpu > 1时通过dist.spawn(train_sp, (args, config), nprocs=args.ngpu)拉起多进程训练。

5.3 conf/default.yaml 配置逐项解读

conf/default.yaml 是训练的核心配置，按功能分为若干段，下面给出关键项及其含义：

（1）特征相关（mel 频谱提取参数）

（2）数据加载

（3）模型结构（tts: transformertts+model段）

tts字段声明模型架构为transformertts；model段则是TransformerTTS类的关键字参数，常用项如下：

这些参数与 paddlespeech/t2s/models/transformer_tts/transformer_tts.py 中TransformerTTS类的构造函数一一对应（如idim、odim、embed_dim、elayers、eunits、postnet_chans、use_scaled_pos_enc等），模型 docstring 与配置注释互为印证。

（4）Updater（损失与训练更新逻辑）

TransformerTTSUpdater的实现位于 paddlespeech/t2s/models/transformer_tts/transformer_tts_updater.py，它接收model、optimizer、dataloader、output_dir及上述 updater 参数，在StandardUpdater的框架内完成前向、损失计算与反向更新；TransformerTTSEvaluator则承担 dev 集评估。

（5）优化器与训练设置

六、语音合成：metadata 批量合成与文本端到端合成

本示例使用WaveFlow作为神经声码器（对应仓库中的 examples/ljspeech/voc0 示例）。WaveFlow 预训练模型压缩包（waveflow_ljspeech_ckpt_0.3.zip，residual channel 为 128）需从 PaddleSpeech 官方发布的预训练模型处下载，下载后解压：

unzip waveflow_ljspeech_ckpt_0.3.zip

解压得到的 WaveFlow checkpoint 包含两个文件：

waveflow_ljspeech_ckpt_0.3 ├── config.yaml # default config used to train waveflow └── step-2000000.pdparams # model parameters of waveflow

两个子脚本中的 WaveFlow 路径写死为waveflow_ljspeech_ckpt_0.3/config.yaml与waveflow_ljspeech_ckpt_0.3/step-2000000.pdparams，请确保解压后该目录位于examples/ljspeech/tts1下。

6.1 从 metadata.jsonl 合成（synthesize.py）

local/synthesize.sh 调用synthesize.py，可从metadata.jsonl（即测试集真实文本与特征）批量合成波形：

CUDA_VISIBLE_DEVICES=${gpus} ./local/synthesize.sh ${conf_path} ${train_output_path} ${ckpt_name}

usage: synthesize.py [-h] [--transformer-tts-config TRANSFORMER_TTS_CONFIG] [--transformer-tts-checkpoint TRANSFORMER_TTS_CHECKPOINT] [--transformer-tts-stat TRANSFORMER_TTS_STAT] [--waveflow-config WAVEFLOW_CONFIG] [--waveflow-checkpoint WAVEFLOW_CHECKPOINT] [--phones-dict PHONES_DICT] [--test-metadata TEST_METADATA] [--output-dir OUTPUT_DIR] [--ngpu NGPU] Synthesize with transformer tts & waveflow. optional arguments: -h, --help show this help message and exit --transformer-tts-config TRANSFORMER_TTS_CONFIG transformer tts config file. --transformer-tts-checkpoint TRANSFORMER_TTS_CHECKPOINT transformer tts checkpoint to load. --transformer-tts-stat TRANSFORMER_TTS_STAT mean and standard deviation used to normalize spectrogram when training transformer tts. --waveflow-config WAVEFLOW_CONFIG waveflow config file. --waveflow-checkpoint WAVEFLOW_CHECKPOINT waveflow checkpoint to load. --phones-dict PHONES_DICT phone vocabulary file. --test-metadata TEST_METADATA test metadata. --output-dir OUTPUT_DIR output dir. --ngpu NGPU if ngpu == 0, use cpu.

6.2 从文本文件端到端合成（synthesize_e2e.py）

local/synthesize_e2e.sh 调用synthesize_e2e.py，可从纯文本文件直接合成，适合推理演示：

CUDA_VISIBLE_DEVICES=${gpus} ./local/synthesize_e2e.sh ${conf_path} ${train_output_path} ${ckpt_name}

usage: synthesize_e2e.py [-h] [--transformer-tts-config TRANSFORMER_TTS_CONFIG] [--transformer-tts-checkpoint TRANSFORMER_TTS_CHECKPOINT] [--transformer-tts-stat TRANSFORMER_TTS_STAT] [--waveflow-config WAVEFLOW_CONFIG] [--waveflow-checkpoint WAVEFLOW_CHECKPOINT] [--phones-dict PHONES_DICT] [--text TEXT] [--output-dir OUTPUT_DIR] [--ngpu NGPU] Synthesize with transformer tts & waveflow. optional arguments: -h, --help show this help message and exit --transformer-tts-config TRANSFORMER_TTS_CONFIG transformer tts config file. --transformer-tts-checkpoint TRANSFORMER_TTS_CHECKPOINT transformer tts checkpoint to load. --transformer-tts-stat TRANSFORMER_TTS_STAT mean and standard deviation used to normalize spectrogram when training transformer tts. --waveflow-config WAVEFLOW_CONFIG waveflow config file. --waveflow-checkpoint WAVEFLOW_CHECKPOINT waveflow checkpoint to load. --phones-dict PHONES_DICT phone vocabulary file. --text TEXT text to synthesize, a 'utt_id sentence' pair per line. --output-dir OUTPUT_DIR output dir. --ngpu NGPU if ngpu == 0, use cpu.

两组合成参数的关键说明：

1. --transformer-tts-config、--transformer-tts-checkpoint、--transformer-tts-stat、--phones-dict是 TransformerTTS 侧参数，分别对应其预训练模型中的 4 个文件（配置、checkpoint、统计量、音素表）。
2. --waveflow-config、--waveflow-checkpoint是 WaveFlow 侧参数，对应其预训练模型的 2 个文件。
3. --test-metadata应指向dump/test/norm/metadata.jsonl。
4. --text为待合成文本文件，每行格式为'utt_id sentence'（id 与句子成对，可参考仓库自带的 paddlespeech/t2s/assets/sentences_en.txt，内含001 Life was like a box of chocolates...等 9 句英文例句）。
5. --output-dir为合成音频输出目录（synthesize.sh默认输出到${train_output_path}/test，synthesize_e2e.sh输出到${train_output_path}/test_e2e）。
6. --ngpu为使用的 GPU 数量，为 0 时使用 CPU。

另外，两个脚本开头都设置了两个 Paddle 显存相关环境变量：

FLAGS_allocator_strategy=naive_best_fit \ FLAGS_fraction_of_gpu_memory_to_use=0.01 \

前者选用更朴素的显存分配策略，后者将单卡可用显存比例限制为 1%，用于避免推理时显存占用过高。

七、使用预训练模型快速合成

PaddleSpeech 提供了在 LJSpeech 上训练好的 TransformerTTS 预训练模型（压缩包名transformer_tts_ljspeech_ckpt_0.4.zip），可从预训练模型下载页获取。解压后 checkpoint 包含 4 个文件：

transformer_tts_ljspeech_ckpt_0.4 ├── default.yaml # default config used to train transformer_tts ├── phone_id_map.txt # phone vocabulary file when training transformer_tts ├── snapshot_iter_201500.pdz # model parameters and optimizer states └── speech_stats.npy # statistics used to normalize spectrogram when training transformer_tts

这四个文件恰好与synthesize.py/synthesize_e2e.py的四个 TransformerTTS 侧参数一一对应：default.yaml → --transformer-tts-config，snapshot_iter_201500.pdz → --transformer-tts-checkpoint，speech_stats.npy → --transformer-tts-stat，phone_id_map.txt → --phones-dict。

结合 WaveFlow 预训练模型，可用下面的命令对仓库自带的英文例句文件paddlespeech/t2s/assets/sentences_en.txt进行端到端合成：

source path.sh FLAGS_allocator_strategy=naive_best_fit \ FLAGS_fraction_of_gpu_memory_to_use=0.01 \ python3 ${BIN_DIR}/synthesize_e2e.py \ --transformer-tts-config=transformer_tts_ljspeech_ckpt_0.4/default.yaml \ --transformer-tts-checkpoint=transformer_tts_ljspeech_ckpt_0.4/snapshot_iter_201500.pdz \ --transformer-tts-stat=transformer_tts_ljspeech_ckpt_0.4/speech_stats.npy \ --waveflow-config=waveflow_ljspeech_ckpt_0.3/config.yaml \ --waveflow-checkpoint=waveflow_ljspeech_ckpt_0.3/step-2000000.pdparams \ --text=${BIN_DIR}/../../assets/sentences_en.txt \ --output-dir=exp/default/test_e2e \ --phones-dict=transformer_tts_ljspeech_ckpt_0.4/phone_id_map.txt

执行前需保证：source path.sh已设置好BIN_DIR；两个预训练模型目录（transformer_tts_ljspeech_ckpt_0.4、waveflow_ljspeech_ckpt_0.3）位于当前目录下；文本文件格式符合'utt_id sentence'约定。合成结果将写入exp/default/test_e2e。

八、从源码看 TransformerTTS 的模型组成

对于希望深入原理的读者，paddlespeech/t2s/models/transformer_tts/transformer_tts.py 提供了完整实现，可以印证配置中每个参数的真实作用：

• TransformerTTS(nn.Layer)（第 43 行起）：核心模型类，docstring 描述为「将 token 序列转换为 Mel-filterbank 序列的 TTS-Transformer 模块」，构造函数参数与conf/default.yaml的model段完全对齐。
• 模型内部按idim（音素词表大小）与odim（n_mels，即 80）决定输入输出维度，embed_dim、eprenet_conv_layers等控制 encoder prenet，elayers/eunits/aheads/adim控制 encoder 与注意力，dlayers/dunits控制 decoder，postnet_*控制频谱后处理网络，use_scaled_pos_enc控制缩放位置编码，init_type与init_enc_alpha/init_dec_alpha控制初始化策略。
• 同一文件中还定义了TransformerTTSInference(nn.Layer)（第 726 行起）：推理封装类，接收normalizer与已训练模型，负责在合成阶段把模型输出的频谱反归一化，再交给 WaveFlow 生成波形。

训练侧的TransformerTTSUpdater与TransformerTTSEvaluator位于 paddlespeech/t2s/models/transformer_tts/transformer_tts_updater.py，对应配置中updater段（masking、L1 损失、guided attention loss 等）的实际实现。

九、常见问题与注意事项小结

1. 路径一致性：预处理脚本写死数据根目录为~/datasets/LJSpeech-1.1/，请严格按该路径放置数据。
2. GPU 数量：run.sh默认gpus=0,1且train.sh写死--ngpu=2，单卡环境需同步修改；--ngpu=0表示纯 CPU 训练/推理。
3. 统计量复用：dev与test归一化必须使用dump/train/speech_stats.npy，否则特征分布不一致会导致训练评估失真。
4. WaveFlow 依赖：合成阶段依赖 WaveFlow 预训练模型的两个文件，下载解压后目录名须与脚本中的waveflow_ljspeech_ckpt_0.3一致。
5. 文本格式：--text文件每行必须是'utt_id sentence'形式；仓库自带 paddlespeech/t2s/assets/sentences_en.txt 可作为格式参考。
6. checkpoint 命名：合成时通过ckpt_name指定exp/default/checkpoints/下的具体快照（如snapshot_iter_403.pdz），请根据实际训练进度选择存在的文件。

按照本文的 stage 流程——下载数据、./run.sh --stage 0 --stop-stage 0预处理、./run.sh --stage 1 --stop-stage 1训练、再配好 WaveFlow 后执行 stage 2/3 或直接使用预训练模型合成，即可完整跑通 TransformerTTS 的「训练 → 合成」闭环。

• 人工智能
• 语音
• 音频