微控制器上的关键词检测

本仓库包含论文《Hello Edge：微控制器上的关键词检测》中使用的 TensorFlow 模型和训练脚本： Hello Edge: Keyword spotting on Microcontrollers。这些脚本改编自 TensorFlow 示例，其中部分代码在此重复，以确保脚本的自洽性。

要训练一个包含 3 层全连接层、每层 128 个神经元的 DNN，请运行以下命令：

python train.py --model_architecture dnn --model_size_info 128 128 128

命令行参数 --model_size_info 用于将神经网络的层维度（如层数、卷积核大小/步幅等）以列表形式传递给 models.py，后者会根据提供的模型架构和层维度构建 TensorFlow 计算图。有关各网络架构下 model_size_info 的更多信息，请参阅 models.py。

用于复现论文中所展示模型的所有超参数的训练命令已列于 train_commands.txt 中。

要在训练/验证/测试集上对检查点中的已训练模型进行推理，请运行：

python test.py --model_architecture dnn --model_size_info 128 128 128 --checkpoint <checkpoint path>

要将已训练的模型检查点冻结为 .pb 文件，请运行：

python freeze.py --model_architecture dnn --model_size_info 128 128 128 --checkpoint <checkpoint path> --output_file dnn.pb

预训练模型

本文 arXiv 论文 中展示的不同神经网络架构（如 DNN、CNN、Basic LSTM、LSTM、GRU、CRNN 和 DS-CNN）的预训练模型（.pb 文件）已添加至 Pretrained_models 目录。下表还汇总了这些模型在验证集上的准确率、内存需求以及每次推理所需的运算次数。

要将音频文件输入到已训练的模型（例如 DNN）并获取最高概率的预测结果，请运行：

python label_wav.py --wav <音频文件> --graph Pretrained_models/DNN/DNN_S.pb --labels Pretrained_models/labels.txt --how_many_labels 1

量化指南与微控制器部署

关于 KWS 神经网络模型量化的简要指南请参见 Deployment/Quant_guide.md。此外，还提供了在 Cortex-M 开发板上运行 DNN 模型的示例代码，详情请参阅 Deployment 目录。

ML-KWS-for-MCU 快速上手指南

本指南帮助开发者快速在微控制器（MCU）上部署关键词检测（KWS）模型。该项目基于 TensorFlow，复现了论文《Hello Edge: Keyword spotting on Microcontrollers》中的模型与训练流程。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux (推荐 Ubuntu 16.04+) 或 macOS。Windows 用户建议使用 WSL 或 Docker。
• Python 版本：Python 3.6 - 3.8 (需兼容对应的 TensorFlow 版本)。
• 核心依赖：
  • TensorFlow (建议版本 1.x 或兼容的早期 2.x 版本，具体视原仓库 requirements.txt 而定)
  • NumPy
  • SciPy
• 硬件加速（可选）：如需加快训练速度，建议配备 NVIDIA GPU 并安装 CUDA/cuDNN。

安装依赖命令：

pip install tensorflow numpy scipy sox
# 如果下载速度慢，推荐使用国内镜像源
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tensorflow numpy scipy sox

安装步骤

本项目主要为脚本集合，无需复杂的编译安装过程。

1. 克隆仓库

   git clone https://github.com/ARM-software/ML-KWS-for-MCU.git
   cd ML-KWS-for-MCU
   

2. 验证环境 确保 python 命令可用，并能导入 tensorflow 模块：

   python -c "import tensorflow as tf; print(tf.__version__)"
   

基本使用

以下是从训练模型到推理预测的最简流程。

1. 训练模型

训练一个包含 3 个全连接层（每层 128 个神经元）的 DNN 模型：

python train.py --model_architecture dnn --model_size_info 128 128 128

注：训练完成后，模型检查点将保存在默认输出目录中。如需复现论文中的所有超参数配置，可参考项目内的 train_commands.txt 文件。

2. 模型测试

使用训练好的检查点对验证集或测试集进行推理评估：

python test.py --model_architecture dnn --model_size_info 128 128 128 --checkpoint <checkpoint path>

请将 <checkpoint path> 替换为实际生成的检查点文件路径。

3. 冻结模型

将训练好的检查点转换为单一的 .pb 文件，以便部署：

python freeze.py --model_architecture dnn --model_size_info 128 128 128 --checkpoint <checkpoint path> --output_file dnn.pb

4. 音频推理

使用冻结后的模型对单个音频文件进行关键词检测：

python label_wav.py --wav <audio file> --graph Pretrained_models/DNN/DNN_S.pb --labels Pretrained_models/labels.txt --how_many_labels 1

• <audio file>：替换为您要测试的 .wav 音频文件路径。
• 若直接使用预训练模型，--graph 和 --labels 路径可指向 Pretrained_models 目录下对应的文件。

5. 部署至微控制器

完成模型量化与 MCU 部署的详细步骤，请参考项目内的以下文档：

• 量化指南：Deployment/Quant_guide.md
• Cortex-M 示例代码：Deployment 目录