小智 ESP-32 后端服务(xiaozhi-esp32-server)

（中文 | English）

本项目为开源智能硬件项目 xiaozhi-esp32 提供后端服务。根据小智通信协议使用Python实现。

适用人群

本项目需要配合esp32硬件设备使用，如果童鞋们已经购买了esp32相关硬件，且成功对接虾哥部署的后端，并且想自己独立搭建 xiaozhi-esp32后端服务，可学习本项目。

想看使用效果,请猛戳这个视频小智esp32连接自己的后台模型

要想完整体验本项目，需要以下总体步骤：

• 准备一套兼容xiaozhi-esp32 项目的硬件设备，具体型号可点击这里。
• 拥有一台至少4核CPU 8G内存的普通电脑或服务器，运行本项目。部署后可以在控制台看到本项目服务的接口地址。
• 下载xiaozhi-esp32项目，把接口地址修改成本项目地址，然后编译，把新固件烧录到硬件设备上。
• 启动设备，查看电脑或服务器的控制台，如果看到日志，说明成功连到本项目的接口了。

功能清单

已实现

• xiaozhi-esp32 通信 WebSocket 协议
• 支持唤醒对话、手动对话、实时打断对话
• 支持国语、粤语、英语、日语、韩语 5 种语言识别（FunASR（默认））
• 自由更换 LLM（支持ChatGLM（默认）、Dify、DeepSeek）
• 自由更换 TTS（支持EdgeTTS（默认）、火山引擎豆包TTS）

正在实现

• 长时间不聊天进入休眠状态
• 对话记忆
• 更换心情模式

本项目依赖服务

部署方式

本项目支持docker快速部署和本地源码运行。如果您主要是想快速体验，推荐使用docker部署。如果想深入了解本项目，推荐本地源码运行。

方式一：docker快速部署

如果你的电脑是arm架构的电脑，请暂时使用方式二：本地源码运行。arm架构需要再等几天，因为目前还没有适配arm架构的镜像。

1. 安装docker

如果您的电脑还没安装docker，可以按照这里的教程安装：docker安装

2. 创建目录

安装完后，你需要为这个项目找一个安放配置文件的目录，我们暂且称它为项目目录，这个目录最好是一个新建的空的目录。

3. 下载配置文件

用浏览器打开这个链接。

在页面的右侧找到名称为RAW按钮，在RAW按钮的旁边，找到下载的图标，点击下载按钮，下载config.yaml文件。 把文件下载到你的项目目录。

4. 修改配置文件

修改刚才你下载的config.yaml文件，配置本项目所需的各种参数。默认的LLM使用的是ChatGLMLLM，你需要配置密钥，才能启动。

默认的TTS使用的是EdgeTTS，这个无需配置，如果你需要更换成豆包TTS，则需要配置密钥。

配置说明：这里是各个功能使用的默认组件，例如LLM默认使用ChatGLMLLM模型。如果需要切换模型，就是改对应的名称。

本项目的默认配置原则是成本最低配置原则（glm-4-flash和EdgeTTS都是免费的），如果需要更优的更快的搭配，需要自己结合部署环境切换各组件的使用。

selected_module:
  ASR: FunASR
  VAD: SileroVAD
  LLM: ChatGLMLLM
  TTS: EdgeTTS

比如修改LLM使用的组件，就看本项目支持哪些LLM，如下就是支持DeepSeekLLM、ChatGLMLLM。你们在selected_module修改成对应的LLM

LLM:
  DeepSeekLLM:
    ...
  ChatGLMLLM:
    ...
  DifyLLM:
    ...

有些服务，比如如果你使用Dify、豆包的TTS，是需要密钥的，记得在配置文件加上哦！

5. 执行docker命令

打开命令行工具，cd 进入到你的项目目录，执行以下命令

#如果你是linux，执行
ls
#如果你是windows，执行
dir

如果你能看到config.yaml文件，确确实实进入到了项目目录，接着执行以下命令：

