企业官网建设流程全解析

ML-KWS-for-MCU，全称 Machine Learning Keyword Spotting for Microcontrollers，是 ARM 在 GitHub 上开源的一个关键词唤醒示例工程。光看名字，很多人会以为它只是跑在 STM32 开发板上的一个语音识别小 demo，没多少信息量。但如果你真的把它当成“玩具”跳过，会错过一个非常典型的边缘 AI 落地样本：它把数据采集、特征工程、模型训练、量化导出、嵌入式部署这一整条链路，完完整整地放在一个仓库里。这篇文章我想从一个做过多次源码静态评测的开发者视角，把这个仓库的工程架构拆开讲清楚，也会把我实际阅读和移植过程中踩过的坑一并写上。适合正准备在 MCU 上做离线唤醒、语音控制，或者想研究 ARM 官方怎么组织边缘 AI 工程代码的读者。

作为一个研究过不少嵌入式机器学习项目的人，我可以直接说结论：这个项目虽然老了，但它是理解“MCU 上怎么跑通一个实时 AI 应用”的最佳解剖样本之一。它的代码没有过度封装，算法也足够简单，你可以一行行读下来，而不像看某些商用 SDK 那样一头雾水。下面我按自己的静态评测路径，把这个仓库完整过一遍。

1. 为什么说 ML‑KWS‑for‑MCU 是理解边缘 AI 落地的关键样本

1.1 在 MCU 上做关键词识别，比听起来难得多

MCU 和云端服务器的差别，不是“配置低一点”，而是完全不同的约束环境。以 ML-KWS-for-MCU 主推的 STM32F746G-DISCO 为例，这颗芯片有 1MB Flash、320KB RAM，主频 216MHz，带 FPU，这在 MCU 里已经算中高端了。但就算这样，你要在这上面跑实时语音识别，依然要精打细算：模型权重动不动就是几百 KB，RAM 里还要留出音频缓冲、特征缓冲、推理中间变量、系统栈，实际可用空间比想象中小得多。

更麻烦的是实时性。音频流是 16kHz 采样，按 20ms 一帧算，每秒要处理 50 帧。每一帧都得在帧移时间内完成特征提取和推理，否则音频数据就会积压，出现丢帧和识别卡顿。同时，MCU 上往往没有操作系统，内存靠手动管理，外设要靠寄存器或者 HAL 库操作，任何一步出了差错都很难调试。ML-KWS-for-MCU 的价值就在这里：它把“如何在资源受限的芯片上做 AI 推理”这个问题，用一套完整可跑的代码回答了一遍。

1.2 一条完整链路：音频采集到唤醒决策

在 MCU 上做关键词唤醒，数据链路大概是这样的：麦克风采集 PDM 数字音频信号，通过 I2S/SAI 接口和 DMA 搬运到内存，放进一个环形缓冲区；主循环从缓冲区取数据，算 MFCC 特征；特征送入神经网络推理，得到各个关键词的置信度；最后根据置信度和触发门限，决定是否唤醒系统。整个链路里每一环都是独立的工程问题，任何一个环节没做好，最终产品都会出问题。

ML-KWS-for-MCU 的代码组织恰好就是围绕这条链路展开的。它没有把算法做成一个黑盒，而是把音频采集、特征提取、神经网络推理、结果后处理这几个模块分开存放。所以读这个仓库时，你会发现它的目录结构天然像一张系统框图，这是我觉得它在教学层面相当优秀的原因。你读懂它，后面再接触任何商业 KWS 方案，都会觉得似曾相识。

1.3 它后来去哪了：TFLite Micro 的源头之一

还有一个容易忽略的背景：ML-KWS-for-MCU 在 ARM 内部更多是作为参考实践，而不是正式产品 SDK。它的很多设计被后来的 TensorFlow Lite for Microcontrollers 项目吸收，演变成了我们今天看到的 micro_speech demo。所以，与其说今天还要在生产环境直接使用 ML-KWS-for-MCU，不如说它是很多现代 MCU 语音方案的源头。

理解了这层关系，你再看这个老仓库，就不会用“这东西还能不能跑”来评判它，而会把它当作一套活教材：训练侧怎么准备数据和导出权重，部署侧怎么在极低资源下完成推理，训练与部署之间怎么约定接口。这些思路放到 2025 年的今天依然不过时。

2. 仓库全景：先把 training 与 deploy 两块地盘分清楚

2.1 顶层目录到底放了什么

