网页里做语音功能，很多人的第一反应是调用云端语音识别：采集麦克风、上传音频、等待返回文字，再判断用户说了什么。
但如果需求只是“开始录音”“下一页”“打开面板”或者一个固定唤醒词，整套 ASR 链路其实太重了。更合适的做法是关键词识别（KWS）：模型不转写整句话，只判断目标短语有没有出现。
这类模型足够小，可以直接放进网页，由 ONNX Runtime Web 在浏览器本地推理：
麦克风 → 单声道 PCM → 重采样到 16kHz → Mel 特征
→ ONNX 模型 → 时序判决 → 触发前端事件
模型和运行库加载完成后，音频不需要上传到业务服务器。
先在线体验，再决定是否集成
听词控制台已经放了可以直接使用的演示模型：打开 Voicute 控制台 并登录，在“演示模型”区域选择一个模型，点击“在线测试”，允许浏览器使用麦克风后就能直接说出页面显示的关键词，观察识别分数和触发结果。
演示模型旁边同时提供“下载”按钮。下载后可以通过页面给出的推理代码在本地复现，不必先训练自己的模型。自己生成的模型也可以先在控制台里用麦克风测试，确认实际发音效果后再下载部署。
也就是说，可以先用现成 Demo 验证“浏览器本地推理”这条链路，再考虑自定义关键词和正式集成。
为什么值得放到浏览器里做
第一是隐私。原始麦克风音频留在当前页面，不需要为了一个固定指令持续上传。
第二是部署简单。静态站点、内网控制台、PWA、展厅大屏和设备配网页面，都可以直接承载推理逻辑，不需要另建语音识别服务。
第三是响应稳定。没有网络往返，触发延迟主要来自音频窗口、模型推理和判决规则。
当然，它不适合自由对话。如果要把任意一句话转成文字，仍然应该使用 ASR。
模型输出不能直接当触发结果
KWS 模型通常对连续的短音频窗口输出概率。如果只写一句“概率大于 0.7 就触发”，很快会遇到三个问题：
所以完整引擎还需要后处理：
| 连续帧确认 | 过滤单帧尖峰 |
| 冷却时间 | 防止一次发音重复触发 |
| 峰值与背景比 | 避免在持续底噪上误判 |
| 爆发封锁 | 处理电视、音乐等连续高概率片段 |
| 能量跳变 | 判断人声是否从近期背景中突然出现 |
调参原则不是“五层全开、数值拉满”，而是先只开连续帧和冷却时间，再根据真实误触类型逐项增加限制。过滤越严格，漏检风险也越高。
前端代码应该怎么组织
业务层最好只接收检测事件，不直接处理音频帧和张量：
const detector = await WakeWordDetector.create({
modelUrl: '/models/ni-hao-xiao-ting.onnx',
threshold: 0.72,
consecutiveFrames: 2,
cooldownMs: 1800
})
detector.on('detected', ({ keyword, score }) => {
console.log('检测到：', keyword, score)
openControlPanel()
})
await detector.start()
具体库的 API 会不同，但结构最好保持清晰：检测器负责麦克风、特征、推理和时序状态；业务代码只决定检测成功后做什么。
浏览器端的几个工程限制
除 localhost 外，浏览器麦克风通常要求 HTTPS。页面还需要明确的用户授权，音频上下文往往也要由点击等用户操作启动。
设备输入可能是 44.1kHz 或 48kHz，而模型通常要求固定采样率。必须在送入特征提取前重采样，否则即使张量形状没报错，识别效果也会明显下降。
浏览器还可能降低后台标签页的执行频率，移动端甚至会挂起页面。需要常年待机的硬件，更适合 Android、Linux 或 ESP32-S3；浏览器适合用户正在使用的页面。
上线前怎样测
不要只拿训练样本测试。建议自己建立一个小测试集：
- 多个人以不同语速、距离说目标词；
- 正常聊天但不说目标词；
- 电视、音乐、键盘和房间底噪；
- 目标产品实际会遇到的麦克风和设备。
正样本统计召回率，长时间负样本统计误触发次数，两者不要混成一个“准确率”。如果某种口音或自然说法总是叫不醒，加入少量经过授权的真人录音重新训练，通常比不断降低阈值更有效。
什么时候应该选这套方案
适合：网页唤醒词、语音快捷键、展厅大屏、演示控制、无障碍操作、网页内按词启动录音，以及少量固定命令。
不适合：语音输入法、会议转写、自由对话和开放词表搜索。
开源项目 onnx-wakeword 提供了浏览器等平台的参考推理实现。自定义模型可以自行训练，也可以通过 听词 Voicute 生成标准 ONNX/TFLite 文件；下载后在本地运行，不需要推理 AccessKey，也不按设备收运行费用。
想先验证效果，可以直接进入 控制台演示模型，点击“在线测试”；需要本地调试时，再点击“下载”取得模型和集成入口。
官网还提供了可被搜索引擎直接访问的完整教程：浏览器端离线唤醒词：用 ONNX 实现网页本地语音触发。
