原文链接

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

（中文 | English）

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

适用人群 👥

本项目需要配合 ESP32 硬件设备使用。如果您已经购买了 ESP32 相关硬件，且成功对接过虾哥部署的后端服务，并希望独立搭建自己的 xiaozhi-esp32 后端服务，那么本项目非常适合您。

想看使用效果？请猛戳视频 🎥

系统要求与部署前提 🖥️

• 硬件：一套兼容 xiaozhi-esp32 的硬件设备（具体型号请参考 此处）。

• 电脑或服务器：至少 4 核 CPU、8G 内存的电脑。

• 固件编译：请将本后端服务的接口地址更新至 xiaozhi-esp32 项目中，再重新编译xiaozhi-esp32固件并烧录到设备上。

如果你没有esp32相关的硬件设备，但是非常想体验该项目，可以使用以下的项目让你的电脑、手机模拟成esp32设备。

• 小智安卓端
• 小智电脑端

警告 ⚠️

1、本项目为开源软件，本软件与对接的任何第三方API服务商（包括但不限于语音识别、大模型、语音合成等平台）均不存在商业合作关系，不为其服务质量及资金安全提供任何形式的担保。 建议使用者优先选择持有相关业务牌照的服务商，并仔细阅读其服务协议及隐私政策。本软件不托管任何账户密钥、不参与资金流转、不承担充值资金损失风险。

2、本项目成立时间较短，还未通过网络安全测评，请勿在生产环境中使用。 如果您在公网环境中部署学习本项目，请务必在配置文件 config.yaml 中开启防护：

server:
  auth:
    # 开启防护
    enabled: true  

开启防护后，您需要根据实际情况校验机器的 token 或 mac 地址，详细请参见配置说明。

功能清单 ✨

已实现 ✅

• 通信协议
  基于 xiaozhi-esp32 协议，通过 WebSocket 实现数据交互。
• 对话交互
  支持唤醒对话、手动对话及实时打断。长时间无对话时自动休眠
• 意图识别
  支持使用LLM意图识别、function call函数调用，减少硬编码意图判断
• 多语言识别
  支持国语、粤语、英语、日语、韩语（默认使用 FunASR）。
• LLM 模块
  支持灵活切换 LLM 模块，默认使用 ChatGLMLLM，也可选用阿里百炼、DeepSeek、Ollama 等接口。
• TTS 模块
  支持 EdgeTTS（默认）、火山引擎豆包 TTS 等多种 TTS 接口，满足语音合成需求。
• 记忆功能
  支持超长记忆、本地总结记忆、无记忆三种模式，满足不同场景需求。

正在开发 🚧

• 多种心情模式
• 智控台webui
• iot功能

本项目支持的平台/组件列表 📋

LLM 语言模型

实际上，任何支持 openai 接口调用的 LLM 均可接入使用。

TTS 语音合成

VAD 语音活动检测

ASR 语音识别

Memory 记忆存储

Intent 意图识别

使用方式 🚀

一、部署文档

本项目支持以下三种部署方式，您可根据实际需求选择。

本项目的文档主要是文字版本的教程，如果你想要视频版本 的教程，您可以学习一下这个大佬的手把手教程。

如果你能把文字版本的教程和视频版本的教程结合起来一起看，可以让你更快上手。

1. Docker 快速部署

适合快速体验的普通用户，不需过多环境配置。缺点是，拉取镜像有点慢。

2. 借助 Docker 环境运行部署

适用于已安装 Docker 且希望对代码进行自定义修改的软件工程师。

3. 本地源码运行

适合熟悉Conda 环境或希望从零搭建运行环境的用户。

对于对响应速度要求较高的场景，推荐使用本地源码运行方式以降低额外开销。

二、固件编译

点这里查看固件编译的详细过程。

烧录成功且联网成功后，通过唤醒词唤醒小智，留意server端输出的控制台信息。

常见问题 ❓

1、为什么我说的话，小智识别出来很多韩文、日文、英文？🇰🇷

建议：检查一下models/SenseVoiceSmall是否已经有model.pt 文件，如果没有就要下载，查看这里下载语音识别模型文件

2、为什么会出现“TTS 任务出错 文件不存在”？📁

建议：检查一下是否正确使用conda 安装了libopus和ffmpeg库。

如果没有安装，就安装

conda install conda-forge::libopus
conda install conda-forge::ffmpeg

3、TTS 经常失败，经常超时 ⏰

建议：如果 EdgeTTS 经常失败，请先检查是否使用了代理（梯子）。如果使用了，请尝试关闭代理后再试；
如果用的是火山引擎的豆包 TTS，经常失败时建议使用付费版本，因为测试版本仅支持 2 个并发。

4、如何提高小智对话响应速度？ ⚡

本项目默认配置为低成本方案，建议初学者先使用默认免费模型，解决“跑得动”的问题，再优化“跑得快”。
如需提升响应速度，可尝试更换各组件。以下为各组件的响应速度测试数据（仅供参考，不构成承诺）：

测试方法：

1、把各组件的密钥配置上去，只有配置了密钥的组件才参与测试。

2、配置完密钥后，执行以下方法

# 进入项目根目录，执行以下命令：
conda activate xiaozhi-esp32-server
python performance_tester.py 

生成报告如下

LLM 性能排行:

TTS 性能排行:

推荐配置组合 (综合响应速度):

结论 🔍

2025年2月19日，如果我的电脑在广东省广州市海珠区，且使用的是中国联通网络，我会优先使用：

• LLM：AliLLM
• TTS：DoubaoTTS

5、我说话很慢，停顿时小智老是抢话 🗣️

建议：在配置文件中找到如下部分，将 min_silence_duration_ms 的值调大（例如改为 1000）：

VAD:
  SileroVAD:
    threshold: 0.5
    model_dir: models/snakers4_silero-vad
    min_silence_duration_ms: 700  # 如果说话停顿较长，可将此值调大

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

建议：在配置文件中将 LLM 设置为 HomeAssistant，通过 调用HomeAssistant接口实现相关控制。

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

我们的联系方式放在百度网盘中,点击前往，提取码是223y。

网盘里有“硬件烧录QQ群”、“开源服务端交流群”、“产品建议联系人” 三张图片，请根据需要选择加入。

• 硬件烧录QQ群：适用于硬件烧录问题
• 开源服务端交流群：适用于服务端问题
• 产品建议联系人：适用于产品功能、产品设计等建议

鸣谢 🙏

• 本项目受 百聆语音对话机器人 启发，并在其基础上实现。
• 感谢 十方融海 对小智通讯协议提供的详尽文档支持。