PaddleSpeech 声音分类实战:基于 PANNs 预训练模型的 ESC-50 微调、评估与部署

原创2026-09-24 22:51:151,603 阅读
文章标签:语音音频人工智能深度学习

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,其关键流程为:

  1. 读取 YAML 配置,拆分为 model_conf、data_conf、feat_conf、training_conf;
  2. 通过 dynamic_import 加载 ESC50 数据集类,构造 train_ds 与 dev_ds,并用 paddle.io.DistributedBatchSampler + paddle.io.DataLoader 构建数据流水线;
  3. 构造特征提取器 LogMelSpectrogram(**feat_conf);
  4. 动态导入骨干网络,以 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) 分类头);
  5. 优化器为 paddle.optimizer.Adam,损失函数为 CrossEntropyLoss;
  6. 训练循环中对每个 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,核心思路是:

  1. 准备一份 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
    
  2. 继承基类 AudioClassificationDataset(位于 audio/paddleaudio/datasets/dataset.py),实现 _get_data 返回文件列表与标签索引列表;
  3. 用 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 的自定义数据集类,其余训练与部署流程与本示例完全一致。

登录后查看全文
PaddleSpeech