手把手教你一步一步搭建基于火山引擎端到端语音大模型的esp32s3的智能Agent

效果视频：

从零到一：构建你自己的 ESP32 实时语音助手（基于火山引擎）

文章摘要

本文将带你一步步搭建一个功能强大的 ESP32 实时语音对话系统。我们将利用火山引擎的语音技术，配合一台 Python 中转服务器，让小小的 ESP32 开发板也能实现流畅、智能的语音交互。无论你是想 DIY 一个智能音箱，还是为你的机器人项目增加语音功能，这篇文章都将为你提供详尽的指导。

一、项目概述

1. 功能简介

本项目旨在打造一个低成本、高性能的实时语音对话解决方案。通过 ESP32-S3 采集音频，实时传输到一个 Python 服务器，该服务器再将音频流对接到火山引擎的实时语音对话服务。云端处理完成后，合成的语音再被传回 ESP32 进行播放，从而实现一个完整的“录音 -> 识别 -> 对话 -> 合成 -> 播放”的闭环。

2. 技术架构

- ESP32 客户端: 运行 MicroPython，负责：
- 通过 I2S 麦克风实时采集音频数据。
- 通过 WebSocket 将音频数据流式传输到中转服务器。
- 接收中转服务器下发的音频流，并通过 I2S 功放播放。
- Python 中转服务器: 作为桥梁，负责：
- 接收 ESP32 的 WebSocket 连接。
- 与火山引擎的 WebSocket 服务建立连接并处理复杂的认证逻辑。
- 在两条 WebSocket 连接之间高效、低延迟地双向转发音频数据流。
- 火山引擎: 提供核心的 PaaS 能力：
- 实时语音识别 (ASR): 将用户的语音流实时转换为文字。
- 对话系统: 对识别出的文字进行理解，并生成回复文本。
- 实时语音合成 (TTS): 将回复文本实时合成为语音流。

3. 最终效果

部署成功后，你只需对着 ESP32 的麦克风说话，就能像使用智能音箱一样，与设备进行自然流畅的语音对话。设备会实时响应，并用清晰的语音作出回答。

二、环境与硬件准备

1. 硬件清单

- 主控: ESP32-S3 开发板（理论上支持 I2S 的其他 ESP32 型号也可以，但 S3 的性能和内存更优）。
- 音频输入: I2S 麦克风模块，推荐 `INMP441`，它信噪比高，效果出色。
- 音频输出: I2S 功放模块和扬声器，推荐 `MAX98357A` 模块，驱动简单，音质好。
- 连接线: 杜邦线若干。

硬件接线参考:

注意：以上为 `esp32_client.py` 中的默认引脚配置，你可以根据自己的实际情况修改代码中的引脚定义。

2. 软件环境

- Python: 确保你的电脑安装了 Python 3.7 或更高版本。
- MicroPython IDE: 推荐使用 Thonny IDE，它对初学者非常友好，集成了代码编辑、文件管理和 REPL 交互。
- Git: 用于从代码仓库克隆本项目。

3. 云服务账号

