hadb/waxgourd-addons
1
0
Fork 0
mirror of https://gitcode.com/waxgourd/addons synced 2025-12-06 12:28:28 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
waxgourd-addons/xiaozhi-esp32-server/DOCS.md

207 lines
9.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 小智 AI Server 最简化版
本加载项提供小智 ESP32 语音识别服务器功能，可与 ESP32 设备配合使用实现语音识别功能。
## 安装
1. 更换成小智AI音箱（HA专用固件），烧录地址：https://xzfw.wghaos.com/ 并配置网络
1. 在 Home Assistant 的加载项商店中添加此仓库地址或复制到本地加载项目录
1. 安装"小智 AI Server 最简化版"加载项
1. 配置加载项
## 配置参数
| 参数 | 描述 |
| ------------------------------------ | --------------------------------- |
| timezone | 时区设置 |
| server.auth.enabled | 是否启用设备认证（可选） |
| server.auth.tokens | 设备认证令牌列表（可选） |
| log_level | 日志级别 (INFO/DEBUG) |
| llm.type | 大语言模型类型 |
| model_name | 大语言模型名称 |
| llm.api_key | 大语言模型 API 密钥 |
| tts.type | 语音合成服务类型 |
| tts.appid | TTS 服务应用 ID (DoubaoTTS 需要) |
| tts.access_token | TTS 服务访问令牌 (DoubaoTTS 需要) |
| tts.voice | TTS 音色 (DoubaoTTS 可选) |
| asr.type | 语音识别服务类型 |
| asr.appid | ASR 服务应用 ID（在线服务需要） |
| asr.access_token | ASR 服务访问令牌（在线服务需要） |
| asr.secret_key | ASR 服务密钥（腾讯 ASR 需要） |
| plugins.get_weather.api_key | 和风天气 API 密钥 |
| plugins.get_weather.default_location | 默认天气查询位置 |
| plugins.home_assistant.base_url | Home Assistant 地址 |
| plugins.home_assistant.api_key | Home Assistant 长期访问令牌 |
| plugins.home_assistant.devices | Home Assistant 设备列表 |
## 使用说明
安装并启动后，服务器会在 8000 端口启动 WebSocket 服务。您可以通过 ESP32 设备连接到此服务进行语音识别。
### 配置方式说明
本加载项支持两种配置方式：
1. **通过 Home Assistant 加载项页面配置**：在 Home Assistant -> 设置 -> 加载项 -> 小智 AI Server 最简化版 中配置基本参数
- 这些配置会自动应用到服务器的.config.yaml 文件中
- 每次重启加载项时，Home Assistant 配置会自动覆盖相应的.config.yaml 设置
2. **手动编辑配置文件**：
- 配置文件位于: `/config/data/.config.yaml`（通过文件编辑器访问）
- 适合进行高级配置调整，如不在加载项页面提供的参数
**注意**：所有需要的 ASR 和 LLM 参数都应当在 Home Assistant 加载项配置页面中设置，这是推荐的配置方法。修改后需要重启加载项才能生效。
### 具体配置路径
1. **加载项配置页面**:
- Home Assistant → 设置 → 加载项 → 小智 AI Server 极速版 → 配置
- 在此页面可以设置所有主要参数，包括 ASR 类型、appid、access_token、LLM 类型、model_name 和 api_key 等
2. **通过文件编辑器**:
- Home Assistant → 设置 → 加载项 → 文件编辑器
- 导航到 `/config/data/.config.yaml` (加载项配置文件)
- 此文件包含更详细的配置，但每次重启加载项后会被加载项配置页面的设置覆盖
### 模型文件
使用 FunASR 模型时，需要使用 SenseVoiceSmall 模型文件才能正常工作。系统会自动下载模型文件并放置在以下位置：
```
/config/models/SenseVoiceSmall/model.pt
```
如果自动下载失败，您需要手动下载并放置模型文件。
### 语音识别服务 (ASR)
本插件支持以下语音识别服务：
1. **FunASR**：本地语音识别模型，需要下载模型文件。无需配置 API 密钥。
2. **DoubaoASR**：豆包 ASR 服务，需要配置 appid 和 access_token。
3. **TencentASR**：腾讯云 ASR 服务，需要配置 appid、access_token 和 secret_key。
**注意**：如果您选择 DoubaoASR 或 TencentASR，但未提供完整的配置信息，系统将无法启动相应服务。请确保提供所有必要的参数。
### 大语言模型服务 (LLM)
本插件支持以下大语言模型服务：
1. **DoubaoLLM**：豆包大语言模型服务
2. **ChatGLMLLM**：智谱 AI 大语言模型服务
3. **DeepSeekLLM**：DeepSeek 大语言模型服务
每种 LLM 服务都需要配置相应的 model_name 和 api_key。
### 如何获取各服务的配置信息
#### DoubaoASR (豆包语音识别)
- **获取地址**: [火山引擎语音服务](https://console.volcengine.com/speech/app)
- **appid**: 申请开通火山引擎语音合成服务后获取的 appid
- **access_token**: 开通后获取的访问令牌
#### TencentASR (腾讯云语音识别)
- **密钥申请**: [获取密钥](https://console.cloud.tencent.com/cam/capi)
- **免费资源**: [领取免费资源](https://console.cloud.tencent.com/asr/resourcebundle)
- **appid**: 腾讯云语音识别服务应用 ID
- **secret_id**: 获取的腾讯云语音识别 SecretID
- **secret_key**: 获取的腾讯云语音识别 SecretKey
#### DoubaoLLM (豆包大语言模型)
- **开通地址**: [开通服务](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)
- **获取密钥**: 开通后，进入[这里](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D)获取
- **适用模型**: 推荐模型名 `doubao-pro-32k-functioncall-241028`
- **免费额度**: 开通后提供 500000 token 的免费额度
#### ChatGLMLLM (智谱 AI 大语言模型)
- **获取密钥**: [智谱 AI 平台](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
- **推荐模型**: `glm-4-flash` (免费模型，但需要注册并填写 API 密钥)
- **API 访问**: 模型通过 `https://open.bigmodel.cn/api/paas/v4/` 接口访问
#### DeepSeekLLM (DeepSeek 大语言模型)
- **获取密钥**: [DeepSeek 平台](https://platform.deepseek.com/)
- **模型名称**: 如 `deepseek-chat`
- **访问地址**: https://api.deepseek.com
### 语音合成服务 (TTS)
本插件支持多种语音合成服务：
#### EdgeTTS (微软 Edge 浏览器 TTS)
- **无需 API 密钥**: 免费使用的本地 TTS 服务
- **默认语音**: `zh-CN-XiaoxiaoNeural`，中文女声
#### DoubaoTTS (豆包/火山引擎 TTS)
- **配置参数**: 需要设置`tts.appid`、`tts.access_token`和`tts.voice`（可选）
- **获取地址**: [火山引擎语音合成](https://console.volcengine.com/speech/service/8)
- **购买建议**: 建议购买付费服务，起步价 30 元可获得 100 并发，免费版本只有 2 个并发
- **特色音色**: 湾湾小何音色可在[此处开通](https://console.volcengine.com/speech/service/10007)
- **音色设置**: 默认使用`BV001_streaming`，湾湾小何音色设置为`zh_female_wanwanxiaohe_moon_bigtts`
- **开通说明**: 购买服务后，可能需要等待约半小时才能使用
- **验证要求**: 系统会在启动时验证 appid 和 access_token，如果缺少将无法启动
### FunASR 才会使用下面模型文件
您可以通过以下方式下载模型文件（正常情况下会自动下载）：
1. 线路一：[阿里魔塔下载 SenseVoiceSmall](https://www.modelscope.cn/models/iic/SenseVoiceSmall/summary)
2. 线路二：[百度网盘下载 SenseVoiceSmall](https://pan.baidu.com/s/1HW_UmfLiXhWwMjzS0GIpWg?pwd=qvna) 提取码：`qvna`
下载后，请将模型文件放置在上述路径中，或通过文件编辑器上传到 addon 配置目录的 models/SenseVoiceSmall 文件夹中。
### 配置文件
配置文件位于加载项配置目录：
```
/config/data/.config.yaml
```
如果未找到配置文件，系统会自动创建默认配置文件。首次运行时，会提示您修改配置文件中的 API 密钥等重要信息。
### 初次运行
首次启动插件时，会出现以下流程：
1. 检查模型文件，不存在则自动下载
2. 检查配置文件，不存在则自动创建
3. 提示您修改配置文件中的 API 密钥和其他设置
4. 配置好后需重启插件应用更改
这些提示只会在首次运行时显示，后续启动不会重复提示。
## 技术实现
本插件基于以下技术实现：
1. 使用 Home Assistant 标准加载项结构
2. 采用 S6-Overlay 进行服务管理，提高稳定性和可靠性
3. 使用 addon_config 目录存储配置和模型文件，符合 Home Assistant 最佳实践
4. 自动同步 Home Assistant 加载项配置到服务器配置
## 连接 ESP32 设备
1. 确保 ESP32 设备与 Home Assistant 在同一网络
2. WebSocket 服务地址：`ws://<您的Home Assistant IP>:8000/xiaozhi/v1/`
3. 将 ESP32 设备配置为连接上述 WebSocket 地址
## 故障排除
如果遇到以下问题，请参考处理方法：
1. **语音识别出现韩文、日文、英文**：检查模型文件是否正确加载
2. **TTS 任务出错或超时**：检查网络连接和配置文件设置
3. **连接问题**：确保 ESP32 设备与 Home Assistant 在同一网络
4. **无法自动下载模型**：网络问题或服务器故障，请尝试手动下载
5. **配置问题**：如果在加载项页面修改的配置未生效，请重启加载项并检查日志
6. **ASR 配置不完整错误**：确保您选择的 ASR 服务（如 DoubaoASR 或 TencentASR）已配置所有必要的参数
7. **TTS 配置不完整错误**：当选择 DoubaoTTS 时，确保已配置 appid 和 access_token
Reference in New Issue View Git Blame Copy Permalink