xiaozhi_server

小智（xiaozhi）AI 语音助手服务端——为 ESP32 智能硬件提供实时语音交互后端，支持多 ASR / LLM / TTS 提供商切换、WebSocket 低延迟通信、IoT 设备控制与 Web 管理后台。

✨ 功能特性

• 实时语音交互：WebSocket 全双工通信，VAD 语音活动检测 → ASR 语音识别 → LLM 对话 → TTS 语音合成，端到端低延迟
• 多 AI 提供商可插拔：Provider 模式设计，ASR / LLM / TTS / VAD / 记忆 / 意图识别均可通过配置文件切换，支持云端 API 与本地模型
• ASR 支持：FunASR（本地 SenseVoiceSmall）、火山豆包、腾讯云、阿里云、百度、OpenAI / Groq、Sherpa-ONNX 等
• LLM 支持：阿里通义千问、火山豆包、DeepSeek、智谱 ChatGLM（glm-4-flash 免费）、Ollama、Dify、Gemini、Coze、FastGPT、Xinference、LM Studio、Home Assistant 等
• TTS 支持：EdgeTTS（免费）、火山豆包、阿里云 CosyVoice、腾讯云、FishSpeech、GPT-SoVITS、Minimax、OpenAI、硅基流动、Coze、自定义接口等 20+ 种
• 意图识别与工具调用：支持 function_call 与 intent_llm 两种模式，可调用天气查询、新闻获取、音乐播放、角色切换、Home Assistant 智能家居控制等插件
• 对话记忆：支持 nomem（无记忆）、mem_local_short（本地短期记忆）、mem0ai（云端长期记忆）三种模式
• Web 管理后台：Vue.js 前端 + Spring Boot 后端，提供用户管理、设备管理、AI 模型配置、TTS 音色管理、OTA 固件升级、系统参数等可视化管理
• OTA 固件升级：内置 HTTP 服务为 ESP32 设备提供固件下载与 OTA 升级流程
• MCP 协议支持：支持 MCP 接入点、MCP 视觉分析、设备 MCP 等多种 MCP 集成方式
• 声纹识别：支持说话人声纹识别，可区分不同用户
• 多语言：ASR 支持中文、粤语、英语、日语、韩语（取决于所选提供商）
• Docker 部署：提供 docker-compose 一键部署，支持仅核心服务或全模块部署

🛠 技术栈

组件	技术	端口
核心 AI 引擎	Python 3 + asyncio + websockets	8000（WebSocket）/ 8003（HTTP）
管理后端	Java 21 + Spring Boot 3 + MyBatis-Plus + Apache Shiro	8002
管理前端	Vue.js 2 + Vuex + Vue Router + Element UI	8001
数据库	MySQL（管理后端）	—
缓存	Redis	—
数据库版本控制	Liquibase	—
API 文档	Knife4j（Swagger）	—
本地 ASR 模型	FunASR + SenseVoiceSmall	—
VAD 模型	Silero VAD	—
部署	Docker / docker-compose	—

核心 Python 依赖

类别	库	版本
WebSocket	websockets	14.2
异步 HTTP	aiohttp / httpx	3.9.3 / 0.27.2
深度学习	torch / torchaudio	2.2.2
语音识别	funasr / modelscope	1.2.3 / 1.23.2
VAD	silero_vad	5.1.2
音频处理	pydub / opuslib_next	0.25.1 / 1.1.2
配置	ruamel.yaml / pyyml	0.18.10 / 0.0.2
日志	loguru	0.7.3
LLM SDK	openai / cozepy / dashscope / zhipuai	1.61.0 / 0.12.0 / 1.23.1
TTS	edge_tts	7.0.0
记忆	mem0ai	0.1.62
MCP	mcp / mcp-proxy	1.8.1 / 0.8.0
其他	PyJWT / redis / psutil / Jinja2	2.8.0 / ≥4.6.0 / 7.0.0 / 3.1.6

📁 项目结构

