搭建本地语音 Pipeline 完整步骤

为什么要本地 Pipeline

Home Assistant 的语音处理链路分三段：

用户说话 → 【STT 语音转文字】→ 【NLU 语义理解】→ 【执行设备动作 / 查询数据】→ 【TTS 文字转语音】→ 用户听到回应

每一段都可以选本地或云端。本地 Pipeline 的价值：

隐私：音频不出家门
无网络依赖：断网也能语音控制
免费：不用给云服务付费
延迟：局域网内的延迟比云往返更快（取决于硬件）

第一步：安装 Whisper STT

Whisper 是 OpenAI 开源的语音识别模型，Home Assistant 通过 Add-on 集成。

Home Assistant OS 用户：

Settings → Apps → Official repository → 搜索 Whisper（faster-whisper）
点击 Install → 配置模型：

Model Size：tiny（树莓派）→ base（N100）→ small → medium → large-v3（精度最高但最慢）
Compute Type：auto（自动检测）或 cpu
Language：Chinese（中文）或 auto

启动 App

模型大小选择：

tiny（~40MB）：速度快，精度一般，树莓派首选
base（~100MB）：速度和精度平衡
small（~500MB）：精度不错，推荐 N100 机器
medium / large-v3：精度最高但极慢（几十秒一次识别），需要 GPU 加速才实用

Container 用户：faster-whisper 有独立 Docker 镜像，启动后 Home Assistant 连它的 API。

第二步：安装 Piper TTS

Piper 是开源的轻量级 TTS 引擎，专为本地运行设计：

Settings → Apps → Official repository → 搜索 Piper
Install → 启动
Piper 会在后台运行一个 API，Home Assistant 自动识别

下载中文语音模型

Piper 默认只有英文语音。要中文：

打开 Piper App → 点击 Open Web UI
Models tab → 找到中文模型（zh_CN 或 zh_TW）
Download → 等待下载完成
在 Voice Assistants 设置里把中文模型设为默认

常用中文模型（Piper 仓库）：

zh_CN-huimeng-medium：女声，推荐
zh_CN-xiaobei-medium：男声
zh_TW-leeching-medium：女声（台湾腔）

第三步：配置 Conversation Agent

Conversation Agent 是 Assist 的"大脑"，负责理解用户意图：

方式一：Home Assistant 内置（推荐新手）

Settings → System → Voice Assistants → 编辑你的 Voice Assistant → Conversation Agent → 选 Home Assistant

内置 Agent 基于 Intent Matching——它理解 Home Assistant 的实体名、区域名和设备名。只要你说的话能被拆解成"动作 + 对象 + 条件"，就能正确执行。

方式二：Ollama + LLM（进阶）

想要更灵活的自然语言理解？接入本地 LLM：

Settings → Apps → 搜索 Ollama → Install → Start
进入 Ollama Web UI → Pull 一个支持中文的模型（qwen2.5、Llama 3.1、InternLM 等）
Settings → Devices & services → Add integration → 搜索 Ollama → Configure → 选模型
Voice Assistants → Conversation Agent → 选 Ollama

LLM Agent 的优势：可以理解更灵活的表达方式（"空调有点冷了"→ 理解为调高温度），可以回答开放式问题（"今天天气怎么样"）。劣势：本地 LLM 需要较强硬件（至少 N100 + 8GB RAM），响应速度比内置 Agent 慢。

第四步：组合 Pipeline

Settings → System → Voice Assistants → 编辑你的 Voice Assistant

Assistant name: My Assistant
Pipeline: Assist
Conversation Agent: Home Assistant（或 Ollama）
Speech-to-Text: Whisper（本地）
Text-to-Speech: Piper（本地）
Wake Word: N/A（Assist 没有唤醒词）

保存后，Lovelace 右上角出现麦克风图标 → 点击 → 说话 → Home Assistant 处理 → 回应。

第五步：测试

快速测试：Lovelace 右上角麦克风 → 说 "打开客厅的灯" → 看灯有没有开。

测试 STT：Developer Tools → Whisper → 输入音频或说话 → 看转写的文字对不对。转错了就调 Whisper 模型（换更大的模型或换语言设置）。

测试 TTS：Developer Tools → Services → 找 tts.piper_say → 填一段中文文字 → Call Service → 看 Piper Web UI 里有没有生成语音。

树莓派本地 Pipeline 的体验极限

树莓派 5 跑 faster-whisper tiny + Piper：

STT 延迟：1~3 秒
TTS 合成速度：基本同步（Piper 非常快）
NLU：内置 Agent 即时响应

可以用，但不要指望像 Alexa/Siri 那样"即说即应"。x86 N100 + Whisper base 会好很多。

常见问题

点了麦克风但没反应

浏览器权限问题。Chrome/Edge 会弹出麦克风请求——点允许。或检查站点设置里的麦克风权限。

Whisper 转出来的中文是乱码

Language 设置成了 English 或 auto。在 Whisper App 里把 Language 明确设为 Chinese。

Piper 说英文不说中文

需要下载中文语音模型（见第二步）。默认只有英文。

Pipeline 速度太慢

换更快的 STT 模型（更小的）
如果是 x86 机器，确保 Whisper 用的是 compute_type: auto（自动检测 CPU 指令集优化）
考虑用 Nabu Casa Cloud 做 STT/TTS，换本地 NLU（兼顾隐私和速度）