# solon-xiaozhi **Repository Path**: weirdor_admin/solon-xiaozhi ## Basic Information - **Project Name**: solon-xiaozhi - **Description**: solon 服务端版小智 AI 后台服务 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-29 - **Last Updated**: 2026-07-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Solon-XiaoZhi > 基于 Solon 框架构建的 IoT 智能语音交互服务端，为嵌入式设备提供完整的 **ASR → LLM → TTS** 实时对话管道。 [![Java](https://img.shields.io/badge/Java-21-orange)](https://openjdk.org/projects/jdk/21/) [![Solon](https://img.shields.io/badge/Solon-4.0.3-blue)](https://solon.noear.org/) [![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE) --- ## 目录 - [项目简介](#项目简介) - [系统架构](#系统架构) - [核心特性](#核心特性) - [技术栈](#技术栈) - [模块结构](#模块结构) - [AI 提供商支持](#ai-提供商支持) - [设备通信协议](#设备通信协议) - [音频处理管道](#音频处理管道) - [环境要求](#环境要求) - [快速开始](#快速开始) - [配置说明](#配置说明) - [服务端口](#服务端口) - [接口文档](#接口文档) - [管理后台功能](#管理后台功能) - [项目结构](#项目结构) --- ## 项目简介 Solon-XiaoZhi 是基于 Java/Solon 框架的 IoT 智能语音交互服务端，面向 IoT 智能硬件（如 ESP32 开发板）提供云端 AI 语音交互能力。设备通过 **WebSocket** 或 **MQTT + UDP** 协议接入服务端，实现低延迟的实时语音对话。 **典型应用场景：** - 智能音箱 / AI 陪伴机器人 - 智能家居语音中控 - 儿童教育对话设备 - 车载语音助手 --- ## 系统架构 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ IoT 设备 (ESP32 等) │ └───────────────────────────┬─────────────────────────────────────────┘ │ WebSocket / MQTT + UDP ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ xiaozhi-api (设备接入层) │ │ ┌──────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │ │ │ WebSocket │ │ MQTT Server │ │ UDP Audio Server │ │ │ │ Endpoint │ │ (mica-mqtt) │ │ (Opus + AES-CTR 加密) │ │ │ └──────┬───────┘ └──────┬───────┘ └─────────────┬─────────────┘ │ │ └──────────────────┼────────────────────────┘ │ │ ▼ │ │ DeviceMessageDispatcher (消息分发) │ └────────────────────────────┬────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ xiaozhi-voice (语音交互引擎) │ │ │ │ ┌─────────┐ ┌─────────────┐ ┌──────────┐ ┌────────────┐ │ │ │ VAD │───▶│ ASR 识别 │───▶│ LLM 推理 │───▶│ TTS 合成 │ │ │ │(Silero) │ │ (多提供商) │ │(多提供商) │ │ (多提供商) │ │ │ └─────────┘ └─────────────┘ └──────────┘ └────────────┘ │ │ ▲ │ │ │ │ ConversationSession ▼ │ │ │ (会话状态 / 上下文 / 打断) Opus 编码下发 │ │ └───────────────────────────────────────────────────────── │ └─────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ xiaozhi-modules (业务层) │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────┐ ┌──────┐ │ │ │ module-ai │ │ module-iot │ │module-system│ │module- │ │module│ │ │ │(AI配置/角色)│ │(设备/固件) │ │(用户/权限) │ │ ums │ │ -oss │ │ │ └────────────┘ └────────────┘ └────────────┘ └────────┘ └──────┘ │ └─────────────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────┐ │ MySQL │ Redis │ OSS │ └──────────────────────────────┘ ``` --- ## 核心特性 - **完整对话管道**：ASR → LLM → TTS 全链路流式处理，支持实时打断 - **多传输协议**：WebSocket 与 MQTT + UDP 双模式，适配不同硬件能力 - **多 AI 提供商**：插件化 Provider 架构，支持 10+ 种 ASR/TTS/LLM 服务商 - **音频处理引擎**：Opus 编解码 + Silero VAD + WebRTC AEC3 回声消除 - **MCP 工具集成**：基于 Solon AI MCP 协议，支持 Function Call 扩展 - **设备全生命周期**：OTA 升级、激活码绑定、固件管理、在线状态监控 - **AI 角色系统**：可配置对话角色、Prompt 模板、音色参数 - **知识库 & 记忆**：支持知识库文档检索与对话记忆管理 - **安全认证**：Sa-Token + Redis 会话管理，RBAC 权限模型 - **虚拟线程**：基于 JDK 21 Virtual Threads，高并发低资源占用 --- ## 技术栈 | 类别 | 技术 | 版本 | |------|------|------| | **语言** | Java（Virtual Threads） | 21 | | **Web 框架** | Solon | 4.0.3 | | **构建工具** | Apache Maven | 3.8+ | | **ORM** | MyBatis-Plus + MyBatis-Plus-Join | 3.5.17 / 1.5.9 | | **数据库** | MySQL | 8.0+ | | **连接池** | HikariCP | 5.1.0 | | **缓存** | Redis（Redisson） | - | | **认证鉴权** | Sa-Token | 1.45.0 | | **MQTT Broker** | mica-mqtt | 2.6.8 | | **网络框架** | Netty | 4.1.118.Final | | **AI 框架** | Solon AI + Solon AI MCP | 4.0.3 | | **VAD 推理** | ONNX Runtime（Silero VAD） | 1.23.2 | | **Opus 编解码** | Concentus（纯 Java） | 1.0.2 | | **回声消除** | WebRTC AEC3（webrtc-java） | 0.14.0 | | **文件存储** | x-file-storage | 2.3.0 | | **接口文档** | Knife4j（OpenAPI 3.0） | - | | **日志** | Logback（solon-logging） | - | --- ## 模块结构 ``` solon-xiaozhi/ ├── xiaozhi-dependencies # BOM 依赖版本统一管理（所有第三方版本锁定于此） ├── xiaozhi-common # 通用基础设施 │ ├── annotation/ # 自定义注解 │ ├── config/ # 全局配置（异常处理、MetaHandler 等） │ ├── entity/ # 实体基类（BaseEntity / SysBaseEntity） │ ├── enums/ # 通用枚举 │ ├── exception/ # 统一异常体系 │ ├── param/ # 通用参数（分页等） │ ├── result/ # 统一响应封装（R） │ └── util/ # 工具类 │ ├── xiaozhi-voice # 语音交互引擎（核心模块） │ ├── audio/ # 音频处理层 │ │ ├── aec/ # AEC 回声消除 │ │ ├── opus/ # Opus 编解码 │ │ ├── vad/ # VAD 语音活动检测（Silero） │ │ └── handler/ # 音频事件监听 │ ├── speech/ # 语音管道层 │ │ ├── asr/model/ # ASR Provider 实现（10 种） │ │ ├── llm/model/ # LLM Provider 实现（4 种） │ │ ├── tts/model/ # TTS Provider 实现（10 种） │ │ └── support/ # 音频格式转换、流式工具 │ ├── session/ # 会话管理（ConversationSession / AI 配置加载） │ └── mcp/ # MCP 工具集成（Function Call） │ ├── xiaozhi-api # 设备端服务（可独立部署） │ ├── controller/ # 设备 API（OTA / 激活 / 用户认证） │ ├── transport/ # 传输层 │ │ ├── websocket/ # WebSocket 端点 & 会话管理 │ │ ├── mqtt/ # MQTT 消息端点 & 会话注册 │ │ └── udp/ # UDP 音频服务（AES-CTR 加密） │ ├── ota/ # OTA 升级逻辑 │ └── service/ # 设备业务服务 │ ├── xiaozhi-admin # 管理后台服务（可独立部署） │ ├── ai/controller/ # AI 配置管理（LLM/TTS/ASR/角色/知识库） │ ├── iot/controller/ # IoT 设备管理（设备/固件/激活/OTA 报告） │ ├── auth/ # 管理员认证（登录/改密） │ ├── system/ # 系统管理（配置/用户/角色/菜单） │ └── config/ # DocConfig（Knife4j 文档配置） │ └── xiaozhi-modules/ # 业务模块聚合 ├── xiaozhi-module-ai # AI 能力（配置/角色/知识库/消息/音乐/模板） ├── xiaozhi-module-iot # IoT（设备/固件/OTA 记录） ├── xiaozhi-module-system # 系统（用户/角色/权限/菜单/配置） ├── xiaozhi-module-ums # 终端用户（注册/登录/设备绑定） └── xiaozhi-module-oss # 对象存储（多平台文件上传/访问） ``` --- ## AI 提供商支持 ### ASR（语音识别） | 提供商 | 实现类 | 说明 | |--------|--------|------| | 阿里云 DashScope | `AliyunAsrProvider` | Qwen3-ASR-Flash，OpenAI 兼容协议 | | 阿里云 NLS | `AliyunNlsAsrProvider` | 智能语音交互标准版 | | FunASR | `FunAsrProvider` | 开源离线/在线 ASR | | OpenAI | `OpenAiAsrProvider` | Whisper API | | Deepgram | `DeepgramAsrProvider` | 高精度英文 ASR | | 腾讯云 | `TencentAsrProvider` | 腾讯云语音识别 | | 火山引擎 | `VolcengineAsrProvider` | 字节跳动语音识别 | | 讯飞 | `XunfeiAsrProvider` | 科大讯飞语音转写 | | Vosk | `VoskAsrProvider` | 离线轻量 ASR | ### LLM（大语言模型） | 提供商 | 实现类 | 说明 | |--------|--------|------| | OpenAI 兼容 | `OpenAiLlmProvider` | DeepSeek / OpenAI / 通义千问等 | | 智谱 AI | `ZhipuLlmProvider` | GLM 系列 | | Coze | `CozeLlmProvider` | 字节扣子 Bot | | Dify | `DifyLlmProvider` | Dify 平台 | ### TTS（语音合成） | 提供商 | 实现类 | 说明 | |--------|--------|------| | 阿里云 CosyVoice | `AliyunTtsProvider` | DashScope 流式合成 | | 阿里云 NLS | `AliyunNlsTtsProvider` | 智能语音交互标准版 | | Edge TTS | `EdgeTtsProvider` | 微软免费 TTS（降级方案） | | OpenAI | `OpenAiTtsProvider` | OpenAI TTS API | | ElevenLabs | `ElevenLabsTtsProvider` | 高保真语音克隆 | | Minimax | `MinimaxTtsProvider` | 海螺 AI 语音 | | Deepgram | `DeepgramTtsProvider` | 低延迟英文 TTS | | 腾讯云 | `TencentTtsProvider` | 腾讯云语音合成 | | 火山引擎 | `VolcengineTtsProvider` | 字节跳动语音合成 | | 讯飞 | `XunfeiTtsProvider` | 科大讯飞语音合成 | > 所有 Provider 通过工厂模式（`AsrProviderFactory` / `LlmProviderFactory` / `TtsProviderFactory`）按数据库配置动态实例化，支持运行时切换。 --- ## 设备通信协议 ### 模式一：WebSocket 适用于网络环境稳定、硬件资源充足的设备。信令与音频复用同一 WebSocket 连接。 ``` 设备 ──── ws://host:8003/ws/xiaozhi/v1/ ────▶ 服务端 ◀──── JSON 信令 + Opus 音频帧 ────▶ ``` ### 模式二：MQTT + UDP（推荐） 适用于低带宽、弱网环境。MQTT 负责信令控制，UDP 负责音频流传输（AES-CTR 加密）。 ``` 设备 ──── mqtt://host:1885 ────▶ 服务端 (信令: hello/listen/iot/abort) 设备 ──── udp://host:1884 ────▶ 服务端 (音频: Opus 帧 + AES-CTR) ``` ### 设备接入流程 ``` 1. 设备发送 OTA 请求 → 获取服务端连接参数（WebSocket/MQTT 地址、端口、认证信息） 2. 若设备未绑定 → 服务端生成激活码 → 设备屏幕显示 / 语音播报 3. 用户在前端输入激活码 → 完成设备绑定 4. 设备建立 WebSocket/MQTT 连接 → 发送 hello 消息 → 服务端返回配置 5. 进入语音对话循环：listen(start/stop) → ASR → LLM → TTS → 音频下发 ``` --- ## 音频处理管道 ``` ┌──────────────────────────────────────────────────────────────┐ │ 上行（设备 → 服务端） │ │ │ │ Opus 帧 → OpusDecoder → PCM 16kHz/16bit │ │ → AEC 回声消除（WebRTC AEC3） │ │ → Silero VAD（语音活动检测） │ │ → AudioAggregator（聚合完整语句） │ │ → ASR Provider（语音 → 文本） │ └──────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────┐ │ 下行（服务端 → 设备） │ │ │ │ LLM 流式输出 → 分句 → TTS Provider（文本 → 音频） │ │ → PCM → OpusEncoder → Opus 帧 │ │ → AudioRateController（播放速率控制） │ │ → WebSocket / UDP 下发 │ └──────────────────────────────────────────────────────────────┘ ``` **关键参数：** - 采样率：16000 Hz - 位深度：16 bit - 声道：单声道（Mono） - Opus 帧长：60ms（960 samples） - VAD 模型：Silero VAD v5（ONNX Runtime 推理） --- ## 环境要求 | 依赖 | 最低版本 | 说明 | |------|----------|------| | JDK | 21 | 必须，使用虚拟线程 | | Maven | 3.8 | 构建工具 | | MySQL | 8.0 | 主数据库 | | Redis | 6.0 | 会话缓存 & Sa-Token 存储 | --- ## 快速开始 ### 1. 克隆项目 ```bash git clone cd solon-xiaozhi ``` ### 2. 初始化数据库 ```sql CREATE DATABASE `xiaozhi-new` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; ``` 导入初始化脚本： ```bash mysql -u root -p xiaozhi-new < xiaozhi-api/src/main/resources/db/split-ai-model-config.sql ``` ### 3. 修改配置 编辑开发环境配置文件： ```bash # 设备端服务配置 vim xiaozhi-api/src/main/resources/app-dev.yml # 管理后台配置 vim xiaozhi-admin/src/main/resources/app-dev.yml ``` 需修改的关键配置： ```yaml # 数据库连接 solon.dataSources: db1!: jdbcUrl: jdbc:mysql://localhost:3306/xiaozhi-new?useUnicode=true&characterEncoding=utf8 username: root password: your_password # Redis solon.redis: server: "localhost:6379" password: your_redis_password ``` ### 4. 编译构建 ```bash mvn clean install -DskipTests ``` ### 5. 启动服务 **管理后台**（端口 8001）： ```bash cd xiaozhi-admin && mvn solon:run ``` **设备端服务**（端口 8002 / 8003 / 1885 / 1884）： ```bash cd xiaozhi-api && mvn solon:run ``` ### 6. 验证 - 管理后台文档：http://localhost:8001/api/doc.html - 设备 OTA 接口：`POST http://localhost:8002/api/device/ota` --- ## 配置说明 ### 配置文件层级 ``` app.yml # 主配置（所有环境共享） app-dev.yml # 开发环境（solon.env=dev 时生效） app-prod.yml # 生产环境（solon.env=prod 时生效） ``` ### 核心配置项 | 配置路径 | 说明 | 默认值 | |----------|------|--------| | `server.port` | HTTP 服务端口 | 8001(admin) / 8002(api) | | `server.contextPath` | 全局请求前缀 | `/api` | | `server.websocket.port` | WebSocket 端口 | 8003 | | `xiaozhi.transport.mode` | 传输模式 | `mqtt` | | `xiaozhi.api.ota.mqtt-port` | MQTT 端口 | 1885 | | `xiaozhi.api.ota.udp-port` | UDP 端口 | 1884 | | `xiaozhi.api.ota.activation-expire-minutes` | 激活码有效期 | 10 分钟 | | `sa-token.timeout` | Token 有效期 | 30 天 | ### AI 配置 AI 模型配置存储在数据库中（`ai_llm_config` / `ai_tts_config` / `ai_asr_config` 表），通过管理后台动态管理，无需修改配置文件。 --- ## 服务端口 | 服务 | 端口 | 协议 | 说明 | |------|------|------|------| | xiaozhi-admin | 8001 | HTTP | 管理后台 API | | xiaozhi-api | 8002 | HTTP | 设备端 API（OTA / 激活） | | WebSocket | 8003 | WS | 设备语音通道 | | MQTT Broker | 1885 | MQTT | 设备信令通道 | | UDP Audio | 1884 | UDP | 设备音频流 | --- ## 接口文档 启动 `xiaozhi-admin` 后访问 Knife4j 文档： ``` http://localhost:8001/api/doc.html ``` 支持在线调试、Token 自动注入、接口分组浏览。 --- ## 管理后台功能 | 模块 | 功能 | |------|------| | **AI 配置** | LLM / TTS / ASR 模型配置、提供商管理 | | **AI 角色** | 对话角色、Prompt 模板、音色绑定 | | **知识库** | 知识库创建、文档上传与检索 | | **对话消息** | 对话记录查看、统计 | | **记忆管理** | 对话记忆查看与管理 | | **MCP 工具** | MCP 工具排除配置 | | **设备管理** | 设备列表、在线状态、绑定关系 | | **固件管理** | 固件版本上传、OTA 推送 | | **激活管理** | 激活码生成记录、有效期管理 | | **系统管理** | 用户、角色、权限、菜单、系统配置 | | **认证** | 管理员登录、密码修改 | --- ## 项目结构 ``` solon-xiaozhi/ ├── pom.xml # 父 POM（继承 solon-parent 4.0.3） ├── xiaozhi-dependencies/pom.xml # BOM 版本锁定 ├── xiaozhi-common/ # 通用基础设施 ├── xiaozhi-voice/ # 语音交互引擎 ├── xiaozhi-api/ # 设备端服务（启动类: App.java） ├── xiaozhi-admin/ # 管理后台服务（启动类: Admin.java） └── xiaozhi-modules/ # 业务模块 ├── xiaozhi-module-ai/ # AI 能力 ├── xiaozhi-module-iot/ # IoT 设备 ├── xiaozhi-module-system/ # 系统管理 ├── xiaozhi-module-ums/ # 终端用户 └── xiaozhi-module-oss/ # 对象存储 ``` --- ## 技术依赖 - [Solon](https://solon.noear.org/) — Java 应用开发框架 - [mica-mqtt](https://gitee.com/dromara/mica-mqtt) — MQTT 服务端/客户端框架 - [x-file-storage](https://x-file-storage.xuyanwu.cn/) — 文件存储框架