Skip to content

小智后端服务 xiaozhi-esp32-server

项目定位:开源的语音交互与物联网控制后端
核心价值:模块化设计 · 实时流式处理 · 多服务兼容
源码地址github.com/xinnan-tech/xiaozhi-esp32-server

本项目为开源智能硬件项目小智 ESP32 提供后端服务,根据小智通信协议实现功能:

  • Python 实现的 Websocket Server
  • Java 实现的管理 API
  • Vue.js 实现的管理界面

帮助开发者快速搭建小智智能硬件服务器

功能架构

核心能力

  1. 语音交互系统

    • 语音识别 (ASR):支持多语言(中文/粤语/英语/日语/韩语)
    • 语音合成 (TTS):默认微软 EdgeTTS,支持火山引擎双流式合成
    • 语音活动检测 (VAD):通过 SileroVAD 实现实时打断
  2. 智能对话引擎

    • 大语言模型 (LLM):支持智谱/火山豆包/DeepSeek/Ollama 等模型
    • 记忆管理:本地短期记忆 + mem0ai 云端长期记忆
    • 意图识别:通过 function_call 实现设备控制指令解析
  3. 物联网控制

    • 设备注册与状态管理
    • 上下文感知控制(如"打开客厅灯")
  4. 管理平台

  5. 高级扩展

    • OTA升级:支持设备远程固件更新(/xiaozhi/ota/ 接口)。
    • 多协议兼容:适配 xiaozhi-esp32 硬件通信协议,支持第三方LLM/ASR/TTS服务接入。

系统架构

项目采用 模块化微服务架构,关键组件如下:

  1. 通信层

    • 协议:基于 xiaozhi-esp32 自定义协议,使用 WebSocket 实现设备与服务器的双向实时通信。
    • 接口
      • 对话接口:wss://domain/xiaozhi/v1/
      • OTA升级:https://domain/xiaozhi/ota/
  2. 业务逻辑层

    • 模块化设计:ASR、LLM、TTS、Intent、Memory 等模块可独立替换(通过配置文件切换)。
    • 流式处理:全链路流式支持(ASR→LLM→TTS),响应速度优化(较旧版提升2.5秒)。
  3. 数据层

    • 简化版:数据存储在配置文件(无数据库)。
    • 完整版:使用数据库存储设备/用户数据(具体DB类型未说明)。
  4. 部署架构

    • 容器化:提供 Dockerfile-serverDockerfile-web,支持一键部署。
    • 资源要求
      • 简化版:2核2G(全API)或 2核4G(含FunASR)。
      • 完整版:2核4G(全API)或 4核8G(含FunASR)。

原作者的使用效果视频 🎥

已使用本地test-page验证的功能

  • 语音/文本交互
  • 音色切换
  • 天气查询
  • 播放音乐
  • 新闻播报

