PaddleSpeech 声音分类实战:基于 PANNs 预训练模型的 ESC-50 微调、评估与部署
PaddleSpeech 声音分类实战:基于 PANNs 预训练模型的 ESC-50 微调、评估与部署
导读
本文以 PaddleSpeech 仓库中的声音分类(Audio Classification)示例 examples/esc50/cls0 为主线,完整讲解如何基于 Audioset 预训练的 PANNs(Pretrained Audio Neural Networks)模型在 ESC-50 环境声音数据集上完成微调(Fine-tuning)、模型预测、动转静导出与静态图部署的全流程。读者读完本文后,将掌握 PaddleSpeech 声音分类任务的四阶段脚本用法(训练/预测/导出/部署)、panns.yaml 全部配置项的语义与调参要点,以及 CNN14/CNN10/CNN6 三种骨干网络在源码层面的结构差异,能够直接将其迁移到自己的音频分类场景。
一、任务背景:从 Audioset 到 ESC-50
声音分类是声音算法领域最热门的研究方向之一。传统机器学习做法是人工提取音频时域/频域特征,再交给 SVM 或决策树分类;而端到端深度学习则直接用深度网络(RNN、CNN 等)对原始波形或时频特征进行表示学习与分类预测。
本示例涉及两个关键数据集与模型:
- Audioset:Google 在 IEEE ICASSP 2017 开放的大规模音频数据集,包含 632 类音频类别、超过 200 万条人工标注的 10 秒音频片段(来源于 YouTube 视频)。
- PANNs(论文:PANNs: Large-Scale Pretrained Audio Neural Networks for Audio Pattern Recognition):基于 Audioset 训练的声音分类/识别模型,预训练后可用于提取音频 embedding。PaddleSpeech 的 PaddleAudio 提供了 CNN14、CNN10、CNN6 三种预训练模型。
- ESC-50:环境声音分类基准数据集,包含 2000 个带标签的 5 秒环境音样本,44,100 Hz 单声道,按标签划分为 50 个类别,每类 40 个样本,并预分为 5 个 fold 用于交叉验证。
三种预训练骨干网络的规格如下(详见 examples/esc50/README.md):
| 模型 | 结构 | 参数量 | Embedding 维度 |
|---|---|---|---|
| CNN14 | 12 个卷积层 + 2 个全连接层 | 79.6M | 2048 |
| CNN10 | 8 个卷积层 + 2 个全连接层 | 4.9M | 512 |
| CNN6 | 4 个卷积层 + 2 个全连接层 | 4.5M | 512 |
根据 ESC-50 提供的 fold 信息进行 5-fold 微调与评估,三者在 ESC-50 上的平均准确率分别为:CNN14 0.9500、CNN10 0.8975、CNN6 0.8825。
二、整体流程与脚本结构
PaddleSpeech 为声音分类任务提供了高度脚本化的示例工程,位于 examples/esc50/cls0,覆盖数据准备、模型训练、模型评估与模型部署等核心环节。目录结构如下:
examples/esc50/cls0/
├── conf/
│ └── panns.yaml # 数据集、模型、特征、训练、预测的全部配置
├── local/
│ ├── export.sh # 动转静:导出静态图
│ ├── infer.sh # 动态图推理(模型预测)
│ ├── static_model_infer.sh # 静态图部署推理
│ └── train.sh # 模型微调(支持单卡/多卡)
├── path.sh # 环境变量初始化
└── run.sh # 主入口,按 stage 调度上述脚本
1. 进入示例目录并初始化环境
cd examples/esc50/cls0
source path.sh
path.sh 负责设置仓库根目录 MAIN_ROOT、把 MAIN_ROOT 与 utils 加入 PATH,并设置 PYTHONPATH;同时指定本次示例的模型为 panns,并将 BIN_DIR 指向 paddlespeech/cls/exps/panns,后续 train/infer/export 脚本都会调用该目录下的 Python 实现。
2. 主入口 run.sh 的四个阶段
run.sh 以 stage 参数调度四个子流程(stop_stage 默认为 100,即单阶段模式,执行完即退出):
| Stage | 功能 | 所需参数 | 调用的脚本 |
|---|---|---|---|
| 1 | 模型微调(训练) | cfg_path(如 conf/panns.yaml) |
local/train.sh |
| 2 | 模型预测(动态图推理) | cfg_path |
local/infer.sh |
| 3 | 动转静(导出静态图) | ckpt、output_dir |
local/export.sh |
| 4 | 静态图部署推理 | infer_device、graph_dir、audio_file |
local/static_model_infer.sh |
一键执行完整流程(以 stage 1 训练为例):
CUDA_VISIBLE_DEVICES=0 ./run.sh 1 conf/panns.yaml
注意:示例脚本默认按单卡环境配置。若要使用 8 张 GPU 训练,请将
CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7;若完全没有 GPU,请设置为CUDA_VISIBLE_DEVICES=(空值)以 CPU 模式运行。ngpu由脚本通过awk -F "," '{print NF}'根据该环境变量自动计算,无需手动指定。
三、模型微调(Fine-tuning)
1. 训练命令
PANNs 预训练模型可以直接作为特征提取器,在其基础上微调一个分类头即可完成声音分类任务。启动微调:
CUDA_VISIBLE_DEVICES=0 ./run.sh 1 conf/panns.yaml
在 local/train.sh 内部,会根据 ngpu 自动选择启动方式:
ngpu > 0:使用python3 -m paddle.distributed.launch --gpus $CUDA_VISIBLE_DEVICES ${BIN_DIR}/train.py --cfg_path ${cfg_path}进行多卡分布式训练;ngpu = 0:直接运行python3 ${BIN_DIR}/train.py --cfg_path ${cfg_path}单进程(CPU/单卡)训练。
提示:早期版本的快速开始文档中微调命令写作
./local/train.sh ${ngpu} ${feat_backend},其中feat_backend(如numpy)为旧版特征后端参数。在当前仓库中,local/train.sh 的第二个参数已演变为配置文件路径cfg_path,请以./run.sh 1 conf/panns.yaml为准。
2. 训练配置全解析:conf/panns.yaml
conf/panns.yaml 是本次任务的完整配置,分为 data、model、feature、training、predicting 五部分:
data:
dataset: 'paddle.audio.datasets:ESC50'
num_classes: 50
train:
mode: 'train'
split: 1
dev:
mode: 'dev'
split: 1
model:
backbone: 'paddlespeech.cls.models:cnn14'
feature:
sr: 32000
n_fft: 1024
hop_length: 320
window: 'hann'
win_length: 1024
f_min: 50.0
f_max: 14000.0
n_mels: 64
training:
epochs: 50
learning_rate: 0.00005
num_workers: 2
batch_size: 16
checkpoint_dir: './checkpoint'
save_freq: 10
log_freq: 10
predicting:
audio_file: '/audio/dog.wav'
top_k: 10
checkpoint: './checkpoint/epoch_50/model.pdparams'
各部分参数含义:
data 部分
dataset:数据集类名的动态导入路径。'paddle.audio.datasets:ESC50'对应 audio/paddleaudio/datasets/esc50.py 中的ESC50类,训练脚本通过 paddlespeech/utils/dynamic_import.py 的dynamic_import加载。num_classes:分类类别数,ESC-50 为 50。train.mode/dev.mode:数据集模式,train表示训练集,dev表示验证集。split:ESC-50 的 fold 编号(1–5)。ESC-50 官方将数据划分为 5 个 fold,用于交叉验证;此处split: 1表示使用第 1 个 fold 作为划分依据。
model 部分
backbone:骨干网络的动态导入路径。默认'paddlespeech.cls.models:cnn14'。可切换为cnn10或cnn6(见下文)。
feature 部分
特征提取使用 LogMelSpectrogram(对数梅尔谱),这些参数必须与预训练模型对齐,否则会影响 embedding 质量。核心参数:
sr:采样率,32000 Hz。PANNs 预训练模型要求输入为 32 kHz 音频,因此ESC50数据集在加载时会重采样到 32 kHz。n_fft:FFT 窗口大小,1024。hop_length:帧移,320 个采样点。window:窗函数,hann(汉宁窗)。win_length:窗长,1024。f_min/f_max:梅尔滤波器的最低/最高频率,50.0 / 14000.0 Hz。n_mels:梅尔滤波器组数量,64。
training 部分
epochs:训练轮次,默认 50。learning_rate:微调学习率,默认 5e-5。微调预训练模型通常使用较小的学习率(1e-5 ~ 5e-5)以避免破坏预训练特征。batch_size:批大小,默认 16。需结合显存调整,显存不足时适当调低。num_workers:DataLoader 加载数据的子进程数,默认 2。checkpoint_dir:模型参数与优化器参数的保存目录,默认./checkpoint。save_freq:模型保存频率,默认每 10 个 epoch 保存一次。log_freq:训练信息打印频率,默认每 10 个 batch 打印一次。
predicting 部分
audio_file:预测的音频文件路径。top_k:输出得分最高的前 k 个类别,默认 10。checkpoint:用于预测的模型参数 checkpoint 文件。
3. 切换骨干网络
示例默认使用 CNN14。若想更换预训练骨干,只需修改 model.backbone 一项:
# CNN14
model:
backbone: 'paddlespeech.cls.models:cnn14'
# CNN10
model:
backbone: 'paddlespeech.cls.models:cnn10'
# CNN6
model:
backbone: 'paddlespeech.cls.models:cnn6'
三种骨干在 paddlespeech/cls/models/panns/panns.py 中实现为 CNN14、CNN10、CNN6 三个 nn.Layer 子类。以 CNN14 为例,其结构为 6 个卷积块(每块含 2 个 3×3 卷积层,通道数从 64 逐块翻倍至 2048),再接 fc1 全连接层输出 2048 维 embedding,并保留一个面向 Audioset 527 类的 fc_audioset 分类头(extract_embedding=True 时只取 embedding 输出)。
4. 训练循环的源码实现
训练主程序为 paddlespeech/cls/exps/panns/train.py,其关键流程为:
- 读取 YAML 配置,拆分为
model_conf、data_conf、feat_conf、training_conf; - 通过
dynamic_import加载 ESC50 数据集类,构造train_ds与dev_ds,并用paddle.io.DistributedBatchSampler+paddle.io.DataLoader构建数据流水线; - 构造特征提取器
LogMelSpectrogram(**feat_conf); - 动态导入骨干网络,以
pretrained=True, extract_embedding=True加载预训练权重,再包一层SoundClassifier(backbone, num_class=num_classes)(定义见 paddlespeech/cls/models/panns/classifier.py:backbone 后接 Dropout(0.1) 与Linear(emb_size, num_class)分类头); - 优化器为
paddle.optimizer.Adam,损失函数为CrossEntropyLoss; - 训练循环中对每个 batch 提取特征(
paddle.transpose(feats, [0, 2, 1])转为[N, length, n_mels]布局)、前向计算 logits、反向传播并更新参数,同时按log_freq打印 loss / acc / lr。
说明:训练脚本中注释“Need a padding when lengths of waveforms differ in a batch”,即同一 batch 内波形长度不一致时需要先补齐到相同长度再提取特征,这是 train.py 与部署脚本中共用的处理逻辑。
四、模型预测(动态图推理)
训练完成后,可通过 stage 2 在验证集上进行动态图推理评估:
CUDA_VISIBLE_DEVICES=0 ./run.sh 2 conf/panns.yaml
该阶段调用 local/infer.sh,实际执行 python3 ${BIN_DIR}/predict.py --cfg_path=$1。预测使用的音频、top-k 与 checkpoint 均来自 predicting 配置段。典型输出如下(对 dog.wav 的预测结果,按得分降序展示 top-k 类别):
[/audio/dog.wav]
Dog: 0.9999538660049438
Clock tick: 1.3341237718123011e-05
Cat: 6.579841738130199e-06
五、模型部署:动转静与静态图推理
训练得到 checkpoint 后,即可导出为静态图并部署。整个部署链路为“动态图参数 → 静态图模型 → paddle.inference 推理”。
1. 导出静态图(动转静)
./local/export.sh ${ckpt_dir} ./export
其中 ckpt_dir 为存放模型 checkpoint 的目录,例如 checkpoint/epoch_50。注意 local/export.sh 实际接收的是 checkpoint 文件(model.pdparams),而 run.sh 的 stage 3 用法是:
CUDA_VISIBLE_DEVICES=0 ./run.sh 3 ./checkpoint/epoch_50/model.pdparams ./export
导出脚本 export_model.py 支持两个参数:
--checkpoint:模型参数 checkpoint 文件;--output_dir:静态图模型与参数保存目录,默认./export。
其实现核心是:重新构建 SoundClassifier(cnn14(pretrained=False, extract_embedding=True), num_class=len(ESC50.label_list)),加载 checkpoint 权重后调用 paddle.jit.to_static 并指定输入 InputSpec 完成动转静。导出产物为 Paddle Inference 标准三件套:
export
├── inference.pdmodel # 静态图模型结构
├── inference.pdiparams # 静态图模型参数
└── inference.pdiparams.info # 参数元信息
2. 静态图部署推理
./local/static_model_infer.sh ${infer_device} ./export ${audio_file}
infer_device:推理设备,可选cpu或gpu;audio_file:待预测的音频文件,要求为*.wav格式。
对应 run.sh 的 stage 4:
CUDA_VISIBLE_DEVICES=0 ./run.sh 4 cpu ./export /audio/dog.wav
部署推理程序为 paddlespeech/cls/exps/panns/deploy/predict.py,基于 paddle.inference 模块提供 Python 端部署示例。除脚本包装的三个参数外,该程序还暴露了丰富的推理调优参数:
--model_dir:静态图模型与参数目录(必填,默认./export);--device:推理设备,可选cpu、gpu、xpu、gcu,默认gpu;--wav:待预测音频(必填);--batch_size:推理批大小,默认 1;--use_tensorrt:是否启用 TensorRT 加速,默认False;--precision:TensorRT 精度,可选fp32/fp16,默认fp32;--cpu_threads:CPU 推理线程数,默认 10;--enable_mkldnn:CPU 推理是否启用 MKL-DNN 加速,默认False。
从源码看,其推理流程为:加载音频 → 按 batch 内最大长度做 padding → 用 LogMelSpectrogram 提取对数梅尔谱 → 交给 Predictor 类执行 paddle.inference.Config 配置(GPU 分支支持 TensorRT 引擎、CPU 分支支持 MKLDNN 与线程数设置)→ 输出 logits 经 softmax 得到各类别概率并排序展示 top-k 结果。
六、延伸:自定义数据集与训练
声音分类的官方文档还提供了自定义数据集的完整教程 docs/source/cls/custom_dataset.md,核心思路是:
- 准备一份 meta 文件,每行包含音频绝对路径与标签,例如:
/PATH/TO/WAVE_FILE/1.wav cat /PATH/TO/WAVE_FILE/2.wav cat /PATH/TO/WAVE_FILE/3.wav dog /PATH/TO/WAVE_FILE/4.wav dog - 继承基类
AudioClassificationDataset(位于 audio/paddleaudio/datasets/dataset.py),实现_get_data返回文件列表与标签索引列表; - 用
LogMelSpectrogram按与预训练模型对齐的特征参数提取特征,再以SoundClassifier组装分类模型即可训练自己的分类任务。
七、小结
PaddleSpeech 声音分类示例以 examples/esc50/cls0 为入口,将“数据加载 → 特征提取 → 预训练模型微调 → 动态图预测 → 动转静导出 → 静态图部署”串成了一条开箱即用的流水线。核心要点可归纳为:
- 一条命令
CUDA_VISIBLE_DEVICES=0 ./run.sh <stage> <参数...>即可驱动训练(stage 1)、预测(stage 2)、导出(stage 3)、静态部署(stage 4)四个环节; - 全部可调项集中在 conf/panns.yaml,特征参数必须与预训练骨干对齐(32 kHz、64 维梅尔谱);
- 骨干网络可按需在 CNN14 / CNN10 / CNN6 之间切换,分别对应 2048 / 512 / 512 维 embedding;
- 部署链路基于
paddle.jit.to_static与paddle.inference,并支持 TensorRT、MKL-DNN 等加速选项,便于落地到生产环境。
如果需要将模型应用到自有数据,可参考 docs/source/cls/custom_dataset.md 编写继承自 AudioClassificationDataset 的自定义数据集类,其余训练与部署流程与本示例完全一致。