把Linux电脑变成家庭语音终端|Linux Voice Assistant

旧设备变语音助手

复用一台Linux电脑和USB会议扬声器,接入Home Assistant,用语音查询状态、设置计时器、控制已接入的设备。软件来自Open Home Foundation,已有独立家庭用户的实机演示;本页采用免焊接旧设备复用路线,需要已有Home Assistant环境。

alan000

复现文档

核对 Linux 主机和 Speak 410

先确认这条路线的主机、音频设备和 HA 服务齐备。

1. 准备一台运行 64 位 Debian 或 Ubuntu 的 Linux 电脑,接好电脑电源并连接可信局域网。LVA v1.1.15 支持 linux/amd64 与 linux/aarch64;上游要求约 1 GHz CPU、至少 512 MB 内存和约 4 GB 软件/系统空间。

2. 检查设备标签为 `Jabra Speak 410`,用它自带 USB 线直连电脑,或接有外部供电的 USB Hub;不要经由键盘上的无源 USB 口。Jabra 手册的可观察指示是连接上电后机身 LED 亮白。

3. 在 Linux 音频设置中把 Speak 410 选作输入麦克风与输出扬声器;打开系统录音工具录一段短音频并回放,确认能录到人声且由 Speak 410 播出。

4. 终端运行 `pactl info`、`pactl list short sources` 和 `pactl list short sinks`,确认音频服务在线并能看到输入与输出设备。

5. **完成检查**:Jabra LED 亮白,录音/回放正常,PulseAudio 或 PipeWire-Pulse 能列出输入与输出。若设备未出现或没有清晰录放,先停在此处排查;LVA 还要求麦克风支持 16 kHz 单声道音频。

