当前位置：首页 > news >正文

基于AI大模型智能硬件--小智 AI 聊天机器人项目介绍

news 2025/11/4 9:20:32

一、xiaozhi-esp32 项目介绍

1、项目概述

这是一个由虾哥开源的基于 ESP32 的聊天机器人项目，以 MIT 许可证发布，允许免费使用及商业用途。项目旨在帮助大家了解 AI 硬件开发，将大语言模型应用到实际硬件设备中，采用 MCP（多端控制协议）实现多端控制，作为语音交互入口，利用 Qwen / DeepSeek 等大模型的 AI 能力。

小智项目github地址： https://github.com/78/xiaozhi-esp32

2、核心功能

网络支持：Wi-Fi / ML307 Cat.1 4G
语音相关：离线语音唤醒（基于 ESP-SR）、采用 OPUS 音频编解码、基于流式 ASR + LLM + TTS 架构的语音交互、声纹识别（基于 3D Speaker）
通信协议：支持 Websocket 或 MQTT+UDP
显示与电源：OLED / LCD 显示屏（支持表情显示）、电量显示与电源管理
多语言支持：中文、英文、日文
硬件兼容：支持 ESP32-C3、ESP32-S3、ESP32-P4 芯片平台

3、硬件支持

支持面包板手工制作，相关教程可参考《小智 AI 聊天机器人百科全书》。👉 《小智 AI 聊天机器人百科全书》

兼容 70 多个开源硬件，部分包括：立创・实战派 ESP32-S3 开发板、乐鑫 ESP32-S3-BOX3、M5Stack CoreS3、AtomS3R + Echo Base、神奇按钮 2.4 等。

4、软件相关

提供了板级初始化代码、配置文件等，方便适配不同开发板。
包含 OTA（空中下载技术）功能相关代码，用于检查固件版本并进行更新。
有 release.py 脚本用于构建和发布不同开发板的固件。

大模型配置

如果你已经拥有一个的小智 AI 聊天机器人设备，并且已接入官方服务器，可以登录 xiaozhi.me 控制台进行配置。

开发环境

Cursor 或 VSCode
安装 ESP-IDF 插件，选择 SDK 版本 5.4 或以上
Linux 比 Windows 更好，编译速度快，也免去驱动问题的困扰
本项目使用 Google C++ 代码风格，提交代码时请确保符合规范

5、相关开源项目

在个人电脑上部署服务器，可以参考以下第三方开源的项目：

xinnan-tech/xiaozhi-esp32-server Python 服务器
joey-zhou/xiaozhi-esp32-server-java Java 服务器
AnimeAIChat/xiaozhi-server-go Golang 服务器

使用小智通信协议的第三方客户端项目：

huangjunsen0406/py-xiaozhi Python 客户端
TOM88812/xiaozhi-android-client Android 客户端
100askTeam/xiaozhi-linux 百问科技提供的 Linux 客户端
78/xiaozhi-sf32 思澈科技的蓝牙芯片固件
QuecPython/solution-xiaozhiAI 移远提供的 QuecPython 固件

6、开发者文档

自定义开发板指南 - 学习如何为小智 AI 创建自定义开发板
MCP 协议物联网控制用法说明 - 了解如何通过 MCP 协议控制物联网设备
MCP 协议交互流程 - 设备端 MCP 协议的实现方式
MQTT + UDP 混合通信协议文档
一份详细的 WebSocket 通信协议文档

二、项目技术架构与功能分析

1、技术架构

项目基于 ESP32 系列芯片构建，以 MCP（多端控制协议）为核心，实现语音交互与多设备控制，整体架构分为三层：

硬件层

硬件支持：ESP32-C3/S3/P4 等芯片平台，兼容 70+ 开源硬件（如立创・实战派 ESP32-S3、乐鑫 ESP32-S3-BOX3 等）。
外设支持：OLED/LCD 显示屏、麦克风、扬声器、Wi-Fi/4G 模块（ML307 Cat.1）、GPIO 设备（灯光、电机等）。

中间层

通信协议：WebSocket 或 MQTT+UDP 混合协议（控制指令通过 MQTT，音频流通过 UDP 传输，确保实时性）。
核心协议：MCP 协议实现设备与云端 / 客户端的交互，支持工具调用、状态同步、能力协商。
音视频处理：基于 ESP-SR 实现离线语音唤醒，OPUS 编解码处理音频流，流式 ASR+LLM+TTS 架构支持实时语音交互。