docker run -d --name xiaozhi-esp32-server --restart always --security-opt seccomp:unconfined -p 8000:8000 -v $(pwd)/config.yaml:/opt/xiaozhi-es32-server/config.yaml ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest

如果首次执行，可能需要几分钟时间，你要耐心等待他完成拉取。正常拉取完成后，你可以在命令行执行以下命令查看服务是否启动成功

docker ps

如果你能看到xiaozhi-server，说明服务启动成功。那你还可以进一步执行以下命令，查看服务的日志

docker logs -f xiaozhi-esp32-server

如果你能看到，类似以下日志,则是本项目服务启动成功的标志。

2025-xx-xx xx:51:59,492 - core.server - INFO - Server is running at ws://xx.xx.xx.xxx:8000
2025-xx-xx xx:51:59,516 - websockets.server - INFO - server listening on 0.0.0.0:8000

接下来，你就可以开始 编译esp32固件了，请往下翻，翻到编译esp32固件相关章节。那么由于你是用docker部署，你要自己查看自己本机电脑的ip是多少。 正常来说，假设你的ip是192.168.1.25，那么你的接口地址就是：ws://192.168.1.25:8000。这个信息很有用的，后面编译esp32固件需要用到。

后期如果想升级版本，可以这么操作

1、备份好config.yaml文件，一些关键的配置到时复制到新的config.yaml文件里。

2、执行以下命令

docker stop xiaozhi-esp32-server
docker rm xiaozhi-esp32-server
docker rmi ccr.ccs.tencentyun.com/xinnan/xiaozhi-esp32-server:latest

3.按本教程重新来一遍

方式二：本地源码运行

1.安装基础环境

本项目依赖ffmpeg、libopus-dev、conda，安装好后开始执行以下命令。

conda remove -n xiaozhi-esp32-server --all -y
conda create -n xiaozhi-esp32-server python=3.10 -y
conda activate xiaozhi-esp32-server

2.安装本项目依赖

# 拉取本项目后进入本项目根目录
cd xiaozhi-esp32-server
conda activate xiaozhi-esp32-server
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip install -r requirements.txt

3.下载语音识别模型

默认使用SenseVoiceSmall模型，进行语音转文字。因为模型较大，需要独立下载，下载后把model.pt文件放在model/SenseVoiceSmall目录下。下面两个下载路线任选一个。

• 线路一：阿里魔塔下载SenseVoiceSmall
• 线路二：百度网盘下载SenseVoiceSmall 提取码: qvna

4.配置项目

修改config.yaml文件，配置本项目所需的各种参数。默认的LLM使用的是ChatGLMLLM，你需要配置密钥，才能启动。 默认的TTS使用的是EdgeTTS，这个无需配置，如果你需要更换成豆包TTS，则需要配置密钥。

配置说明：这里是各个功能使用的默认组件，例如LLM默认使用ChatGLMLLM模型。如果需要切换模型，就是改对应的名称。

本项目的默认配置仅是成本最低配置（glm-4-flash和EdgeTTS都是免费的），如果需要更优的更快的搭配，需要自己结合部署环境切换各组件的使用。

selected_module:
  ASR: FunASR
  VAD: SileroVAD
  LLM: ChatGLMLLM
  TTS: EdgeTTS

比如修改LLM使用的组件，就看本项目支持哪些LLM，如下就是支持DeepSeekLLM、ChatGLMLLM。你们在selected_module修改成对应的LLM

LLM:
  DeepSeekLLM:
    ...
  ChatGLMLLM:
    ...
  DifyLLM:
    ...

有些服务，比如如果你使用Dify、豆包的TTS，是需要密钥的，记得在配置文件加上哦！

5.运行项目

启动项目

# 确保在本项目的根目录下执行
conda activate xiaozhi-esp32-server
python app.py

启动后，会看到类似以下日志

2025-xx-xx xx:51:59,492 - core.server - INFO - Server is running at ws://192.168.1.25:8000
2025-xx-xx xx:51:59,516 - websockets.server - INFO - server listening on 0.0.0.0:8000

