唤醒词/命令词模型全平台部署指南

模型一次训练，六端通用

唤醒词和命令词模型导出为标准 ONNX 格式，不绑定任何硬件或芯片。同一个 100-167KB 的模型文件，配合开源推理引擎 onnx-wakeword（Apache 2.0），支持六个平台：

引擎内置了完整的音频处理管线——Mel 频谱特征提取、ONNX Runtime 推理、五层防误触检测。不需要额外加载 Mel 模型，不需要自己写音频处理代码。

Android 部署

适合手机 App、平板、车载设备。后台常驻监听，CPU 占用不到 1%，几乎不耗电。

val engine = OnnxWakeWord.create(context, "model_info.json", "melspectrogram.onnx")
engine.setCallback { word, prob ->
    when (word) {
        "打开灯光" -> turnOnLight()
        "关闭灯光" -> turnOffLight()
        "调亮"     -> brighten()
        "调暗"     -> dim()
    }
}
engine.start()
// 后台 CPU < 1%，单帧推理 < 5ms

实测小米 14（骁龙 8 Gen2），单帧推理不到 5ms，挂一晚上电量几乎无感。

Linux / Windows / macOS 部署

支持 Python 和 C++ 两种接口。适合树莓派、Jetson、普通 PC 等设备。

# Python 版本 — pip install onnx-wakeword
from wakeword_engine import WakeWordEngine
engine = WakeWordEngine()
engine.load("model_info.json", "melspectrogram.onnx")
engine.set_threshold(0.5)
engine.set_L1(True)   # 连续帧过滤瞬态噪声
engine.set_L3(True)   # 冷却防重复触发
engine.start(lambda word, prob, info: print(f"检测到: {word}"))

// C++ 版本 — 适合嵌入式集成
#include "wakeword/engine.h"
WakeWordEngine engine;
engine.Load("model.onnx");
engine.SetCallback([](const std::string& word, float prob) {
    if (word == "打开灯光") turn_on_light();
});
engine.Start();

树莓派 4B 上单帧推理约 2-3ms，CPU 占用不到 2%。

ESP32 部署

适合智能开关、IoT 设备等资源受限场景。INT8 量化后模型约 50KB，SRAM 占用约 200KB。ESP32-S3 + INMP441 I2S 麦克风。

#include "wakeword.h"

wakeword_config_t config = {
    .model_data = model_onnx_buffer,
    .model_size = model_onnx_size,
    .sample_rate = 16000,
    .threshold = 0.5,
    .cons_frames = 2,     // L1: 2 帧连续确认
    .cooldown_ms = 1500,  // L3: 冷却 1.5 秒
};
wakeword_handle_t handle;
wakeword_init(&handle, &config);
wakeword_set_callback(handle, on_keyword_detected, NULL);
wakeword_start(handle);

平均功耗约 13mA，2000mAh 电池可撑 6 天。

Web 浏览器部署

WebAssembly + ONNX Runtime Web，浏览器端本地推理，无需安装。适合在线 Demo、产品演示。

const engine = VoicuteWakeWord.create()
await engine.load("model_info.json", "melspectrogram.onnx")
await engine.start((word, prob) => {
    console.log(`检测到: ${word} (${(prob*100).toFixed(0)}%)`)
})

支持 Chrome、Edge、Safari。音频在浏览器内处理，不上传服务器。

五层防误触发

所有平台共享同一套检测逻辑，五层可独立开关：

日常使用建议 L1 + L3 常开，有电视/音乐环境加开 L5。

部署流程

1. 在 听词 Voicute 输入命令词，十来分钟拿到 ONNX 模型
2. 从 GitHub onnx-wakeword 下载对应平台的 SDK
3. 把模型文件和 model_info.json 放进项目目录
4. 按上面示例代码写几行集成，回调里做你想做的事
5. 测试阈值和防误触参数，调整到最佳状态

同一个 ONNX 文件，同一个引擎，同一套 API。在浏览器上调试好参数，到了 ESP32 上不用重新调。

更多训练和选型细节见 自定义唤醒词训练指南 和 KWS vs ASR 对比。