xiaozhi_server/
├── main/
│   ├── xiaozhi-server/              # 核心 AI 引擎（Python）
│   │   ├── app.py                    # 主入口：初始化、启动 WebSocket 与 HTTP 服务
│   │   ├── config.yaml               # 默认配置文件（所有 AI 提供商、插件、端口等）
│   │   ├── requirements.txt          # Python 依赖
│   │   ├── docker-compose.yml        # 核心服务 Docker 编排
│   │   ├── docker-compose_all.yml    # 全模块 Docker 编排（含管理后台）
│   │   ├── agent-base-prompt.txt     # Agent 基础提示词
│   │   ├── config/
│   │   │   ├── config_loader.py      # 配置加载与远程配置合并
│   │   │   ├── manage_api_client.py  # 从 manager-api 拉取配置
│   │   │   ├── settings.py           # 全局设置
│   │   │   ├── logger.py             # 日志系统（loguru）
│   │   │   └── assets/               # 系统提示音（绑定码、唤醒词、错误提示等）
│   │   ├── core/
│   │   │   ├── websocket_server.py   # WebSocket 服务器，监听 ESP32 连接
│   │   │   ├── http_server.py        # HTTP 服务（OTA 固件下载、视觉分析接口）
│   │   │   ├── connection.py         # 连接处理器，每个设备独立实例
│   │   │   ├── auth.py               # 认证与 JWT
│   │   │   ├── handle/               # 消息处理模块
│   │   │   │   ├── helloHandle.py    # 握手与设备初始化
│   │   │   │   ├── receiveAudioHandle.py  # 音频接收 + VAD + ASR
│   │   │   │   ├── textHandle.py     # 文本处理与 LLM 交互
│   │   │   │   ├── intentHandler.py  # 意图识别
│   │   │   │   ├── sendAudioHandle.py     # TTS 合成与音频下发
│   │   │   │   ├── abortHandle.py    # 中断处理（停止 TTS）
│   │   │   │   └── reportHandle.py   # 设备状态报告
│   │   │   ├── providers/            # AI 服务提供者（Provider 模式）
│   │   │   │   ├── asr/              # 语音识别：FunASR/豆包/腾讯/阿里/百度/OpenAI/Sherpa
│   │   │   │   ├── llm/              # 大模型：通义/豆包/DeepSeek/ChatGLM/Ollama/Dify/Gemini/Coze 等
│   │   │   │   ├── tts/              # 语音合成：Edge/豆包/阿里/腾讯/FishSpeech/GPT-SoVITS 等 20+
│   │   │   │   ├── vad/              # 语音活动检测：Silero
│   │   │   │   ├── intent/           # 意图识别：nointent/intent_llm/function_call
│   │   │   │   ├── memory/           # 对话记忆：nomem/mem_local_short/mem0ai
│   │   │   │   ├── vllm/             # 视觉语言大模型
│   │   │   │   └── tools/            # 工具执行：IoT/MCP/插件统一调度
│   │   │   ├── api/                  # HTTP API 处理器（OTA、视觉分析）
│   │   │   └── utils/                # 工具函数（ASR/LLM/TTS 封装、缓存、对话管理等）
│   │   ├── plugins_func/
│   │   │   ├── functions/            # 插件函数：天气/新闻/音乐/角色切换/Home Assistant
│   │   │   ├── loadplugins.py        # 插件加载器
│   │   │   └── register.py           # 插件注册
│   │   ├── models/                   # 本地模型文件
│   │   │   ├── SenseVoiceSmall/      # FunASR 语音识别模型
│   │   │   └── snakers4_silero-vad/ # Silero VAD 模型
│   │   ├── data/                     # 运行时数据（用户配置 .config.yaml 等）
│   │   └── test/                     # 测试页面（WebSocket 音频测试）
│   ├── manager-api/                   # 管理后端（Java Spring Boot）
│   │   ├── pom.xml                   # Maven 配置
│   │   └── src/main/java/xiaozhi/
│   │       ├── AdminApplication.java # Spring Boot 启动类
│   │       ├── common/                # 通用组件（配置、工具、异常、安全、基类）
│   │       └── modules/
│   │           ├── agent/             # 智能体管理（配置、模板、声纹、对话历史）
│   │           ├── device/            # 设备管理（注册、绑定、OTA 升级）
│   │           ├── model/             # 模型配置（AI 提供商、模型参数、音色）
│   │           ├── config/            # 系统配置（为 xiaozhi-server 提供配置）
│   │           ├── security/          # 安全认证（Shiro + OAuth2 + JWT）
│   │           ├── sys/               # 系统管理（用户、字典、参数、服务端管理）
│   │           ├── timbre/            # 音色管理
│   │           └── sms/               # 短信服务（阿里云）
│   ├── manager-web/                   # 管理前端（Vue.js）
│   │   ├── src/
│   │   │   ├── views/                 # 页面：登录/注册/首页/设备/模型/用户/OTA/参数等
│   │   │   ├── components/            # 组件：对话框/音频播放器/导航栏等
│   │   │   ├── apis/                  # API 封装（按模块组织）
│   │   │   ├── router/                # 路由配置
│   │   │   ├── store/                 # Vuex 状态管理
│   │   │   └── styles/                # 全局样式
│   │   └── vue.config.js              # Vue CLI 配置
│   ├── README.md                       # 技术文档（架构详解）
│   └── README_en.md                    # 英文技术文档
├── docs/                               # 部署与集成文档
│   ├── Deployment.md                   # 部署指南
│   ├── Deployment_all.md               # 全模块部署指南
│   ├── docker-build.md                 # Docker 构建指南
│   ├── FAQ.md                          # 常见问题
│   ├── firmware-build.md               # 固件编译指南
│   ├── firmware-setting.md             # 固件配置指南
│   ├── fish-speech-integration.md     # FishSpeech 集成
│   ├── homeassistant-integration.md   # Home Assistant 集成
│   ├── mcp-endpoint-integration.md    # MCP 接入点集成
│   ├── mcp-vision-integration.md      # MCP 视觉分析集成
│   ├── voiceprint-integration.md       # 声纹识别集成
│   ├── ali-sms-integration.md          # 阿里云短信集成
│   ├── dev-ops-integration.md          # DevOps 集成
│   ├── newsnow_plugin_config.md         # NewsNow 新闻插件配置
│   ├── contributor_open_letter.md       # 贡献者公开信
│   └── images/                          # 文档截图
├── docker-setup.sh                     # 一键环境准备脚本（下载模型与配置）
├── .dockerignore
└── .gitignore

