🚀 xiaozhi-esp32-server-golang

Xiaozhi AI Backend for ESP32 Devices

---

项目简介 | Project Overview

xiaozhi-esp32-server-golang 是一款高性能、全流式的 AI 后端服务，专为物联网与智能语音场景设计。项目基于 Go 语言开发，集成了 ASR（自动语音识别）、LLM（大语言模型）、TTS（语音合成）等核心能力，支持大规模并发与多协议接入，助力智能终端与边缘设备的 AI 语音交互。

---

✨ 主要特性 | Key Features

• ⚡ 端到端全流式 AI 语音链路：ASR → LLM → TTS 全流程流式处理，低延迟实时交互
• 🎙️ 声纹识别与动态TTS切换：根据说话人身份自动切换TTS音色，个性化语音体验
• 🔌 Transport 接口层抽象：WebSocket / MQTT UDP 统一抽象，灵活注入主逻辑，便于协议扩展
• 📬 消息队列化处理：LLM 与 TTS 采用消息队列异步处理，支持业务逻辑灵活注入
• 🌐 多协议高并发接入：支持大规模设备并发接入与消息推送
• ♻️ 高效资源池与连接复用：外部资源连接池机制，降低响应耗时，提升系统吞吐
• 🤖 多引擎AI能力集成：基于 Eino 框架，支持 FunASR、OpenAI 兼容、Ollama、Doubao、EdgeTTS、CosyVoice 等多种引擎
• 🧩 模块化可扩展架构：VAD/ASR/LLM/TTS/MCP/视觉等核心模块独立可插拔
• 🎵 MCP Audio Server：音频资源分页获取与流式处理，音乐播放与音量控制
• 🦞 OpenClaw 智能体接入：按智能体生成专属 OpenClaw Endpoint，支持连接状态查看、会话测试、进入/退出关键词路由（默认“打开龙虾/进入龙虾”与“关闭龙虾/退出龙虾”）
• 🖥️ 全功能Web管理控制台：可视化配置向导、VAD/ASR/LLM/TTS全链路可用性测试、设备管理与消息注入、实时延迟监控与OTA验证
• 🧠 高级业务功能：MCP 市场聚合与导入、声音复刻、知识库（Dify/RAGFlow/WeKnora）、设备/智能体维度 MCP 远程调用调试
• 📦 易用的一键部署方案：预编译 aio 包开箱即用（主程序+控制台+声纹服务）、Docker 一键部署、支持 Linux/Windows/macOS 本地编译
• 🔐 安全与权限体系（规划中）：预留用户认证与权限管理接口

---

deepwiki 架构分析

🚀 快速开始 | Quick Start

方式一：一键启动包（推荐）

下载对应平台的压缩包，解压后运行即可：

• Release 页面：https://github.com/hackers365/xiaozhi-esp32-server-golang/releases
• 使用教程：doc/quickstart_bundle_tutorial.md

启动后访问 http://<服务器IP或域名>:8080 进入 Web 控制台进行配置。

方式二：Docker 部署

• Docker Compose（带控制台）
• Docker（无控制台）

方式三：本地编译

适用于开发环境或需要定制编译的场景。

安装依赖（以 Ubuntu 为例）

# Go 1.20+
# Opus 编解码
sudo apt-get install -y pkg-config libopus0 libopusfile-dev

# ONNX Runtime（1.21.0）
wget https://github.com/microsoft/onnxruntime/releases/download/v1.21.0/onnxruntime-linux-x64-1.21.0.tgz
tar -xzf onnxruntime-linux-x64-1.21.0.tgz
sudo cp -r onnxruntime-linux-x64-1.21.0/include/* /usr/local/include/onnxruntime/
sudo cp -r onnxruntime-linux-x64-1.21.0/lib/* /usr/local/lib/
sudo ldconfig

# ten_vad 运行时依赖
sudo apt install -y libc++1 libc++abi1

📖 完整依赖说明与 Windows/macOS 配置请参考 config.md

主程序、控制台前后端、声纹服务的分离编译与 AIO 打包流程请参考 doc/compile_deploy.md

参考 FunASR 官方文档 部署。

编译与启动

# 编译
go build -o xiaozhi_server ./cmd/server/

# 启动（配置文件详见 config/config.yaml）
./xiaozhi_server -c config/config.yaml

---

📚 文档导航 | Docs

部署相关

• 一键启动包教程
• Docker Compose 部署
• Docker 部署
• 编译与部署指南
• 配置详解

使用指南

• 管理后台使用指南
• WebSocket 服务与 OTA 配置
• MQTT + UDP 配置
• MQTT UDP 协议

功能模块

• 视觉能力
• 声纹识别
• MCP 架构
• MCP 音频资源
• MCP 市场（市场发现/导入/热更新）
• OpenClaw 智能体接入（Endpoint/关键词路由/会话测试）
• 声音复刻（用户操作与管理员额度）
• 知识库（Provider 配置/同步/召回测试/RAG）
• 设备/智能体维度 MCP 远程调用（Endpoint/Tools/Call）

设备接入

• ESP32 端接入指南
• OTA MQTT 授权说明

---

🧩 模块架构 | Module Overview

---

📈 性能与测试 | Performance & Testing

• 延迟测试报告
• 管理后台提供 VAD/ASR/LLM/TTS 可用性与延迟测试入口

---

🛠️ 规划中 | Roadmap

• 主动式ai

---

🤝 贡献 | Contributing

欢迎提交 Issue、PR 或建议！

---

📄 License

MIT License

---

📬 联系方式 | Contact

个人微信：hackers365 （加微信拉你进交流群）

开源不易，您的赞助会让项目持续更新

---

© 2024 xiaozhi-esp32-server-golang