应用层

大模型集成：对接 Qwen/DeepSeek 等大模型，提供 AI 对话能力。
多端控制：通过设备端 MCP 控制本地硬件（音量、GPIO 等），通过云端 MCP 扩展智能家居、PC 控制等功能。

2、代码框架

项目代码按功能模块化组织，核心目录结构如下：

xiaozhi-esp32/
├── main/                  # 主程序目录
│   ├── boards/            # 板级配置（不同硬件的初始化代码）
│   │   ├── xxx_board.cc   # 板级初始化（如管脚映射、外设驱动）
│   │   ├── config.h       # 硬件配置（管脚定义、参数设置）
│   ├── audio/             # 音频处理模块
│   │   ├── 音频输入流（麦克风采集→PCM处理→OPUS编码）
│   │   ├── 音频输出流（OPUS解码→PCM播放→扬声器输出）
│   ├── display/           # 显示模块（OLED/LCD驱动，LVGL界面）
│   ├── iot/               # 物联网控制模块（设备注册、命令执行）
│   ├── mcp/               # MCP协议实现（工具调用、交互逻辑）
│   ├── ota.cc             # 固件升级模块（版本检查、OTA更新）
├── scripts/               # 辅助脚本（固件构建、发布、音频转换）
├── docs/                  # 协议文档（WebSocket/MQTT/MCP）
└── sdkconfig.defaults.*   # 芯片配置文件（ESP32不同型号的默认配置）

核心模块职责：

板级模块：抽象不同硬件的差异，通过 config.h 统一管脚映射，xxx_board.cc 实现初始化。
音频模块：分离输入 / 输出流，通过队列（audio_encode_queue_/audio_playback_queue_）异步处理音频数据。
MCP 模块：定义设备与服务器的交互规范（工具列表获取、命令调用、状态通知）。
OTA 模块：通过 HTTP 检查版本，解析 JSON 响应获取固件 URL，支持强制升级。

3、开发流程

（1）环境搭建

工具：Cursor/VSCode + ESP-IDF 插件（SDK 5.4+），推荐 Linux 系统（编译速度快）。
代码规范：遵循 Google C++ 风格。

（3）硬件适配（自定义开发板）

参考相似开发板的实现（如 main/boards/ 下的示例）。
编写 xxx_board.cc 初始化硬件，config.h 配置管脚映射，config.json 定义编译选项。
分步调试：先验证基础功能（显示、网络），再调试音频等复杂模块。

（3）功能开发

基于 MCP 协议扩展设备能力：通过 ThingManager 注册新设备，定义属性和方法。
音频处理：集成 Opus 编解码，通过队列机制衔接采集、编码、传输流程。
通信层：选择 WebSocket 或 MQTT+UDP 协议，参考 docs/ 中的协议文档实现交互。

（4）测试与发布

通过 scripts/release.py 构建不同开发板的固件。
利用 OTA 功能验证固件升级流程，检查版本兼容性。

4、系统架构图

┌─────────────────────────────────────────┐
│              客户端/云端                 │
│ （大模型服务、智能家居平台、PC控制端等）   │
└───────────────────┬─────────────────────┘│▼
┌─────────────────────────────────────────┐
│            通信层（MCP协议）             │
│  ┌───────────────┐  ┌────────────────┐  │
│  │  WebSocket    │  │  MQTT+UDP      │  │
│  └───────────────┘  └────────────────┘  │
└───────────────────┬─────────────────────┘│
┌───────────────────▼─────────────────────┐
│            核心功能层                    │
│  ┌─────────┐ ┌────────┐ ┌────────────┐  │
│  │ 语音交互 │ │ 显示控制│ │ 物联网控制 │  │
│  │（ASR/TTS）│ │（LVGL）│ │（MCP工具） │  │
│  └─────────┘ └────────┘ └────────────┘  │
└───────────────────┬─────────────────────┘│
┌───────────────────▼─────────────────────┐
│              硬件层                      │
│ （ESP32芯片、麦克风、扬声器、显示屏等）    │
└─────────────────────────────────────────┘