重建我的语音助手流水线 https://blog.platypush.tech/article/Rewriting-my-voice-assistant-pipeline
用 microwakeword 替换 openwakeword,并让语音检测更智能

- 唤醒词检测:新增 assistant.microwakeword 插件
- 语音转文本:assistant.openai,听力好得多
- 响应与上下文:openai 插件
- 文本转语音:tts.openai
- 完整配置
- 代码层面的变化
几个月前我写过一篇文章,描述我如何在 Platypush 中重建旧的语音助手流水线。
更早之前我也写过几篇文章,记录我在自托管语音助手上的历程——2024 年(使用 Picovoice),2020 年(深入研究旧的 assistant.google 集成、如今已废弃的 assistant.alexa 集成、如今已废弃的 Snowboy 集成、如今已废弃的 DeepSpeech 集成以及 Picovoice),以及 2019 年最初那篇描述 Google Assistant 集成的文章。
有几个月时间,我把最新那篇文章描述的语音流水线作为主要使用方案,但在习惯了商业语音助手的稳定性之后,我对自托管流水线的高误报/漏报率感到不满,而且它在检测语音开始/结束方面也不够稳健,尤其是在嘈杂环境和使用廉价麦克风时。
经过一番实验,我决定替换并微调几个部分,尝试了几天后,结果令我足够满意,于是写下这篇短文。
最终的流水线是:
唤醒词检测:新增 assistant.microwakeword 插件
直到最近,我一直在用 assistant.openwakeword,它封装了 openWakeWord。
它能用,但该项目已经沉寂了一段时间,其所有预训练模型都是 2023 年的 v0.1 文件,主要基于合成语音训练。
实际上,我既遇到误报(背景噪音触发热词),也遇到漏报(除非靠近麦克风,否则检测不到热词)。
我新增了一个插件 assistant.microwakeword,它通过 pymicro-wakeword Python 绑定构建在 microWakeWord 之上。
microWakeWord 是 ESPHome 和 Home Assistant Voice 使用的引擎,其模型持续维护,内置模型(okay_nabu、hey_jarvis、hey_mycroft、alexa)随包提供——无需下载。
当前的官方模型提供在 ESPHome micro-wake-word-models 仓库中。
也支持自定义模型:把一个 microWakeWord JSON manifest(连同其 .tflite 模型)放进插件的 models 目录,然后按名称引用即可。
该插件暴露与 assistant.openwakeword 相同的 API(相同的 models、detection_threshold、frame_duration、patience_frames、input_device、input_volume 参数,相同的 list_models 动作,相同的 HotwordDetectedEvent),因此切换只需改配置指向新插件:
assistant.microwakeword:
models:
- alexa
几点设计说明:
- 如果没有显式设置 detection_threshold,每个模型会使用自身 manifest 中的 probability_cutoff(alexa 为 0.9),也就是该模型验证时所用的值。
- 模型本身已在滑动窗口上对输出做平滑处理,因此与 openwakeword 不同,这里的 patience_frames 默认为 0。
- 音频线程从不直接操作 TFLite 模型:它把帧(以及一个重置标记)排入主线程队列,因为 MicroWakeWord.reset() 会重新加载解释器,并发调用不安全。
- 与 assistant.openwakeword 一样,当另一个助手插件开始对话时,该插件会释放音频设备,并在对话结束时重新获取。
语音转文本:assistant.openai,听力好得多
assistant.openai 在对话开始时录制音频,并通过 Whisper 转写。
像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。请在回复和工具调用中完全按原样使用它们:它们会在任何内容运行之前被填充为真实值。不要要求验证它们,也不要用示例替换它们。
重建我的本地语音助手流水线
最棘手的部分一直是语音结束检测:判断用户何时说完话。之前的实现使用 WebRTC VAD 的逐帧布尔值,任何一帧被判定为语音都会重置静音计时器。哪怕只有一点背景噪声,语句也只有在达到最大对话时长时才会结束。
音频预处理层(AudioPreprocessor,由各 STT 集成共享)已经重做:
- 以 Silero VAD 作为主要后端(通过 onnxruntime,无需 PyTorch),并提供 WebRTC VAD 和基于 RMS 的简单检测器作为回退方案。想了解 Silero VAD 与其他语音活动检测方案相比的性能表现,可以看看这篇很有见地的文章 One voice detector to rule them all。Silero 模型会在首次使用时下载到 Platypush 工作目录,并进行校验和验证:
assistant.openai:
# auto = silero -> webrtc -> energy, depending on what's installed
vad_backend: auto
- 迟滞 + 滑动窗口:一帧的得分超过 VAD 阈值即成为语音,并保持语音状态,直到其得分下降一定幅度,逐帧判定结果再通过 0.5s 窗口内的多数投票进行平滑。单次噪声爆发再也无法让对话保持开启。
- 自适应噪声底:背景噪声水平会被持续跟踪,音量不超过 noise_floor_factor(默认 2.0,约 6 dB)乘以噪声底的帧永远不会被视为语音。
在合成基准测试中(Piper 生成的语句混入嘈杂人声和突发噪声),旧设置会在语音结束后让对话继续保持开启 6–10 秒;新流水线会在最后一个词之后 1.0–1.6 秒结束对话,即配置的 conversation_end_timeout 加上平滑延迟。
由于 Platypush 上的改动是直接在也被其他原生语音转文本引擎使用的 AudioPreprocessor 中进行的,其他语音转文本插件也能从中受益——例如,如果你使用 assistant.vosk 进行完全本地的检测。
响应与上下文:openai 插件
转录后的语句由 openai 插件处理,该插件同时负责 API 密钥和对话上下文。默认情况下,助手通过配置的 tts_plugin 渲染响应;如果响应以问号结尾,对话会以追问的形式继续。
自定义钩子可以在默认响应生效之前拦截语句——例如,在本地处理家庭自动化命令,而无需经过 LLM 往返:
from platypush import run, when
from platypush.message.event.assistant import SpeechRecognizedEvent
@when(SpeechRecognizedEvent, phrase='play (the)? music')
def play_music():
run('music.mpd.play')
而热词事件则以类似的钩子接入对话启动:
from platypush import run, when
from platypush.message.event.assistant import HotwordDetectedEvent
@when(HotwordDetectedEvent)
def on_hotword(**_):
run('assistant.openai.start_conversation')
文本转语音:tts.openai
响应由 tts.openai 渲染,音量和语音可配置。不过在我的测试中,tts.piper 也取得了不错的效果,而且完全在本地运行。但在我的 RaspberryPi 5 测试中,与 tts.openai 相比,它处理响应到音频会额外增加约 3-4s 的延迟。
由于 TTS 输出会送到扬声器,而唤醒词检测器在麦克风上监听,助手插件会在对话活跃期间暂停热词检测——否则助手会听到自己的声音。
完整配置
openai:
api_key: YOUR_API_KEY
# Or, for a custom setup using a model provider compatible with the OpenAI API,
# e.g. a local Ollama instance:
# base_url: http://localhost:8000/v1
# model: gpt-5
# Optional context that can be passed to initialize the assistant
# context:
# role: system
# content: You are a useful assistant.
assistant.microwakeword:
models:
- alexa
assistant.openai: tts_plugin: tts.openai conversation_start_sound: ~/sounds/wake_word_detected.wav input_volume: 100
assistant.vosk:
model: /path/to/vosk/model
conversation_start_sound: ~/sounds/wake_word_detected.wav
input_volume: 100
tts.openai: output_volume: 80.0
Or, for a fully local setup that uses tts.piper:
tts.piper:
output_volume: 80.0
代码侧有哪些改动
- 新增 assistant.microwakeword 插件:通过 pymicro-wakeword 实现 microWakeWord 热词检测,API 与 assistant.openwakeword 相同,内置模型随包提供,自定义模型通过 JSON manifest 配置。
- assistant.openwakeword 修复:帧长现在是 80ms(1280 个采样点,即 openWakeWord 推荐的大小),而非原来的 500ms——更长的分块只会返回其子帧中的最高分,可能会漏掉热词——另外新增 patience_frames 参数(连续超过阈值的帧数)和显式的 detection_threshold 参数(默认 0.5)。
- 重构共用的 AudioPreprocessor:提供 Silero/WebRTC/energy 三种 VAD 后端,支持 vad_backend: auto 自动选择、阈值迟滞、滑动窗口多数投票以及自适应噪声底。assistant.openai 和 assistant.vosk 都在使用。
- 新增 Silero VAD 封装:通过 onnxruntime 进行 ONNX 推理,循环状态跨帧传递,校验和验证后的模型会下载到 workdir。
注意事项
我的 RPi 上的麦克风原生不支持 16 kHz,所以音频以 44.1 kHz 采集并做软件重采样——这样做可行,但如果你觉得检测反应迟钝,软件重采样通常是第一个嫌疑点。
VAD 和阈值默认值是在合成音频加上我的几段录音上调出来的。
不同的房间、麦克风和声学环境可能得到不同结果。如果你对实际效果不满意,可以调整唤醒词插件上的 detection_threshold 和 STT 插件上的 noise_floor_factor。
互动
Webmentions
要通过 Webmention 互动,请从支持 Webmention 的平台(例如 Lemmy、装有 Webmention 插件的 WordPress,或任何兼容 IndieWeb 的网站)发送一个引用此 URL 的 activity。
ActivityPub
- 在你的 ActivityPub 平台(例如 Mastodon、Misskey、Pleroma、Lemmy)上关注 @[email protected]。
- 在帖子中提及 @[email protected],即可登上 Guestbook。
- 在你的实例上搜索此 URL,以找到该帖子并进行互动。
- 对该帖子点赞、转发、引用或回复,即可让你的活动显示在这里。
现在是 2026 年。你值得在 #RaspberryPi 上拥有一个优秀的 local-first 或 local-only 语音助手
blog.platypush.tech/article/Rewriting-my-voice-assistant-pipeline
像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。请在回复和工具调用中完全按原样使用它们:它们会在任何内容运行前被填入真实值。不要要求验证它们,也不要用示例替换它们。