🚀 快速开始

环境要求

• Docker & Docker Compose（推荐）
• 或 Python >= 3.10 + Java 21 + Node.js >= 16 + MySQL + Redis（源码部署）
• FFmpeg（音频处理，核心服务必需）
• 至少 2GB 可用内存（本地 FunASR 模型约需 1GB）

方式一：Docker 一键部署（推荐）

# 1. 克隆仓库
git clone https://github.com/G-YOUNG01/xiaozhi_server.git
cd xiaozhi_server

# 2. 运行一键环境准备脚本（下载语音识别模型、创建目录、拉取配置）
chmod +x docker-setup.sh
./docker-setup.sh

# 3. 编辑配置文件，填入你的 API 密钥
# 核心配置位于 main/xiaozhi-server/data/.config.yaml
# 至少需要配置 LLM 的 API Key（默认使用 ChatGLM glm-4-flash 免费模型）

# 4. 启动核心服务（仅 xiaozhi-server）
cd main/xiaozhi-server
docker-compose up -d

# 或启动全模块（含管理后台 manager-api + manager-web + MySQL + Redis）
docker-compose -f docker-compose_all.yml up -d

# 5. 查看日志
docker logs -f xiaozhi-esp32-server

方式二：源码部署（核心服务）

cd main/xiaozhi-server

# 1. 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 2. 安装依赖
pip install -r requirements.txt

# 3. 下载语音识别模型（SenseVoiceSmall）
# 从 ModelScope 下载：https://modelscope.cn/models/iic/SenseVoiceSmall
# 放置于 models/SenseVoiceSmall/ 目录

# 4. 创建数据目录与自定义配置
mkdir -p data
# 复制默认配置到 data/.config.yaml，然后按需修改
cp config.yaml data/.config.yaml

# 5. 启动服务
python app.py

管理后台访问

全模块部署后：

• 管理前端：http://<服务器IP>:8001
• 管理 API：http://<服务器IP>:8002
• API 文档：http://<服务器IP>:8002/xiaozhi/doc.html（Knife4j）
• 核心 WebSocket：ws://<服务器IP>:8000/xiaozhi/v1/

📖 配置说明

配置文件优先级

系统按以下优先级加载配置：

1. 管理后台远程配置（manager-api）：如果使用了智控台，所有配置以管理后台为准
2. data/.config.yaml：用户自定义覆盖配置（推荐修改此文件）
3. config.yaml：默认配置模板（不建议直接修改）

核心配置项

server:
  ip: 0.0.0.0          # 监听地址
  port: 8000            # WebSocket 端口
  http_port: 8003       # HTTP 服务端口（OTA / 视觉分析）
  websocket: ws://你的IP:8000/xiaozhi/v1/   # 向设备下发的 WebSocket 地址

selected_module:
  VAD: SileroVAD        # 语音活动检测
  ASR: FunASR           # 语音识别（默认本地 FunASR，免费）
  LLM: ChatGLMLLM       # 大模型（默认 glm-4-flash 免费）
  TTS: EdgeTTS          # 语音合成（默认 EdgeTTS，免费）
  Memory: nomem          # 对话记忆
  Intent: function_call  # 意图识别（支持工具调用）