拿到仓库，第一件事不是急着编译，而是先看顶层目录结构和 README。ML-KWS-for-MCU 的根目录大致分为三块：training、deploy、release_prebuilt。

training 目录里是 Python 训练脚本，负责从 WAV 音频数据中提取特征、训练神经网络、导出模型权重。deploy 目录里是 C/C++ 嵌入式工程，包含完整的 STM32 应用代码，以及 MFCC 和神经网络推理的具体实现。release_prebuilt 里则是官方预先训练好的模型文件，目的是让你跳过训练环节，直接把模型下到板子上跑通流程。

这三块的职责边界非常清晰。训练侧是“生成模型”的地方，部署侧是“消费模型”的地方，预编译文件是给不想碰训练的人准备的快速通道。理解这个分工，后面看代码时就不会在 Python 脚本和 C 文件之间迷路。

2.2 训练与部署是两个语言、两个世界

训练侧的世界里，数据是浮点张量，模型层可以随意调整，显存/内存不够就换更大的机器。部署侧的世界里，一切都要落到 C 语言和具体的芯片外设上，文件里的每一字节都可能是有限资源。ML-KWS-for-MCU 最需要注意的，是训练脚本里计算 MFCC 特征的方式，必须和部署端 C 代码里的特征提取保持完全一致。如果训练时用的是 13 维 MFCC、部署时却配置成 12 维，模型精度会直接崩掉，而且这个崩法不是报编译错，是静默地精度劣化，极难排查。

我在静态评测时最关注的就是这种“训练-部署一致性”。ML-KWS-for-MCU 的解法是把特征参数集中管理，在部署端用一个头文件定义采样率、帧长、帧移、Mel 滤波器数量等常量，训练脚本里也读取同一份配置，从机制上减少两边不一致的可能。这个设计思路非常值得借鉴，哪怕你后续改成 TFLite Micro 路线，这种“训练与部署共享一份配置契约”的做法也应该保留。

2.3 模型权重藏在哪个文件里

很多人拿到仓库后会有一个疑问：模型呢？在 ML-KWS-for-MCU 中，模型权重一般会生成 C 头文件或源文件，比如 dnn_weights.c/h、wav2mfcc 相关的初始化数据头文件，部署代码在编译时直接 include 这些文件，把权重作为只读常量放进 Flash。所以换模型时，你真正要替换的是这些权重文件，以及和它们配套的网络结构定义。

这里要提醒一句：不要只换权重不换结构。神经网络推理代码里的层数、每层节点数、激活函数类型，都必须和权重一一对应。否则在 MCU 上不会立即崩溃，但推理结果会变成垃圾数据。后面第 5 章我会详细讲替换流程，这里先记住一个原则：权重和结构是绑定的，替换时必须成对修改。

3. 训练侧源码静态走读：模型是怎么被“装进”单片机的

3.1 数据流水线：从 WAV 到 MFCC 张量

训练侧的第一步是准备数据。ML-KWS-for-MCU 使用的是 Google Speech Commands 数据集，每条音频大约 1 秒，16kHz 采样率，内容是各种英文单词，比如 yes、no、one、two 这类常见指令词。训练脚本会把 WAV 文件读进来，做分帧、加窗、FFT、Mel 滤波器组、对数运算、DCT，最终得到 MFCC 特征。

MFCC 本质上是一种声音的“压缩表示”，它把一段音频变成一组系数，让神经网络不用直接面对几万个原始采样点。熟悉语音处理的读者应该知道，MFCC 的配置参数会直接影响识别效果：Mel 滤波器数量多了，特征维度大、计算量大；少了可能丢失关键信息。ML-KWS-for-MCU 的做法在小模型场景下比较典型：特征维度不用太大，否则模型参数量和计算量都会失控。具体每帧取多少维、每次堆叠多少帧，你可以去代码里搜索 kNumMelBins、kNumFrames 这类常量确认，不同版本略有差别。

3.2 模型结构：CNN、DFS 与 TC-ResNet 的取舍

仓库里提供的模型不只一种，常见的有小型 1D/2D CNN，以及更省参数的 Depthwise Separable Filter（DFS）和时间卷积残差网络（TC-ResNet）。为什么要在 MCU 上用这些结构，而不是更火的 Transformer？原因很简单：Flash 容量有限。一个简单的 MLP/CNN 模型，参数可以压到几十 KB 到一两百 KB 之间，这是 MCU 能接受的量级。而稍微大一点的模型，哪怕只有 1MB，也会直接耗尽整颗芯片的 Flash，更别提运行时 RAM 的开销。

