综合介绍
xiaozhi-esp32-server 是一个为 小智AI聊天机器人（xiaozhi-esp32）提供后端服务的工具。它用 Python 编写，基于 WebSocket 协议，帮助用户快速搭建一个控制 ESP32 设备的服务器。这个项目适合已经购买 ESP32 硬件并想自己动手搭建后端的人。它的功能很实用，比如支持语音对话、多语言识别和智能家居控制。项目在 GitHub 上开源，最新更新是 2025 年 3 月，官方文档详细，社区活跃。注意，它还在开发中，不建议直接用在生产环境。
功能列表
- WebSocket 通信：用 xiaozhi-esp32 协议与硬件实时交换数据。
- 语音对话：支持唤醒对话、手动对话和实时打断，长时间没用会自动休眠。
- 意图识别：用大模型识别用户意图，还能调用函数执行指令。
- 多语言支持：能听懂中文、粤语、英语、日语和韩语，默认用 FunASR。
- 语言模型切换：默认用 ChatGLM，也支持阿里百炼、DeepSeek 等。
- 语音合成：支持 EdgeTTS 和火山引擎 TTS，生成自然语音。
- 记忆模式：有超长记忆、本地总结和无记忆三种选择。
- 智能家居控制：能连 HomeAssistant，控制家电开关。
使用帮助
安装流程
要用 xiaozhi-esp32-server，你得先准备好硬件和环境。以下是具体步骤：
1. 准备工作
- 硬件：一台支持 xiaozhi-esp32 固件的 ESP32 设备，具体型号看官方列表。
- 电脑：建议 4 核 CPU、8GB 内存。如果用 API 跑语音识别，2 核、2GB 也行。
- 软件：安装 Python 3.10 和 Conda。
2. 下载项目
- 打开 https://github.com/xinnan-tech/xiaozhi-esp32-server。
- 点击 "Code"，选 "Download ZIP" 下载。
- 解压后，把文件夹改名为 "xiaozhi-esp32-server"。
3. 配置 Conda 环境
- 打开命令行，运行：
conda create -n xiaozhi-esp32-server python=3.10 -y
conda activate xiaozhi-esp32-server
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda install libopus -y
conda install ffmpeg -y
- 检查每步输出，确保没报错。
4. 安装依赖
- 进入项目文件夹：
cd xiaozhi-esp32-server/main/xiaozhi-server
- 设置国内源并安装：
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip install -r requirements.txt
5. 下载模型
- 默认用 FunASR 语音识别。去官方指引（见 README）下载模型，放进 "models" 文件夹。
- 检查 "SenseVoiceSmall" 文件夹里有没有 "model.pt"，没有就下载。
6. 修改配置
- 打开 "config.yaml" 文件，调整设置：
- 语言模型：默认 ChatGLM，可改成 DeepSeek 或 HomeAssistant。
- 语音合成：默认 EdgeTTS，可换火山引擎 TTS。
- 沉默时间：把
min_silence_duration_ms调到 1000（适合慢说话）。 - 保存文件。
7. 启动服务器
- 在 "xiaozhi-server" 文件夹运行：
python main.py
- 看到 "Server running on port 8000" 就成功了。
8. 更新固件
- 把服务器地址（比如
http://你的IP:8000）写进 xiaozhi-esp32 固件。 - 按固件编译指引重新编译并烧录。
其他部署方式
- Docker 快速部署：适合新手。运行
docker pull xinnan-tech/xiaozhi-esp32-server，按指引启动。 - Docker 源码运行：适合改代码的人。先装 Docker，再用官方文档跑项目。
- 详情看部署文档。
功能操作
语音对话
- 唤醒：说唤醒词（固件里设），服务器会回应。
- 手动触发：按设备按钮开始对话。
- 打断：说话时插话，设备会立刻处理。
- 操作：对着设备说 "你好"，听回复。
多语言识别
- 支持五种语言。配置文件里可调优先级。
- 操作：说 "Hello" 或 "こんにちは"，设备都能懂。
语音合成
- 配置 TTS 后，文字会变语音。
- 操作：用测试脚本输入 "今天天气"，设备会念出来。
- 切换：改配置文件里的 TTS 接口。
智能家居
- 连接 HomeAssistant：填入 token。
- 操作：说 "开灯"，灯就亮。
- 测试：跑
python performance_tester.py检查速度。
注意事项
- 网络：保持稳定，WebSocket 靠实时连接。
- 安全：公网部署要开防护（
auth: enabled: true）。 - 调试：看命令行日志，解决问题。
应用场景
- 智能家居
- 连上 HomeAssistant，说 "关空调"，空调就停。
- 语音助手
- 放桌上，问 "明天天气"，它会告诉你。
- 语言练习
- 用英语对话，设备帮你练发音。
QA
- 识别出乱七八糟的语言怎么办？
- 检查 "models/SenseVoiceSmall" 里有没 "model.pt"。没有就去指引下载。
- TTS 出错说文件不存在？
- 确认装了
libopus和ffmpeg。没装就跑conda install conda-forge::libopus和conda install conda-forge::ffmpeg。
- 响应太慢怎么办？
- 换快点的模型，比如 AliLLM + DoubaoTTS。跑
python performance_tester.py测一下。
- 说话慢被抢话怎么办？
- 在 "config.yaml" 里把
min_silence_duration_ms改成 1000。
- 怎么控制家电？
- 配置里选 HomeAssistant，填 token，说指令就行。
简体中文 
English 
日本語 
Deutsch (Sie) 
Português do Brasil