zimonianhua
aafdf024d3
- 新增完整的 Home Assistant 集成示例，支持文本对话与上下文会话 - 实现小爱音箱事件解析与 TTS 播报，支持实时打断功能 - 添加连续会话管理，支持区域上下文注入和会话超时结束 - 提供完整的配置系统、类型定义和错误处理 - 包含 Rust 扩展模块用于小爱音箱通信，支持音频流处理 - 添加单元测试、集成测试脚本和 Docker 部署支持 - 提供详细的使用文档和配置说明
126 lines
5.1 KiB
Markdown
126 lines
5.1 KiB
Markdown
# Open-XiaoAI x Home Assistant Assist
|
||
|
||
该示例用于将小爱音箱接入 Home Assistant 的对话/语音助手能力，支持文本对话与上下文会话，并提供可选的语音输入管线对接能力。
|
||
|
||
## 功能说明
|
||
|
||
- 文本对话：对接 Home Assistant `conversation.process` API，支持自然语言控制设备/查询信息
|
||
- 实时打断：接收到新用户消息时先中断当前播报，再处理新输入，避免并发播报
|
||
- 连续对话会话管理：默认开启连续对话；当命中结束词或语音静默超时时自动结束并重建 `conversation_id`
|
||
- 区域上下文注入：支持客户端 IP 到 Home Assistant 区域映射，命中后在每次请求前注入区域前置提示词
|
||
- 小爱音箱 I/O：从小爱音箱事件中提取最终识别文本（ASR），将回复通过小爱本机 TTS 播放
|
||
- 可选音频能力（扩展点）：支持接收小爱录音流 `record`，用于后续对接 Assist pipeline（STT→Intent→TTS）
|
||
|
||
## 使用场景
|
||
|
||
- 用中文/英文自然语言控制 Home Assistant：开灯、关灯、调亮度、问温度/天气、查询传感器状态
|
||
- 把小爱音箱作为 Home Assistant 的“外置麦克风 + 扬声器”（局域网内运行）
|
||
## 架构概览
|
||
|
||
- 小爱音箱 →（WebSocket 4399）→ Rust 网关（`open_xiaoai_server`）→ Python 回调
|
||
- 文本链路（默认，低延迟）：
|
||
- 设备事件 `instruction/NewLine` → 抽取 `SpeechRecognizer.RecognizeResult` 文本
|
||
- 调用 HA `/api/conversation/process`
|
||
- 把返回的 `response.speech.plain.speech` 交给小爱 TTS 播报
|
||
|
||
## 目录结构
|
||
|
||
本目录包含：
|
||
|
||
- `hass_assistant.py`：主入口
|
||
- `config.example.json`：配置模板
|
||
- `requirements.txt`：Python 依赖
|
||
- `src/`：Rust(PyO3) 扩展模块（小爱音箱 I/O 网关）
|
||
- `hass/`：Python 实现（HA 客户端、对话编排、上下文记忆）
|
||
- `tests/`：单元测试
|
||
- `scripts/`：集成测试脚本
|
||
|
||
## 安装与运行
|
||
|
||
### 前置条件
|
||
|
||
- 你的小爱音箱已刷机并运行 Rust 客户端补丁（否则服务端收不到事件/音频流）
|
||
- Home Assistant 已启用 `conversation`（默认配置一般已启用）并生成 Long-Lived Access Token
|
||
- 本机具备 Python（建议 3.10+）与 Rust 工具链（用于编译 PyO3 扩展）
|
||
- 可选：如果你希望使用 webrtcvad（更好的语音端点检测），Windows 需要安装 MSVC Build Tools
|
||
|
||
### 1) 准备配置
|
||
|
||
复制配置模板：
|
||
|
||
```bash
|
||
cd examples/hass
|
||
cp config.example.json config.json
|
||
```
|
||
|
||
编辑 `config.json`：
|
||
|
||
- `homeassistant.url`：HA 地址（例如 `http://192.168.1.10:8123`）
|
||
- `homeassistant.access_token`：HA Long-Lived Access Token
|
||
- `homeassistant.assistant_entity_id`：对话助理 ID（对应 `agent_id`，默认 `home_assistant`）
|
||
|
||
### 配置新增项说明
|
||
|
||
`xiaoai` 段新增以下关键配置：
|
||
|
||
- `interrupt_on_new_input`：是否在收到新消息时立即执行打断，默认 `true`
|
||
- `interrupt_command`：打断命令，默认使用 `ubus call mibrain ai_service` 触发中断
|
||
- `continuous_conversation_enabled`：是否开启连续会话，默认 `true`
|
||
- `session_idle_timeout_seconds`：连续会话静默超时秒数，默认 `15`
|
||
- `session_end_keywords`：结束词列表，默认包含 `再见` `拜拜` `滚` `退下`，按包含匹配
|
||
- `client_ip_area_mapping`：客户端 IP 到区域名称映射，仅在命中时注入区域提示词
|
||
|
||
区域提示词注入内容为：
|
||
|
||
`当前用户对话所在区域：<区域名称>，如后续对话未明确指定区域，则默认为此区域`
|
||
|
||
### 2) 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3) 编译 Rust 扩展（open_xiaoai_server）
|
||
|
||
推荐使用 maturin：
|
||
|
||
```bash
|
||
pip install maturin
|
||
maturin develop --release
|
||
```
|
||
|
||
### 4) 运行
|
||
|
||
```bash
|
||
python hass_assistant.py
|
||
```
|
||
|
||
## API 调用示例
|
||
|
||
### Home Assistant conversation.process（curl）
|
||
|
||
```bash
|
||
curl -X POST \
|
||
-H "Authorization: Bearer YOUR_LONG_LIVED_ACCESS_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
http://HOME_ASSISTANT:8123/api/conversation/process \
|
||
-d '{"text":"打开客厅灯","language":"zh-cn","agent_id":"home_assistant"}'
|
||
```
|
||
|
||
### Python 调用（不连接小爱，仅验证 HA）
|
||
|
||
可参考 `scripts/integration_text.py`。
|
||
## 故障排除
|
||
|
||
- 401/403：检查 `access_token` 是否正确、是否完整复制
|
||
- 连接超时：检查 `homeassistant.url` 是否可达、是否被防火墙/反代阻断
|
||
- 无语音输入：确认小爱已运行客户端补丁且能连到本机 4399 端口
|
||
- 无语音输出：确认小爱系统 `ubus`/`mibrain` 可用（或改用 `play_url` 播放 URL）
|
||
- 对话不连贯：确认 `state.json` 能写入（用于持久化 `conversation_id`），或删除它重置会话
|
||
- 打断不生效：检查 `xiaoai.interrupt_command` 是否可在设备上执行，以及日志中是否出现 `xiaoai_interrupt_failed`
|
||
- 区域提示词未注入：检查 `client_ip_area_mapping` 是否包含当前客户端 IP，并查看 `area_mapping_hit/area_mapping_miss` 日志
|
||
## 部署说明
|
||
|
||
- 建议仅在局域网内部署运行，避免将 4399 暴露到公网
|
||
- 如果 HA 与运行本示例的机器不在同一网段，确保 HA 的 URL 在设备侧可访问（尤其是播放 URL 时）
|