我在阅读训练代码时，建议的顺序是：先打开模型定义文件（例如 cnn_1d.py），看网络层是怎么搭的，再回到数据加载脚本理解输入张量形状，最后看导出脚本。这样你就能把“一个具体的网络结构”和“部署侧 C 代码里的那一串数组”对应起来。这个仓库早期的训练代码基于 TensorFlow 1.x，用了一些如今已经移除的 API，这是静态评测时需要特别标注的风险点，后面细说。

3.3 权重导出：从 checkpoint 到 C 头文件

训练收敛之后，模型权重并不会像服务器端那样直接保存成 SavedModel 或者 ONNX，而是要通过导出脚本转成 C 语言数组。这个导出过程通常包括几个动作：把 TensorFlow checkpoint 读取出来，按层顺序把权重展开成一维数组，可选地做 int8 量化，最终生成头文件。这些头文件被放到部署工程里，用 const 关键字修饰，烧录到 Flash 中。

我在做静态评测时，会重点检查导出脚本是否包含量化逻辑。使用 float32 权重直接推理的好处是简单，配合 Cortex-M 的 FPU 可以直接跑；缺点是占用 Flash 较大、推理稍慢。使用 int8 量化则可以把模型压到原来的四分之一，但部署端必须实现反量化逻辑，否则推理结果会明显偏差。ML-KWS-for-MCU 的方案相对直接，有些版本直接用 float 权重在 MCU 上推理，追求更极致的性能时可以再走 CMSIS-NN 的 int8 路径。理解这条导出链路，是后续自定义模型的关键。

3.4 复现训练时的三个老坑

如果你真把训练脚本拉下来跑，大概率会踩到这些坑：

第一个是环境兼容。TensorFlow 1.x 的 API 和现在的 TensorFlow 2.x 差别很大，slim、tf.contrib 这些模块早已被移除，Python 2/3 的兼容问题也让人头大。第二个是数据集获取，Speech Commands 数据集体积不小，下载速度受网络环境影响很大，跑完整训练并不轻松。第三个是依赖管理，训练代码可能牵涉很多老版本库，你不得不花大量时间在装环境上。

所以我的建议是：不要死磕老训练代码。如果你的目标只是把官方预编译模型跑通，就直接跳去 deploy 目录用 release_prebuilt。如果你是做新项目、新关键词，最好用现代框架重新实现一个同等规模的模型，然后把 ML-KWS-for-MCU 的部署代码作为参考。它的部署端才是真正的宝藏。

4. 部署侧 C 源码精读：从 PDM 麦克风到串口打印结果

4.1 音频采集：板载麦克风与 DMA 环形缓冲

部署侧的音频输入，在 STM32F746G-DISCO 板子上用的是板载数字麦克风，输出 PDM 格式数字信号。芯片内部的 I2S/SAI 外设负责接收，DMA 负责把数据搬运到内存，这样 CPU 不需要一字节一字节地去读外设寄存器，能腾出时间做特征提取和推理。

代码里通常会有一个环形缓冲区，中断回调函数把新音频数据写进去，主循环按帧去读。生产者和消费者之间的读写指针必须处理正确，否则会出现新数据覆盖未处理数据的丢帧问题，或者读到重复数据的重复帧问题。ML-KWS-for-MCU 在这里的代码组织比较清晰，把缓冲操作封装成独立的读写接口，我在实际移植时也延续了这种设计。

4.2 MFCC 前端：CMSIS-DSP 是真正的主角

MFCC 前端是整个项目里最“信号处理”的部分。它没有自己从头写 FFT，而是直接调用 CMSIS-DSP 库里的 arm_rfft_fast_f32 等函数。CMSIS-DSP 是 ARM 官方针对 Cortex-M 优化过的数学库，充分使用了 FPU 和 DSP 指令，性能比自己写的朴素 FFT 高出一大截。

MFCC 的计算流程大体是：音频分帧、加窗、做 FFT、求功率谱、经过 Mel 滤波器组、取对数、做 DCT，输出一组系数。每一帧音频会得到一个特征向量，连续若干帧再堆叠成一个特征矩阵，作为神经网络的输入。如果你看到的代码里函数名是 wav2mfcc 或类似的名字，那基本就是这条流程的封装。这里要特别强调：如果你要在其他 MCU 上移植，一定要保证 FFT 的实现足够高效，否则光特征提取就可能吃掉好几毫秒的 CPU 时间，实时性直接不达标。

