diff --git a/README.md b/README.md index 27c8c759..25907967 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,33 @@ + + + + + 实时打断 + + + + + + + 拍照识物品 + + + + + + + 多指令任务 + + + + + + + + --- @@ -141,11 +168,10 @@ 本项目提供两种部署方式，请根据您的具体需求选择： #### 🚀 部署方式选择 - -| 部署方式 | 特点 | 适用场景 | Docker部署文档 | 源码部署文档 | 视频教程 | +| 部署方式 | 特点 | 适用场景 | 部署文档 | 配置要求 | 视频教程 | |---------|------|---------|---------|---------|---------| -| **最简化安装** | 智能对话、IOT功能，数据存储在配置文件 | 低配置环境，无需数据库 | [Docker只运行Server](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) | [本地源码只运行Server](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| - | -| **全模块安装** | 智能对话、IOT、OTA、智控台，数据存储在数据库 | 完整功能体验 |[Docker运行全模块](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) | [本地源码运行全模块](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) | [本地源码视频教程](https://www.bilibili.com/video/BV1wBJhz4Ewe) | +| **最简化安装** | 智能对话、IOT、MCP、视觉感知，数据存储在配置文件 | 低配置环境，无需数据库 | [①Docker版](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②源码部署](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 如果使用`FunASR`要2核4G，如果全API，要2核2G | - | +| **全模块安装** | 智能对话、IOT、MCP、视觉感知、OTA、智控台，数据存储在数据库 | 完整功能体验 |[①Docker版](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②源码部署](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③源码部署自动更新教程](./docs/dev-ops-integration.md) | 如果使用`FunASR`要4核8G，如果全API，要2核4G| [本地源码启动视频教程](https://www.bilibili.com/video/BV1wBJhz4Ewe) | > 💡 提示：以下是按最新代码部署后的测试平台，有需要可烧录测试，并发为6个，每天会清空数据 @@ -158,22 +184,49 @@ OTA接口地址: https://2662r3426b.vicp.fun/xiaozhi/ota/ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/ ``` +#### 🚩 配置说明和推荐 +> [!Note] +> 本项目默认的配置是`入门全免费`设置，如果想效果更优，推荐使用`流式配置`。 +> +> 本项目自`0.5.2`版本，已支持使用流式配置，相比`0.5`版本以前，响应速度提升约`2.5秒` + +| 模块名称 | 入门全免费设置 | 流式配置 | +|:---:|:---:|:---:| +| ASR(语音识别) | FunASR(本地) | 👍DoubaoStreamASR(火山流式语音识别) | +| LLM(大模型) | ChatGLMLLM(智谱glm-4-flash) | 👍DoubaoLLM(火山doubao-1-5-pro-32k-250115) | +| VLLM(视觉大模型) | ChatGLMVLLM(智谱glm-4v-flash) | 👍QwenVLVLLM(千问qwen2.5-vl-3b-instructh) | +| TTS(语音合成) | EdgeTTS(微软语音) | 👍HuoshanDoubleStreamTTS(火山双流式语音合成) | +| Intent(意图识别) | function_call(函数调用) | ✅function_call(函数调用) | +| Memory(记忆功能) | mem_local_short(本地短期记忆） | ✅mem_local_short（本地短期记忆） | + +#### 🔧 测试工具 +本项目提供以下测试工具，帮助您验证系统和选择合适的模型： + +| 工具名称 | 位置 | 使用方法 | 功能说明 | +|:---:|:---|:---:|:---:| +| 音频交互测试工具 | main》xiaozhi-server》test/》est_page.html | 使用谷歌浏览器直接打开 | 测试音频播放和接收功能，验证Python端音频处理是否正常 | +| 模型响应测试工具1 | main》xiaozhi-server》performance_tester.py | 执行 `python performance_tester.py` | 测试ASR(语音识别)、LLM(大模型)、TTS(语音合成)三个核心模块的响应速度 | +| 模型响应测试工具2 | main》xiaozhi-server》performance_tester_vllm.py | 执行 `python performance_tester_vllm.py` | 测试VLLM(视觉模型)的响应速度 | + +> 💡 提示：测试模型速度时，只会测试配置了密钥的模型。 + --- ## 功能清单 ✨ - ### 已实现 ✅ | 功能模块 | 描述 | -|---------|------| -| 通信协议 | 基于 `xiaozhi-esp32` 协议，通过 WebSocket 实现数据交互 | -| 对话交互 | 支持唤醒对话、手动对话及实时打断。长时间无对话时自动休眠 | -| 意图识别 | 支持使用LLM意图识别、function call函数调用，减少硬编码意图判断 | -| 多语言识别 | 支持国语、粤语、英语、日语、韩语（默认使用 FunASR） | -| LLM 模块 | 支持灵活切换 LLM 模块，默认使用 ChatGLMLLM，也可选用阿里百炼、DeepSeek、Ollama 等接口 | -| TTS 模块 | 支持 EdgeTTS（默认）、火山引擎豆包 TTS 等多种 TTS 接口，满足语音合成需求 | -| 记忆功能 | 支持超长记忆、本地总结记忆、无记忆三种模式，满足不同场景需求 | -| IOT功能 | 支持管理注册设备IOT功能，支持基于对话上下文语境下的智能物联网控制 | -| 智控台 | 提供Web管理界面，支持智能体管理、用户管理、系统配置等功能，方便管理员和用户进行管理 | +|:---:|:---| +| 核心服务架构 | 基于WebSocket和HTTP服务器，提供完整的控制台管理和认证系统 | +| 语音交互系统 | 支持流式ASR(语音识别)、流式TTS(语音合成)、VAD(语音活动检测)，支持多语言识别和语音处理 | +| 智能对话系统 | 支持多种LLM(大语言模型)，实现智能对话 | +| 视觉感知系统 | 支持多种VLLM(视觉大模型)，实现多模态交互 | +| 意图识别系统 | 支持LLM意图识别、Function Call函数调用，提供插件化意图处理机制 | +| 记忆系统 | 支持本地短期记忆、mem0ai接口记忆，具备记忆总结功能 | +| IOT/MCP控制协议 | 支持设备注册管理、智能控制接口，同时支持IOT、MCP控制协议 | +| 管理后台 | 提供Web管理界面，支持用户管理、系统配置和设备管理 | +| 测试工具 | 提供性能测试工具、视觉模型测试工具和音频交互测试工具 | +| 部署支持 | 支持Docker部署和本地部署，提供完整的配置文件管理 | +| 插件系统 | 支持功能插件扩展、自定义插件开发和插件热加载 | ### 正在开发 🚧 @@ -210,6 +263,16 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/ --- +### VLLM 视觉模型 + +| 使用方式 | 支持平台 | 免费平台 | +|:---:|:---:|:---:| +| openai 接口调用 | 阿里百炼、智谱ChatGLMVLLM | 智谱ChatGLMVLLM | + +实际上，任何支持 openai 接口调用的 VLLM 均可接入使用。 + +--- + ### TTS 语音合成 | 使用方式 | 支持平台 | 免费平台 | diff --git a/README_en.md b/README_en.md index 9b4ed8ce..d66cbe5d 100644 --- a/README_en.md +++ b/README_en.md @@ -6,14 +6,14 @@ This project provides backend services for the open-source smart hardware project xiaozhi-esp32
Implemented using Python, Java, and Vue according to the Xiaozhi Communication Protocol
-Helping you quickly set up your Xiaozhi server +Helps you quickly set up your Xiaozhi server

中文 · FAQ · Report Issues -· Deployment Guide +· Deployment Guide · Release Notes