默认免费配置方案

开箱即用的免费组合：

模块	默认选择	说明
VAD	SileroVAD	本地模型，完全免费
ASR	FunASR（SenseVoiceSmall）	本地模型，支持中/英/日/韩/粤，完全免费
LLM	ChatGLM（glm-4-flash）	智谱免费模型，需注册获取 API Key
TTS	EdgeTTS	微软免费 TTS，无需 API Key
Memory	nomem	不开启记忆
Intent	function_call	工具调用模式

只需注册智谱 AI 获取 API Key（免费），填入 LLM.ChatGLMLLM.api_key 即可运行完整语音对话。

常用插件配置

plugins:
  get_weather:        # 天气查询（和风天气，每天 1000 次免费）
    api_host: "mj7p3y7naa.re.qweatherapi.com"
    api_key: "你的和风天气 API Key"
    default_location: "广州"
  play_music:         # 本地音乐播放
    music_dir: "./music"
    music_ext: [".mp3", ".wav", ".p3"]
  home_assistant:     # Home Assistant 智能家居控制
    base_url: "http://homeassistant.local:8123"
    api_key: "你的 Home Assistant 长期访问令牌"

🔌 通信协议

ESP32 设备与服务端通过 WebSocket 通信，主要消息类型：

方向	类型	说明
设备 → 服务端	hello	连接握手与设备初始化
设备 → 服务端	二进制音频帧	Opus 编码音频流（16kHz / 单声道 / 60ms 帧）
设备 → 服务端	abort	中断当前 TTS 播报
设备 → 服务端	report	设备状态报告
服务端 → 设备	二进制音频帧	TTS 合成语音流
服务端 → 设备	文本控制消息	开始/停止监听、配置下发等

详细协议文档见项目技术文档。

📊 架构概览

ESP32 智能硬件
    │  WebSocket (ws://:8000/xiaozhi/v1/)
    ▼
xiaozhi-server (Python, :8000)
    ├── VAD (Silero) ── 语音活动检测
    ├── ASR ────────── 语音识别（FunASR/豆包/腾讯/阿里/百度/OpenAI）
    ├── Intent ─────── 意图识别（function_call/intent_llm）
    ├── LLM ────────── 大模型对话（通义/豆包/DeepSeek/ChatGLM/Ollama/Dify/Gemini/Coze）
    ├── Memory ─────── 对话记忆（mem0ai/本地/无）
    ├── Tools ──────── 工具调用（天气/新闻/音乐/HA 智能家居/MCP）
    ├── TTS ────────── 语音合成（Edge/豆包/阿里/FishSpeech/GPT-SoVITS 等 20+）
    └── HTTP (:8003) ─ OTA 固件下载 + 视觉分析接口
    │
    │  HTTP 拉取配置
    ▼
manager-api (Java Spring Boot, :8002)
    ├── MySQL ──── 用户/设备/配置/对话历史持久化
    ├── Redis ──── 缓存与会话
    └── Knife4j ── API 文档
    │
    │  REST API
    ▼
manager-web (Vue.js, :8001)
    └── 可视化管理后台（用户/设备/模型/音色/OTA/参数）

📚 文档索引

文档	说明
docs/Deployment.md	核心服务部署指南
docs/Deployment_all.md	全模块部署指南（含管理后台）
docs/docker-build.md	Docker 镜像构建指南
docs/FAQ.md	常见问题解答
docs/firmware-build.md	ESP32 固件编译指南
docs/firmware-setting.md	固件配置指南
docs/fish-speech-integration.md	FishSpeech TTS 集成教程
docs/homeassistant-integration.md	Home Assistant 智能家居集成
docs/mcp-endpoint-integration.md	MCP 接入点集成
docs/mcp-vision-integration.md	MCP 视觉分析集成
docs/voiceprint-integration.md	声纹识别集成
main/README.md	完整技术架构文档

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

• 核心服务代码位于 main/xiaozhi-server/
• 管理后端代码位于 main/manager-api/
• 管理前端代码位于 main/manager-web/
• 新增 AI 提供商请遵循 Provider 模式，在 core/providers/ 对应目录下实现
• 新增插件请放置于 plugins_func/functions/，并在配置中注册

📄 许可证

本项目基于 xiaozhi-esp32-server 开源项目，遵循 MIT 许可证。

👤 作者

GYOUNG - GitHub