小智 AI 聊天机器人 (XiaoZhi-ESP32) 的部署。这是一个基于 ESP32 系列芯片的开源 AI 硬件项目，实现了语音交互、设备控制等多种功能 | 极客的赛博空间

这份详细的部署教程将指引您完成 小智 AI 聊天机器人 (XiaoZhi-ESP32) 的部署。这是一个基于 ESP32 系列芯片的开源 AI 硬件项目，实现了语音交互、设备控制等多种功能。

小智 AI 聊天机器人利用大模型（如通义千问、DeepSeek）的 AI 能力，通过 MCP 协议实现终端控制。它支持语音唤醒、对话，并能在 OLED/LCD 屏幕上显示表情，是一款功能丰富的 AI 硬件伴侣。

整个部署流程分为两个主要部分：

服务端部署：为设备提供 AI 能力的后端服务器。
固件编译与烧录：将程序刷入 ESP32 硬件设备。

🖥️ 第一部分：部署服务端 (Server)

服务端是整个系统的“大脑”，负责处理语音识别、调用大模型和生成回复。官方推荐使用 Docker 方式部署，最简单快捷。

准备工作：一台安装了 Docker 和 Docker Compose 的服务器（Linux 或 Mac），并确保能正常访问 GitHub。

一键部署（推荐）：
在终端中执行以下命令，脚本会自动完成目录创建、模型下载和配置文件生成。

# 下载并执行部署脚本
curl -L -o docker-setup.sh https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/main/docker-setup.sh
chmod +x docker-setup.sh
./docker-setup.sh

手动部署（备选）：如果一键脚本执行失败，可以手动操作。详细步骤如下：
- 创建目录结构：新建一个文件夹（如 xiaozhi-server），并在其下创建 data 和 models/SenseVoiceSmall 目录。
  1
  2
  3
  4
  xiaozhi-server
  ├─ data
  ├─ models
  └─ SenseVoiceSmall
- 下载模型文件：将语音识别模型 model.pt 文件放入 models/SenseVoiceSmall 目录。可以从魔搭社区或百度网盘下载。
- 下载配置文件：从项目仓库下载 docker-compose.yml 和 config.yaml。将 config.yaml 重命名为 .config.yaml 并放入 data 目录。
- 配置模型：编辑 data/.config.yaml 文件，配置你想要使用的AI模型（如通义千问、DeepSeek）的API密钥和其他参数。
启动服务：在 xiaozhi-server 目录下执行命令启动容器。
1
2
3
docker compose up -d
# 查看日志确认启动成功
docker logs -f xiaozhi-esp32-server
服务启动后，你的设备就可连接此服务器了。

🔌 第二部分：编译与烧录固件

你需要将小智的固件烧录到 ESP32 开发板上。对于新手，推荐先直接烧录现成固件体验；如需深度定制，可搭建开发环境自行编译。

方式一：免开发环境烧录（新手推荐）

使用现成的固件，通过网页工具烧录，无需搭建开发环境。

获取固件：从项目 Releases 页面或社区下载最新的 merged-binary.bin 固件文件。注意选择匹配你开发板型号的固件。
连接设备：使用 USB 数据线将 ESP32 开发板连接到电脑。
使用网页烧录工具：用 Chrome 或 Edge 浏览器打开 ESP Launchpad 工具：https://espressif.github.io/esp-launchpad/。
烧录固件：按照网页提示，连接你的设备，选择下载的 merged-binary.bin 文件，点击烧录即可。

方式二：从源码编译（进阶定制）

此方式适合需要修改源代码或适配自定义硬件的开发者。项目推荐使用 ESP-IDF v6.0.2 或更新的稳定版本，并建议在 Linux 环境下编译以提升速度并减少驱动问题。

搭建 ESP-IDF 开发环境：安装 ESP-IDF 开发框架。推荐使用 VS Code 并安装 ESP-IDF 插件，可以极大简化环境配置、编译和烧录过程。详细的 ESP-IDF 安装指南可参考乐鑫官方文档。

获取源代码：

1 2	git clone https://github.com/78/xiaozhi-esp32.git cd xiaozhi-esp32

配置项目：
- 设置目标芯片：根据你的开发板设置目标芯片，例如 ESP32-S3：idf.py set-target esp32s3。
- 菜单配置：运行 idf.py menuconfig 进入配置界面。
  - 进入 Xiaozhi Assistant 配置项。
  - Board Type：选择与你硬件匹配的开发板型号。
  - Connection Type：如果需要连接自建服务器，需将连接类型改为 Websocket，并修改 Websocket URL 为你自己服务器的地址。
  - 其他配置：根据硬件情况调整Flash大小、分区表、外设GPIO引脚等。
编译与烧录：
- 编译：在项目根目录下运行 idf.py build。编译成功后，固件会生成在 build/ 目录。
- 烧录：将开发板连接电脑，运行 idf.py -p PORT flash（将 PORT 替换为实际的串口号，如 /dev/ttyUSB0 或 COM3）。
- 监控：运行 idf.py -p PORT monitor 可以查看设备日志，方便调试。