其中上面的ws://192.168.1.25:8000就是本项目提供的接口地址了，当然你自己的机器和我的是不一样的，记得要找到自己的地址。

编译esp32固件

1. 下载xiaozhi-esp32 项目，按照这个教程配置项目环境《Windows搭建 ESP IDF 5.3.2开发环境以及编译小智》

2. 打开xiaozhi-esp32/main/Kconfig.projbuild文件，找到WEBSOCKET_URL的default的内容，把wss://api.tenclass.net 改成你自己的地址，例如，我的接口地址是ws://192.168.1.25:8000，就把内容改成这个。

修改前：

config WEBSOCKET_URL
    depends on CONNECTION_TYPE_WEBSOCKET
    string "Websocket URL"
    default "wss://api.tenclass.net/xiaozhi/v1/"
    help
        Communication with the server through websocket after wake up.

修改后(示例)：

config WEBSOCKET_URL
    depends on CONNECTION_TYPE_WEBSOCKET
    string "Websocket URL"
    default "ws://192.168.1.25:8000/xiaozhi/v1/"
    help
        Communication with the server through websocket after wake up.

3. 设置编译参数

# 终端命令行进入xiaozhi-esp32的根目录
cd xiaozhi-esp32
# 例如我使用的板子是esp32s3，所以设置编译目标为esp32s3，如果你的板子是其他型号，请替换成对应的型号
idf.py set-target esp32s3
# 进入菜单配置
idf.py menuconfig

进入菜单配置后，再进入Xiaozhi Assistant，将CONNECTION_TYPE设置为Websocket 回退到主菜单，再进入Xiaozhi Assistant，将BOARD_TYPE设置你板子的具体型号 保存退出，回到终端命令行。

4. 编译固件

idf.py build

5. 打包bin固件

cd scripts
python release.py

编译成功后，会在项目根目录下的build目录下生成固件文件merged-binary.bin。 这个merged-binary.bin就是要烧录到硬件上的固件文件。

6. 烧录固件 将esp32设备连接电脑，使用chrome浏览器，打开以下网址

https://espressif.github.io/esp-launchpad/

打开这个教程，Flash工具/Web端烧录固件（无IDF开发环境）。 翻到：方式二：ESP-Launchpad 浏览器WEB端烧录，从3. 烧录固件/下载到开发板开始，按照教程操作。

常见问题

1、TTS 经常失败，经常超时

建议：如果EdgeTTS慢或经常失败，可以更换成火山引擎的豆包TTS，如果两个都慢，可能所处的网络环境需要优化一下。 有部分网友反馈，使用EdgeTTS时，最好不要使用梯子，容易失败。

2、大模型回复有点慢

建议：大模型和TTS都是依赖接口，如果网络环境不佳，可以考虑换成本地模型。或多尝试切换不同的接口模型。

3、为啥我的ChatGLMLLM回复有点问题，明明它才是小智，却把我当小智。

建议： 可以先修改配置文件里的提示词。也可以把免费的glm-4-flash，换成智谱其他收费版本的模型。

4、我想通过小智控制电灯、空调、远程开关机等操作。

建议：在配置文件里，将LLM设置成DifyLLM，然后通过Dify编排智能体实现。

5、我说话很慢，我停顿一下，小智老是抢我的话，咋办。

建议：在配置文件里，找到这一段，将min_silence_duration_ms值改大一点，比如改成1000。

VAD:
  SileroVAD:
    threshold: 0.5
    model_dir: models/snakers4_silero-vad
    min_silence_duration_ms: 700  # 如果说话停顿比较长，可以把这个值设置大一些

6、更多问题，可联系我们反馈

鸣谢

• 本项目受百聆语音对话机器人项目启发，基于该项目的基础思路完成实现。
• 感谢腾讯云为本次项目提供免费docker镜像空间。
• 感谢十方融海在小智通讯协议上提供充分的文档支持。