零基础入门ESP32 AI开发：手把手教你实现大语言模型硬件应用

xiaozhi-esp32是基于ESP32的开源AI聊天机器人项目，集成Qwen/DeepSeek等大模型，采用MCP协议实现多端控制。支持离线语音唤醒、实时语音交互、声纹识别等功能，兼容70+硬件平台。项目提供完整开发环境、文档和模块化代码架构，支持OTA升级和自定义开发，是学习大模型硬件应用的理想入门项目。

一、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-serverPython 服务器
●joey-zhou/xiaozhi-esp32-server-javaJava 服务器
●AnimeAIChat/xiaozhi-server-goGolang 服务器
使用小智通信协议的第三方客户端项目：
●huangjunsen0406/py-xiaozhiPython 客户端
●TOM88812/xiaozhi-android-clientAndroid 客户端
●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、代码框架
项目代码按功能模块化组织，核心目录结构如下：
核心模块职责：
●板级模块：抽象不同硬件的差异，通过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、系统架构图