完全本地语音助手搭建指南

# 在2026年构建一个完全本地的语音助手 来源：https://blog.platypush.tech/article/Local-voice-assistant ### 一个基于 Platypush 的、适合树莓派的实用语音助手搭建方案 - 流水线 (https://blog.platypush.tech/article/Local-voice-assistant#the-pipeline) - 环境准备 (https://blog.platypush.tech/article/Local-voice-assistant#setup)- 模型 (https://blog.platypush.tech/article/Local-voice-assistant#models)- 唤醒词检测 (https://blog.platypush.tech/article/Local-voice-assistant#hotword-detection) - 语音转文字 (https://blog.platypush.tech/article/Local-voice-assistant#speech-to-text) - 文字转语音 (https://blog.platypush.tech/article/Local-voice-assistant#text-to-speech) - 配置 (https://blog.platypush.tech/article/Local-voice-assistant#configuration)- 智能家居插件 (https://blog.platypush.tech/article/Local-voice-assistant#home-automation-plugins) - 构建 (https://blog.platypush.tech/article/Local-voice-assistant#build) - 运行 (https://blog.platypush.tech/article/Local-voice-assistant#run)- Linux (https://blog.platypush.tech/article/Local-voice-assistant#linux) - macOS (https://blog.platypush.tech/article/Local-voice-assistant#macos) - Windows (https://blog.platypush.tech/article/Local-voice-assistant#windows) - 使用 (https://blog.platypush.tech/article/Local-voice-assistant#usage) - 扩展助手 (https://blog.platypush.tech/article/Local-voice-assistant#extending-the-assistant)- 开始对话 (https://blog.platypush.tech/article/Local-voice-assistant#starting-a-conversation) - 确定性命令 (https://blog.platypush.tech/article/Local-voice-assistant#deterministic-commands) - AI 命令 (https://blog.platypush.tech/article/Local-voice-assistant#ai-commands)- 语音转意图 (https://blog.platypush.tech/article/Local-voice-assistant#speech-to-intent) - 回退响应 (https://blog.platypush.tech/article/Local-voice-assistant#response-fallback) - 聆听时暂停音乐 (https://blog.platypush.tech/article/Local-voice-assistant#pausing-music-while-listening) - 完全本地化 (https://blog.platypush.tech/article/Local-voice-assistant#going-fully-local) - 为何这套架构经久不衰 (https://blog.platypush.tech/article/Local-voice-assistant#why-this-architecture-ages-well) - 最后的话 (https://blog.platypush.tech/article/Local-voice-assistant#final-notes) 关注我一段时间的朋友都知道，我对自建语音助手有一种执念。 多年来我的实验可以总结如下： - *2007年*: Voxifera (https://github.com/blacklight/voxifera)，我首次尝试构建一个原始的语音助手，基于隐马尔可夫模型 (https://en.wikipedia.org/wiki/Hidden_Markov_model)。当然不适合通用场景，但在2007年足以区分十几个简单的语音命令。 - *2019年*: 第一个语音助手 (https://blog.platypush.tech/article/Build-your-customizable-voice-assistant-with-Platypush)，基于 Platypush (https://platypush.tech/) 构建。它在树莓派上使用现已废弃的 Google Assistant Library (https://developers.google.com/assistant/sdk/guides/library/python/)，配合麦克风和扬声器，通过事件钩子可接入任何自动化例程和自定义命令。 - *2020年*: 第二次迭代 (https://blog.platypush.tech/article/Build-custom-voice-assistants) 基于 #Platypush (https://blog.platypush.tech/tags/platypush)，这次还支持了其他助手插件——Alexa（集成已移除）、Snowboy（因项目已死而移除）、Mozilla DeepSpeech（因 Mozilla 停止维护而移除）、PicoVoice，以及 mimic3（基于 Mycroft 的文本转语音引擎，Mycroft 现已破产）。 - *2024年*: 第三次迭代 (https://blog.platypush.tech/article/The-state-of-voice-assistant-integrations-in-2024) 基于 Platypush，这次增强了 PicoVoice 集成，并新增了基于 OpenAI API 的语音转文字和文字转语音插件。 但现在是2026年，或许硬件和软件都已足够成熟，可以构建完全基于设备的语音助手，且采用可能长期存在的完全开源方案。 在本文中，我们将用 Platypush 来填补最后一块拼图： - `assistant.openwakeword` (https://docs.platypush.tech/platypush/plugins/assistant.openwakeword.html) 本地监听唤醒词。 - `assistant.vosk` (https://docs.platypush.tech/platypush/plugins/assistant.vosk.html) 本地转录命令。 - `tts.piper` (https://docs.platypush.tech/platypush/plugins/tts.piper.html) 本地播报回答。 - `openai` (https://docs.platypush.tech/platypush/plugins/openai.html) 仅在语言模型有用时才使用：将杂乱的语音转化为意图，或回答一般性问题。 - 现有的智能家居插件，如 `light.hue` (https://docs.platypush.tech/platypush/plugins/light.hue.html)、`music.mpd` (https://docs.platypush.tech/platypush/plugins/music.mpd.html) 或 `weather.openweathermap` (https://docs.platypush.tech/platypush/plugins/weather.openweathermap.html)，用于执行动作。 结果并不是另一个换皮的云助手。唤醒词引擎、语音识别、命令分发和语音合成都可以在设备上运行。如果 `openai` 步骤指向本地的 OpenAI 兼容服务器，那么整个流水线也可以留在你的局域网内。 ## 流水线 架构可以总结如下： 监听 触发 唤醒词已检测 触发 语音已识别 短语匹配本地命令 普通响应 文字转语音 文字转语音 处理意图 播放语音响应 后续追问 对话结束 对话结束 麦克风 assistant.openwakeword HotwordDetectedEvent assistant.vosk.start_conversation ConversationStartEvent SpeechRecognizedEvent 本地命令钩子 openai.get_response tts.piper 扬声器 ConversationEndEvent 监听 触发 唤醒词已检测 触发 语音已识别 短语匹配本地命令 普通响应 文字转语音 文字转语音 处理意图 播放语音响应 后续追问 对话结束 对话结束 麦克风 assistant.openwakeword HotwordDetectedEvent assistant.vosk.start_conversation ConversationStartEvent SpeechRecognizedEvent 本地命令钩子 openai.get_response tts.piper 扬声器 ConversationEndEvent **唤醒词检测**（“OK Google”、“Alexa”等）是一个持续、低延迟的工作负载，不需要网络。 **语音转文字**也很适合本地推理：Vosk 模型足够小，可以在包括树莓派在内的中等硬件上运行，对于短小的智能家居命令完全够用。 **文字转语音**是另一个当今本地模型已经足够好的领域：Piper 声音库快速、小巧，而且比老旧的机器人式 `espeak` 回退方案好得多。 唯一可选的需要网络的部分是**语言模型**。 但这是一种策略选择，而非语音栈的硬性要求。 ## 环境准备 克隆助手示例仓库： `` git clone https://git.platypush.tech/platypush/assistant-sample cd assistant-sample `` ### 模型 下一步是下载语音栈所需的语音模型。 #### 唤醒词检测 服务首次启动时，会自动下载所有可用模型。 之后，你可以使用以下命令列出可用的模型（当服务运行时）： `` curl -s -XPOST \ -H 'Content-type: application/json' \ -H "Authorization: Bearer $PLATYPUSH_TOKEN" \ -d '{"type":"request", "action":"assistant.openwakeword.list_models"}' \ http://localhost:8008/execute `` 其中 `$PLATYPUSH_TOKEN` 是运行服务的用户的令牌。 你可以在服务首次启动时访问 `http://localhost:8008` 获取令牌。创建凭证，然后选择 *设置* -> *令牌* -> *生成 API 令牌*。 #### 语音转文字 Vosk 语音模型的完整列表在此处 (https://alphacephei.com/vosk/models)。 关于英语模型质量的一些反馈： 模型大小备注`vosk-model-small-en-us-0.15` (https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip)40 MB非常快速且轻量的模型，甚至在老树莓派上也能运行，但准确性可能较低。`vosk-model-en-us-0.22-lgraph` (https://alphacephei.com/vosk/models/vosk-model-en-us-0.22-lgraph.zip)128 MB对于清晰的母语者语音相当准确，但体积足够小，即使在树莓派上也能流畅运行。`vosk-model-en-us-0.22` (https://alphacephei.com/vosk/models/vosk-model-en-us-0.22.zip)1.8 GB准确的通用美式英语模型。在笔记本电脑或 x86 处理器上很快，但在树莓派上可能有点重。将选中的模型下载到 Docker 卷工作目录： `` mkdir -p ./workdir/assistant.vosk/models cd ./workdir/assistant.vosk/models wget "https://alphacephei.com/vosk/models/vosk-model-en-us-0.22-lgraph.zip" unzip "vosk-model-en-us-0.22-lgraph.zip" rm "vosk-model-en-us-0.22-lgraph.zip" `` #### 文字转语音 从此处 (https://rhasspy.github.io/piper-samples/) 下载语音合成模型。 音频样本也可获取，以便在下载前了解声音类型。 模型通常包含一个 `*.onnx` 文件和一个 `*.onnx.json` 文件。将这两个文件下载到 Docker 卷工作目录： `` mkdir -p ./workdir/piper_tts cd ./workdir/piper_tts wget "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/hfc_female/medium/en_US-hfc_female-medium.onnx" wget "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/hfc_female/medium/en_US-hfc_female-medium.onnx.json" `` ### 配置 复制并编辑示例配置文件 (https://git.platypush.tech/platypush/assistant-sample/src/branch/main/config/config.example.yaml)。 `` cp config/config.example.yaml config/config.yaml `` #### 智能家居插件 当识别的语音能够到达家中其他设备时，助手才真正有用。 例如，Hue 灯： `` light.hue: bridge: hue groups: - Living Room `` 以及 MPD/Mopidy 用于音乐： `` music.mopidy: host: localhost music.mpd: host: localhost poll_interval: null `` 这些只是普通的 Platypush 插件 (https://docs.platypush.tech/plugins.html)。 助手不需要特别了解 Hue、MPD、Chromecast、Zigbee、MQTT 或其他任何东西。 它只需要发出事件；你的钩子来决定如何处理它们。 构建助手服务的容器镜像： `` docker build -t platypush-voice . `` ## 运行 助手需要访问主机的麦克风和扬声器。容器通过 PulseAudio 路由 ALSA，因此下面的示例将其连接到主机上运行的 PulseAudio 服务器。 ### Linux 安装了 PulseAudio 或 `pipewire-pulseaudio` 的情况下： `` docker run --rm \ -e PULSE_SERVER=unix:/run/pulse/native \ -v /run/user/$(id -u)/pulse/native:/run/pulse/native \ --name voice-assistant \ -p 8008:8008 \ -v ./config:/etc/platypush \ -v ./workdir:/var/lib/platypush \ platypush-voice `` ### macOS 在主机上安装并启动 PulseAudio： `` brew install pulseaudio pulseaudio --daemonize=yes --exit-idle-time=-1 pactl load-module module-native-protocol-tcp \ auth-anonymous=1 \ listen=0.0.0.0 \ port=4713 `` 然后启动容器： `` docker run --rm \ -e PULSE_SERVER=tcp:host.docker.internal:4713 \ --name voice-assistant \ -p 8008:8008 \ -v "$(pwd)/config:/etc/platypush" \ -v "$(pwd)/workdir:/var/lib/platypush" \ platypush-voice `` 如果 `pactl load-module` 报告模块已加载，你可以继续使用现有的 PulseAudio 守护进程。 ### Windows 为 Windows 安装 PulseAudio，然后在 `pulseaudio.exe` 所在目录创建一个 `default.pa` 文件： `` load-module module-waveout sink_name=output source_name=input record=1 load-module module-native-protocol-tcp auth-anonymous=1 listen=0.0.0.0 port=4713 set-default-sink output set-default-source input `` 从 PowerShell 启动 PulseAudio： `` .\pulseaudio.exe -F .\default.pa --exit-idle-time=-1 `` 然后从仓库目录启动容器： `` docker run --rm ` -e PULSE_SERVER=tcp:host.docker.internal:4713 ` --name voice-assistant ` -p 8008:8008 ` -v "${PWD}/config:/etc/platypush" ` -v "${PWD}/workdir:/var/lib/platypush" ` platypush-voice `` 确保在 Windows 隐私设置中为桌面应用启用了麦克风访问，如果提示，请允许 PulseAudio 通过防火墙。 ## 使用 一旦服务运行，你就可以通过语音命令与之交互（默认激活词是“Alexa”）。 如果启用了天气插件，有关天气的任何问题将由天气插件解析。 如果启用了音乐或灯光插件，则可以通过语音命令控制它们（“停止音乐”、“打开灯”等）。 否则，助手将使用 `openai` 插件来回答你的问题，当 OpenAI 的响应也是一个问题时，会进行后续轮次。 ## 扩展助手 助手逻辑通过 `config/scripts` (https://git.platypush.tech/platypush/assistant-sample/src/branch/main/config/scripts) 下的简单 Platypush 钩子建模。 你可以通过定义自己的钩子或修改现有钩子来随意扩展它。 ### 开始对话 通过钩住 `HotwordDetectedEvent` (https://docs.platypush.tech/platypush/events/assistant.html#platypush.message.event.assistant.HotwordDetectedEvent) 开始对话。 `` import logging from platypush import run, when from platypush.events.assistant import HotwordDetectedEvent logger = logging.getLogger(__name__) ai_plugin = "openai" assistant_plugin = "assistant.vosk" @when(HotwordDetectedEvent) def on_hotword_detected(event: HotwordDetectedEvent): """ 当检测到唤醒词时，开始一段对话。 """ logger.info(f"检测到唤醒词 {event.hotword}") run(f"{assistant_plugin}.start_conversation") `` ### 确定性命令 对于常见的智能家居命令，常规事件钩子仍然是最佳工具。它们速度快、可检查、而且不会产生幻觉。 `` from platypush import run, when from platypush.events.assistant import SpeechRecognizedEvent @when(SpeechRecognizedEvent, phrase="turn on (the)? lights") def turn_on_lights(): """ 当用户说“turn on the lights”（正则表达式）时运行的钩子 """ run("light.hue.on") @when(SpeechRecognizedEvent, phrase="play (the)? music") def play_music(): """ 当用户说“play the music”（正则表达式）时运行的钩子 """ run("music.mpd.play") @when(SpeechRecognizedEvent, phrase="set the music volume (to|on|at) ${volume}") def set_volume(volume: int): """ 当用户说“set the music volume to ${volume}”（含参数的正则表达式）时运行的钩子 """ run("music.mpd.set_volume", volume=volume) `` ### AI 命令 如果启用了 `openai` (https://docs.platypush.tech/platypush/plugins/openai.html) 插件，你可以使用它来帮助回答问题。 语音助手有两个通用用例中 AI 插件是有益的： - **语音转意图** - **回退响应** #### 语音转意图 你可能需要这个来处理一般性问题、不适合整洁正则表达式的命令，或者将原始句子（例如： > 调暗一点并降低音乐音量 ）转换为结构化的动作计划，比如： `` [ { "action": "light.hue.set_lights", "args": { "bri": 50 } }, { "action": "music.mpd.set_volume", "args": { "volume": 20 } } ] `` 助手示例中提供了一个天气预报 (https://git.platypush.tech/platypush/assistant-sample/src/branch/main/config/sc) 的例子。