生态与扩展

  • 客户端支持
    • Android/iOS客户端(Flutter开发)
    • Python模拟客户端(py-xiaozhi
    • Java服务端替代方案(xiaozhi-esp32-server-java
  • 第三方服务兼容
    • LLM:阿里百炼、Dify、FastGPT、Coze 等兼容OpenAI接口的模型。
    • TTS:腾讯云、阿里云、GPT-SoVITS 本地合成等。
    • ASR:支持本地(SherpaASR)或云端(腾讯/Aliyun)方案。

部署文档

本项目提供两种部署方式,请根据您的具体需求选择:

🚀 部署方式选择
部署方式特点适用场景部署文档配置要求视频教程
最简化安装智能对话、IOT功能,数据存储在配置文件低配置环境,无需数据库Docker版 / 源码部署如果使用FunASR要2核4G,如果全API,要2核2G-
全模块安装智能对话、IOT、OTA、智控台,数据存储在数据库完整功能体验Docker版 / 源码部署如果使用FunASR要4核8G,如果全API,要2核4G本地源码启动视频教程 / 本地源码自动更新教程

总结

项目定位:为ESP32硬件提供低代码、可扩展的语音交互与物联网控制后端,核心价值在于:

  1. 模块化:自由组合ASR/LLM/TTS服务(本地/云端混合)。
  2. 实时性:全流式架构优化响应速度。
  3. 生态整合:兼容多品牌硬件和AI服务,提供智控台统一管理。
    适用场景:个人开发者搭建智能家居中控、教育类语音机器人等实验性项目。

附:通信协议:Websocket 连接

基本信息

  • 协议版本: 1
  • 传输方式: Websocket
  • 音频格式: OPUS
  • 音频参数:
    • 采样率: 16000Hz
    • 通道数: 1
    • 帧长: 60ms

连接建立

  1. 客户端连接Websocket服务器时需要携带以下headers:
Plain
Authorization: Bearer <access_token>
Protocol-Version: 1
Device-Id: <设备MAC地址>
Client-Id: <设备UUID>

设备MAC地址和UUID都是设备唯一识别码。

  1. 连接成功后,客户端发送hello消息:
JSON
{
    "type": "hello",
    "version": 1,
    "transport": "websocket",
    "audio_params": {
        "format": "opus",
        "sample_rate": 16000,
        "channels": 1,
        "frame_duration": 60
    }
}
  1. 服务端响应hello消息:
JSON
{
    "type": "hello",
    "transport": "websocket",
    "audio_params": {
        "format": "opus",
        "sample_rate": 24000,
        "channels": 1,
        "frame_duration": 60
    }
}

Websocket协议不返回 session_id,所以消息中的会话ID可设置为空。

消息类型

1. 语音识别相关消息

开始监听
JSON
{
    "session_id": "<会话ID>",
    "type": "listen",
    "state": "start",
    "mode": "<监听模式>"
}

监听模式:

  • "auto": 自动停止
  • "manual": 手动停止
  • "realtime": 持续监听

auto 与 realtime 是服务器端 VAD 的两种工作模式,realtime 需要 AEC 支持。

停止监听
JSON
{
    "session_id": "<会话ID>",
    "type": "listen",
    "state": "stop"
}
唤醒词检测
JSON
{
    "session_id": "<会话ID>",
    "type": "listen",
    "state": "detect",
    "text": "<唤醒词>"
}

2. 语音合成相关消息

服务端发送的TTS状态消息:

JSON
{
    "type": "tts",
    "state": "<状态>",
    "text": "<文本内容>" // 仅在 sentence_start 时携带
}

状态类型:

  • "start": 开始播放
  • "stop": 停止播放
  • "sentence_start": 新句子开始

3. 中止消息

JSON
{
    "session_id": "<会话ID>",
    "type": "abort",
    "reason": "wake_word_detected" // 可选
}

4. IoT设备相关消息

设备描述
JSON
{
    "session_id": "<会话ID>",
    "type": "iot",
    "descriptors": <设备描述JSON>
}
设备状态
JSON
{
    "session_id": "<会话ID>",
    "type": "iot",
    "states": <状态JSON>
}

5. 情感状态消息

服务端发送:

JSON
{
    "type": "llm",
    "emotion": "<情感类型>"
}

状态流程图

  1. Manual 模式

img

  1. Auto 模式

img

二进制数据传输

  • 音频数据使用二进制帧传输
  • 客户端发送OPUS编码的音频数据
  • 服务端返回OPUS编码的TTS音频数据

错误处理

当发生网络错误时,客户端会收到错误消息并关闭连接。客户端需要实现重连机制。

会话流程

  1. 建立Websocket连接
  2. 交换hello消息
  3. 开始语音交互:
    1. 发送开始监听
    2. 发送音频数据
    3. 接收识别结果
    4. 接收TTS音频
  4. 结束会话时关闭连接

通信协议:Emoji 心情显示

大语言模型会使用 1 个 token 来输出 emoji 来表示当前的心情,这个 emoji 不会被 TTS 朗读出来,但是会被以独立数据类型进行返回。

示例:

JSON
 {"type":"llm", "text": "😊", "emotion": "smile"}

以下是常用的 emoji 列表。

  1. 😶 - neutral
  2. 🙂 - happy
  3. 😆 - laughing
  4. 😂 - funny
  5. 😔 - sad
  6. 😠 - angry
  7. 😭 - crying
  8. 😍 - loving
  9. 😳 - embarrassed
  10. 😲 - surprised
  11. 😱 - shocked
  12. 🤔 - thinking
  13. 😉 - winking
  14. 😎 - cool
  15. 😌 - relaxed
  16. 🤤 - delicious
  17. 😘 - kissy
  18. 😏 - confident
  19. 😴 - sleepy
  20. 😜 - silly
  21. 🙄 - confused

文章来源于自己总结和网络转载,内容如有任何问题,请大佬斧正!联系我