✨ 小智 AI 聊天机器人后端服务（商业版）

小智 AI 是一个语音交互机器人，结合 Qwen、DeepSeek 等强大大模型，通过 MCP 协议连接多端设备（ESP32、Android、Python 等），实现高效自然的人机对话。

本项目是其后端服务，旨在提供一套 商业级部署方案 —— 高并发、低成本、功能完整、开箱即用。

项目初始基于 虾哥的 ESP32 开源项目，目前已形成完整生态，支持多种客户端协议兼容接入。

---

✨ 核心优势

优势	说明
🚀 高并发	单机支持 3000+ 在线，分布式可扩展至百万用户
👥 用户系统	完整的用户注册、登录、权限管理能力
💰 支付集成	接入支付系统，助力商业闭环
🛠️ 模型接入灵活	支持通过 API 调用多种大模型，简化部署，支持定制本地部署
📈 商业支持	提供 7×24 技术支持与运维保障
🧠 模型兼容	支持 ASR（豆包）、TTS（EdgeTTS）、LLM（OpenAI、Ollama）、图文解说（智谱）等

---

✅ 社区版功能清单

• 支持 websocket 连接
• 支持 PCM / Opus 格式语音对话
• 支持大模型：ASR（豆包流式）、TTS（EdgeTTS/豆包）、LLM（OpenAI API、Ollama）
• 支持语音控制调用摄像头识别图像（智谱 API）
• 支持 auto/manual/realtime 三种对话模式，支持对话实时打断
• 支持 ESP32 小智客户端、Python 客户端、Android 客户端连入，无需校验
• OTA 固件下发
• 支持 MCP 协议（客户端 / 本地 / 服务器），可接入高德地图、天气查询等
• 支持语音控制切换角色声音
• 支持语音控制切换预设角色
• 支持语音控制播放音乐
• 支持单机部署服务
• 支持本地数据库 sqlite
• 支持coze工作流
• 支持Docker部署

✅商务版功能清单

• 社区版所有功能
• 开发团队技术支持
• 后续核心功能免费更新
• 商务版管理后台，更多的功能选项
• 支持多用户管理
• 自定义修改欢迎界面
• 自定义修改版权logo，使用自己公司的商务标识
• 自定义修改Agent角色模板
• 支持更多的模型
• 支持 websocket 和 MQTT+UDP 两种通信协议
• 支持 tts 流式生成及发送
• 支持声音克隆
• 支持知识库
• 支持定制音色（cosyvoice2, indextts）
• 支持通过 OTA 升级固件
• 支持 Coze 工作流
• 支持 Dify 工作流
• 深度优化响应速度
• 支持用户身份验证，激活绑定设备
• 支持设备管理：解绑/禁用
• 支持后台解绑设备
• 支持用户自定义 Agent
• 国际化多语言支持：中文、英语、日语、西班牙语、印尼语等
• 支持MCP接入点
• 支持网络数据库
• 支持分布式部署
• 支持本地部署大模型

商务版测试/体验地址：

https://xiaozhi.xf.bj.cn/login

---

🚀 快速开始

1. 下载 Release 版

推荐直接下载 Release 版本，无需配置开发环境：

👉 点击前往 Releases 页面

• 选择你平台对应的版本（如 Windows: windows-amd64-server.exe）
• .upx.exe 是压缩版本，功能一致，体积更小，适合远程部署

---

2. 配置 .config.yaml

• 推荐复制一份 config.yaml 改名为 .config.yaml
• 按需求配置模型、WebSocket、OTA 地址等字段
• 不建议自行删减字段结构

WebSocket 地址配置（必配）

web:
  websocket: ws://your-server-ip:8000

用于 OTA 服务下发给客户端的连接地址，ESP32 客户端会自动从此地址连接 WS，不再手动配置。

注：如果是局域网调试，your-server-ip要配置为电脑在局域网中的IP，且终端设备和电脑在同一网段，设备才能通过这个IP地址连到电脑上的服务。

OTA 地址配置（必配）

http://your-server-ip:8080/api/ota/

ESP32 固件内置 OTA 地址，确保该服务地址可用，服务运行后可以在浏览器中输出此地址，确认服务可以访问。

ESP32设备可以在联网界面修改OTA地址，从而在不重新刷固件的情况下，切换后端服务。

配置ASR，LLM，TTS

根据配置文件的格式，配置好相关模型服务，尽量不要增减字段

---

💬 MCP 协议配置

参考：src/core/mcp/README.md

---

🧪 源码安装与运行

前置条件

• Go 1.24.2+
• Windows 用户需安装 CGO 和 Opus 库（见下文）

git clone https://github.com/AnimeAIChat/xiaozhi-server-go.git
cd xiaozhi-server-go
cp config.yaml .config.yaml

---

Windows 安装 Opus 编译环境

安装 MSYS2，打开MYSY2 MINGW64控制台，然后输入以下命令：

pacman -Syu
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-go mingw-w64-x86_64-opus
pacman -S mingw-w64-x86_64-pkg-config

设置环境变量（用于 PowerShell 或系统变量）：

set PKG_CONFIG_PATH=C:\msys64\mingw64\lib\pkgconfig
set CGO_ENABLED=1

尽量在MINGW64环境下运行一次 “go run ./src/main.go” 命令，确保服务正常运行

GO mod如果更新较慢，可以考虑设置go代理，切换国内镜像源。

---

运行项目

go mod tidy
go run ./src/main.go

编译发布版本

go build -o xiaozhi-server.exe src/main.go

测试

• 推荐使用ESP32硬件设备测试，可以最大程度避免兼容问题

• 推荐使用玄凤小智Android客户端，在设置界面增加本地服务的ota地址即可。安卓版本在Release页面发布，可选择最新版本

  xiaozhi-0.0.6.apk

• 可使用其他兼容小智协议的客户端进行测试

---

📚 Swagger 文档

• 打开浏览器访问：http://localhost:8080/swagger/index.html

更新 Swagger 文档（每次修改 API 后都要运行）

cd src
swag init -g main.go

---

☁️ CentOS 源码部署指南

文档见：Centos 8 安装指南

---

Docker 环境部署

1. 准备docker-compose.yml,.config.yaml,二进制程序文件

👉 点击前往 Releases 页面下载二进制程序文件

• 选择你平台对应的版本（默认使用 Liunx: linux-amd64-server-upx，如使用其他版本，需要修改docker-compose.yml）

2. 三个文件放到同一目录下，配置docker-compose.yml,.config.yaml

3. 运行docker compose up -d

---

💬 社区支持

欢迎提交 Issue、PR 或新功能建议！

---

🛠️ 定制开发

我们接受各种定制化开发项目，如果您有特定需求，欢迎通过微信联系洽谈。

📄 License

本仓库遵循 Xiaozhi-server-go Open Source License（基于 Apache 2.0 增强版）