mirror of https://gitcode.com/waxgourd/addons synced 2025-12-06 12:28:28 +08:00

Files

waxgourd 062165aa78 首次推出xiaozhi-esp32-server-java;

升级了dozzle、dpanel、drawio、emby、portainer、redis-server、xiaozhi-esp32-server-mini、xiaozhi-esp32-server、xiaozhi-esp32-webui;

2025-04-27 19:51:54 +08:00

6.6 KiB

Raw Blame History

小智 ESP32 语音助手

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

使用指南

安装前准备

Home Assistant OS、Supervised 或 Container 安装方式
MariaDB 加载项已安装（或外部 MySQL/MariaDB 数据库）
具有较好网络连接的环境
足够的存储空间（至少 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 设备配置

获取并烧录 ESP32 固件（从原始项目获取）
将 ESP32 设备连接到与 Home Assistant 相同的网络
在 ESP32 固件配置中设置服务器地址：
```
ws://你的HA地址:8091/ws/xiaozhi/v1/
```
在 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 页面。欢迎提交问题报告、功能请求或代码贡献。

6.6 KiB Raw Blame History Unescape Escape