1. 访问 [火山引擎官网](https://www.volcengine.com/) 并完成注册。
2. 进入https://www.volcengine.com/docs/6561/1594356，按照流程开通服务。
3. 跟网页的向导文件获取到 `App-ID` 和 `Access-Key`信息。这将在服务器配置步骤中使用。

三、服务器端部署 (Python Bridge)

中转服务器是连接esp32设备和云端语音及模型服务的关键。

第一步：克隆项目代码

打开终端或命令行，执行以下命令：

​git clone https://github.com/zhou19830318/S2S_doubao_esp32s3_Agent.git cd <项目目录>

第二步：安装依赖

为了保持项目环境的纯净，强烈建议使用 Python 虚拟环境；也可以使用Vscode打开运行。

# 创建虚拟环境 python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate # 安装所需的库 pip install -r Agent_Server/requirements.txt

第三步：配置密钥

这是最关键的一步。使用你的代码编辑器打开 `Agent_Server/config.py` 文件。

找到 `ws_connect_config` 这个字典，将你在上一步中获取的火山引擎密钥填入其中：

ws_connect_config = { "base_url": "wss://openspeech.bytedance.com/api/v3/realtime/dialogue", "headers": { "X-Api-App-ID": "你的App-ID", # <--- 修改这里 "X-Api-Access-Key": "你的Access-Key", # <--- 修改这里 "X-Api-Resource-Id": "volc.speech.dialog", "X-Api-App-Key": "PlgvMymc7f3tQnJ6", "X-Api-Connect-Id": str(uuid.uuid4()), } }

完成上述操作后可以通过运行local_agent_test.py外PC测试豆包api是否可用。

第四步：启动服务器

在激活了虚拟环境的终端中，运行服务器启动脚本：

python Agent_Server/esp32_server.py

如果一切顺利，你将看到以下输出，表示服务器已成功启动并正在监听 `8765` 端口：

python Agent_Server/esp32_server.py PS D:\esp32-s3\s2s_doubao_agent_esp32s3> & D:/esp32-s3/s2s_doubao_agent_esp32s3/.venv/Scripts/Activate.ps1 (.venv) PS D:\esp32-s3\s2s_doubao_agent_esp32s3> & 'd:\esp32-s3\s2s_doubao_agent_esp32s3\.venv\Scripts\python.exe' 'c:\Users\Administrator\.vscode\extensions\ms-python.debugpy-2025.18.0-win32-x64\bundled\libs\debugpy\launcher' '39125' '--' 'D:\esp32-s3\s2s_doubao_agent_esp32s3\python3.7\esp32_server.py' 3\x5cs2s_doubao_agent_esp32s3\x5cpython3.7\x5cesp32_server.py' ;961b39d2-1bb1-4f4e-8bea-8d02c340418e [Server] Running on ws://0.0.0.0:8765

四、客户端部署 (ESP32)

现在我们来配置硬件部分。

第一步：刷入 MicroPython 固件

如果你的 ESP32 还没有 MicroPython 环境，你需要先为其刷入固件。
1. 从 [MicroPython 官网](https://micropython.org/download/esp32/) 下载适用于你的开发板型号的最新稳定版固件。
2. 使用 `esptool.py` 工具进行刷写。你可以通过 Thonny IDE 的“工具”->“选项”->“解释器”菜单来引导你完成此过程。

第二步：配置客户端参数

1. 使用 Thonny IDE 连接到你的 ESP32。
2. 将项目根目录下的 `esp32_client.py` 文件上传到 ESP32 的根目录。
3. 在 Thonny 中打开 `esp32_client.py`，修改以下三处关键配置：

```python
class ESP32RealtimeClient:
def __init__(self):
# ... I2S 引脚定义 ...

# 1. 修改你的 Wi-Fi 名称和密码
self.WIFI_SSID, self.WIFI_PASSWORD = "你的WiFi名称", "你的WiFi密码"

# 2. 修改为运行 Python 服务器的电脑的 IP 地址
self.SERVER_URL = "ws://192.168.1.6:8765" # <-- 重要！

# 3. (可选) 如果你的硬件接线不同，请修改这里的 I2S 引脚
self.I2S_SCK_I, self.I2S_WS_I, self.I2S_SD_I = Pin(5), Pin(6), Pin(7)
self.I2S_SCK_O, self.I2S_WS_O, self.I2S_SD_O = Pin(12), Pin(11), Pin(13)

# ...
```

如何找到电脑的 IP 地址？
- Windows: 在命令提示符中输入 `ipconfig`。
- macOS/Linux: 在终端中输入 `ifconfig` 或 `ip addr`。
找到你的局域网 IP 地址（通常以 `192.168.` 开头）。

第三步：上传并运行代码

保存修改后的 `esp32_client.py`。在 Thonny 中，按下 `F5` 或点击“运行”按钮。观察 Thonny REPL (Shell) 中的日志输出。

MPY: soft reboot WiFi Connected: 192.168.1.8 I2S HW Buffer: 64KB [System] Free memory: 140.0 KB [WS] Connecting to ws://192.168.1.6:8765... [WS] Opening connection to 192.168.1.6:8765... [WS] Waiting for handshake response... [WS] Handshake successful. [System] Connected to server. [Record] Task started. [Recv] Task started. [Play] Task started. [Record] Sent 10 KB [Record] Sent 20 KB [Record] Sent 30 KB [Record] Sent 40 KB [Record] Sent 50 KB [Record] Sent 60 KB [Record] Sent 70 KB [Record] Sent 80 KB [Record] Sent 90 KB [Record] Sent 100 KB

五、联调与验证

如果一切配置正确，你应该会看到：
1. ESP32 端 (Thonny REPL):
- 首先是 Wi-Fi 连接成功的日志。
- 然后是 WebSocket 连接成功的日志 `[System] Connected to server.`。
2. 服务器端 (电脑终端):
- 会显示一条新的连接记录 `[Server] New connection: ...`。

现在，对着麦克风说“你好”。
- 服务器终端会开始打印日志，显示云端会话已建立。
- 片刻之后，ESP32 的扬声器应该会播放出豆包的回复“你好，有什么可以帮你的吗？”之类的回复。

六、常见问题 (FAQ)

1. ESP32 无法连接 Wi-Fi?
- 检查: `WIFI_SSID` 和 `WIFI_PASSWORD` 是否完全正确？
- 排查: 确保你的 Wi-Fi 是 2.4GHz 频段，ESP32 对 5GHz 的支持不佳。

2. 无法连接服务器?
- 检查: `SERVER_URL` 中的 IP 地址是否是服务器电脑的 **当前** 局域网 IP？电脑重启后 IP 可能会改变。
- 排查: 确保 ESP32 和电脑连接在同一个Wi-Fi 网络下。
- 排查: 检查电脑的防火墙设置，确保它允许来自局域网的对 `8765` 端口的访问。可以尝试暂时关闭防火墙进行测试。

3. 没有声音或声音异常?
- 检查: I2S 引脚接线是否与代码中的定义完全一致？`SCK`, `WS`, `SD` 等引脚不要接错。
- 排查: 确保麦克风和功放模块的 `VDD` 和 `GND` 已正确连接。
- 调试: 在 `record_task` 中加入打印语句，确认 `audio_in.readinto(read_buf)` 是否能读到非零数据。

七、总结

恭喜你！你已经成功搭建了一个属于自己的语音助手。这个项目不仅是一个有趣的 DIY 作品，更是一个学习嵌入式系统、网络编程和云服务的绝佳实践。从这里开始，你可以探索更多有趣的功能，例如：
- 自定义唤醒词: 集成一个轻量级的本地唤醒词引擎。
- 控制智能家居: 通过对话来控制家中的灯光、开关等设备。
- 赋予机器人“生命”: 将其作为机器人的交互中枢，让你的机器人能听会说。

希望这篇文章能对你有所帮助，祝你玩得开心！