## 一个下午搞定：在 ESP32 上跑自定义唤醒词，离线语音唤醒新手教程 想象一下，你只需对着设备喊一声自定义的“小宝贝”或“启动”，它就能瞬间响应。这听起来像是科幻电影里的场景，但如今，借助 TFLite Micro 和 ESP32 这颗不到 30 元的芯片，你完全可以在喝杯咖啡的功夫里实现它。本教程将带你从零开始，搭建一个稳定、低误触的离线语音唤醒系统，让你彻底告别昂贵且依赖网络的云端方案。 ### 为什么选择 TFLite + ESP32？ 如果你在搭建智能家居、机器人或任何需要语音交互的硬件项目，一个核心痛点就是：如何让设备精准地识别一句特定的唤醒词，而不被周围嘈杂的声音干扰。 市面上有很多方案，但它们要么是依赖云端 ASR（自动语音识别）的高成本方案，要么是绑定固定唤醒词（如“小爱同学”），要么需要长期联网。而 **ESP32-S3 这颗芯片**——双核 240MHz 主频、自带 8MB PSRAM、价格不到 30 元——已经足够在本地运行一个完整的神经网络，完成唤醒词检测。 这个方案的**核心组合**是 **TFLite Micro + ESP-IDF**。TFLite 是谷歌针对嵌入式设备优化的推理引擎，ESP-IDF 则直接内置了对其的组件支持。模型经过 INT8 量化后，体积不到 80KB，在 ESP32 上推理一次大约需要 360ms。配合内置的 5 层检测管线，即使在安静环境下，误触率也极低。 ### 唤醒词模型：它到底在算什么？ 很多初学者看到“神经网络”就会觉得门槛很高。其实，唤醒词模型的工作逻辑非常直观，可以分解为以下三个步骤： 1. **音频到“图”**：将 16kHz 的原始音频信号，转换为一张 **Mel 频谱图**。你可以把它想象成一段声音的“指纹”或“照片”：横轴是时间，纵轴是频率，颜色深浅代表能量大小。1秒的音频会被切成 98 帧，每帧包含 32 个频率通道，形成一个 `[98帧 × 32维]` 的矩阵。 2. **“图”到特征**：模型的 **Backbone** 部分（常见的是 DS-TCN 或 SRNN 网络）负责从这张“图”中提取出最关键的特征。它最终输出一个 256 维的向量——你可以理解为“这段音频的精髓”，它浓缩了声音的关键模式。 3. **特征到概率**：模型的 **Head** 部分（通常使用 MultiProto head）将 256 维向量转换为一个 0 到 1 之间的概率值。这个概率值越高，说明模型越确信你听到了唤醒词。 `音频 (16kHz) → Mel 频谱 [98帧 × 32维] → Backbone → [256维向量] → Head → 概率 [0~1]` `Mel 频谱 Backbone Head 输出 ┌──────────┐ ┌────────┐ ┌─────────┐ │········ │ │ SRNN │ │ prob=0.9 │ ← 说出唤醒词 │████████ │────→│or │────→│ prob=0.0 │ ← 安静/噪音 │████████ │ │ DS-TCN │ │ prob=0.1 │ ← 其他词 │········ │ └────────┘ └─────────┘ └──────────┘ ↑ 98×32 ↑ 256维向量` 你最终只需要两个文件：一个 `.tflite` 文件（Backbone，INT8 量化，约 76KB）和一个 `head.h` 文件（MultiProto 权重，约 17KB）。 ### 集成 onnx-wakeword —— 3 步跑起来 `voicute/onnx-wakeword` 是一个完整的 ESP-IDF 开源项目，它已经为你封装好了唤醒词推理引擎和完整的 Demo 示例。 #### 项目结构 `esp32/ ├── components/voicute/ ← 核心库（不依赖具体模型） ├── main/ ← Demo 应用 │ ├── main.cpp │ └── head.h ← 模型 head（用户替换） ├── spiffs_content/ ← 放 .tflite 模型 ├── build.bat / flash.bat ← 一键编译烧录 └── sdkconfig.defaults ← 预配好 PSRAM、Flash` #### 第一步：Clone + 编译 `git clone https://github.com/voicute/onnx-wakeword.git cd onnx-wakeword/esp32 build.bat # Windows` > **小提示：** 首次编译时，系统会自动下载 ESP-IDF 的依赖库（如 `esp-tflite-micro`、`esp-dsp`、`esp-sr` 等），这个过程可能稍长，请耐心等待。之后，你只需要双击 `build.bat` 即可快速编译。项目已经预配好了 ESP32-S3、16MB Flash 和 PSRAM 的配置，开箱即用。 #### 第二步：替换模型 `cp your_wakeword.tflite spiffs_content/ cp your_head.h main/head.h` > **小提示：** 请确保你替换的模型文件路径正确。`spiffs_content/` 目录用于存放 `.tflite` 模型文件，而 `main/head.h` 文件则用于存放模型头部权重。 #### 第三步：烧录 `flash.bat python wake_monitor.py COM5 # 观察实时 prob/RMS` > **常见问题：** 如果烧录失败，请检查你的硬件连接和串口配置。`wake_monitor.py` 脚本用于实时监控模型的推理概率（prob）和音频能量（RMS），是调试误触发的绝佳工具。 #### 核心代码就这么几行 `#include "recognizer.h" #include "head.h" #include "kws_postprocess.h" // 唤醒回调 static void on_wake(voice_event_t ev, voice_evt_data_t d, void *u) { if (ev == VOICE_EVT_AWAKEN) ESP_LOGI("APP", ">>> 关键词!"); } void app_main() { recognizer_config_t cfg = { .model_path = "/spiffs", .threshold = 0.70f, .l5_enabled = 1, // 能量跳变过滤（防音乐/视频误触） .l5_delta = 200.0f, .postprocess = kws_postprocess, }; recognizer_start(&cfg); recognizer_register_callback(0, on_wake, NULL); while (1) { // 从麦克风采集 16192 采样点 int64_t now = esp_timer_get_time() / 1000; recognizer_run_frame(pcm, rms, now); } }` 这个 Demo 还包含了一个 MultiNet 语音命令示例（唤醒后说“灯光变红/蓝/绿”），完整展示了唤醒→进入命令模式的流程。如果不需要，你可以在 `sdkconfig.defaults` 中删除相关配置。 ### 5 层检测管线：如何避免误触发？ 仅仅拿到一个概率值只是基础。真正决定用户体验好坏的是**误触发控制**。`onnx-wakeword` 内置了一套与 Android 端同款的 L1-L5 检测管线，用于层层过滤，确保只有真正的人声唤醒词才能通过。 | 层 | 作用 | 说明 | | --- | --- | --- | | L1 | 连续帧确认 | N 帧连续超阈值才放行 | | L2 | 峰/底比 | 峰值必须远高于背景概率 | | L3 | 冷却 | 1.5s 内不重复触发 | | L4 | 突发阻断 | 短时间连触发 → 拉黑 5s | | L5 | 能量跳变 | 当前音量必须明显高于历史窗口 → 排除平稳音乐/视频声 | **L5 是最核心的过滤器**。它的逻辑是：如果音频能量（RMS）突然跳变（说明有人在说话），则进入待确认状态；等待 400ms 后检查尾音是否降回安静水平。如果是，则确认唤醒，否则拦截。这个机制能有效挡住绝大多数电视、视频、音乐等持续性声音的误触。 #### 调参实战 如果你是第一次跑，推荐配置：**开启 L5，关闭其他层**。因为 ESP32 推理一帧大约 360ms，而唤醒词大约 500ms，最多被一帧覆盖，所以 L1 的连续帧确认不适用；L2/L3 可以根据需要按需开启。 如果遇到误触发，可以按以下两步进行排查： 1. **开启 L5 并调整 delta 值**：首先确保 `l5_enabled=1`，并将 `l5_delta` 设为 200。这个值适合安静环境，意味着“当前音量比之前 0.5~2 秒的最低音量高 200 才放行”。安静时，底噪 RMS 一般在 10~50，说话时能到 300~1000，200 的差值足以区分。 2. **如果仍然误触发，调大 delta 值**： `.l5_enabled = 1, .l5_delta = 800.0f, // 从 200 加大到 800，嘈杂环境用` | 环境 | 建议 delta | 安静 RMS | 说话 RMS | | --- | --- | --- | --- | | 安静房间 | 200~400 | 10~50 | 200~500 | | 普通室内 | 400~800 | 50~150 | 300~800 | | 嘈杂/有音乐 | 800~1200 | 100~300 | 500~1500 | > **常见问题：** 如果怎么调都唤不醒（`l5_delta` 太大导致说话也被拦截），可以查看串口日志中的 `L5 steady: curRms=xxx preMin=xxx`。将这个值调整到比你说话时的 RMS 差值略小即可。反之，如果没说话也莫名其妙触发，则把 `delta` 往大了加。 ### 获得自己的唤醒词模型 无需准备数据，无需 GPU，无需懂深度学习。你只需要打开 **voicute.com**，输入你想用的关键词，点击生成，即可直接下载两个文件： * `xxx.tflite` → 放到 `spiffs_content/` * `head.h` → 替换 `main/head.h` 然后，重新编译并烧录即可。从改词到跑通，整个过程最快只需要十分钟。 ### 总结 | 你需要的 | 去哪搞 | | --- | --- | | ESP-IDF 推理引擎 + Demo | [github.com/voicute/onn…](https://github.com/voicute/onnx-wakeword) | | 自定义唤醒词模型 | [voicute.com](https://voicute.com) 输关键词直接下载 | 从零开始，到在自己的 ESP32 设备上喊出专属的唤醒词，最快一个下午就能搞定。更重要的是，整个过程是**离线、免费、想换就换**的。现在，就动手开启你的离线语音交互之旅吧！