@@ -50,7 +50,7 @@ Want to see it in action? Check out these videos 🎥 - Xiaozhi esp32 connecting to custom backend model + Xiaozhi esp32 connecting to own backend model @@ -64,14 +64,14 @@ Want to see it in action? Check out these videos 🎥 - Cantonese communication + Using Cantonese - Home appliance control + Control home appliances @@ -94,7 +94,7 @@ Want to see it in action? Check out these videos 🎥 - Music playback + Play music @@ -108,7 +108,7 @@ Want to see it in action? Check out these videos 🎥 - IOT device control + IOT command control @@ -120,6 +120,33 @@ Want to see it in action? Check out these videos 🎥 + + + + + Real-time interruption + + + + + + + Photo recognition + + + + + + + Multi-command tasks + + + + + + + + --- @@ -137,91 +164,102 @@ It is recommended that users prioritize service providers with relevant business ![Banners](docs/images/banner2.png) -This project offers two deployment methods. Please choose based on your specific needs: +This project provides two deployment methods. Please choose according to your specific needs: #### 🚀 Deployment Method Selection +| Deployment Method | Features | Suitable Scenarios | Deployment Guide | Requirements | Video Tutorial | +|---------|------|---------|---------|---------|---------| +| **Simplified Installation** | Smart dialogue, IOT functionality, data stored in configuration files | Low-configuration environment, no database needed | [Docker Version](./docs/Deployment.md#method-1-docker-server-only) / [Source Code Deployment](./docs/Deployment.md#method-2-local-source-code-server-only) | 2 cores 4G if using `FunASR`, 2 cores 2G if using all APIs | - | +| **Full Module Installation** | Smart dialogue, IOT, OTA, Control Panel, data stored in database | Complete functionality experience | [Docker Version](./docs/Deployment_all.md#method-1-docker-full-modules) / [Source Code Deployment](./docs/Deployment_all.md#method-2-local-source-code-full-modules) | 4 cores 8G if using `FunASR`, 2 cores 4G if using all APIs | [Local Source Code Startup Video Tutorial](https://www.bilibili.com/video/BV1wBJhz4Ewe) / [Local Source Code Auto-Update Tutorial](./docs/dev-ops-integration.md) | -| Deployment Method | Features | Use Case | Docker Deployment Guide | Source Code Deployment Guide | -|---------|------|---------|---------|---------| -| **Simplified Installation** | Smart dialogue, IOT functionality, data stored in configuration files | Low-configuration environment, no database required | [Docker Server Only](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) | [Local Source Code Server Only](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| -| **Full Module Installation** | Smart dialogue, IOT, OTA, Control Panel, data stored in database | Complete functionality experience |[Docker Full Module](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) | [Local Source Code Full Module](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) | - -> 💡 Note: Below is the test platform deployed with the latest code. You can flash and test if needed. Concurrent users: 6, data cleared daily +> 💡 Note: Below are the test platforms deployed with the latest code. You can flash and test if needed. Concurrent users: 6, data will be cleared daily ``` -Control Panel: https://2662r3426b.vicp.fun +Control Panel Address: https://2662r3426b.vicp.fun Service Test Tool: https://2662r3426b.vicp.fun/test/ -OTA Interface: https://2662r3426b.vicp.fun/xiaozhi/ota/ -Websocket Interface: wss://2662r3426b.vicp.fun/xiaozhi/v1/ +OTA Interface Address: https://2662r3426b.vicp.fun/xiaozhi/ota/ +Websocket Interface Address: wss://2662r3426b.vicp.fun/xiaozhi/v1/ ``` +#### 🚩 Configuration Description and Recommendations +> [!Note] +> The default configuration of this project is `Entry Level Free` settings. For better results, we recommend using `Full Streaming Configuration`. +> +> Since version `0.5.2`, this project supports full streaming throughout the entire lifecycle. Compared to versions before `0.5`, response speed has improved by approximately `2.5 seconds` + +| Module Name | Entry Level Free Settings | Full Streaming Configuration | +|---------|---------|------| +| ASR(Speech Recognition) | FunASR(Local) | ✅DoubaoASR(Volcano Streaming Speech Recognition) | +| LLM(Large Language Model) | ChatGLMLLM(Zhipu glm-4-flash) | ✅DoubaoLLM(Volcano doubao-1-5-pro-32k-250115) | +| VLLM(Vision Large Model) | ChatGLMVLLM(Zhipu glm-4v-flash) | ✅ChatGLMVLLM(Zhipu glm-4v-flash) | +| TTS(Speech Synthesis) | EdgeTTS(Microsoft Speech) | ✅HuoshanDoubleStreamTTS(Volcano Double Streaming Speech Synthesis) | +| Intent(Intent Recognition) | function_call(Function Call) | ✅function_call(Function Call) | +| Memory(Memory Function) | mem_local_short(Local Short-term Memory) | ✅mem_local_short(Local Short-term Memory) | + --- ## Feature List ✨ - ### Implemented ✅ | Feature Module | Description | |---------|------| | Communication Protocol | Based on `xiaozhi-esp32` protocol, implements data interaction through WebSocket | -| Dialogue Interaction | Supports wake-up dialogue, manual dialogue, and real-time interruption. Auto-sleep after long periods of inactivity | +| Dialogue Interaction | Supports wake-up dialogue, manual dialogue, and real-time interruption. Auto-sleep after long periods of no dialogue | | Intent Recognition | Supports LLM intent recognition, function call, reducing hard-coded intent judgment | | Multi-language Recognition | Supports Mandarin, Cantonese, English, Japanese, Korean (default using FunASR) | -| LLM Module | Supports flexible LLM module switching, default using ChatGLMLLM, also supports Ali Bailing, DeepSeek, Ollama, etc. | -| TTS Module | Supports EdgeTTS (default), Volcano Engine Doubao TTS, and other TTS interfaces for speech synthesis | -| Memory Function | Supports ultra-long memory, local summary memory, and no memory modes for different scenarios | -| IOT Function | Supports managing registered device IOT functionality, intelligent IoT control based on dialogue context | -| Control Panel | Provides web management interface, supports agent management, user management, system configuration, etc. | +| LLM Module | Supports flexible LLM module switching, default using ChatGLMLLM, can also use Ali Bailian, DeepSeek, Ollama, etc. | +| TTS Module | Supports EdgeTTS (default), Volcano Engine Doubao TTS, and other TTS interfaces | +| Memory Function | Supports ultra-long memory, local summary memory, and no memory modes | +| IOT Function | Supports managing registered device IOT functionality, supports smart IoT control based on dialogue context | +| Control Panel | Provides Web management interface, supports agent management, user management, system configuration, etc. | ### In Development 🚧 To learn about specific development progress, [click here](https://github.com/users/xinnan-tech/projects/3) -If you're a software developer, here's an [Open Letter to Developers](docs/contributor_open_letter.md). Welcome to join! +If you are a software developer, here is an [Open Letter to Developers](docs/contributor_open_letter.md). Welcome to join! --- ## Product Ecosystem 👬 -Xiaozhi is an ecosystem. When using this product, you might want to check out other excellent projects in this ecosystem: +Xiaozhi is an ecosystem. When using this product, you might also want to check out other excellent projects in this ecosystem -| Project Name | Project Link | Description | +| Project Name | Project Address | Project Description | |:---------------------|:--------|:--------| -| Xiaozhi Android Client | [xiaozhi-android-client](https://github.com/TOM88812/xiaozhi-android-client) | A Flutter-based Android and iOS voice dialogue application supporting real-time voice interaction and text dialogue | -| Xiaozhi PC Client | [py-xiaozhi](https://github.com/Huang-junsen/py-xiaozhi) | A Python-based AI client that allows you to experience Xiaozhi AI functionality through code without physical hardware | -| Xiaozhi Java Server | [xiaozhi-esp32-server-java](https://github.com/joey-zhou/xiaozhi-esp32-server-java) | A Java-based open-source project providing complete backend service solutions | +| Xiaozhi Android Client | [xiaozhi-android-client](https://github.com/TOM88812/xiaozhi-android-client) | A Flutter-based Android and iOS voice dialogue application supporting real-time voice interaction and text dialogue. | +| Xiaozhi PC Client | [py-xiaozhi](https://github.com/Huang-junsen/py-xiaozhi) | This project provides a Python-based Xiaozhi AI client, allowing you to experience Xiaozhi AI's functionality through code even without physical hardware. | +| Xiaozhi Java Server | [xiaozhi-esp32-server-java](https://github.com/joey-zhou/xiaozhi-esp32-server-java) | The Java version of Xiaozhi open-source backend service is a Java-based open-source project.
It includes both frontend and backend services, aiming to provide users with a complete backend service solution. | --- -## Supported Platforms/Components 📋 +## Supported Platforms/Components List 📋 ### LLM Language Models | Usage Method | Supported Platforms | Free Platforms | |:---:|:---:|:---:| -| openai API | Ali Bailing, Volcano Engine Doubao, DeepSeek, ChatGLM, Gemini | ChatGLM, Gemini | -| ollama API | Ollama | - | -| dify API | Dify | - | -| fastgpt API | Fastgpt | - | -| coze API | Coze | - | +| openai interface call | Ali Bailian, Volcano Engine Doubao, DeepSeek, Zhipu ChatGLM, Gemini | Zhipu ChatGLM, Gemini | +| ollama interface call | Ollama | - | +| dify interface call | Dify | - | +| fastgpt interface call | Fastgpt | - | +| coze interface call | Coze | - | -Actually, any LLM supporting openai API calls can be integrated. - ---- +In fact, any LLM that supports openai interface calls can be integrated and used. ### TTS Speech Synthesis | Usage Method | Supported Platforms | Free Platforms | |:---:|:---:|:---:| -| API Calls | EdgeTTS, Volcano Engine Doubao TTS, Tencent Cloud, Aliyun TTS, CosyVoiceSiliconflow, TTS302AI, CozeCnTTS, GizwitsTTS, ACGNTTS, OpenAITTS | EdgeTTS, CosyVoiceSiliconflow(partial) | +| API Call | EdgeTTS, Volcano Engine Doubao TTS, Tencent Cloud, Alibaba Cloud TTS, CosyVoiceSiliconflow, TTS302AI, CozeCnTTS, GizwitsTTS, ACGNTTS, OpenAITTS | EdgeTTS, CosyVoiceSiliconflow(partial) | | Local Service | FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3, MinimaxTTS | FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3, MinimaxTTS | --- ### VAD Voice Activity Detection -| Type | Platform Name | Usage Method | Pricing | Notes | +| Type | Platform Name | Usage Method | Pricing Model | Notes | |:---:|:---------:|:----:|:----:|:--:| -| VAD | SileroVAD | Local Use | Free | | +| VAD | SileroVAD | Local Usage | Free | | --- @@ -229,26 +267,26 @@ Actually, any LLM supporting openai API calls can be integrated. | Usage Method | Supported Platforms | Free Platforms | |:---:|:---:|:---:| -| Local Use | FunASR, SherpaASR | FunASR, SherpaASR | -| API Calls | DoubaoASR, FunASRServer, TencentASR, AliyunASR | FunASRServer | +| Local Usage | FunASR, SherpaASR | FunASR, SherpaASR | +| API Call | DoubaoASR, FunASRServer, TencentASR, AliyunASR | FunASRServer | --- ### Memory Storage -| Type | Platform Name | Usage Method | Pricing | Notes | +| Type | Platform Name | Usage Method | Pricing Model | Notes | |:------:|:---------------:|:----:|:---------:|:--:| -| Memory | mem0ai | API Calls | 1000 calls/month quota | | +| Memory | mem0ai | API Call | 1000 calls/month quota | | | Memory | mem_local_short | Local Summary | Free | | --- ### Intent Recognition -| Type | Platform Name | Usage Method | Pricing | Notes | +| Type | Platform Name | Usage Method | Pricing Model | Notes | |:------:|:-------------:|:----:|:-------:|:---------------------:| -| Intent | intent_llm | API Calls | Based on LLM pricing | Uses large model for intent recognition, highly versatile | -| Intent | function_call | API Calls | Based on LLM pricing | Uses large model function calls for intent, fast and effective | +| Intent | intent_llm | API Call | Based on LLM pricing | Uses large model for intent recognition, highly versatile | +| Intent | function_call | API Call | Based on LLM pricing | Uses large model function calls for intent, fast and effective | --- @@ -257,10 +295,10 @@ Actually, any LLM supporting openai API calls can be integrated. | Logo | Project/Company | Description | |:---:|:---:|:---| | | [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) | This project was inspired by [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) and implemented based on it | -| | [Tenclass](https://www.tenclass.com/) | Thanks to [Tenclass](https://www.tenclass.com/) for developing standard communication protocols, multi-device compatibility solutions, and high-concurrency scenario practices for the Xiaozhi ecosystem; providing comprehensive technical documentation support for this project | -| | [Xuanfeng Technology](https://github.com/Eric0308) | Thanks to [Xuanfeng Technology](https://github.com/Eric0308) for contributing function call framework, MCP communication protocol, and plugin call mechanism implementation code, significantly improving front-end device (IoT) interaction efficiency and functional extensibility through standardized instruction scheduling system and dynamic expansion capabilities | -| | [Huiyuan Design](http://ui.kwd988.net/) | Thanks to [Huiyuan Design](http://ui.kwd988.net/) for providing professional visual solutions for this project, empowering product user experience with their design experience serving over a thousand enterprises | -| | [Xi'an Qinren Information Technology](https://www.029app.com/) | Thanks to [Xi'an Qinren Information Technology](https://www.029app.com/) for deepening this project's visual system, ensuring consistency and extensibility of overall design style in multi-scenario applications | +| | [Tenclass](https://www.tenclass.com/) | Thanks to [Tenclass](https://www.tenclass.com/) for establishing standard communication protocols, multi-device compatibility solutions, and high-concurrency scenario practices for the Xiaozhi ecosystem; providing full-chain technical documentation support for this project | +| | [Xuanfeng Technology](https://github.com/Eric0308) | Thanks to [Xuanfeng Technology](https://github.com/Eric0308) for contributing the function call framework, MCP communication protocol, and plugin call mechanism implementation code, significantly improving front-end device (IoT) interaction efficiency and functional extensibility through standardized instruction scheduling system and dynamic expansion capabilities | +| | [Huiyuan Design](http://ui.kwd988.net/) | Thanks to [Huiyuan Design](http://ui.kwd988.net/) for providing professional visual solutions for this project, empowering the product user experience with their design experience serving over a thousand enterprises | +| | [Xi'an Qinren Information Technology](https://www.029app.com/) | Thanks to [Xi'an Qinren Information Technology](https://www.029app.com/) for deepening the visual system of this project, ensuring consistency and extensibility of the overall design style in multi-scenario applications | @@ -270,4 +308,4 @@ Actually, any LLM supporting openai API calls can be integrated. Star History Chart - \ No newline at end of file + diff --git a/docs/FAQ.md b/docs/FAQ.md index f04f3d78..e2d428e3 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -108,7 +108,11 @@ VAD: 参考教程[阿里云短信集成指南](./ali-sms-integration.md) -### 9、更多问题，可联系我们反馈 💬 +### 9、如何开启视觉模型实现拍照识物 📷 + +参考教程[视觉模型使用指南](./mcp-vision-integration.md) + +### 10、更多问题，可联系我们反馈 💬 可以在[issues](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues)提交您的问题。 diff --git a/docs/TECHNICAL_OVERVIEW.md b/docs/TECHNICAL_OVERVIEW.md new file mode 100644 index 00000000..9351a987 --- /dev/null +++ b/docs/TECHNICAL_OVERVIEW.md @@ -0,0 +1,236 @@ +# Technical Documentation: xiaozhi-esp32-server + +**Table of Contents:** + +1. [Introduction](#1-introduction) +2. [Overall Architecture](#2-overall-architecture) +3. [Component Deep Dive](#3-component-deep-dive) + * [xiaozhi-server (Python AI Engine)](#31-xiaozhi-server-python-ai-engine) + * [manager-api (Java Management Backend)](#32-manager-api-java-management-backend) + * [manager-web (Vue.js Management Frontend)](#33-manager-web-vuejs-management-frontend) +4. [Data Flow and Interaction Mechanisms](#4-data-flow-and-interaction-mechanisms) +5. [Key Features Summary](#5-key-features-summary) +6. [Deployment and Configuration Overview](#6-deployment-and-configuration-overview) + +--- + +## 1. Introduction + +The `xiaozhi-esp32-server` project provides a comprehensive backend system designed to power intelligent voice interactions for ESP32-based smart hardware. Its primary purpose is to enable developers to quickly establish a robust server infrastructure capable of understanding natural language commands, interacting with various AI services (for speech recognition, language understanding, and speech synthesis), managing IoT devices, and offering a web-based interface for system configuration and administration. This project facilitates the creation of customizable voice assistants and smart control systems by integrating multiple cutting-edge technologies into a cohesive and extensible platform. + +--- + +## 2. Overall Architecture + +The `xiaozhi-esp32-server` system is architected as a distributed suite of interconnected components, each with a distinct role, ensuring modularity and scalability. The primary components are: + +1. **ESP32 Hardware (Client Device):** This is the physical smart hardware device that the end-user interacts with. It's responsible for: + * Capturing user's voice commands. + * Sending captured audio to the `xiaozhi-server`. + * Receiving synthesized audio responses from `xiaozhi-server` and playing them back. + * Potentially controlling other connected peripherals or IoT devices based on commands from `xiaozhi-server`. + +2. **`xiaozhi-server` (Core AI Engine):** This Python-based server is the central brain for voice processing and interaction logic. Its key responsibilities include: + * Establishing real-time, bidirectional WebSocket communication with ESP32 devices. + * Receiving audio streams and performing Voice Activity Detection (VAD). + * Converting speech to text using integrated Automatic Speech Recognition (ASR) services. + * Interpreting user intent and generating responses by interacting with Large Language Models (LLMs). + * Managing dialogue context and memory. + * Converting text responses back to speech using Text-to-Speech (TTS) services. + * Executing commands, including IoT device control via a plugin system. + * Fetching its operational configuration from the `manager-api`. + +3. **`manager-api` (Management Backend):** A Java Spring Boot application that provides a RESTful API for system administration and configuration. It serves as the backend for the `manager-web` frontend and a configuration source for `xiaozhi-server`. Its functions include: + * User authentication and management for the control panel. + * Registration and management of ESP32 devices. + * Storage and retrieval of system configurations (e.g., selected AI service providers, API keys, device settings) in a MySQL database. + * Providing endpoints for `xiaozhi-server` to fetch its configuration. + * Managing voice timbre settings, OTA firmware updates, and other system parameters. + * Utilizing Redis for caching to enhance performance. + +4. **`manager-web` (Web Control Panel):** A Vue.js Single Page Application (SPA) that provides a graphical user interface for administrators. It allows for: + * Easy configuration of `xiaozhi-server`'s AI services and operational parameters. + * Management of users, devices, and their respective settings. + * Monitoring system status (potentially) and managing other administrative tasks. + * Interaction with all backend functionalities exposed by `manager-api`. + +**High-Level Interaction Flow:** + +* The **ESP32** device captures voice and communicates primarily with **`xiaozhi-server`** via WebSockets for all voice-related interactions. +* **`xiaozhi-server`** processes the voice data, interacts with various AI cloud services or local models, and sends responses back to the ESP32. +* The **`manager-web`** frontend communicates with **`manager-api`** using RESTful HTTP calls to manage and configure the entire system. +* **`xiaozhi-server`** also communicates with **`manager-api`** (via REST) to pull its latest configuration, ensuring that changes made in the web panel are reflected in its operation. + +This separation of concerns allows the `xiaozhi-server` to focus on efficient real-time AI processing, while the `manager-api` and `manager-web` provide a robust and user-friendly interface for administration and setup. + +--- + +## 3. Component Deep Dive + +### 3.1. `xiaozhi-server` (Python AI Engine) + +The `xiaozhi-server` is the intelligent core of the system, responsible for processing voice interactions, interfacing with AI services, and managing communication with ESP32 devices. + +* **Purpose:** + * To provide real-time processing of voice commands from ESP32 devices. + * To integrate with various AI services for Speech-to-Text (ASR), Natural Language Understanding (via Large Language Models - LLMs), Text-to-Speech (TTS), Voice Activity Detection (VAD), Intent Recognition, and Memory. + * To manage dialogue flow and context with users. + * To execute custom functions and control IoT devices based on user commands. + * To be dynamically configurable through the `manager-api`. + +* **Core Technologies:** + * **Python 3:** The primary programming language. + * **Asyncio:** Python's asynchronous programming framework, crucial for handling concurrent WebSocket connections and non-blocking I/O for AI service API calls. + * **`websockets` Library:** For WebSocket server implementation. + * **HTTP Client (e.g., `aiohttp`, `httpx`):** For asynchronous HTTP requests to `manager-api` and external AI services. + * **YAML (PyYAML):** For local configuration file parsing. + +* **Key Implementation Aspects:** + + 1. **AI Service Provider Pattern (`core/providers/`):** + * **Concept:** A flexible design for integrating AI services. Each service type (ASR, TTS, LLM, etc.) has an abstract base class defining a common interface. Concrete classes implement this interface for specific vendors or local models. + * **Benefit:** Allows easy switching of AI service backends via configuration and simplifies adding new service integrations. + * **Initialization:** `core/utils/modules_initialize.py` acts as a factory to load and instantiate configured providers. + + 2. **WebSocket Communication & Connection Handling (`core/websocket_server.py`, `core/connection.py`):** + * **Server Setup:** Manages WebSocket connections from ESP32 devices. + * **Connection Isolation:** Each ESP32 client gets a dedicated `ConnectionHandler` instance, isolating its session state and dialogue. + * **Dynamic Configuration Updates:** Can fetch updated configurations from `manager-api` and re-initialize AI service modules live, without a full server restart. + + 3. **Message Handling & Dialogue Flow (`core/handle/`):** + * Employs a modular handler pattern. The `ConnectionHandler` dispatches message processing to specialized modules based on message type or dialogue phase (e.g., `receiveAudioHandle.py` for audio input, `intentHandler.py` for NLU, `functionHandler.py` for plugin execution, `sendAudioHandle.py` for TTS output). + + 4. **Plugin System for Extensible Functions (`plugins_func/`):** + * **Purpose:** Allows adding custom "skills" (e.g., weather, news, Home Assistant control). + * **Mechanism:** Plugins define functions and schemas. The LLM can request execution of these functions (function calling). `loadplugins.py` and `register.py` manage plugin discovery and registration. + + 5. **Configuration Management (`config/`):** + * Loads settings from a local `config.yaml` and merges them with configurations fetched from `manager-api` (via `manage_api_client.py`), enabling remote dynamic configuration. + * `logger.py` sets up structured application logging. + * `config/assets/` stores predefined audio files for system notifications. + + 6. **Auxiliary HTTP Server (`core/http_server.py`):** + * Handles specific HTTP requests, notably for OTA firmware updates (`/xiaozhi/ota/`) and other utility endpoints. + +### 3.2. `manager-api` (Java Management Backend) + +The `manager-api` component is a backend server built using Java and the Spring Boot framework, serving as the administrative hub. + +* **Purpose:** + * Provide a secure RESTful API for the `manager-web` frontend. + * Act as a centralized configuration provider for `xiaozhi-server`. + * Manage persistent data (users, devices, AI configurations, voice timbres, OTA firmware). + +* **Core Technologies:** + * **Java 21 & Spring Boot 3:** Core language and framework. + * **Spring MVC:** For building REST controllers. + * **MyBatis-Plus:** ORM for database interaction with MySQL. + * **MySQL:** Relational database. + * **Druid:** JDBC connection pool. + * **Redis (Spring Data Redis):** For caching. + * **Apache Shiro:** Security framework for authentication and authorization. + * **Liquibase:** Database schema migration. + * **Knife4j:** OpenAPI (Swagger) API documentation. + * **Maven:** Build and dependency management. + +* **Key Implementation Aspects:** + + 1. **Modular Architecture (`modules/` package):** + * Business logic is organized into distinct modules (e.g., `sys` for users/roles, `agent` for assistant configs, `device` for ESP32s, `config` for `xiaozhi-server` settings, `security`, `timbre`, `ota`). + * Each module typically follows a layered pattern: Controller, Service, DAO (Mapper), Entity, DTO. + + 2. **Layered Architecture:** + * **Controller Layer (`@RestController`):** Defines API endpoints, handles HTTP request/response. + * **Service Layer (`@Service`):** Contains business logic, transaction management. + * **Data Access Layer (MyBatis-Plus Mappers):** Interacts with the MySQL database. + + 3. **Common Functionalities (`common/` package):** + * Provides shared code: base classes, global configurations (Spring, MyBatis, Redis, Knife4j), custom annotations (e.g., `@LogOperation`), AOP aspects, global exception handling, utility classes, and XSS protection. + + 4. **Security (Apache Shiro):** + * Manages user authentication and permissions for accessing API endpoints. Configured with Shiro Realms and security filters. + + 5. **Database Schema Management (Liquibase):** + * Ensures consistent database structure across environments through versioned schema changes. + +### 3.3. `manager-web` (Vue.js Management Frontend) + +The `manager-web` is a Single Page Application (SPA) providing the administrative user interface. + +* **Purpose:** + * Offer a web-based control panel for system configuration and management. + * Enable administrators to configure `xiaozhi-server`'s AI services, manage users and devices, customize voice timbres, and handle OTA updates. + +* **Core Technologies:** + * **Vue.js 2 & Vue CLI:** Core JavaScript framework and build tools. + * **Vue Router:** For client-side routing within the SPA. + * **Vuex:** For centralized state management. + * **Element UI:** UI component library for a consistent look and feel. + * **SCSS:** CSS preprocessor. + * **HTTP Client (Flyio or Axios):** For API calls to `manager-api`. + * **Workbox:** For PWA features (caching, service worker). + * **Opus Libraries:** For potential in-browser audio recording/playback. + +* **Key Implementation Aspects:** + + 1. **SPA Structure:** Single HTML page with dynamic view updates. + 2. **Component-Based Architecture:** UI built from reusable Vue components (`.vue` files in `src/views/` for pages and `src/components/` for smaller elements). + 3. **Client-Side Routing (`src/router/index.js`):** Maps browser URLs to view components, with route guards for authentication. + 4. **State Management (`src/store/index.js`):** Vuex manages global state (user info, device lists, etc.) via state, getters, mutations, and actions (often involving API calls). + 5. **API Communication (`src/apis/`):** Modularized API service files make asynchronous calls to `manager-api`. + 6. **Build Process & PWA Features:** Vue CLI (Webpack) bundles assets. Workbox enables PWA features like caching. + 7. **Environment Configuration (`.env` files):** Manages settings like the `manager-api` base URL for different environments. + +--- + +## 4. Data Flow and Interaction Mechanisms + +The system uses WebSockets for real-time voice interactions and RESTful APIs for management tasks. + +* **Core Voice Interaction (ESP32 <-> `xiaozhi-server` - WebSockets):** + * ESP32 connects to `xiaozhi-server` via WebSocket. + * Audio is streamed from ESP32 to server. + * Server processes audio (VAD, ASR), interacts with LLM (possibly executing plugin functions), synthesizes response via TTS. + * Synthesized audio is streamed back to ESP32. + * JSON control/status messages are also exchanged. + +* **Management & Configuration (RESTful APIs - HTTP/JSON):** + * **`manager-web` -> `manager-api`:** Admin actions in the web UI trigger REST API calls to `manager-api` for managing users, devices, configurations, etc. Shiro secures these endpoints. + * **`xiaozhi-server` -> `manager-api`:** `xiaozhi-server` pulls its operational configuration from `manager-api` via REST API calls. + +* **OTA Updates (Conceptual - HTTP & WebSocket):** + * Firmware uploaded via `manager-web` to `manager-api`. + * `xiaozhi-server` may notify ESP32 of updates via WebSocket. + * ESP32 downloads firmware via HTTP from an endpoint (likely on `xiaozhi-server`). + +--- + +## 5. Key Features Summary + +* **Modular AI Services:** Pluggable ASR, LLM, TTS, VAD, Intent, Memory. +* **Advanced Dialogue:** Real-time interruption, contextual memory, multi-language support. +* **Extensible Skills:** Plugin system for custom functions (e.g., IoT, Home Assistant). +* **Comprehensive Web Management:** UI for users, devices, AI configs, OTA, timbres. +* **Flexible Deployment:** Docker (simplified/full) and source code options. +* **Dynamic Remote Configuration:** `xiaozhi-server` updates settings from `manager-api` live. +* **Open Source (MIT License).** +* **Cost-Effective Options:** "Entry Level Free Settings" available. +* **PWA Admin Panel:** Enhanced caching and user experience. +* **API Documentation:** Knife4j for `manager-api`. + +--- + +## 6. Deployment and Configuration Overview + +* **Deployment:** + * **Docker:** Recommended for ease. Options for `xiaozhi-server` only or full stack (all components + databases). `docker-compose.yml` files provided. + * **Source Code:** For development or custom setups, requiring manual environment setup for Python, Java/Maven, and Node.js. + +* **Configuration:** + * **`xiaozhi-server`:** Uses a local `config.yaml`, but primarily pulls dynamic configurations (AI providers, API keys) from `manager-api` via its `manage_api_client.py`. + * **`manager-api`:** Configured via Spring Boot's `application.properties` or `application.yml` (database, Redis, Shiro settings). + * **`manager-web`:** Configured via `.env` files (e.g., `manager-api` URL). + * The `manager-web` UI is the primary interface for most system configurations in a full deployment. + * Predefined profiles like "Entry Level Free Settings" and "Full Streaming Configuration" guide AI service choices. + +--- diff --git a/docs/TECHNICAL_OVERVIEW_CN.md b/docs/TECHNICAL_OVERVIEW_CN.md new file mode 100644 index 00000000..ce70aaa7 --- /dev/null +++ b/docs/TECHNICAL_OVERVIEW_CN.md @@ -0,0 +1,450 @@ +# 技术文档：`xiaozhi-esp32-server` + +**目录：** + +1. [引言](#1-引言) +2. [整体架构](#2-整体架构) +3. [核心组件深度剖析](#3-核心组件深度剖析) + * [3.1. `xiaozhi-server` (核心AI引擎 - Python实现)](#31-xiaozhi-server-核心ai引擎---python实现) + * [3.2. `manager-api` (管理后端 - Java Spring Boot实现)](#32-manager-api-管理后端---java-spring-boot实现) + * [3.3. `manager-web` (Web管理前端 - Vue.js实现)](#33-manager-web-web管理前端---vuejs实现) +4. [数据流与交互机制](#4-数据流与交互机制) +5. [核心功能概要](#5-核心功能概要) +6. [部署与配置概述](#6-部署与配置概述) + +--- + +## 1. 引言 + +`xiaozhi-esp32-server` 项目是一个专为基于ESP32的智能硬件提供支持的**综合性后端系统**。其核心目标是使开发人员能够快速构建一个强大的服务器基础设施，该设施不仅能够理解自然语言指令，还能与多种AI服务（用于语音识别、自然语言理解及语音合成）进行高效交互、管理物联网（IoT）设备，并提供一个基于Web的用户界面以进行系统配置和管理。通过将多种尖端技术整合到一个高内聚且可扩展的平台中，本项目旨在简化和加速可定制化语音助手及智能控制系统的开发进程。它不仅仅是一个简单的服务器，更是一个连接硬件、AI能力与用户管理的桥梁。 + +--- + +## 2. 整体架构 + +`xiaozhi-esp32-server` 系统采用了一种**分布式、多组件协作**的架构设计，确保了系统的模块化、可维护性和可扩展性。各个核心组件各司其职，协同工作。主要组件包括： + +1. **ESP32 硬件 (客户端设备):** + 这是终端用户直接与之交互的物理智能硬件设备。其主要职责包括： + * 捕捉用户的语音指令。 + * 将捕捉到的原始音频数据安全地发送至 `xiaozhi-server` 进行处理。 + * 接收来自 `xiaozhi-server` 合成的语音回复，并通过扬声器播放给用户。 + * 根据从 `xiaozhi-server` 收到的指令，控制与之连接的其他外围设备或IoT设备（例如智能灯泡、传感器等）。 + +2. **`xiaozhi-server` (核心AI引擎 - Python实现):** + 这个基于Python的服务器是整个系统的“大脑”，负责处理所有语音相关的逻辑和AI交互。其关键职责细化如下： + * 通过WebSocket协议与ESP32设备建立**稳定、低延迟的实时双向通信链路**。 + * 接收来自ESP32的音频流，并利用语音活动检测（VAD）技术精确切分有效的语音片段。 + * 集成并调用自动语音识别（ASR）服务（可配置本地或云端），将语音片段转换为文本。 + * 通过与大型语言模型（LLM）的交互来解析用户意图、生成智能回复，并支持复杂的自然语言理解任务。 + * 管理多轮对话中的上下文信息和用户记忆，以提供连贯的交互体验。 + * 调用文本转语音（TTS）服务，将LLM生成的文本回复合成为自然流畅的语音。 + * 通过一个灵活的**插件系统**执行自定义命令，包括对IoT设备的控制逻辑。 + * 从 `manager-api` 服务获取其详细的运行时操作配置。 + +3. **`manager-api` (管理后端 - Java实现):** + 这是一个基于Java Spring Boot框架构建的应用程序，它为整个系统的管理和配置提供了一套安全的RESTful API。它不仅是 `manager-web` 控制台的后端支撑，也是 `xiaozhi-server` 的配置数据来源。其核心功能包括： + * 为Web控制台提供用户认证（登录、权限验证）和用户账户管理功能。 + * ESP32设备的注册、信息管理以及设备特定配置的维护。 + * 在**MySQL数据库**中持久化存储系统配置，例如用户选择的AI服务提供商、API密钥、设备参数、插件设置等。 + * 提供特定的API端点，供 `xiaozhi-server` 拉取其所需的最新配置。 + * 管理TTS音色选项、处理OTA（Over-The-Air）固件更新流程及相关元数据。 + * 利用 **Redis** 作为高速缓存，存储热点数据（如会话信息、频繁访问的配置），以提升API响应速度和系统整体性能。 + +4. **`manager-web` (Web控制面板 - Vue.js实现):** + 这是一个基于Vue.js构建的单页应用（SPA），为系统管理员提供了一个图形化、用户友好的操作界面。其主要能力包括： + * 便捷地配置 `xiaozhi-server` 所使用的各项AI服务（如ASR、LLM、TTS的提供商切换、参数调整）。 + * 管理平台用户账户、角色分配及权限控制。 + * 管理已注册的ESP32设备及其相关设置。 + * （潜在功能）监控系统运行状态、查看日志、进行故障排查等。 + * 与 `manager-api` 提供的所有后端管理功能进行全面的交互。 + +**高层交互流程概述:** + +* **语音交互主线:** **ESP32设备**捕捉到用户语音后，通过**WebSocket**将音频数据实时传输给**`xiaozhi-server`**。`xiaozhi-server`完成一系列AI处理（VAD、ASR、LLM交互、TTS）后，再通过WebSocket将合成的语音回复发送回ESP32设备进行播放。所有与语音直接相关的实时交互均在此链路完成。 +* **管理配置主线:** 管理员通过浏览器访问**`manager-web`**控制台。`manager-web`通过调用**`manager-api`**提供的**RESTful HTTP接口**来执行各种管理操作（如修改配置、管理用户或设备）。数据以JSON格式在两者间传递。 +* **配置同步:** **`xiaozhi-server`**在启动或特定更新机制触发时，会主动通过HTTP请求从**`manager-api`**拉取其最新的操作配置。这确保了管理员在Web界面上所做的配置更改能够及时有效地应用到核心AI引擎的运行中。 + +这种**前后端分离、核心服务与管理服务分离**的架构设计，使得 `xiaozhi-server`能够专注于高效的实时AI处理任务，而 `manager-api` 和 `manager-web` 则共同提供了一个功能强大且易于使用的管理和配置平台。各组件职责清晰，有利于独立开发、测试、部署和扩展。 + +--- + +## 3. 核心组件深度剖析 + +### 3.1. `xiaozhi-server` (核心AI引擎 - Python实现) + +`xiaozhi-server` 作为系统的智能核心，全权负责处理语音交互、对接各类AI服务以及管理与ESP32设备间的通信。其设计目标是实现高效、灵活且可扩展的语音AI处理能力。 + +* **核心目标:** + * 为ESP32设备提供实时的语音指令处理服务。 + * 深度集成各类AI服务，包括：自动语音识别 (ASR)、大型语言模型 (LLM) 进行自然语言理解 (NLU)、文本转语音 (TTS)、语音活动检测 (VAD)、意图识别 (Intent Recognition) 及对话记忆 (Memory)。 + * 精细管理用户与设备间的对话流程及上下文状态。 + * 基于用户指令，通过插件化机制执行自定义函数及控制物联网 (IoT) 设备。 + * 支持通过 `manager-api`进行动态配置加载与更新。 + +* **核心技术栈:** + * **Python 3:** 作为主要编程语言，Python以其丰富的AI/ML生态库和快速开发特性被选用。 + * **Asyncio:** Python的异步编程框架，是`xiaozhi-server`高性能的关键。它被广泛用于高效处理来自大量ESP32设备的并发WebSocket连接，以及执行与外部AI服务API通信时的非阻塞I/O操作，确保服务器在高并发下的响应能力。 + * **`websockets` 库:** 提供WebSocket服务器的具体实现，支持与ESP32客户端进行全双工实时通信。 + * **HTTP客户端 (如 `aiohttp`, `httpx`):** 用于异步执行HTTP请求，主要目的是从`manager-api`获取配置信息，以及与云端AI服务的API进行交互。 + * **YAML (通常通过 PyYAML 库):** 用于解析本地的 `config.yaml` 配置文件。 + * **FFmpeg (外部依赖):** 在 `app.py` 启动时会进行检查 (`check_ffmpeg_installed()`)。FFmpeg通常用于音频处理和格式转换，例如，确保音频数据符合特定AI服务的要求或进行内部处理。 + +* **关键实现细节:** + + 1. **AI服务提供者模式 (Provider Pattern - `core/providers/`):** + * **设计思想:** 这是`xiaozhi-server`集成不同AI服务的核心设计模式，极大地增强了系统的灵活性和可扩展性。针对每一种AI服务类型（ASR, TTS, LLM, VAD, Intent, Memory, VLLM），都在其对应子目录下定义了一个抽象基类 (ABC, Abstract Base Class)，例如 `core/providers/asr/base.py`。这个基类规定了该类型服务必须实现的通用接口方法（如ASR的 `async def transcribe(self, audio_chunk: bytes) -> str: pass`）。 + * **具体实现:** 各种具体的AI服务提供商或本地模型的实现，则以独立的Python类形式存在（例如 `core/providers/asr/fun_local.py` 实现了本地FunASR的逻辑，`core/providers/llm/openai.py` 实现了与OpenAI GPT模型的对接）。这些具体类继承自相应的抽象基类，并实现其定义的接口。部分提供者还使用DTOs (Data Transfer Objects, 存在于各自的 `dto/` 目录) 来结构化与外部服务交换的数据。 + * **优势:** 使得核心业务逻辑能够以统一的方式调用不同的AI服务，而无需关心其底层具体实现。用户可以通过配置文件轻松切换AI服务后端。添加对新AI服务的支持也变得相对简单，只需实现对应的Provider接口。 + * **动态加载与初始化:** `core/utils/modules_initialize.py` 脚本扮演了工厂的角色。它在服务器启动时，或在接收到配置更新指令时，会根据配置文件中 `selected_module` 及各项服务的具体provider设置，动态地导入并实例化相应的Provider类。 + + 2. **WebSocket通信与连接处理 (`app.py`, `core/websocket_server.py`, `core/connection.py`):** + * **服务器启动与入口 (`app.py`):** + * `app.py` 作为主入口，负责初始化应用环境（如检查FFmpeg、加载配置、设置日志）。 + * 它会生成或加载一个 `auth_key` (JWT密钥)，用于保护特定的HTTP接口（如视觉分析接口 `/mcp/vision/explain`）。若配置中 `manager-api.secret` 为空，则会生成一个UUID作为 `auth_key`。 + * 使用 `asyncio.create_task()` 并发启动 `WebSocketServer` (监听如 `ws://0.0.0.0:8000/xiaozhi/v1/`) 和 `SimpleHttpServer` (监听如 `http://0.0.0.0:8003/xiaozhi/ota/`)。 + * 包含一个 `monitor_stdin()` 协程，用于在某些环境下保持应用存活或处理终端输入。 + * **WebSocket服务器核心 (`core/websocket_server.py`):** + * `WebSocketServer` 类使用 `websockets` 库监听来自ESP32设备的连接请求。 + * 对于每一个成功的WebSocket连接，它都会创建一个**独立的 `ConnectionHandler` 实例** (推测定义于 `core/connection.py`)。这种每个连接一个处理程序实例的设计模式，是实现多设备状态隔离和并发处理的关键，确保每个设备的对话流程和上下文信息互不干扰。 + * 该服务器还提供一个 `_http_response` 方法，允许在同一端口上对非WebSocket升级的HTTP GET请求做出简单响应（例如返回 "Server is running"），便于进行健康检查。 + * **动态配置更新:** `WebSocketServer` 包含一个 `update_config()` 异步方法。此方法使用 `config_lock` (一个 `asyncio.Lock`) 保证配置更新的原子性。它调用 `get_config_from_api()` (可能在 `config_loader.py` 中实现，通过 `manage_api_client.py` 与 `manager-api` 通信) 来获取新的配置。通过 `check_vad_update()` 和 `check_asr_update()` 等辅助函数判断是否需要重新初始化特定的AI模块，避免不必要的开销。更新后的配置会用于重新调用 `initialize_modules()`，从而实现AI服务提供者的热切换。 + + 3. **消息处理与对话流程控制 (`core/handle/` 和 `ConnectionHandler`):** + * `ConnectionHandler` (推测) 作为每个连接的控制中心，负责接收来自ESP32的消息，并根据消息类型或当前对话状态，将其分发给 `core/handle/` 目录下的相应处理模块。这种模块化的处理器设计使得 `ConnectionHandler` 逻辑更清晰，易于扩展。 + * **主要处理模块及其职责:** + * `helloHandle.py`: 处理与ESP32初次连接时的握手协议、设备认证或初始化信息交换。 + * `receiveAudioHandle.py`: 接收音频流数据，调用VAD Provider进行语音活动检测，并将有效的音频片段传递给ASR Provider进行识别。 + * `textHandle.py` / `intentHandler.py`: 获取ASR识别出的文本后，与Intent Provider (可能利用LLM进行意图识别) 和LLM Provider交互，以理解用户意图并生成初步回复或决策。 + * `functionHandler.py`: 当LLM的响应包含执行特定“函数调用”的指令时，此模块负责从插件注册表中查找并执行对应的插件函数。 + * `sendAudioHandle.py`: 将LLM最终生成的文本回复交给TTS Provider合成语音，并将音频流通过WebSocket发送回ESP32。 + * `abortHandle.py`: 处理来自ESP32的中断请求，例如停止当前的TTS播报。 + * `iotHandle.py`, `mcpHandle.py`: 处理与IoT设备控制相关的特定指令或更复杂的模块通信协议 (MCP)。 + + 4. **插件化功能扩展系统 (`plugins_func/`):** + * **设计目的:** 提供一种标准化的方式来扩展语音助手的功能和“技能”，而无需修改核心代码。 + * **实现机制:** + * 各个具体功能以独立的Python脚本形式存在于 `plugins_func/functions/` 目录中（例如 `get_weather.py`, `hass_set_state.py` 用于Home Assistant集成）。 + * `loadplugins.py` 在服务器启动时负责扫描并加载这些插件模块。 + * `register.py` (或插件模块内部的特定装饰器/函数) 可能用于定义每个插件函数的元数据，包括： + * **函数名称 (Function Name):** LLM调用时使用的标识符。 + * **功能描述 (Description):** 供LLM理解此函数的作用。 + * **参数模式 (Parameters Schema):** 通常是一个JSON Schema，详细定义了函数所需的参数、类型、是否必需以及描述。这是LLM能够正确生成函数调用参数的关键。 + * **执行流程:** 当LLM在其思考过程中决定需要调用某个外部工具或函数来获取信息或执行操作时，它会依据预先提供的函数模式生成一个结构化的“函数调用”请求。`xiaozhi-server`中的`functionHandler.py`捕获此请求，从插件注册表中找到对应的Python函数并执行，然后将执行结果返回给LLM，LLM再基于此结果生成最终给用户的自然语言回复。 + + 5. **配置管理 (`config/`):** + * **加载机制:** `config_loader.py` (通过 `settings.py` 被调用) 负责从根目录的 `config.yaml` 文件加载基础配置。 + * **远程配置与合并:** 通过 `manage_api_client.py` (使用如`aiohttp`的库与`manager-api`通信) 可以从`manager-api`服务拉取配置。远程配置通常会覆盖本地 `config.yaml` 中的同名设置，从而实现通过Web界面动态调整服务器行为。 + * **日志系统:** `logger.py` 初始化应用日志系统（可能使用 `loguru` 或对标准 `logging` 模块进行封装，支持通过 `logger.bind(tag=TAG)` 添加标签，便于追踪和过滤）。 + * **静态资源:** `config/assets/` 目录下存放了用于系统提示音的静态音频文件（如设备绑定提示音 `bind_code.wav`、错误提示音等）。 + + 6. **辅助HTTP服务 (`core/http_server.py`):** + * 与WebSocket服务并行运行一个简单的HTTP服务器，用于处理特定的HTTP请求。最主要的功能是为ESP32设备提供OTA (Over-The-Air) 固件更新的下载服务 (通过 `/xiaozhi/ota/` 端点)。此外，也可能承载其他如 `/mcp/vision/explain` (视觉分析) 等工具性HTTP接口。 + +综上所述，`xiaozhi-server` 是一个采用现代Python异步编程模型构建的、高度模块化、配置驱动的AI应用服务器。其精心设计的Provider模式和插件架构赋予了它强大的适应性和扩展性，能够灵活接入不同的AI能力并支持日益增长的功能需求。 + +--- + +### 3.2. `manager-api` (管理后端 - Java Spring Boot实现) + +`manager-api` 组件是使用Java和Spring Boot框架构建的强大后端服务，作为整个`xiaozhi-esp32-server`生态系统的中央行政管理和配置中枢。 + +* **核心目标:** + * 为`manager-web`（Vue.js前端）提供一套安全、稳定、符合RESTful规范的API接口，使得管理员能够便捷地管理用户、设备、系统配置及其他相关资源。 + * 充当`xiaozhi-server`（Python核心AI引擎）的集中化配置数据提供者，允许`xiaozhi-server`实例在启动或运行时获取其最新的操作参数。 + * 持久化存储关键数据，例如：用户账户信息、设备注册详情、AI服务提供商配置（包括API密钥、选定的服务模型等）、TTS音色参数，以及OTA固件版本信息等。 + +* **核心技术栈:** + * **Java 21:** 项目采用的JDK版本，确保了对现代Java特性的支持。 + * **Spring Boot 3:** 作为核心开发框架，极大地简化了独立、生产级别的Spring应用的创建和部署。它提供了自动配置、内嵌Web服务器（默认为Tomcat）、依赖管理等关键功能。 + * **Spring MVC:** Spring框架中用于构建Web应用和RESTful API的模块。 + * **MyBatis-Plus:** 一个对MyBatis进行功能增强的ORM（对象关系映射）框架。它简化了数据库操作，提供了强大的CRUD（增删改查）功能、条件构造器、代码生成器等，并能很好地与Spring Boot集成。 + * **MySQL:** 作为主要的后端关系型数据库，用于存储所有需要持久化的管理数据和配置信息。 + * **Druid (Alibaba Druid):** 一个功能强大的JDBC连接池实现，提供了丰富的监控功能和优秀的性能，用于高效管理数据库连接。 + * **Redis (通过 Spring Data Redis):** 一个高性能的内存数据结构存储，常用于实现数据缓存（例如缓存热点配置数据、用户会话信息），以显著提升API的响应速度。 + * **Apache Shiro:** 一个成熟且易用的Java安全框架，负责处理应用的认证（用户身份验证）和授权（API访问权限控制）需求。 + * **Liquibase:** 一个用于跟踪、管理和应用数据库 schéma（模式）变更的开源工具。它允许开发者以数据库无关的方式定义和版本化数据库结构变更。 + * **Knife4j:** 一个集成了Swagger并增强了UI的API文档生成工具，专为Java MVC框架（尤其是Spring Boot）设计。它能生成美观且易于交互的API文档界面（通常通过 `/xiaozhi/doc.html` 访问）。 + * **Maven:** 用于项目的构建自动化和依赖项管理。 + * **Lombok:** 一个Java库，通过注解自动生成构造函数、getter/setter、equals/hashCode、toString等样板代码，减少冗余。 + * **HuTool / Google Guava:** 提供大量实用工具类，简化常见编程任务。 + * **Aliyun Dysmsapi:** 阿里云短信服务SDK，用于集成发送短信功能（如验证码、通知）。 + +* **关键实现细节:** + + 1. **模块化项目结构 (`modules/` 包):** + * `manager-api` 的核心业务逻辑被清晰地划分到 `src/main/java/xiaozhi/modules/` 目录下的不同模块中。这种按功能领域划分模块的方式（例如 `sys` 负责系统管理，`agent` 负责智能体配置，`device` 负责设备管理，`config` 负责为`xiaozhi-server`提供配置，`security` 负责安全，`timbre` 负责音色管理，`ota` 负责固件升级）极大地提高了代码的可维护性和可扩展性。 + * **各模块内部结构:** 每个业务模块通常遵循经典的三层架构或其变体： + * **Controller (控制层):** 位于 `xiaozhi.modules.[模块名].controller`。 + * **Service (服务层):** 位于 `xiaozhi.modules.[模块名].service`。 + * **DAO/Mapper (数据访问层):** 位于 `xiaozhi.modules.[模块名].dao`。 + * **Entity (实体类):** 位于 `xiaozhi.modules.[模块名].entity`。 + * **DTO (数据传输对象):** 位于 `xiaozhi.modules.[模块名].dto`。 + + 2. **分层架构实现:** + * **Controller层 (`@RestController`):** 这些类使用Spring MVC注解（如 `@GetMapping`, `@PostMapping` 等）来定义API的端点(endpoints)。它们负责接收HTTP请求，将请求体中的JSON数据反序列化为DTO对象，调用相应的Service层方法处理业务逻辑，最后将Service层的返回结果序列化为JSON并作为HTTP响应返回给客户端。 + * **Service层 (`@Service`):** 这些类（通常是接口及其实现类的组合）封装了核心的业务规则和操作流程。它们可能会调用一个或多个DAO/Mapper对象来与数据库交互，并常常使用 `@Transactional` 注解来管理数据库事务的原子性。 + * **Data Access (DAO/Mapper) 层 (MyBatis-Plus Mappers):** 这些是Java接口，继承自MyBatis-Plus提供的 `BaseMapper` 接口。MyBatis-Plus会为这些接口自动提供标准的CRUD方法。对于更复杂的数据库查询，开发者可以通过在Mapper接口中定义方法并使用注解（如 `@Select`, `@Update`）或编写对应的XML映射文件来实现。例如，`UserMapper.selectById(userId)` 会被MyBatis-Plus自动实现。 + * **Entity层 (`@TableName`, `@TableId` 等MyBatis-Plus注解):** 这些POJO（Plain Old Java Objects）类直接映射到数据库中的表结构。Lombok的 `@Data` 注解常用于自动生成getter/setter等。 + * **DTO层:** 用于在各层之间，特别是Controller层与Service层之间，以及API的请求/响应体中传递数据。使用DTO有助于解耦API接口的数据结构与数据库实体的数据结构，使API更稳定。 + + 3. **通用功能与配置 (`common/` 包):** + * `src/main/java/xiaozhi/common/` 包提供了一系列跨模块共享的通用组件和配置： + * **基类:** 如 `BaseDao`, `BaseEntity`, `BaseService`, `CrudService`，为各模块的相应组件提供通用的属性或方法。 + * **全局配置:** 包括 `MybatisPlusConfig` (MyBatis-Plus的配置，如分页插件、数据权限插件等)、`RedisConfig` (Redis连接及序列化配置)、`SwaggerConfig` (Knife4j的配置)、`AsyncConfig` (异步任务执行器配置)。 + * **自定义注解:** 例如 `@LogOperation` 用于通过AOP记录操作日志，`@DataFilter` 可能用于实现数据范围过滤。 + * **AOP切面:** 如 `RedisAspect` 可能用于实现方法级别的缓存逻辑。 + * **全局异常处理:** `RenExceptionHandler` (使用 `@ControllerAdvice` 注解) 捕获应用中抛出的特定或所有异常 (如自定义的 `RenException`)，并返回统一格式的JSON错误响应给客户端。`ErrorCode` 定义了标准化的错误码。 + * **工具类:** 提供了日期转换、JSON处理(Jackson)、IP地址获取、HTTP上下文操作、统一结果封装 (`Result` 类)等多种实用工具。 + * **校验工具:** `ValidatorUtils` 和 `AssertUtils` 用于简化参数校验逻辑。 + * **XSS防护:** `XssFilter` 等组件用于防止跨站脚本攻击。 + * **MyBatis-Plus自动填充:** `FieldMetaObjectHandler` 用于在执行插入或更新数据库操作时，自动填充如 `createTime`, `updateTime` 等公共字段。 + + 4. **安全机制 (Apache Shiro):** + * Shiro的配置（通常在 `modules/security/config/` 或 `common/config/` 下）定义了如何进行用户认证和授权。 + * **Realms (域):** 自定义的Shiro Realm类负责从数据库中查询用户信息（用户名、密码、盐值）进行身份验证，以及获取用户的角色和权限信息用于授权决策。 + * **Filters (过滤器):** Shiro过滤器链被应用于保护API端点，确保只有经过认证且拥有足够权限的用户才能访问特定资源。 + * **Session/Token Management:** Shiro管理用户会话。对于RESTful API，可能结合OAuth2或JWT等令牌机制实现无状态认证。 + + 5. **数据库版本控制 (Liquibase):** + * 数据库的表结构、索引、初始数据等变更，都通过Liquibase的 `changelog` 文件（通常是XML格式）进行定义和版本化管理。当应用启动时，Liquibase会自动检查并应用必要的数据库结构更新，确保开发、测试和生产环境数据库结构的一致性。 + +`manager-api` 通过这些精心选择的技术和设计模式，构建了一个功能全面、结构清晰、安全可靠且易于维护和扩展的Java后端服务。其模块化的设计特别适合处理具有多种管理功能需求的复杂系统。 + +--- + +### 3.3. `manager-web` (Web管理前端 - Vue.js实现) + +`manager-web` 组件是一个采用 Vue.js 2 框架构建的单页应用 (SPA - Single Page Application)。它为系统管理员提供了一个功能丰富、交互友好的图形用户界面，用于全面管理和配置 `xiaozhi-esp32-server` 生态系统。 + +* **核心目标:** + * 提供一个基于Web的集中式控制面板，供管理员进行系统操作与监控。 + * 实现对 `xiaozhi-server` 中AI服务提供商（ASR、LLM、TTS等）及其相关API密钥或许可配置的便捷管理。 + * 支持用户账户、角色及权限的精细化管理。 + * 提供ESP32设备的注册、配置及状态查看功能。 + * 允许管理员自定义TTS音色、管理OTA固件更新流程、调整系统级参数及字典数据等。 + * 作为 `manager-api` 所暴露各项功能的图形化交互前端。 + +* **核心技术栈:** + * **Vue.js 2:** 一个渐进式的JavaScript框架，用于构建用户界面。其核心特性包括声明式渲染、组件化系统、数据绑定等，非常适合构建复杂的SPA。 + * **Vue CLI (`@vue/cli-service`):** Vue.js的官方命令行工具，用于项目的快速搭建、开发服务器的运行（支持热模块替换HMR）、以及生产环境构建打包（内部集成并配置了Webpack）。 + * **Vue Router (`vue-router`):** Vue.js官方的路由管理器。它负责在SPA内部实现不同“页面”或视图组件之间的导航切换，而无需重新加载整个HTML页面，提供了流畅的用户体验。 + * **Vuex (`vuex`):** Vue.js官方的状态管理模式和库。它充当了应用中所有组件的“中央数据存储”，用于管理全局共享状态（例如当前登录用户信息、设备列表、应用配置等），特别适用于大型复杂应用。 + * **Element UI (`element-ui`):** 一个广受欢迎的基于Vue 2.0的桌面端UI组件库。它提供了大量预先设计和实现的组件（如表单、表格、对话框、导航菜单、按钮、提示等），帮助开发者快速构建出专业且一致的用户界面。 + * **JavaScript (ES6+):** 前端逻辑实现的主要编程语言，利用其现代特性进行开发。 + * **SCSS (Sassy CSS):** 一种CSS预处理器，它为CSS增加了变量、嵌套规则、混合(Mixin)、继承等高级特性，使得CSS代码更易于组织、维护和复用。 + * **HTTP客户端 (Flyio 或 Axios 通过 `vue-axios`):** 用于在浏览器端向 `manager-api` 后端发起异步HTTP（AJAX）请求，以获取数据或提交操作。 + * **Webpack:** 一个强大的模块打包工具（由Vue CLI在底层管理和配置）。它将项目中的各种资源（JavaScript文件、CSS、图片、字体等）视为模块，并将它们打包成浏览器可识别的静态文件。 + * **Workbox (通过 `workbox-webpack-plugin`):** Google开发的一个库，用于简化Service Worker的编写和PWA（Progressive Web App - 渐进式Web应用）的实现。它可以帮助生成Service Worker脚本，实现资源缓存、离线访问等功能。 + * **Opus库 (`opus-decoder`, `opus-recorder`):** 这些音频处理库表明前端可能具备一些直接在浏览器中处理Opus格式音频的能力，例如：用于测试麦克风输入、允许管理员录制自定义音频片段（可能用于TTS音色样本或语音指令测试），或播放在管理界面中预览的Opus编码音频。 + +* **关键实现细节:** + + 1. **单页应用 (SPA) 结构:** + * 整个前端应用加载一个主HTML文件 (`public/index.html`)。后续的所有页面切换和内容更新都在客户端由Vue Router动态完成，无需每次都从服务器请求新的HTML页面。这种模式能提供更快的页面加载速度和更流畅的交互体验。 + + 2. **组件化架构 (Component-Based Architecture):** + * 用户界面由一系列可复用的Vue组件 (`.vue` 单文件组件) 构成，形成一个组件树。这种方式提高了代码的模块化程度、可维护性和复用性。 + * **`src/main.js`:** 应用的入口JS文件。它负责创建和初始化根Vue实例，注册全局插件（如Vue Router, Vuex, Element UI），并把根Vue实例挂载到 `public/index.html` 中的某个DOM元素上（通常是 `#app`）。 + * **`src/App.vue`:** 应用的根组件。它通常定义了应用的基础布局结构（如包含导航栏、侧边栏、主内容区），并通过 `` 标签来显示当前路由匹配到的视图组件。 + * **视图组件 (`src/views/`):** 这些组件代表了应用中的各个“页面”或主要功能区（例如 `Login.vue` 登录页, `DeviceManagement.vue` 设备管理页, `UserManagement.vue` 用户管理页, `ModelConfig.vue` 模型配置页）。它们通常由Vue Router直接映射。 + * **可复用UI组件 (`src/components/`):** 包含了在不同视图之间共享的、更小粒度的UI组件（例如 `HeaderBar.vue` 顶部导航栏, `AddDeviceDialog.vue` 添加设备对话框, `AudioPlayer.vue` 音频播放器组件）。 + + 3. **客户端路由 (`src/router/index.js`):** + * Vue Router在此文件中进行配置，定义了应用的路由表。每个路由规则将一个特定的URL路径映射到一个视图组件。 + * 常常包含**导航守卫 (Navigation Guards)**，例如 `beforeEach` 守卫，用于在路由跳转前执行逻辑，如检查用户是否已登录，如果未登录则重定向到登录页面，从而保护需要认证才能访问的页面。 + + 4. **状态管理 (`src/store/index.js`):** + * Vuex被用来构建一个集中的状态管理中心（Store）。这个Store包含了： + * **State:** 存储应用级别的共享数据（例如，当前登录用户的详细信息、从API获取的设备列表、系统配置等）。 + * **Getters:** 类似于Vue组件中的计算属性，用于从State派生出一些状态值，方便组件使用。 + * **Mutations:** **唯一**可以同步修改State中数据的方法。它们必须是同步函数。 + * **Actions:** 用于处理异步操作（如API调用）或封装多个Mutation提交。Actions会调用API，获取数据后，通过 `commit` 一个或多个Mutation来更新State。 + * 例如，用户登录时，一个名为 `login` 的Action可能会被调用，它会向后端API发送登录请求，成功后获取到用户信息和token，然后 `commit` 一个名为 `SET_USER_INFO` 的Mutation来更新State中的用户信息和token。 + + 5. **API通信 (`src/apis/`):** + * 与 `manager-api` 后端的所有HTTP通信逻辑被封装在 `src/apis/` 目录下，通常会按照后端API的模块进行组织（例如 `src/apis/module/agent.js`, `src/apis/module/device.js`）。 + * 每个模块导出一系列函数，每个函数对应一个具体的API请求。这些函数内部使用配置好的HTTP客户端实例 (例如，在 `src/apis/api.js` 或 `src/apis/httpRequest.js` 中统一配置Axios或Flyio实例，可能包含设置请求基地址、请求/响应拦截器等)。 + * **拦截器 (Interceptors):** HTTP客户端的请求拦截器常用于在每个请求发送前自动添加认证令牌（如JWT）；响应拦截器则可用于全局处理API错误（如权限不足、服务器错误）或对响应数据进行预处理。 + + 6. **样式与资源 (`src/styles/`, `src/assets/`):** + * `Element UI` 提供了基础的组件样式。 + * `src/styles/global.scss` 文件用于定义全局共享的SCSS样式、变量、混合(Mixin)等。 + * Vue单文件组件内部的 `