waxgourd-addons/xiaozhi-esp32-server-java/DOCS.md

小智 ESP32 语音助手

这是一个基于 ESP32 的语音交互助手系统，支持中文语音识别和播放功能，适用于智能家居控制。作为 Home Assistant 的加载项，提供便捷的安装和管理体验。

使用指南

安装前准备

1. Home Assistant OS、Supervised 或 Container 安装方式
2. MariaDB 加载项已安装（或外部 MySQL/MariaDB 数据库）
3. 具有较好网络连接的环境
4. 足够的存储空间（至少 500MB）

配置选项说明

选项	描述
mysql_host	数据库主机地址，默认使用 MariaDB 插件为 core-mariadb
mysql_port	数据库端口，默认为 3306
mysql_database	数据库名称，默认为 xiaozhi
mysql_user	数据库用户名，默认为 xiaozhi
mysql_password	数据库密码，默认为 123456
java_memory	Java 应用内存分配，如 512m、1g、1.5g

数据库设置

自动配置方式： 插件会尝试自动创建数据库和所需表结构，您只需在配置中提供有效的数据库连接信息。

手动配置方式： 如果您希望手动设置数据库，可以执行以下步骤：

CREATE DATABASE xiaozhi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'xiaozhi'@'%' IDENTIFIED BY '你的安全密码';
GRANT ALL PRIVILEGES ON xiaozhi.* TO 'xiaozhi'@'%';
FLUSH PRIVILEGES;

内存管理

可以通过配置项 java_memory 控制分配给 Java 应用的堆内存大小，格式示例：

• 512m（512 兆字节，适合大多数使用场景）
• 1g（1 吉字节，适合大量设备和频繁交互场景）
• 1.5g或更高（适合高负载场景）

内存管理建议：

• 默认内存分配（512MB）足够普通使用
• 对于多设备场景，建议分配 1GB 或更多内存
• 如遇内存不足问题，增加分配至 1GB 或更高

优化资源使用：

• 关闭其他不必要的加载项释放资源：Home Assistant 上可能同时运行多个加载项，每个加载项都会消耗系统资源。建议临时停用不常用的加载项，特别是资源密集型的加载项（如 Node-RED、VS Code 等），以释放更多内存给语音识别服务。

• 监控资源使用：通过 Home Assistant 的系统监控加载项，定期检查系统资源使用情况，确保有足够的可用内存。

• 优化运行时参数：对于性能有限的设备（如某些 Raspberry Pi 型号），确保系统有足够的交换空间(swap)。

• 定期重启：如果发现内存使用率持续升高，建议定期重启加载项，以释放累积的内存占用。可以在 Home Assistant 中设置自动化，定期重启此加载项。

端口说明

本加载项使用以下端口：

• 8091：API 服务端口（ESP32 设备通过 WebSocket 连接此端口）
• 8084：Web 管理界面端口（可通过 Home Assistant 边栏访问）

Web 界面功能

通过 Home Assistant 的边栏图标或直接访问http://你的HA地址:8084进入 Web 管理界面。 默认账号：admin 默认密码：123456

设备管理

可以添加、编辑和删除 ESP32 设备，主要功能：

• 设备列表查看
• 设备状态监控（在线/离线）
• 设备信息编辑

音色配置

支持为 ESP32 设备配置不同的语音合成音色：

• 预设多种中文音色
• 音色预览功能
• 为不同设备分配不同音色

角色设置

可以选择不同的 AI 助手角色：

• AI 助手
• 智能家居助手
• 其他预设角色

对话管理

查看与 ESP32 设备的历史对话：

• 按时间查看历史消息
• 按关键词搜索对话内容
• 消息管理功能

ESP32 设备配置

1. 获取并烧录 ESP32 固件（从原始项目获取）
2. 将 ESP32 设备连接到与 Home Assistant 相同的网络
3. 在 ESP32 固件配置中设置服务器地址：

   ws://你的HA地址:8091/ws/xiaozhi/v1/
   

4. 在 Web 管理界面中添加对应的设备信息

高级功能

持久化对话

系统支持持久化对话记录，可以记住与用户的对话上下文：

• 自动保存对话历史
• 根据历史对话进行上下文理解
• 提供更自然的对话体验

自定义唤醒词（需 ESP32 固件支持）

如果 ESP32 固件支持，可以通过接口设置自定义唤醒词。

故障排查

加载项无法启动

• 检查 MariaDB 服务是否正常运行
• 验证数据库连接信息（主机、端口、用户名、密码）
• 查看 Home Assistant 日志是否有错误信息
• 确保分配了足够的内存给加载项

语音模型问题

• 检查 /config/models/vosk-model 目录是否存在模型文件
• 如果模型不存在，请手动下载并解压到该目录
• 确保存储空间足够（至少需要 100MB 空闲空间）
• 确保下载的是中文语音模型

ESP32 设备无法连接

• 验证 ESP32 和 Home Assistant 在同一网络环境
• 检查 WebSocket 地址格式是否正确（ws://ip:8091/ws/xiaozhi/v1/）
• 确认 ESP32 固件是否正确配置
• 检查防火墙是否阻止了 WebSocket 连接

内存不足错误

• 增加java_memory配置：根据设备性能适当增加，如从 512m 改为 1g
• 关闭其他不必要的加载项释放资源：
  • 在 Home Assistant 的加载项页面，暂时停用不常用的资源密集型加载项
  • 特别关注数据库、多媒体相关加载项，它们通常消耗较多资源
  • 考虑使用 Home Assistant 的"系统诊断"功能，检查哪些加载项占用较多资源
  • 如果使用的是低配置设备（如 Raspberry Pi 3 或更低），可能需要限制同时运行的加载项数量
• 优化系统配置：
  • 增加系统交换空间（在树莓派等设备上尤为重要）
  • 考虑使用性能更强的设备运行 Home Assistant
  • 确保设备有足够的散热，避免因过热导致的性能降低

技术架构

本加载项基于以下技术构建：

• 容器技术：Docker + S6 Overlay（进程管理）
• 前端：Vue.js + Ant Design（Web 管理界面）
• 后端：Java Spring Boot（RESTful API 和 WebSocket 服务）
• 语音处理：VOSK（语音识别）+ ONNX Runtime（模型推理）
• 数据存储：MySQL/MariaDB（对话历史和配置）

支持与贡献

如有问题或建议，请访问项目 GitHub 页面。 欢迎提交问题报告、功能请求或代码贡献。