PaddleSpeech 关键词识别（KWS）实战指南：基于 MDTC 模型的命令行与 Python API 使用详解

PaddleSpeech 关键词识别KWS实战指南基于 MDTC 模型的命令行与 Python API 使用详解【免费下载链接】PaddleSpeechEasy-to-use Speech Toolkit including Self-Supervised Learning model, SOTA/Streaming ASR with punctuation, Streaming TTS with text frontend, Speaker Verification System, End-to-End Speech Translation and Keyword Spotting. Won NAACL2022 Best Demo Award.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleSpeech关键词识别Keyword Spotting, KWS是语音技术中的一项核心任务旨在从一段连续的语音中判定是否包含指定的唤醒词或关键词。本文以 PaddleSpeech 仓库中 demos/keyword_spotting 为骨架完整讲解如何通过单条命令行或几行 Python 代码使用 PaddleSpeech 预训练模型mdtc_heysnips对 WAV 音频执行关键词识别并结合仓库源码深入剖析其调用链、特征提取流程与 MDTC 模型结构帮助读者既会开箱即用也能理解底层实现原理。一、KWS 任务与 Demo 概述KWSKeyword Spotting是一项从给定语音音频中识别是否包含特定关键词的技术是智能音箱、语音助手、低功耗唤醒等场景的核心模块。PaddleSpeech 仓库在 demos/keyword_spotting 中提供了一个完整的演示实现输入一段 WAV 格式的语音文件输出该语音与目标关键词的匹配得分Score、判定阈值Threshold以及是否命中关键词Is keyword的布尔结论使用方式既可执行单条paddlespeech kws命令行命令也可以通过paddlespeech.cli.kws.KWSExecutor以 Python API 的方式在几行代码内完成调用。该 demo 默认使用的模型为mdtc_heysnips针对英文 Hey Snips 唤醒词训练采样率为 16k。除此之外仓库还提供了配套的完整训练与评估示例见 examples/hey_snips/kws0支持从零训练 MDTC 模型并在 HeySnips 数据集上评估 DET 指标。二、环境安装在使用 KWS demo 之前需要先完成 PaddleSpeech 的安装。PaddleSpeech 提供了 easy、medium、hard 三种安装方式easy通过 pip 直接安装发布包适合大多数仅需调用预训练模型的场景medium安装包含完整依赖如 kenlm、numpy 等的标准环境hard从源码编译安装适合需要二次开发或使用最新特性的用户。详细的安装步骤请参阅仓库内的安装文档中文版见 install_cn.md根据自身环境选择合适的方式即可。安装完成后可以通过paddlespeech命令或 Python 导入来验证环境是否就绪。三、准备输入音频KWS demo 的输入需要满足两个约束必须是 WAV 格式文件.wav采样率必须与模型一致。默认模型mdtc_heysnips的采样率为 16k因此输入的 WAV 文件采样率也应为 16k。若采样率不匹配识别结果将不可靠建议使用sox等工具对音频进行重采样。仓库提供了两个官方示例音频可直接下载用于体验wget -c https://paddlespeech.cdn.bcebos.com/kws/hey_snips.wav https://paddlespeech.cdn.bcebos.com/kws/non-keyword.wavhey_snips.wav包含 Hey Snips 关键词的阳性样本non-keyword.wav不包含关键词的阴性样本。这两个文件同样出现在 demo 目录的 run.sh 脚本中可以直接bash run.sh一键完成下载与推理演示。四、命令行使用推荐4.1 基本命令安装完成后在包含音频文件的目录下执行paddlespeech kws --input ./hey_snips.wav paddlespeech kws --input ./non-keyword.wav对应输出如下# Input file: ./hey_snips.wav Score: 1.000, Threshold: 0.8, Is keyword: True # Input file: ./non-keyword.wav Score: 0.000, Threshold: 0.8, Is keyword: False可以看到模型对包含关键词的音频给出接近 1.0 的高分1.000 0.8判定为命中对不含关键词的音频给出 0.0 分0.000 0.8判定为未命中。4.2 全部参数说明执行paddlespeech kws --help可查看完整的命令行参数。结合 paddlespeech/cli/kws/infer.py 中KWSExecutor的参数定义各参数含义如下参数类型默认值说明--inputstr必填用于关键词识别的音频文件路径--thresholdfloat0.8判定是否命中关键词的得分阈值得分高于该值判定为包含关键词--modelstrmdtc_heysnipsKWS 任务的模型类型可选值由预训练模型列表动态生成tag[:tag.index(-)]当前为mdtc_heysnips--configstrNoneKWS 任务的配置文件YAML不设置时使用预训练模型自带的默认配置--ckpt_pathstrNone模型参数文件checkpoint不设置时自动下载并使用预训练模型权重--devicestrpaddle.get_device()执行推理的设备默认取当前环境中 PaddlePaddle 的默认设备-d, --job_dump_resultflag关闭将任务结果保存到文件-v, --verboseflag关闭增加当前任务的 logger 输出信息从源码实现看infer.py--model的 choices 并非硬编码而是从task_resource.pretrained_models的键中动态截取-之前的模型名生成因此预训练模型表更新后命令行选项也会自动扩展。4.3 使用自定义配置与权重当不满足于预训练模型默认配置时可以通过--config与--ckpt_path指定自己训练或微调得到的模型。在 infer.py 的_init_from_path中可以看到两条路径使用预训练模型ckpt_pathNone时拼接资源标签model_type -16k从云端下载模型配置与权重均取自下载目录使用本地模型显式传入config与ckpt_path时两者被转换为绝对路径后直接加载此时配置文件中的stack_num、stack_size、in_channels、res_channels、kernel_size、num_keywords、sample_rate、frame_shift、frame_length、n_mels等字段将决定模型结构与特征提取参数。五、Python API 使用除了命令行PaddleSpeech 还提供面向开发者更友好的 Python API。核心入口是paddlespeech.cli.kws.KWSExecutor其定义与导出见 paddlespeech/cli/kws/init.py 与 infer.pyimport paddle from paddlespeech.cli.kws import KWSExecutor kws_executor KWSExecutor() result kws_executor( audio_file./hey_snips.wav, threshold0.8, modelmdtc_heysnips, configNone, ckpt_pathNone, devicepaddle.get_device()) print(KWS Result: \n{}.format(result))输出KWS Result: Score: 1.000, Threshold: 0.8, Is keyword: True__call__方法infer.py的执行流程可以归纳为四个阶段设备设置paddle.set_device(device)模型初始化_init_from_path(model, config, ckpt_path)构建 backbone 与分类头、加载权重并置为eval()模式预处理与推理preprocess()完成音频加载与特征提取infer()在paddle.no_grad()下执行前向计算得到 logits后处理postprocess(threshold)将 logits 转换为可读的字符串结果并返回。值得注意的是该 executor 还支持批量输入命令行模式下execute()会通过get_input_source()解析输入源对多个输入逐一执行推理并将结果汇总infer.py任一输入出错时返回False并在结果中以异常类名: 错误信息的形式标注。六、输出结果解读KWS 推理的最终输出是一行形如Score: X.XXX, Threshold: Y, Is keyword: True/False的文本。其计算逻辑在 infer.py 的postprocess中kws_score max(self._outputs[logits][0, :, 0]).item() return Score: {:.3f}, Threshold: {}, Is keyword: {}.format( kws_score, threshold, kws_score threshold)关键点模型输出的logits形状为(batch, time_steps, num_keywords)取[0, :, 0]表示对第一个样本、所有时间步、第一个关键词的输出取最大值作为整段音频的得分Score保留三位小数展示判定规则为简单的大小比较Score Threshold时Is keyword: True否则为False阈值threshold是影响误报率False Alarm与漏报率Miss平衡的关键超参数阈值越高越不容易误触发但可能漏掉真正包含关键词的语音阈值越低则相反。实际落地时通常结合 DET 曲线Detection Error Tradeoff选择业务可接受的阈值。七、预训练模型PaddleSpeech 官方发布并内置到命令与 Python API 的 KWS 预训练模型如下模型语言采样率mdtc_heysnipsen16k目前官方预训练模型聚焦于英文 Hey Snips 唤醒词场景采样率 16k。如需其他语言或自定义关键词可参考仓库内的训练示例见下文第九节自行训练模型。八、源码级原理剖析从音频到得分8.1 音频加载与特征提取在preprocess阶段infer.py输入音频经过两条核心路径音频读取通过paddlespeech.audio.backends.soundfile_load加载 WAV 波形特征提取使用 Kaldi 风格的 FBank 滤波器组特征即paddlespeech.audio.compliance.kaldi.fbank参数来自模型配置self.feature_extractor lambda x: kaldi_fbank( x, srconfig[sample_rate], frame_shiftconfig[frame_shift], frame_lengthconfig[frame_length], n_melsconfig[n_mels])默认配置下见 examples/hey_snips/kws0/conf/mdtc.yaml采样率16000、帧移10ms、帧长25ms、80 维 Mel 滤波器组。提取后的特征经unsqueeze(0)增加 batch 维度后送入模型。8.2 MDTC 模型结构mdtc_heysnips对应的骨干网络是MDTCMulti-scale Dilated Temporal Convolution其实现位于 paddlespeech/kws/models/mdtc.py整体由以下组件构成DSDilatedConv1d深度可分离膨胀卷积Depthwise Separable Dilated Conv1d先用groupsin_channels的分组膨胀卷积捕获长时依赖再以1x1逐点卷积混合通道配合 BatchNorm显著降低参数量TCNBlock单个时间卷积块由两个卷积路径组成并带有残差连接causalTrue时对输入做因果裁剪避免未来信息泄漏适合流式/在线场景TCNStack按stack_size组、组内膨胀率2^ll从 0 到stack_num-1递增的方式堆叠多个TCNBlock逐层扩大感受野MDTC整体骨干包含一个预处理TCNBlock与stack_num个TCNStack多个尺度stack的输出在时间维度对齐后求和融合KWSModel分类头在 backbone 的隐藏表示上接nn.Linear(hidden_dim, num_keywords)线性层与 Sigmoid 激活将输出归一化到(0, 1)区间作为关键词存在的概率得分。默认配置stack_num3、stack_size4、res_channels32、kernel_size5、num_keywords1。训练过程中使用的损失与相关工具位于 paddlespeech/kws/models/loss.py推理时为causalTrue的因果模式。九、从零训练与评估进阶若想复现或训练自己的 KWS 模型仓库提供了完整的 HeySnips 示例examples/hey_snips/kws0/README.md。其使用步骤如下准备数据集按照该 README 指向的 sonos/keyword-spotting-research-datasets 说明下载并解压 HeySnips 数据集然后将data_dir替换为实际路径一键训练与评估CUDA_VISIBLE_DEVICES0,1 ./run.sh conf/mdtc.yaml脚本通过stage/stop_stage控制执行阶段脚本位于 examples/hey_snips/kws0/run.shstage 1从零开始训练stage 2在测试集上评估模型并计算所有触发阈值下的检测错误权衡DET指标stage 3绘制 DET 曲线用于可视化。训练脚本与评分脚本分别位于 paddlespeech/kws/exps/mdtc/train.py、score.py 与 compute_det.py路径环境由 examples/hey_snips/kws0/path.sh 提供。配置文件关键项conf/mdtc.yaml 是训练与推理共用的配置模板按区块划分区块关键参数默认值作用Datadataset: paddleaudio.datasets:HeySnips、data_dir指定数据集类与数据路径Networknum_keywords: 1、stack_num: 3、stack_size: 4、in_channels: 80、res_channels: 32、kernel_size: 5定义 MDTC 网络结构与关键词类别数Featurefeat_type: kaldi_fbank、sample_rate: 16000、frame_shift: 10、frame_length: 25、n_mels: 80特征提取参数推理阶段由 infer.py 读取使用Trainingepochs: 100、batch_size: 100、learning_rate: 0.001、weight_decay: 0.00005、grad_clip: 5.0、checkpoint_dir等训练超参数与日志/保存频率Scoringcheckpoint、score_file、stats_file、img_file评估阶段的权重路径与输出文件十、常见注意事项采样率对齐输入 WAV 必须与模型采样率16k一致否则特征与模型训练分布不匹配导致得分失真阈值调节threshold0.8为默认值实际业务中应根据误报/漏报的代价参考 DET 曲线调整自定义模型传入--config与--ckpt_path时需保证配置中的网络参数与 checkpoint 匹配且特征参数frame_shift、frame_length、n_mels、sample_rate应与训练时一致设备指定--device支持cpu/gpu等 PaddlePaddle 设备标识默认取环境中的paddle.get_device()日志输出默认关闭 verbose 日志排查问题时可加-v观察预处理与推理细节。至此读者应已掌握 PaddleSpeech KWS demo 从安装、数据准备、命令行/ Python API 推理到输出解读、模型原理与训练评估的完整链路可在自己的项目中直接落地关键词识别能力。【免费下载链接】PaddleSpeechEasy-to-use Speech Toolkit including Self-Supervised Learning model, SOTA/Streaming ASR with punctuation, Streaming TTS with text frontend, Speaker Verification System, End-to-End Speech Translation and Keyword Spotting. Won NAACL2022 Best Demo Award.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleSpeech创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考