开通火山引擎rtc指引

13 2025-11-19 21:25

快速接入

步骤一：前置准备

开通火山引擎 实时音视频、语音识别、音频合成、火山方舟大模型 服务。参看开通服务开通相关产品、配置角色策略并获取以下参数值：
- 火山引擎：AK、SK
- 实时音视频 RTC：APPID、APPKEY
- 豆包语音-语音识别-流式语音识别：APP ID、Access Token
- 豆包语音-音频生成-语音合成：APP ID、Access Token、Voice_type
- 火山方舟大模型：EndPointId
配置不同权限账号调用智能体，创建角色。
启用硬件场景配置，并使用相应的房间规则。
准备 Linux PC 服务器：推荐使用 Ubuntu18.04 及以上版本。（服务端示例程序在 Windows 11 python 3.12、MacOs python 3.9、Ubuntu 24.04 Python 3.12 实测可以正常运行。）

运行设备端

请根据你使用的硬件开发板，选择对应的设备端部署教程：
- 乐鑫 ESP32-S3-Korvo-2、AtomS3R：运行设备端_乐鑫
- 博通：运行设备端_博通

本教程将指导你如何在乐鑫 ESP32-S3-Korvo-2 开发板上运行火山引擎 RTC AIGC Demo，实现与 AI 实时对话。

开通服务并运行服务端

运行设备端（乐鑫）

以下操作以 macOS 操作系统为例。

环境与硬件要求

乐鑫 ESP32-S3-Korvo-2 或 AtomS3R 开发板。
USB 数据线：两条 A 转 Micro-B 数据线，一条作为电源线，一条作为串口线。
PC 设备服：编译和烧录。支持 Windows、Linux 或者 macOS 操作系统。（本文操作以 macOS 为例）

配置乐鑫环境

详见开发环境配置文档。

安装 CMake 和 Ninja 编译工具。
```
brew install cmake ninja dfu-util
```

将乐鑫 ADF 框架克隆到本地，并同步各子仓（submodule）代码。

注意：Demo 中使用的 ADF 版本为 eca11f20e56f9b5321b714da4305e123672d92a9，对应 IDF 版本为 v5.4，请确保 ADF 版本与 IDF 版本匹配。

# 1. clone 乐鑫 ADF 框架
git clone https://github.com/espressif/esp-adf.git
# 2. 进入esp-adf目录
cd esp-adf
# 3. 切换到乐鑫 ADF 指定版本
git reset --hard eca11f20e56f9b5321b714da4305e123672d92a9
# 4. 同步各子仓代码
git submodule update --init --recursive

安装乐鑫 esp32s3 开发环境相关依赖。

./install.sh esp32s3

成功安装所有依赖后，命令行会出现如下提示：

All done! You can now run:
. ./export.sh

如在上述任何步骤中遇到以下错误: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:xxx) 可前往访达->应用程序->Python 文件夹，点击 Install Certificates.command 安装证书。更多信息，请参考安装 ESP-IDF 工具时出现的下载错误。
设置环境变量。

每次打开命令行窗口均需要运行该命令进行设置。
```
. ./export.sh
```

下载并配置工程

将实时对话式 AI 硬件示例工程克隆到乐鑫 ADF examples 目录下。
1. 进入 esp-adf/examples 目录。
```
cd $ADF_PATH/examples
```

克隆实时对话式 AI 硬件示例工程。

git clone https://github.com/volcengine/rtc-aigc-embedded-demo.git

禁用乐鑫工程中的火山组件。

cd $ADF_PATH

禁用乐鑫工程中的火山组件。

git apply $ADF_PATH/examples/rtc-aigc-embedded-demo/0001-feat-disable-volc-esp-libs.patch

编译固件

进入 esp-adf/examples/rtc-aigc-embedded-demo/client/espressif/esp32s3_demo 目录下编译固件。

进入 esp32s3_demo 目录。

cd $ADF_PATH/examples/rtc-aigc-embedded-demo/client/espressif/esp32s3_demo

设置编译目标平台。

idf.py set-target esp32s3

设置 RTC APPID、服务端地址和端口号。

idf.py menuconfig

进入 Example Configuration 菜单，在 RTC APPID 中填入你的 RTC APPID，在 AIGENT Server Host 中填入你的服务端地址和端口号，并保存。
设置开发板型号。
```
idf.py menuconfig
```
进入 Audio HAL 菜单，在 Audio board 中选择你的开发板型号。(例如: 方舟开发板选择 M5STACK-ATOMS3R)，并保存。
编译固件。
```
idf.py build
```

烧录并运行示例 Demo

打开乐鑫开发板电源开关。
烧录固件。
```
idf.py flash
```

运行示例 Demo 并查看串口日志输出。

idf.py monitor

Wi-Fi 配网。
1. 手机找到名如 “VolcRTC-XXXXXX” 的 Wi-Fi 热点，连接上 Wi-Fi。
2. 打开浏览器，在地址栏输入 http://192.168.4.1，进入 Wi-Fi 配网页面。
3. 输入 Wi-Fi 名称和密码，点击提交。
注意：如果需更换 Wi-Fi，请重启设备。如果设备重启后无法连接到之前保存的 Wi-Fi（例如超出了范围或旧网络已关闭），请等待 30s 进入配网模式，再重新执行上面 Wi-Fi 配网的 3 个步骤。

博客