PaddleSpeech 运行时音频分类引擎实战:PANNS 模型 CPU 推理与 Android 部署全指南
PaddleSpeech 运行时音频分类引擎实战:PANNS 模型 CPU 推理与 Android 部署全指南
导读
本文以 PaddleSpeech 仓库中 runtime/examples/audio_classification/README.md 为骨架,系统讲解基于 PANNS(Pre-trained Audio Neural Networks)模型的音频场景分类(Audio Classification / Acoustic Scene Classification)在 C++ 运行时中的完整落地流程:从引擎配置文件的逐项解析、标签字典与 wav 列表(scp)的准备,到 Linux x86_64 CPU 上的命令行推理,再到 Android 端 JNI 集成的端侧部署。读完本文,你将能够独立配置 conf 文件、运行 panns_nnet_main 推理程序、解析 top-k 分类输出,并把整套分类能力移植到 Android Demo 中。
一、功能定位:C++ 运行时中的音频分类引擎
音频分类任务的目标是判断一段音频属于何种声学事件或场景(如"狗叫""时钟闹铃""直升机""雷雨"等)。在 PaddleSpeech 仓库中,该能力被封装在 runtime/engine/audio_classification/ 目录下,是一个纯 CPU、基于 ONNX 模型 + FastDeploy 运行时的 C++ 引擎,与同目录下的 ASR、VAD 引擎平级,可直接编译为 Linux 可执行程序或 Android 动态库。
引擎的完整处理链路为(对应源码 runtime/engine/audio_classification/nnet/panns_nnet.cc):
- 读入波形:通过 Kaldi 的
WaveData读取 wav 文件; - 波形归一化:
WaveformFloatNormal+WaveformNormal按配置做线性/峰值归一化; - Fbank 特征提取:借助
ppspeech::Fbank与knf::FbankOptions计算对数滤波器组特征(log-fbank),并逐帧做PowerTodb转换; - 模型推理:把
{1, num_frames, feat_dim}维特征送入 FastDeploy Runtime 加载的 ONNX 模型; - Top-k 结果输出:对模型输出的各类别 logits 取前 k 个,结合
label_list字典格式化为 JSON 风格的字符串。
从源码结构看(panns_nnet.h),引擎通过 ClsNnetConf 结构体承载全部配置项,再通过 ClsCreateInstance / ClsFeedForward / ClsReset / ClsDestroyInstance 四个接口对外暴露,这一接口设计同时服务于命令行程序和 Android JNI 层,是理解整套配置体系的关键。
二、配置文件 conf:引擎的唯一输入
README 明确指出:"config is the input of engine"(配置是引擎的输入)。引擎启动时只读取一个 conf 文件,所有音频处理参数、模型路径与推理参数都在其中声明。示例配置文件位于 runtime/examples/audio_classification/conf,完整内容如下:
[CONF]
wav_normal=true
wav_normal_type=linear
wav_norm_mul_factor=1.0
model_path=./inference.onnx
param_path=
dict_path=./label_list
num_cpu_thread=1
samp_freq=32000
frame_length_ms=32
frame_shift_ms=10
num_bins=64
low_freq=50
high_freq=14000
dither=0.0
这些参数由 panns_interface.cc 中的 Config 读取器逐一解析。结合源码中给出的默认值,各参数的含义与取值建议如下:
| 配置项 | 示例值 | 源码默认值 | 含义与说明 |
|---|---|---|---|
wav_normal |
true |
true |
是否对 wav 波形做归一化处理 |
wav_normal_type |
linear |
linear |
归一化方式,示例使用线性归一化 |
wav_norm_mul_factor |
1.0 |
1.0 |
归一化乘法因子,缩放波形幅度 |
model_path |
./inference.onnx |
空字符串 | ONNX 模型文件路径(CPU 版) |
param_path |
空 | 空字符串 | 模型参数文件路径;使用 ONNX 单文件模型时留空 |
dict_path |
./label_list |
空字符串 | 标签字典文件路径,每行一个类别名 |
num_cpu_thread |
1 |
12 |
CPU 推理线程数,源码默认 12,示例环境设为 1 |
samp_freq |
32000 |
32000 |
Fbank 提取时的采样率(Hz),须与训练特征对齐 |
frame_length_ms |
32 |
32 |
帧长(毫秒),决定每帧分析的时长窗 |
frame_shift_ms |
10 |
10 |
帧移(毫秒),即相邻帧的步长 |
num_bins |
64 |
64 |
Fbank 梅尔滤波器组数量(mel bins) |
low_freq |
50 |
50 |
梅尔滤波器起始频率(Hz) |
high_freq |
14000 |
14000 |
梅尔滤波器截止频率(Hz) |
dither |
0.0 |
0.0 |
预加重/加抖参数,0 表示不添加抖动噪声 |
配置如何驱动底层实现
- Fbank 参数映射:在 panns_nnet.cc 的
Init中,samp_freq / frame_length_ms / frame_shift_ms / num_bins / low_freq / high_freq / dither被逐项写入fbank_opts_,并设置use_log_fbank = false(对数转换在后续用PowerTodb显式完成)。因此这些参数必须与模型训练时的特征配置一致,否则推理精度会明显下降。 - 模型后端选择:同一份 conf 在不同编译宏下可驱动不同后端——
USE_PADDLE_INFERENCE_BACKEND时model_path + param_path成对加载 Paddle 模型;USE_ORT_BACKEND时只加载 ONNX 单文件模型;USE_PADDLE_LITE_BACKEND时用于移动端。示例 README 的 Linux 执行日志中出现Runtime initialized with Backend::ORT in Device::CPU,说明默认构建走的是 ONNX Runtime(ORT)后端。 - 线程控制:
num_cpu_thread通过runtime_option.SetCpuThreadNum(conf.num_cpu_thread_)传入 FastDeploy,直接控制推理时的 CPU 并发度。
三、标签字典 label_list 与音频列表 scp
1. label_list:模型输出的类别名映射
README 说明 label_list 是"model output label"(模型输出的标签)。文件位于 runtime/examples/audio_classification/label_list,实际内容为 50 个音频场景类别,每个类别占一行,例如:
Dog
Rooster
Pig
Cow
Frog
Cat
Hen
Insects (flying)
Sheep
Crow
Rain
Sea waves
Crackling fire
...
Clock alarm
Clock tick
Glass breaking
Helicopter
Chainsaw
Siren
Car horn
Engine
Train
Church bells
Airplane
Fireworks
Hand saw
读取逻辑位于 panns_nnet.cc:ReadFileToVector 把文件按行读入 std::vector<std::string> dict_,第 i 行即对应模型输出向量的第 i 个类别的概率/logit。在 GetTopkResult(panns_nnet.cc)中,取 top-k 后通过 dict_[indics[i]] 把下标还原成类别名。因此 label_list 的行顺序必须与模型训练时的类别顺序严格一致,不能随意增删或调序。
2. scp:待分类音频的清单
README 说明 "scp is the input of engine and each line in scp is wav"(scp 是引擎的输入,每行是一个 wav 文件)。示例文件 runtime/examples/audio_classification/scp 内容只有一行:
test.wav
引擎会逐行读取 scp 中的路径(支持相对路径与绝对路径),对每个 wav 依次执行"读取 → 特征提取 → 推理 → 输出",这正是 panns_nnet_main.cc 中的 while 循环逻辑。批量场景下,只需在 scp 中每行写一个 wav 路径即可实现一次跑完整个音频集。
四、Linux CPU 执行:命令行推理实战
1. 前置条件
- 已按 runtime/README.md 完成运行时编译,产物位于
runtime/build/Linux/x86_64/engine/audio_classification/nnet/panns_nnet_main; - 准备
inference.onnx模型文件(PANNS 分类模型导出为 ONNX 格式); - 准备
conf、label_list、scp、test.wav四个文件,目录结构与示例仓库一致。
2. 执行命令
在 runtime/examples/audio_classification/ 目录下运行:
../../build/Linux/x86_64/engine/audio_classification/nnet/panns_nnet_main --conf_path=./conf --scp_path=./scp --topk=1
程序通过 gflags 接收三个命令行参数(定义见 panns_nnet_main.cc):
| 参数 | 必填 | 含义 |
|---|---|---|
--conf_path |
是 | 引擎配置文件 conf 的路径 |
--scp_path |
是 | wav 路径清单 scp 的文件路径 |
--topk |
是 | 每个 wav 输出概率最高的前 k 个类别 |
源码通过 CHECK_GT 校验三个参数均非空,若缺失会直接终止并提示用法(usage: panns_nnet_main conf scp topk)。
3. 运行日志与输出解读
程序启动后会依次打印:加载的完整配置回显、FastDeploy 运行时初始化信息,然后对 scp 中的每个 wav 输出一行分类结果。README 中的典型输出如下:
wav_normal = true
wav_normal_type = linear
wav_norm_mul_factor = 1.0
model_path = ./inference.onnx
param_path =
dict_path = ./label_list
num_cpu_thread = 1
samp_freq = 32000
frame_length_ms = 32
frame_shift_ms = 10
num_bins = 64
low_freq = 50
high_freq = 14000
dither = 0.0
[INFO] fastdeploy/runtime/runtime.cc(293)::CreateOrtBackend Runtime initialized with Backend::ORT in Device::CPU.
--- Init FastDeploy Runitme Done!
--- Model: ./inference.onnx
test.wav{"Clock alarm":"16.5309"}
输出格式解析:
- 前 15 行是 conf 中全部参数的逐项回显(
Config读取后打印,便于核对实际生效的配置); [INFO] ... Runtime initialized with Backend::ORT in Device::CPU.表明 FastDeploy 已成功在 CPU 上初始化 ONNX Runtime 后端(该日志来自 FastDeploy 运行时自身);--- Init FastDeploy Runitme Done!与--- Model: ./inference.onnx来自 panns_nnet.cc 的初始化成功分支;- 最后一行
test.wav{"Clock alarm":"16.5309"}的格式为wav路径 + "{" + "类别名":"logit值" + "}"。当--topk=1时只输出最高分类别;设置--topk=3则输出前 3 个,类别之间以逗号分隔(拼接逻辑见GetTopkResult)。
注:
16.5309是模型输出的原始 logit 分数而非归一化概率,不同模型该数值的含义与量纲可能不同,建议按模型导出时的约定解读。
五、Android Demo:把分类引擎搬到端侧
README 的后半部分给出了完整的 Android 部署路径,对应工程位于 runtime/examples/audio_classification/android_demo/。整体思路是:先用 build_android.sh 交叉编译出 Android 动态库(libcls.so)与接口头文件,再通过 JNI 封装在 Android Studio 工程中调用。
1. 编译 Android 库并拷贝产物
在 runtime/ 目录下执行:
cd ../../
sh build_android.sh
build_android.sh 使用 NDK(示例为 android-ndk-r25b)以 arm64-v8a、android-21(API ≥ 21)、c++_shared STL、clang 工具链配置 CMake 并编译。编译完成后,按 README 把产物拷贝到 Demo 工程的 jniLibs 与 include 目录:
cp build/Android/arm64-v8a-api-21/cls-android-out/*.so examples/audio_classification/android_demo/app/src/main/cpp/jniLibs/arm64-v8a/
cp build/Android/arm64-v8a-api-21/cls-android-out/panns_interface.h examples/audio_classification/android_demo/app/src/main/cpp/includes/
拷贝后 jniLibs/arm64-v8a/ 下应包含 libcls.so、libfastdeploy.so、libonnxruntime.so、libc++_shared.so 四个动态库(这些文件已存在于示例工程中),接口头文件 panns_interface.h 声明了 ClsCreateInstance / ClsDestroyInstance / ClsFeedForward / ClsReset 四个 C 接口。
2. 资源推送到手机并修改路径
由于 Android 应用内相对路径不可用,需要把模型与字典等资源推到设备,并将 conf 中所有资源路径改为绝对路径,例如:
[CONF]
wav_normal=true
wav_normal_type=linear
wav_norm_mul_factor=1.0
model_path=/data/local/tmp/inference.onnx
param_path=
dict_path=/data/local/tmp/label_list
num_cpu_thread=1
samp_freq=32000
frame_length_ms=32
frame_shift_ms=10
num_bins=64
low_freq=50
high_freq=14000
dither=0.0
随后用 adb 把资源推入设备:
adb push conf label_list scp test.wav /data/local/tmp/
3. 修改 native-lib.cpp 并运行
在 android_demo/app/src/main/cpp/native-lib.cpp 中,把 nClsCreateInstance 里的 conf_path 与 nClsFeedForward 里的 wav_path 改为设备上的实际路径(示例源码当前为 /data/local/tmp/masimeng/cls/conf 与 /data/local/tmp/masimeng/cls/test.wav,需按实际 push 位置修改):
std::string conf_path = "/data/local/tmp/conf";
std::string wav_path = "/data/local/tmp/test.wav";
最后在 Android Studio 中打开 android_demo 工程并运行。JNI 层通过 MainActivity.kt 中的四个 external 函数依次调用 nClsCreateInstance() → nClsFeedForward() → nClsReset() → nClsDestroyInstance(),并把识别结果文本展示到界面 TextView 上。其调用链与命令行主程序完全一致,仅入口形态不同:
- 命令行入口:panns_nnet_main.cc 读取 scp 循环推理;
- Android 入口:native-lib.cpp 由 Kotlin 触发单条 wav 推理;
- 二者最终都汇入
ppspeech::ClsNnet::Forward(panns_nnet.cc)完成统一的特征提取与推理流程。
六、二次开发要点与常见坑
结合源码可以总结出以下关键注意点,便于读者在此基础上复用或改造:
- 特征参数必须与模型对齐:
samp_freq(32000)、frame_length_ms(32)、frame_shift_ms(10)、num_bins(64)、low_freq/high_freq(50/14000)直接影响 Fbank 特征维度与分布,改动任何一项都会改变{1, num_frames, feat_dim}的输入张量形状与数值,导致与训练时特征不一致、精度骤降。 - label_list 顺序即类别索引:字典文件按行读入后,行号直接对应模型输出向量的下标,切勿自行排序或去重。
- 后端由编译宏决定:conf 中的
model_path/param_path在 ONNX 后端下只使用model_path;若要加载 Paddle 双文件模型(*.pdmodel+*.pdiparams),需要以USE_PADDLE_INFERENCE_BACKEND宏重新编译。 - Android 端路径必须是绝对路径:JNI 层直接透传字符串路径给引擎,请使用
/data/local/tmp/...这类设备内绝对路径。 - 结果缓冲上限:
ClsFeedForward的result_max_len参数(示例为 1024)限制了结果字符串长度,若 topk 过大或标签名过长会触发result_max_len is short than result len的提示(panns_nnet.cc),需相应调大缓冲区。
七、小结
本文围绕 runtime/examples/audio_classification/README.md 展开,完整覆盖了 PaddleSpeech 音频分类引擎的配置、数据准备、CPU 命令行推理与 Android 端侧部署四个环节,并结合 panns_nnet.cc、panns_interface.cc、panns_nnet_main.cc 等源码说明了每个参数与流程的底层实现。这套"conf 配置 + label_list 字典 + scp 清单 + FastDeploy Runtime 推理"的模式与仓库内 ASR、VAD 等引擎一脉相承,理解后可以快速迁移到其他音频任务的端侧部署中。相关可继续阅读的资源还包括 runtime/README.md、runtime/engine/audio_classification/CMakeLists.txt 以及 runtime/examples/audio_classification/android_demo/ 完整工程。