4.3 神经网络推理：纯 C 实现，权重全放 Flash

推理部分一般是若干个全连接层或卷积层串联。权重以常量数组放在 Flash，运行时把特征数据拷入 RAM 中的 buffer，然后一层层向前运算。如果使用了 CMSIS-NN，会调用 arm_fully_connected_s8、arm_convolve_s8 这类算子；如果保留 float 路径，则主要靠向量乘加运算和优化过的矩阵乘法。

这里有一个嵌入式推理特有的设计，我认为非常值得关注：内存复用。神经网络每一层的中间激活值，计算完当前层之后，上一层的数据就不再需要了。所以部署代码可以把整个网络所有中间层的结果都放在同一块 RAM 缓冲区里，用偏移量去索引不同的层。这样即使模型的权重占了几百 KB Flash，真正运行时占用的 RAM 也只要几十 KB。这种“静态内存池复用”的思路，是嵌入式推理和服务器推理最本质的区别之一，也是很多从 PC 转嵌入式的人最容易犯的设计错误——他们习惯给每层都申请独立数组，结果内存直接爆掉。

主循环的核心逻辑大概长这样：

while (1) { if (ring_buffer_has_enough(&buf, kNumFrames * kFrameStep)) { extract_mfcc_features(&buf, input_tensor); run_nn(input_tensor, output_scores); post_process(output_scores); } }

代码不复杂，但每一步都踩在资源约束上，读起来非常有“工程感”。

4.4 性能测量：用 DWT 计数器看每一帧的真实耗时

KWS 系统的实时性衡量标准很简单：处理一帧的耗时必须小于帧移时间。如果帧移是 20ms，那特征提取加推理的总耗时就不能超过 20ms，否则音频数据会越积越多，最终识别结果持续滞后。

我当时做静态评测时，常用的测时工具是 Cortex-M 内核自带的 DWT 计数器。初始化代码也很简单：

CoreDebug->DEMCR |= CoreDebug_DEMCR_TRCENA_Msk; DWT->CYCCNT = 0; DWT->CTRL |= DWT_CTRL_CYCCNTENA_Msk;

然后在关键函数入口记录当前计数值，函数结束后相减，再根据主频换算成秒。通过这种办法，可以精确定位到底是 FFT 耗时高，还是矩阵乘法耗时高。我实测下来的经验是，小型模型的矩阵乘往往不是瓶颈，MFCC 里的 FFT 和 Mel 滤波器组反而经常占掉最大头。所以如果性能不够，优化优先级应该是：先优化 FFT，再优化矩阵乘，最后才去动模型结构。

5. 把官方 Demo 改造成自己的唤醒词工程：替换流程与工具链坑点

5.1 换关键词前先弄清三个地方

很多人以为换关键词就是改一个标签字符串，实际完全不是。你需要动的东西至少包括三处：训练数据的标签表、模型输出层的类别数、部署端对输出张量解释的代码。如果只是把英文单词换成中文唤醒词，还要考虑发音时长和音频切分逻辑，因为中文多音节词的 MFCC 特征分布和英文单音节词差异很大。

部署端对输出的解释也很关键：模型输出是一个概率分布，你要决定哪些类别算“唤醒成功”，超过多少置信度才算触发，需不需要连续多帧投票来降低误唤醒率。这些后处理逻辑通常不写在模型代码里，而是写在应用层，但实际效果直接决定产品体验。误唤醒率和漏唤醒率需要反复权衡，门限调高会漏唤醒，调低会频繁误触发。

5.2 替换模型的完整操作顺序

我把整个替换流程按顺序列出来，方便直接对照操作：

1. 准备新关键词数据。建议正样本数千条以上，覆盖不同说话人、不同噪声环境，同时准备充足的负样本，否则模型会倾向乱触发。
2. 用训练脚本完成训练或微调，观察验证集准确率，确保模型本身没有欠拟合。
3. 运行权重导出脚本，生成 C 头文件或源文件。
4. 在 deploy 工程中替换权重文件，并逐个核对网络层的维度，包括输入维度、隐藏层大小、输出类别数。
5. 修改标签定义和置信度门限。
6. 编译、烧录，用串口或板载 LED 观察唤醒效果。
7. 在安静、嘈杂、远场、近场等不同场景下做回归测试，记录误唤醒率和唤醒率。

