自定义语音助手方案
概述
本方案基于 Home Assistant 内置的语音助手框架，整合了开源唤醒词、本地 STT、多选 TTS 以及 LLM 代理，构建了一套完整的中文智能家居语音控制系统。
设计目标
- 低延迟：STT 和唤醒词均使用本地部署，避免网络往返
- 高准确率：中文场景优化，SenseVoice + Smart Conversation 覆盖口语化表达
- 弹性扩展：TTS 和 LLM 支持多种后端切换，降级可用
- 经济优先：优先选择免费/开源方案，TTS 首选免费的 Edge TTS
整体架构
┌──────────────────────┐
│ 用 户 │
│ "嘿 Eventi，开灯" │
└──────────┬───────────┘
│ 语音
▼
┌──────────────────────────────────────────────────────────┐
│ linux-voice-assistant (ESPHome 卫星) │
│ │
│ ① 唤醒词检测 (OpenWakeWord 内置) ─ 未命中 → 忽略 │
│ │ 命中 │
│ ② 音频采集 (PulseAudio) │
│ │ │
│ └── ESPHome 原生 API ──→ HA │
│ │
│ ③ 音频播放 (PulseAudio) │
│ ▲ │
│ └── ESPHome 原生 API ←── HA ←── TTS 音频返回 │
└──────────────────────────────────────────────────────────┘
│ ▲
│ 音频流 (ESPHome) │ TTS 音频 (ESPHome)
▼ │
┌──────────────────────────────────────────────────────────┐
│ Home Assistant │
│ │
│ ④ STT 语音识别 (SenseVoice / Wyoming) │
│ │ 文本（带情绪标签） │
│ ▼ │
│ ⑤ 意图处理 │
│ ├─ Smart Conversation 清洗（去标签/语气词/句式归一） │
│ └─ HassIL 意图匹配 │
│ │ │
│ ┌─────┴─────┐ │
│ │ 成功 │ 失败 │
│ ▼ ▼ │
│ ⑥ 执行命令 ⑦ LLM 代理 (Openclaw) │
│ (直接操控 ├─ 大模型理解意图 │
│ 设备) ├─ HA MCP 操控设备 │
│ └─ 生成回复文本 │
│ │ │
│ ▼ │
│ ⑧ TTS 语音合成 (Edge TTS) │
│ │ │
│ └── TTS 音频 → ESPHome → 卫星扬声器 │
└──────────────────────────────────────────────────────────┘
各组件详解
① 音频采集与输出
| 项目 | 详情 |
|---|---|
| 方案 | linux-voice-assistant（OHF-Voice） |
| 接入方式 | ESPHome 原生协议（在 HA 中自动发现为 ESPHome 设备） |
| 核心功能 | 麦克风采集 + 扬声器输出 + 唤醒词检测（三合一语音卫星） |
| 部署方式 | Docker 容器，PulseAudio 音频透传 |
📄 详见 → [[语音输入和输出]]
② 唤醒词检测
| 项目 | 详情 |
|---|---|
| 方案 | OpenWakeWord（内置于 linux-voice-assistant 中） |
| 接入方式 | 通过 ESPHome 语音管道运行，HA 端无需额外配置 |
| 自定义唤醒词 | 已训练自定义唤醒词 "Eventi" （与 "okay_nabu" 同时激活） |
| 训练仓库 | HappyEventKing/openWakeWord |
📄 详见 → [[设置唤醒词]]
③ 语音识别 / STT
| 项目 | 详情 |
|---|---|
| 方案 | 阿里 SenseVoice（本地部署） |
| 接入方式 | Docker + Wyoming 协议 → HA 语音管道 |
| 部署仓库 | docker_wyoming_sensevoice |
| 优势 | 本地部署中识别速度最快、中文准确率最高 |
| 对比 | faster-whisper 速度较慢，且中英文混合场景不友好 |
📄 详见 → [[设置 STT]]
④ 意图处理
| 项目 | 详情 |
|---|---|
| 框架 | HA 内置语音助手（DefaultAgent） |
| 增强组件 | Smart Conversation |
| 处理流程 | 文本清洗（去 STT 标签/语气词/句式归一）→ HassIL 意图匹配 → 成功执行 / 失败上抛 LLM |
| 关键特性 | 原文保留给 LLM（情绪标签不丢失），缓存不受影响 |
📄 详见 → [[HA 意图配置]]
⑤ LLM 代理
| 项目 | 详情 |
|---|---|
| 方案 | Openclaw |
| 功能 | 当 HA 意图匹配失败时，接收用户原文，调用大模型理解自然语言意图 |
| HA 交互 | 通过 HA MCP 协议操控 HA 设备 |
| 兜底价值 | 处理非标准命令（闲聊、复合指令、模糊请求等） |
📄 详见 → [[openclaw 配置语音代理]]
⑥ 语音合成 / TTS
| 项目 | 详情 |
|---|---|
| 首选方案 | Edge TTS（HA 插件，免费，微软在线引擎） |
| 备选方案 1 | 阿里云 TTS（HA 插件，音色丰富有情感，有免费额度） |
| 备选方案 2 | OpenAI 兼容 TTS（硅基流动语音模型 / Kokoro），本地 GPU 可加速 |
| 已排除 | Piper（特殊字符/表情时易崩溃），Kokoro（中文输出不佳） |
📄 详见 → [[设置 TTS]]
处理流程（时序）
用户说话
│
▼
linux-voice-assistant (ESPHome 卫星)
├─ 唤醒词检测 → 未命中 → 忽略
│ │ 命中
│ ▼
└─ 音频流 → ESPHome API → HA 语音管道
│
▼
STT 语音转文本 (SenseVoice / Wyoming)
│ 文本（可能带情绪标签和口语词）
▼
Smart Conversation 清洗
├─ 去 STT 标签 <|zh|><|NEUTRAL|>
├─ 去前缀/后缀语气词
└─ 句式归一化（把字句→动词前置）
│ 清洗文本 │ 原文本保留
▼ │
HassIL 意图匹配 │
│ │
┌───────────┴───────────┐ │
│ 成功 │ 失败
▼ ▼
执行设备命令 Openclaw (LLM 代理)
│ │
│ 理解意图 + HA MCP 操控设备
│ │
│ 生成回复文本
│ │
└─────────┬─────────┘
│ TTS 文本
▼
TTS 语音合成 (首选 Edge TTS)
│
▼
TTS 音频 → ESPHome API → linux-voice-assistant
│
▼
卫星扬声器播放回复
方案选型理由
| 环节 | 选择 | 理由 |
|---|---|---|
| 音频采集/输出 | linux-voice-assistant | OHF 官方 ESPHome 卫星，一个项目整合麦克风 + 扬声器 + 唤醒词 |
| 唤醒词 | OpenWakeWord（内置在 lva 中） | 纯本地、低功耗、支持自定义训练 |
| STT | SenseVoice（Wyoming） | 中文 SOTA 级别识别，比 faster-whisper 快且准 |
| 意图处理 | HA 内置 + Smart Conversation | 无需额外服务，Monkey-Patch 方式零侵入，原文保留 |
| LLM 代理 | Openclaw + HA MCP | 自然语言兜底，MCP 协议标准化 HA 设备调用 |
| TTS | Edge TTS | 免费、中文可接受、HA 有现成插件、无 GPU 需求 |
⚠️ 重要架构更正：
linux-voice-assistant 使用 ESPHome 原生协议（而非 Wyoming 协议）与 HA 通信。它本身就是一个完整的语音前端，整合了麦克风、扬声器和唤醒词三项功能。Wyoming 协议在本方案中仅用于 STT (SenseVoice) 和 TTS 服务与 HA 语音管道之间的通信——这些是 HA 服务端组件。而语音卫星端（linux-voice-assistant）走的是 ESPHome 原生 API。
详情参见 → [[语音输入和输出]]
完整数据流（HA 语音管道）
HA 的语音管道设计是双向的：
linux-voice-assistant既是音频输入端，也是音频输出端。TTS 合成的语音最终会通过 ESPHome 协议返回给卫星端播出。
┌────────────────────────────────────────────────────────────┐
│ linux-voice-assistant │
│ (ESPHome 语音卫星) │
│ │
│ 麦克风 ──→ ESPHome API ──→ HA ─┐ │
│ 扬声器 ←── ESPHome API ←── HA ←──────────────────┘ │
│ │
│ 内置: 唤醒词 (OpenWakeWord) + 音频处理 (PulseAudio) │
└────────────────────────────────────────────────────────────┘
│ ▲
│ 音频流 (ESPHome) │ TTS 音频 (ESPHome)
▼ │
┌────────────────────────────────────────────────────────────┐
│ Home Assistant │
│ │
│ 语音管道 (Voice Pipeline): │
│ │
│ 音频输入 → STT (SenseVoice/Wyoming) │
│ → 意图匹配 (HassIL + Smart Conversation) │
│ ├─ 成功 → 执行设备命令 │
│ └─ 失败 → LLM 代理 (Openclaw + HA MCP) │
│ → TTS (Edge TTS) │
│ → 音频输出 → 返回卫星 │
│ │
└────────────────────────────────────────────────────────────┘
关键理解：
-
linux-voice-assistant 在 HA 中被注册为一个 ESPHome 媒体播放器实体，TTS 输出就是通过这个实体播放的 - 卫星采集的音频通过 ESPHome 协议传入 HA 语音管道，管道处理完成后 TTS 音频通过同一个 ESPHome 连接返回卫星，由卫星扬声器播出
- 这是一个完整的往返：语音进 → 处理 → 语音出，全部在同一个 ESPHome 连接上完成