WeKws Android 部署完整教程：从训练到 APK，手机端唤醒词实战
【免费下载链接】wekwsProduction First and Production Ready End-to-End Keyword Spotting Toolkit项目地址: https://gitcode.com/gh_mirrors/we/wekws
WeKws 是一个面向生产环境的端到端关键词检测（Keyword Spotting，KWS）工具包，支持在Android 手机上部署唤醒词检测。本教程带你完成完整闭环：训练唤醒词模型 → 导出 ONNX → 转换为 ORT 移动端格式 → 打包安装 APK，最终在手机上实现"Hey Snips"语音唤醒，帮你快速上手手机端唤醒词开发。
一、WeKws 是什么？为什么适合手机端
WeKws 主打小模型、低延迟、流式检测，是物联网设备唤醒词模块的理想选择。它支持：
- 单唤醒词 / 多唤醒词
- 自定义唤醒词
- 个性化唤醒词（唤醒词 + 声纹）
其 Android 运行时位于 runtime/android/ 目录，核心由 C++ 推理引擎（基于 ONNX Runtime）+ JNI 接口 + Java 录音界面组成，架构非常清晰：
| 模块 | 路径 | 作用 |
|---|---|---|
| 录音与 UI | runtime/android/app/src/main/java/cn/org/wenet/wekws/MainActivity.java | 16kHz 采集麦克风音频，多线程送入检测器 |
| JNI 桥接 | runtime/android/app/src/main/java/cn/org/wenet/wekws/Spot.java | 暴露 init / acceptWaveform / startSpot 等原生方法 |
| C++ 推理入口 | runtime/android/app/src/main/cpp/wekws.cc | 特征提取 + 模型推理，流式输出唤醒概率 |
| 推理核心 | runtime/core/kws/keyword_spotting.h | 基于 ONNX Runtime 的 KWS 推理类 |
二、环境准备：克隆仓库并安装依赖 🛠️
git clone https://gitcode.com/gh_mirrors/we/wekws cd wekws创建 Conda 环境并安装 PyTorch（建议 torch 2.5.1 + CUDA 12.4）：
conda create -n wekws python=3.10 conda activate wekws pip install torch torchaudio pip install -r requirements.txt三、第一步：训练唤醒词模型
以官方 Hey Snips 数据集为例（唤醒词为 "Hey Snips"），训练脚本为examples/hey_snips/s0/run.sh，一条命令跑完数据下载 → 特征统计 → 训练 → 模型平均 → 导出 ONNX：
cd examples/hey_snips/s0 bash run.sh -1 4 --num_keywords 1 --gpus "0"说明：
- stage -1 ~ 0：下载并预处理数据（脚本
local/snips_data_extract.sh） - stage 1：用 tools/compute_cmvn_stats.py 计算 CMVN 特征均值方差
- stage 2：调用
wekws/bin/train.py训练（默认 DS_TCN 模型，仅 21K 参数，非常适合手机端） - stage 3：模型平均 + 测试集 FRR/FAR 评估，绘制 DET 曲线
- stage 4：执行 wekws/bin/export_onnx.py，输出
exp/ds_tcn/avg_30.onnx
官方 README 显示，DS_TCN 模型仅21K 参数，在 Hey Snips 测试集上每小时误唤醒率（FAR 固定 1 次/小时）对应的漏检率仅1.98%，小而有保障。
四、第二步：转换为移动端 ORT 模型 📱
PyTorch 导出的 ONNX 还需要再转换一次以启用移动端图优化。参照 runtime/android/README.md：
python -m onnxruntime.tools.convert_onnx_models_to_ort exp/ds_tcn/avg_30.onnx会得到avg_30.ort和avg_30.with_runtime_opt.ort，后者性能更好，推荐使用。
⚠️ 关键一步：把生成的 ORT 文件重命名为kws.ort，放到 Android 工程的 assets 目录：
runtime/android/app/src/main/assets/kws.ort工程里已自带一个示例kws.ort，可直接替换。
五、第三步：检查特征维度配置
Android 侧默认特征维度为40。如果你的模型用的是 80 维特征，需修改runtime/android/app/src/main/cpp/wekws.cc中这一行：
feature_config = std::make_shared<wenet::FeaturePipelineConfig>(40, 16000); // 40 -> 80把40改成80即可，这是新手最常踩的坑。
六、第四步：编译打包 APK
两种方式任选：
方式一：Android Studio（推荐新手）
安装 Android Studio，直接打开wekws/runtime/android目录，等待 Gradle 同步和 CMake（NDK）编译完成后，点击 Run 即可安装到连接的真机。
方式二：Linux 命令行构建
cd wekws/runtime/android bash ./gradlew build生成的 APK 位于app/build/outputs/apk/debug/app-debug.apk，用数据线或adb install装到手机即可。
七、第五步：真机验证唤醒效果 🎉
打开 App 后：
- 授予麦克风权限（App 启动时会自动请求 RECORD_AUDIO 权限）
- 点击Start Record按钮
- 对着手机说 "Hey Snips"
- 界面上会实时显示检测概率（格式为
offset prob: 0.xxxx），概率显著升高即表示唤醒成功
界面还会同步显示麦克风能量波形（由VoiceRectView渲染）。检测流程由三条线程协作完成：录音线程 → 音频队列 → 特征提取与推理线程，保证低延迟流式响应。
八、常见问题 FAQ
Q1：编译时 CMake 报错？确认 Android Studio 中安装了与CMakeLists.txt匹配的 CMake 和 NDK 版本，并开启 Android Gradle 插件的 NDK 支持。
Q2：唤醒不灵敏？
- 检查模型特征维度是否配置一致（40 还是 80）
- 用训练时同款采样率（16kHz）测试
- 更换为
with_runtime_opt优化版模型通常只影响速度，不影响精度
Q3：想换成自己训练的唤醒词？只需重训模型 → 导出 ONNX → 转 ORT → 替换kws.ort，无需改动任何 C++/Java 代码；若需修改提示语，改MainActivity.java中的HINTS常量即可。
Q4：除了 Android 还支持哪些平台？WeKws 同时提供 x86 桌面端（runtime/onnxruntime/）和树莓派（runtime/raspberrypi/）运行时，C++ 核心代码完全复用。
九、核心文件速查
- Android 示例工程：runtime/android/
- Android 部署说明：runtime/android/README.md
- C++ 推理核心：runtime/core/
- Hey Snips 训练脚本：examples/hey_snips/s0/run.sh
- ONNX 导出工具：wekws/bin/export_onnx.py
- 依赖清单：requirements.txt
总结
WeKws 让"唤醒词"这件事变得触手可及：21K 参数的超小模型 + 一条命令训练 + 五步上手机。跟着本教程，你只需训练、导出、替换模型、编译 APK，就能在自己的 Android 设备上跑起流式唤醒词检测，非常适合智能音箱、语音助手等 IoT 场景的原型验证与落地。
【免费下载链接】wekwsProduction First and Production Ready End-to-End Keyword Spotting Toolkit项目地址: https://gitcode.com/gh_mirrors/we/wekws
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