第 4 步是最容易出问题的地方。维度对不上时，C 编译器不一定报错，可能只是数组越界或者输出错乱，这类 bug 在 MCU 调试器里非常隐蔽。所以我习惯在替换后写一段自检代码，在初始化时打印各层期望输入输出尺寸，跑几个固定向量对比输出，确认和训练侧一致后再继续。

5.3 编译器和工具链版本的真实坑点

STM32 工程通常可以用 Keil MDK、IAR 或 GCC 三种工具链编译。老工程默认可能是 Keil AC5 编译器，而新版 MDK 默认已经是 AC6。AC5 和 AC6 对 C 标准支持、内联汇编写法的处理不完全一样，CMSIS-DSP 和 CMSIS-NN 在两个编译器下的表现也存在差异。很多人到处找 arm compiler 5.06，其实就是因为老项目锁定在 AC5，新环境又默认只带 AC6。如果你只是维护老工程，可以去找 AC5 装回去；如果是新项目，建议一步到位用 AC6 或 GCC，省得以后迁移再折腾。

另外，用 GCC 交叉编译链时，务必确认用的是带硬浮点的工具链，并且在编译选项里正确指定 -mcpu、-mfpu、-mfloat-abi 这些参数。否则即使芯片有 FPU，生成的代码也可能走软浮点路径，浮点推理速度会差出一个数量级。这种问题不会报错，只会让你觉得“为什么我的板子比别人的慢这么多”，本质上就是编译选项没配对。

6. 静态评测结论：这套老开源代码现在还用得值不值

6.1 值得学的地方

先说优点。这个仓库的代码量适中，目录结构清晰，训练与部署链路完整，没有把算法封装成黑盒。你从 WAV 文件读到 MFCC，再到神经网络推理，每一步都能在源码里找到对应实现，这对学习嵌入式机器学习的价值非常大。MFCC 和神经网络推理都是纯 C 代码，不依赖庞大的运行时库，比那些必须绑定特定 SDK 的示例工程要清爽得多。

它示范的工程组织方式也值得借鉴：特征参数集中管理、权重只读存放、内存静态复用、训练与部署通过配置文件约定接口。这些思想放在商业项目中依然适用，甚至可以说，正是这些基础工程素养决定了一个边缘 AI 产品能不能稳定落地。

6.2 明显的老化痕迹

再说不好的地方。训练侧过度依赖 TensorFlow 1.x，在现代开发环境里复现成本很高；部署侧默认绑定 STM32F746G-DISCO 的板级外设，换到其他 MCU 需要重写不少 BSP 代码；音频前端只有基础 MFCC，没有任何噪声抑制、回声消除、自适应 VAD，这些在真实语音产品里基本是标配，缺了它们，野外环境下的唤醒率会很难看。

另外，这个项目只解决了关键词唤醒，没有后续的指令词识别或者多轮对话能力。如果你要做的是一个完整的语音交互设备，它只是一个前级触发模块，后面还有很长一段路要走。直接拿它当产品基座，是行不通的。

6.3 如果我在今天重新设计一套类似的 KWS 系统

如果让我在 2025 年重新做一套 MCU 唤醒方案，我不会直接复制它的训练脚本，而会用现代 TFLite 或 PyTorch 训练模型，再导出到 TFLite Micro 或者 CMSIS-NN 执行。但我一定会保留这个仓库里体现出来的工程思维方式：把特征参数集中管理，把权重作为只读常量，用静态内存池复用激活值，把训练与部署之间的接口定义成显式配置。

这套“小模型、低开销、可解释”的架构思想，比代码本身更值得抄。毕竟工具会过时，但工程上的取舍逻辑不会。ML-KWS-for-MCU 的很多具体实现已经被新项目取代，但它作为一个完整落地的参考样本，放在今天看依然很有价值。

我自己做唤醒词项目时，通常会把这个仓库当作主参考而不是主依赖。遇到平台从 STM32 换到别的国产 MCU，或者需要加一个降噪前端，只要掌握了这条链路的来龙去脉，改动就不是伤筋动骨的事。最后再分享一个个人习惯：拿到这类老工程，先别急着重新训练，先把官方预编译模型下到板子上，完整跑通一次音频采集到串口打印结果的过程。这个动作能帮你把“环境工具链问题”和“模型算法问题”分开，后面调试新模型时，你会感谢这个前置步骤。