![Jabra Speak 410 官方使用场景照片](https://assets.jabra.com/0/d/f/a/0dfab3d598bbdbe1d2ee886309f902d26dc8bcbe_Speak_410_contextual.jpg)

Jabra 官方 Speak 410 使用场景图:核对圆形 USB 会议扬声器的型号和接口线。

[Jabra Speak 410 官方支持页](https://www.jabra.com/supportpages/jabra-speak-410) · [LVA v1.1.15 系统与音频要求](https://github.com/OHF-Voice/linux-voice-assistant/blob/v1.1.15/README.md)

在 Home Assistant 建好 Assist 管线

先让 HA 能完成识别、对话和语音合成,再接入 Linux 语音终端。

1. 若 HA 使用 HA OS/Supervisor,打开 **Settings → Apps**(旧界面可能显示 Add-ons),安装并启动Whisper(语音识别)及 Piper(语音合成)。中文操作时,在 Whisper 中选择中文,并为 Piper 安装可用的中文声音。

2. 打开 **Settings → Devices & services**,找到自动发现的 Wyoming 集成卡;在 Whisper 与 Piper 的卡片分别点 **Add** 完成集成。

3. 进入 **Settings → Voice assistants → Add assistant**,填写名称和语言;**Conversation agent** 选 Home Assistant,**Speech-to-text** 选刚接入的引擎与语言,**Text-to-speech** 选 Piper 与语言,然后保存。

4. 进入 **Settings → Voice assistants → Expose**,从列表点选一盏低风险测试灯,仅勾选将它暴露给 Assist。锁、车库门等敏感实体不要作为首次控制对象。

5. 打开 HA 的 Assist 对话,先输入“打开测试灯”,检查文字回复与灯的状态;终端的麦克风、唤醒和播报在步骤 6 一起验收。

6. **完成检查**:HA 的语音助手已列出所选 STT、Home Assistant 对话代理和 Piper;Assist 能回应,测试灯出现在 Expose 清单中。

![](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/1f67c5fd-296f-4663-b702-fc40a824433b/files/image/de3382ea6b094109a95e46c237ee4d91.png)

在添加助手时分别选择识别、对话处理和语音合成组件;测试灯通过 Expose 开放给 Assist。ORecord,CC BY 4.0。

如果 HA 不是 HA OS/Supervisor 且没有 Apps 页面,不要照搬应用商店步骤;先在当前 HA 部署中接入可用的 STT/TTS 服务,再继续。

[HA 官方:安装本地 Assist 管线](https://www.home-assistant.io/voice_control/voice_remote_local_assistant/) · [HA 官方:Settings → Voice assistants → Expose](https://www.home-assistant.io/voice_control/voice_remote_expose_devices/)

核对 Pulse 音频服务和 Docker Compose

LVA 容器通过宿主机的 PulseAudio 兼容服务访问音频设备;它不会直接接管声卡。

1. 在同一 Linux 用户终端运行 `pactl info`。确认命令正常返回 Server Name,再运行 `pactl list short sources` 与 `pactl list short sinks`,记录 Speak 410 对应的输入、输出名称。

2. 如果桌面当前 PipeWire/PulseAudio 已正常录放,不要卸载或替换现有音频栈。若系统没有 Pulse 兼容服务,先按 LVA v1.1.15 的 PipeWire 安装页配置,再重复上一步;不要在仍运行 PipeWire 时直接套用其 PulseAudio 卸载命令。

3. 先执行 `sudo docker compose version`;若已有可用的 Engine 和 Compose,直接验证 hello-world。新装 Debian 主机再执行下列命令;已有其他容器工作负载时,先核对包冲突和迁移方案:

```

sudo apt-get update

sudo apt-get install -y ca-certificates curl wget gnupg lsb-release git jq vim

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

```

Ubuntu 用户将上述两处 `https://download.docker.com/linux/debian` 都改为 `https://download.docker.com/linux/ubuntu` 后执行;`lsb_release -cs` 使用本机发行版代号。只执行与你当前发行版对应的一组。

4. 运行 `sudo docker compose version` 和 `sudo docker run hello-world`;分别确认 Compose 返回版本号、Docker 能拉取并运行 hello-world 测试容器。

5. **完成检查:**`pactl` 能读到音频服务和两类设备,Docker Compose 与测试容器均成功运行。

[LVA v1.1.15:PipeWire/PulseAudio 音频服务](https://github.com/OHF-Voice/linux-voice-assistant/blob/v1.1.15/docs/install_audioserver.md) · [LVA v1.1.15 Docker 安装命令](https://github.com/OHF-Voice/linux-voice-assistant/blob/v1.1.15/docs/install_application.md) · [Docker 官方:Debian/Ubuntu 安装说明](https://docs.docker.com/engine/install/)

![](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/1f67c5fd-296f-4663-b702-fc40a824433b/files/image/f74b3ea7544342bb96f5721a82ca2327.png)

先用 pactl 检查宿主机录放,再核对容器 UID 和 Pulse socket;不要先换声卡。ORecord,CC BY 4.0。

下载 v1.1.15 Compose 文件并填本机音频设置

在 Linux 用户自己的家目录部署,并把容器用户映射到当前用户的音频会话。

1. 在终端运行:

```

mkdir -p ~/linux-voice-assistant

cd ~/linux-voice-assistant

curl -fLO https://raw.githubusercontent.com/OHF-Voice/linux-voice-assistant/v1.1.15/docker-compose.yml

curl -fLO https://raw.githubusercontent.com/OHF-Voice/linux-voice-assistant/v1.1.15/.env.example

cp .env.example .env

```

2. 运行 `id -u` 与 `id -g`,分别记录输出;运行 `nano .env`,将 `LVA_USER_ID`、`LVA_USER_GROUP` 改为这两个数字。保留 `LVA_PULSE_SERVER` 与 `LVA_XDG_RUNTIME_DIR` 的模板表达式,让它们按用户 ID 指向当前用户的 Pulse socket/runtime 目录。

3. 在 `.env` 中添加或取消注释 `LVA_IMAGE_TAG="1.1.15"`,固定镜像标签,不使用 `latest` 或 `nightly`。`AUDIO_INPUT_DEVICE` 和 `AUDIO_OUTPUT_DEVICE` 首次可保持自动检测;若之后需指定设备,使用步骤 5 打印出的确切设备名,不凭型号猜拼写。

4. 增加 `DISABLE_PERIPHERAL_API="1"`,关闭本教程不用的外设 WebSocket API。按 Ctrl+O、回车保存,Ctrl+X 退出;然后运行 `grep -E 'LVA_USER_ID|LVA_USER_GROUP|LVA_IMAGE_TAG|LVA_PULSE_SERVER|AUDIO_INPUT_DEVICE|AUDIO_OUTPUT_DEVICE' .env`,只检查本机配置字段;不要将输出中的个人信息公开。

5. **完成检查**:Compose 与 `.env` 同处 `~/linux-voice-assistant`,版本为 `1.1.15`,UID/GID 与 `id` 输出一致。

[v1.1.15 Compose 文件](https://github.com/OHF-Voice/linux-voice-assistant/blob/v1.1.15/docker-compose.yml) · [v1.1.15 环境变量模板](https://github.com/OHF-Voice/linux-voice-assistant/blob/v1.1.15/.env.example) · [v1.1.15 安装说明](https://github.com/OHF-Voice/linux-voice-assistant/blob/v1.1.15/docs/install_application.md)

![](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/1f67c5fd-296f-4663-b702-fc40a824433b/files/image/c7cfd1ce90a44854ad206c6a2525dc24.png)

原始 .env.example 的真实页面;1000 是模板值,改为本机 id -u/id -g 的输出。OHF-Voice,Apache-2.0。

列出音频设备、启动 LVA 并加入 ESPHome

先让 LVA 枚举设备,再用真实设备名启动容器,最后把它接入 HA。

1. 在 `~/linux-voice-assistant` 执行 `sudo docker compose config`,确认 Compose 能展开配置。

2. 运行 `sudo docker compose run --rm -e LIST_DEVICES=1 linux-voice-assistant`。上游模板规定此选项只列出音频设备并退出;从终端输出抄下 Speak 410 的输入、输出设备名称。

3. 若设备名不是自动检测可用的默认设备,在 `.env` 里设置 `AUDIO_INPUT_DEVICE` 和 `AUDIO_OUTPUT_DEVICE` 为刚才输出的精确名称;删掉/注释任何 `LIST_DEVICES=1`,否则正常服务不会启动。

4. 执行 `sudo docker compose up -d`、`sudo docker compose ps`;再用 `sudo docker compose logs -f linux-voice-assistant`查看启动日志,按 `Ctrl+C` 退出日志跟随(不会停止容器)。`linux-voice-assistant` 服务应保持运行;一次性的 `fix-permissions` 容器退出码为 0 属于正常完成。LVA v1.1.15 的 ESPHome API 默认监听端口是 `6053`。

5. 在 HA 的 **Settings → Devices & services** 等待 ESPHome 设备发现卡。若没有自动发现,点 **Add integration → ESPHome → Set up another instance of ESPHome**,输入 Linux 主机局域网 IP 和端口 `6053`,点 **Submit**。

6. 仅在可信局域网使用该 API,不在家用路由器上做 6053 端口公网转发。**完成检查**:HA 的 ESPHome 集成设备页出现 Linux Voice Assistant 设备;LVA 容器在 `sudo docker compose ps` 中保持运行。

![LVA v1.1.15 作者提供的 Home Assistant ESPHome 设备页示例](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/1f67c5fd-296f-4663-b702-fc40a824433b/files/image/3d55f2d925b7490ab60f2e779da106c0.png)

OHF-Voice v1.1.15 仓库截图:ESPHome 集成下出现 Linux Voice Assistant 设备及实体;用于对照接入成功后的设备行与实体列表。Apache-2.0。

[LVA 作者:Settings → Devices & services → Add integration → ESPHome](https://github.com/OHF-Voice/linux-voice-assistant/blob/v1.1.15/docs/install_application.md#connecting-to-home-assistant)

从 HA 设备页选唤醒词并验证语音请求

接入后先使用 LVA 自带的 `okay_nabu` 唤醒模型,再运行计时器和测试灯两项低风险检查。

1. 在 HA 打开 **Settings → Devices & services → ESPHome**,点 Linux Voice Assistant 设备进入设备页。找到 **Wake Word 1** 下拉项;默认模型为 `okay_nabu`,先保留默认值。下拉列表里带 `(OWW)` 的是 openWakeWord 模型,其他项是 microWakeWord;本教程不要求更换模型。

2. 确认设备的 Assist 管线为步骤 2 建立的助手及语言;将 Speak 410 放在常用说话位置,按已设置语言说出唤醒词,等唤醒提示音结束后,再发出“设置一个一分钟计时器”这一安全测试请求。

3. 在 HA 的 Assist/计时器界面确认计时器已创建;等待播报,听到 Speak 410 回答或计时完成提示。

4. 再对步骤 2 暴露的测试灯发出开关命令;同时查看 HA 灯实体状态确已变化,并听到终端语音回应。若识别文本或播放失败,检查步骤 1 的设备选取、步骤 4 的 UID/Pulse 路径与步骤 5 的设备枚举日志。

5. **完成检查**:同一唤醒词触发 LVA,HA 创建计时器并能通过 Jabra 播报;测试灯状态随请求变化。

![LVA v1.1.15 Home Assistant Wake Word 选择列表](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/1f67c5fd-296f-4663-b702-fc40a824433b/files/image/b2913cb4dc004e47a309ea3670ca7eaa.png)

OHF-Voice 仓库真实设备页截图,展示 Wake Word 下拉菜单;在列表中选择 Okay Nabu,保留本教程默认唤醒模型。Apache-2.0。

[LVA v1.1.15 默认唤醒模型、ESPHome API 与功能说明](https://github.com/OHF-Voice/linux-voice-assistant/blob/v1.1.15/README.md#parameter-overview)

调整音量、验证静音并结束测试

用 HA 设备页的真实控制项设置合适音量,确认隐私静音状态可控,并留存不含个人语音的配置记录。

1. 在 Linux Voice Assistant 设备页的 **Controls** 区找到 **Media Player**,拖动音量滑块到舒适音量;该控件同时影响音乐/媒体和语音卫星提示音、TTS。单独测试后,确认语音回答仍听得清。

2. 找到 **Mute** 开关并开启;按 LVA 定义它会停用唤醒词检测和按钮触发聆听,;如需结束进程,使用本步骤最后的 `docker compose down`。说一次唤醒词,确认设备不响应;再关闭 Mute,确认唤醒恢复。

3. 记录 Linux 发行版、CPU 架构、LVA `1.1.15`、HA 版本、Pulse 服务、实际输入/输出名、测试灯实体及测试结果。不要保存或分享真实私人语音、Wi-Fi 密码、HA token 或包含私密内容的日志。

4. 如需停止服务,在项目目录运行 `sudo docker compose down`;不要加 `-v`,以保留 LVA 命名卷中的设置与唤醒词数据。确认 `sudo docker compose ps` 无运行服务后结束。

5. **完成检查**:滑块可调节播报音量;Mute 开启时无唤醒响应、关闭后恢复;服务停止或继续运行的状态已明确。

![LVA 设备页 Media Player 音量控件](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/1f67c5fd-296f-4663-b702-fc40a824433b/files/image/004bfd6a7989405d82c4461bb4362ad7.png)

OHF-Voice v1.1.15 设备页媒体播放器示例;界面显示 Idle 与音量滑块,截图的音量值仅为示例。Apache-2.0。

![LVA 设备页 Mute 开关](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/1f67c5fd-296f-4663-b702-fc40a824433b/files/image/8f0a3a79f61044b48e19c2f6575d7856.png)

OHF-Voice v1.1.15 Mute 实体截图,用于确认开关位置;开启后禁用唤醒/按钮聆听而不停止服务。Apache-2.0。

相关科技单元