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

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

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

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

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

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

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

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

    1
    2
    3
    4
    # 下载并执行部署脚本
    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

  3. 手动部署（备选）：如果一键脚本执行失败，可以手动操作。详细步骤如下：

    • 创建目录结构：新建一个文件夹（如 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密钥和其他参数。

  4. 启动服务：在 xiaozhi-server 目录下执行命令启动容器。

    1
    2
    3
    docker compose up -d
    # 查看日志确认启动成功
    docker logs -f xiaozhi-esp32-server

    服务启动后，你的设备就可连接此服务器了。

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

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

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

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

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

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

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

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

  2. 获取源代码：

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

  3. 配置项目：

    • 设置目标芯片：根据你的开发板设置目标芯片，例如 ESP32-S3：idf.py set-target esp32s3。
    • 菜单配置：运行 idf.py menuconfig 进入配置界面。
      • 进入 Xiaozhi Assistant 配置项。
      • Board Type：选择与你硬件匹配的开发板型号。
      • Connection Type：如果需要连接自建服务器，需将连接类型改为 Websocket，并修改 Websocket URL 为你自己服务器的地址。
      • 其他配置：根据硬件情况调整Flash大小、分区表、外设GPIO引脚等。

  4. 编译与烧录：

    • 编译：在项目根目录下运行 idf.py build。编译成功后，固件会生成在 build/ 目录。
    • 烧录：将开发板连接电脑，运行 idf.py -p PORT flash（将 PORT 替换为实际的串口号，如 /dev/ttyUSB0 或 COM3）。
    • 监控：运行 idf.py -p PORT monitor 可以查看设备日志，方便调试。

⚙️ 配置与使用

  • 网络配置：烧录完成首次启动后，设备通常会进入配网模式（例如，通过热点或蓝牙）。使用手机连接设备热点，按照引导将其连接至你的 Wi-Fi 网络。
  • 连接服务器：设备默认会尝试连接官方演示服务器。如果你部署了自己的服务器，需在编译时修改 Websocket URL 配置。
  • 设备激活：连接网络后，可能需要通过手机App或网页进行设备绑定和激活，具体请参考官方文档。