mirror of
https://gitcode.com/waxgourd/addons
synced 2025-12-06 12:28:28 +08:00
首次推出xiaozhi-esp32-server-java;
升级了dozzle、dpanel、drawio、emby、portainer、redis-server、xiaozhi-esp32-server-mini、xiaozhi-esp32-server、xiaozhi-esp32-webui;
This commit is contained in:
waxgourd
182
xiaozhi-esp32-server-java/DOCS.md
Normal file
182
xiaozhi-esp32-server-java/DOCS.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# 小智 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` |
|
||||
|
||||
### 数据库设置
|
||||
|
||||
**自动配置方式**：
|
||||
插件会尝试自动创建数据库和所需表结构，您只需在配置中提供有效的数据库连接信息。
|
||||
|
||||
**手动配置方式**：
|
||||
如果您希望手动设置数据库，可以执行以下步骤：
|
||||
|
||||
```sql
|
||||
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 固件（从[原始项目](https://github.com/78/xiaozhi-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 页面](https://github.com/joey-zhou/xiaozhi-esp32-server-java)。
|
||||
欢迎提交问题报告、功能请求或代码贡献。
|
||||
Reference in New Issue
Block a user