150 lines
5.6 KiB
Markdown
150 lines
5.6 KiB
Markdown
# 冬瓜甄选addons：小智ESP32语音助手JAVA版
|
||
|
||
这是一个基于 ESP32 的语音交互助手系统，支持语音识别和播放功能，适用于智能家居控制。此插件将小智 ESP32 服务器整合为 Home Assistant 加载项，提供更简便的部署和管理方式。
|
||
|
||
## 功能特点
|
||
|
||
- **中文语音识别**：基于 VOSK 语音识别引擎，支持准确的中文语音识别
|
||
- **与 Home Assistant 集成**：完全集成到 Home Assistant 界面中，一键安装和配置
|
||
- **Web 管理界面**：提供直观的 Web 界面管理 ESP32 设备
|
||
- **内置中文语音模型**：预装中文语音识别模型，开箱即用
|
||
- **数据库自动化**：自动创建并初始化必要的数据库表结构
|
||
- **资源占用优化**：可自定义 Java 内存分配，适应不同性能的设备
|
||
|
||
## 安装方法
|
||
|
||
### 前置要求
|
||
|
||
- Home Assistant OS 或 Supervised 环境（最低版本 2023.3）
|
||
- MariaDB 插件（或外部 MySQL/MariaDB 数据库）
|
||
- 网络连接（用于初始化）
|
||
|
||
### 安装步骤
|
||
|
||
1. 在 Home Assistant 中，进入**设置** -> **加载项** -> **加载项商店**
|
||
2. 点击右上角的菜单按钮，选择**存储库**
|
||
3. 添加此仓库地址: ``
|
||
4. 点击**添加**，然后关闭存储库对话框
|
||
5. 在加载项商店中找到**小智 ESP32 语音助手**并安装
|
||
|
||
## 配置选项
|
||
|
||
| 配置项 | 默认值 | 描述 |
|
||
| -------------- | ------------ | ---------------------------------------------- |
|
||
| mysql_host | core-mariadb | MySQL 数据库主机地址 |
|
||
| mysql_port | 3306 | MySQL 数据库端口 |
|
||
| mysql_database | xiaozhi | 数据库名称 |
|
||
| mysql_user | xiaozhi | 数据库用户名 |
|
||
| mysql_password | 123456 | 数据库密码 |
|
||
| java_memory | 512m | Java 应用内存分配，格式为 XmXg，如 512m、1g 等 |
|
||
|
||
## 使用说明
|
||
|
||
### 首次启动
|
||
|
||
1. 安装并配置 MariaDB 加载项（如果使用外部数据库则跳过此步骤）
|
||
2. 在小智 ESP32 语音助手的配置页面，设置数据库连接信息
|
||
3. 如需调整 Java 应用内存，可修改 java_memory 参数（默认 512m）
|
||
4. 点击**保存**，然后启动加载项
|
||
|
||
### 访问 Web 界面
|
||
|
||
启动加载项后，有两种方式访问 Web 管理界面：
|
||
|
||
1. 通过 Home Assistant 边栏中的**小智 ESP32**图标直接访问
|
||
2. 或访问`http://你的HomeAssistant地址:8084`
|
||
|
||
### 设备连接
|
||
|
||
在 Web 管理界面中，您可以添加和管理 ESP32 设备：
|
||
|
||
1. 进入**设备管理**页面
|
||
2. 点击**添加设备**
|
||
3. 输入设备名称、IP 地址等信息
|
||
4. 在 ESP32 设备上设置 WebSocket 服务器地址为：`ws://你的HomeAssistant地址:8091/ws/xiaozhi/v1/`
|
||
|
||
## 数据库说明
|
||
|
||
首次启动时，插件会自动：
|
||
|
||
1. 连接到配置的 MySQL/MariaDB 数据库
|
||
2. 如果指定数据库不存在，则创建数据库
|
||
3. 执行必要的 SQL 脚本初始化表结构
|
||
|
||
如果您希望手动初始化数据库，可以：
|
||
|
||
1. 使用 MySQL 客户端连接到数据库服务器
|
||
2. 创建名为"xiaozhi"（或您指定的名称）的数据库
|
||
3. 导入`/app/db/`目录下的 SQL 文件
|
||
|
||
## 内存管理
|
||
|
||
通过配置项 `java_memory` 控制分配给 Java 应用的堆内存大小，格式示例：
|
||
|
||
- `512m`（512 兆字节，适合大多数使用场景）
|
||
- `1g`（1 吉字节，适合大量设备和频繁交互场景）
|
||
- `1.5g`或更高（适合高负载场景）
|
||
|
||
**内存管理建议**：
|
||
|
||
- 默认内存分配（512MB）足够普通使用
|
||
- 对于多设备场景，建议分配 1GB 或更多内存
|
||
- 如遇内存不足问题，增加分配至 1GB 或更高
|
||
|
||
## 故障排查
|
||
|
||
如果遇到问题，请尝试以下方法：
|
||
|
||
1. **无法启动**：
|
||
|
||
- 检查 MariaDB 服务是否正常运行
|
||
- 确认数据库连接信息正确
|
||
- 查看 Home Assistant 日志中是否有错误信息
|
||
|
||
2. **Web 界面无法访问**：
|
||
|
||
- 确认端口 8084 和 8091 未被占用
|
||
- 检查 Home Assistant 的网络设置，确保这些端口可以访问
|
||
|
||
3. **语音模型问题**：
|
||
|
||
- 检查 `/config/models/vosk-model` 目录是否存在模型文件
|
||
- 如果模型不存在，请手动下载并上传到该目录
|
||
- 确保存储空间足够（至少需要 100MB 空闲空间）
|
||
|
||
4. **内存不足**：
|
||
- 增加 java_memory 参数，分配更多内存（如从 512m 改为 1g）
|
||
- 关闭其他不必要的加载项释放资源
|
||
- 考虑使用性能更强的设备运行 Home Assistant
|
||
|
||
## 技术架构
|
||
|
||
本插件采用以下技术栈：
|
||
|
||
- **前端**：Vue.js + Ant Design
|
||
- **后端**：Java Spring Boot
|
||
- **语音识别**：VOSK + ONNX Runtime
|
||
- **数据库**：MySQL/MariaDB
|
||
- **容器化**：Docker + S6 Overlay
|
||
|
||
## S6 初始化系统
|
||
|
||
插件使用 S6 Overlay 作为容器初始化系统，主要初始化流程：
|
||
|
||
1. **环境变量设置**：读取 Home Assistant 配置，设置数据库连接信息等
|
||
2. **数据库初始化**：等待 MySQL 可用，创建并初始化数据库
|
||
3. **模型检查**：检查语音模型是否存在并可用
|
||
4. **Java 应用启动**：启动 Spring Boot 应用
|
||
5. **Nginx 服务**：提供静态资源服务，反向代理 API 请求
|
||
|
||
## 版权和许可
|
||
|
||
本项目基于[xiaozhi-esp32-server-java](https://github.com/joey-zhou/xiaozhi-esp32-server-java)开发，采用 MIT 许可证。
|
||
|
||
## 参考资源
|
||
|
||
- [小智 ESP32 服务器 Java 版](https://github.com/joey-zhou/xiaozhi-esp32-server-java)
|
||
- [VOSK 语音识别系统](https://alphacephei.com/vosk/)
|
||
- [Home Assistant 开发者文档](https://developers.home-assistant.io/)
|
||
- [S6 Overlay](https://github.com/just-containers/s6-overlay)
|