乐鑫ESP32-S3平台SDK接入最佳实践
该文档介绍乐鑫ESP32-S3平台SDK接入大模型互动服务的最佳实践，引导用户快速跑通流程，解答常见的问题。
基础:跑通全流程
第一步:控制台开通云服务，配置互动智能体
1.注册和登陆百度智能云账号：个人用户和企业用户均需先注册百度智能云账号。具体步骤见注册账号， 登录账号
2.开通大模型互动服务：首次使用服务需要先开通，开通步骤见开通服务
3.创建和配置智能体：
第一步：填写基本信息、选择互动类型（创建成功后不可更改）
第二步：选择模型、填写人设、选择function call模版和组件，具体内容详见 创建互动应用、 控制台快速接入
4.云上测试智能体 【互动应用】应用列表处找到要体验的应用，在【操作】点击体验Demo，进行体验
5.领取测试license和购买正式license： 新用户自动下发10个license，如要购买，在【资源列表】-【购买资源】按需配置购买。详情见领取和购买license
6.给已创建的应用绑定资源：应用创建成功后，必须绑定资源才可正常使用。绑定操作见 绑定资源
第二步:运行云对接服务示例
说明：百度智能云服务API接口，均采用AK/SK鉴权，为了增强安全性，要求在服务器上调用（不建议在设备上）。该示例代码实现一个访问中转，接收设备端连接请求，代理访问百度大模型互动API接口创建互动智能体，返回设备端侧访问云服务所需的token、agentid等信息。该代码可作为服务端对接的实现参考。
1.下载云端对接服务示例代码
本示例代码基于JDK17开发，需要先安装JDK17环境，确保可运行java -version命令等。具体安装过程可直接搜索JDK17安装，参考开源链接进行安装。
官网下载云对接服务代码示例，解压缩之后获取到rtc-aiagent-userserver-version.jar包，本JAR包可以直接用于部署启动。
[!NOTE]
本节后续操作均依赖于前一步骤所获取的参数，请在执行后续操作之前，确保之前步骤均已成功执行。
2.配置云对接服务参数
获取到用于百度智能云接口鉴权的AK/SK，如何获取AK/SK。
获取到用于执行接口调用的互动应用AppId，查看互动应用ID。
3.运行云对接服务示例
将本节步骤2获取到的AK/SK参数替换下面执行命令中的对应部分
1## 访问BCE国内节点启动命令
2BCE_APP_AK=your_ak \
3BCE_APP_SK=your_sk \
4nohup java -Djava.net.preferIPv4Stack=true -jar rtc-aiagent-userserver-version.jar \
5--server.address=0.0.0.0 > app.log 2>&1 &1## 访问BCE香港节点启动命令
2BCE_APP_AK=your_ak \
3BCE_APP_SK=your_sk \
4BCE_ENDPOINT=http://rtc-aiagent-out.baidubce.com \
5nohup java -Djava.net.preferIPv4Stack=true -jar rtc-aiagent-userserver-version.jar \
6--server.address=0.0.0.0 > app.log 2>&1 &[!NOTE]
启动成功之后，console/cmd/ssh界面，会打印进程ID, 日志信息会保存到当前目录的app.log中
服务启动之后，可以通过接口调用工具，或使用curl命令，测试服务是否可以正常创建token、agentId等。命令中your_app_id需要替换为本节步骤2获取到的互动应用appId。
1curl --location 'http://localhost:8936/api/v1/aiagent/generateAIAgentCall' \
2--header 'Content-Type: application/json' \
3--data '{
4 "config": "",
5 "app_id": "your_app_id"
6}'1curl --location 'http://localhost:8936/api/v1/aiagent/stopAIAgentInstance' \
2--header 'Content-Type: application/json' \
3--data '{
4 "app_id": "your_app_id",
5 "ai_agent_instance_id": 2568137789341696
6}'服务启动成功之后，会占据8936端口，如需停止/重启服务，可参考以下命令
1# 查看占用端口的进程Id
2lsof -i:8936
3
4kill -9 [进程id]第三步:下载和运行设备端代码示例
1.下载设备SDK和DEMO代码
官网下载RTOS-乐鑫esp32-s3代码示例，解压缩之后可以获取到对应的SDK和Demo代码。
Demo示例运行环境配置如下：
1). esp-idf版本：支持v5.4.2以及上版本，RTOS SDK libbrtc.a默认是v5.4.2版本编译的。
2).下载链接中的sr/chatagent.zip是基于ESP32-S3-Korvo-2L v1板卡调试好的Demo工程。
2.修改参数配置项
chatagent.zip解压后需要更换成客户申请的appId/licenskey以及客户搭建的服务端的locahost参数即可运行，具体如下：
1# 修改baidu_chat_agents_engine.h中your_appId和localhost参数。
2#define BDCloudDefaultRTCAppID "your_appId", your_appId换成客户开通的appId。
3#define SERVER_HOST_ONLINE "http://localhost:8936/api/v1/aiagent", localhost换成客户搭建云服务时的localhost。1# 修改brtc_esp32_chat_agent_demo.c中licenskey参数,your_licenskey换成客户申请的licensekey。
2void setUserParameters(AgentEngineParams *params) {
3snprintf(params->license_key, sizeof(params->license_key), "%s", "your_licenskey");
4}完成上面的参数配置即可chatagent.zip，执行以下命令即可编译下载运行：
1# 编译下载运行命令
2idf.py build
3idf.py flash3.音视频采集及播放代码说明
src/brtc_esp32_chat_agent_demo.c代码中brtc_demo_audio是读取音频PCM数据、编码发送函数，其中音频采样率是16k，单通道，位宽16bit，每帧PCM长度：640byte。代码中的audio_render_task函数是音频播放PCM的函数接口，onAudioData函数是接收到音频PCM数据的接口，接收到的PCM格式是采样率是16k，单通道，位宽16bit，每帧PCM长度：640byte。
音频采集和播放的具体参数和接口如下：
1# 音频采集和播放的代码说明
2#ifdef BRTC_DEMO_AUDIO
3...
4#define BRTC_AUDIO_FRAME_SIZE 640
5#define BRTC_AUDIO_RATE 16000
6#define BRTC_AUDIO_BITS 16
7#define BRTC_AUDIO_CHANNEL 1
8...
9#endif
10
11static void brtc_demo_audio(void * arg) {
12...
13 while (brtcDemoRunning) {
14 rs = raw_stream_read(rec_res.raw_stream, (char *)abuf, BRTC_AUDIO_FRAME_SIZE); //读取音频PCM数据接口
15 if (brtcDemoAudio) {
16 if (rs > 0 && g_engine) {
17 baidu_chat_agent_engine_send_audio(g_engine, (const uint8_t*)abuf, rs);//编码发送接口
18 }
19 } else {
20 vTaskDelay(10 / portTICK_PERIOD_MS);
21 }
22 }
23...
24
25}
26
27void onAudioData(const uint8_t* data, size_t len) { //接收RTC传输过来的解码后的PCM数据接口
28...
29}
30
31static void audio_render_task(void * arg) { //将到PCM数据送到i2s进行播放
32...
33 while (brtcDemoRunning) {
34...
35 if (xQueueReceive(audio_queue, &audio_data, pdMS_TO_TICKS(10)) == pdPASS) {
36 audio_element_output(i2s_stream_writer, (char*)audio_data.data, audio_data.len); ////接收PCM数据，送入i2s进行播放
37 free(audio_data.data);
38 }
39 }
40...
41}src/brtc_esp32_chat_agent_demo.c代码中的brtc_demo_vsend_task函数包含视频采集编码和发送接口，ESP32-S3视频分辨率为320*240， 视频编码格式为JPEG格式。onVideoData是接收RTC服务端的JPEG视频数据的函数接口，brtc_demo_video_decoder_and_render是JPEG解码和显示的函数接口。
视频采集编码和解码显示的函数接口如下：
1# 视频采集和播放的代码说明
2#ifdef BRTC_DEMO_VIDEO
3...
4#define BRTC_DEMO_LCD_H (320)
5#define BRTC_DEMO_LCD_V (240)
6#define BRTC_DEMO_JPG_W (320)
7#define BRTC_DEMO_JPG_H (240)
8...
9#endif
10
11static void brtc_demo_vsend_task(void * arg) {
12 while (brtcDemoRunning) {
13...
14 if (brtcDemoCapture) {
15...
16 if (camera_config.pixel_format != PIXFORMAT_JPEG) {
17 jpg_enc.size = brtc_demo_jpeg_enc(jpg_enc.buffer, rgb_buffer, image_size); //camera采集编码函数接口
18 }
19 if (jpg_enc.size) {
20 brtc_send_image(gBrtcClient, jpg_enc.buffer, jpg_enc.size);//发送视频帧的函数接口
21 }
22...
23 }
24 }
25}
26
27static void brtc_demo_video_decoder_and_render(void * arg) {
28...
29 if (pkg.size > 0) {
30 brtc_demo_disp_jpg((const char *)pkg.buffer, pkg.size); //JPEG解码显示
31 free(pkg.buffer);
32 pkg.buffer = NULL;
33 pkg.size = 0;
34 }
35...
36}4.其他主要函数、事件代码说明
1# 下载链接中的各文件说明：
2./src/brtc_esp32_chat_agent_demo.c 智能体语音互动的demo程序代码， 演示了开启对话及退出对话的全流程。
3./include/baidu_chat_agents_engine.h 是BaiduRTC AGENT SDK的头文件。
4./libs/libbrtc.a 是BaiduRTC AGENT SDK的库文件。
5./README.md 说明文档；
6
7brtc_esp32_chat_agent_demo.c 中主要函数说明如下：
81). baidu_create_chat_agent_engine 创建智能体引擎
92). baidu_chat_agent_engine_init 初始化参数和设置事件回调
103). baidu_chat_agent_engine_call 开启智能体对话
114). baidu_chat_agent_engine_destroy 结束智能体对话和销毁 1# 智能体事件回调说明：
2typedef enum AGentCallState {
3 AGENT_LOGIN_SUCCESS = 1, //创建智能体与信令连接成功事件
4 AGENT_LOGIN_OUT_SUCCESS = 2, //登出RTC房间成功事件
5 AGENT_CALL_SUCCESS = 3, //登入RTC房间成功事件
6
7 AGENT_LOGIN_FAIL = 401, //创建智能体与信令连接失败事件，应用层可先退出，再重新登陆
8 AGENT_LOGIN_OUT_FAIL = 402, //登出RTC房间失败事件，表示baidu_chat_agent_engine_destroy失败
9 AGENT_CALL_FAIL = 403 //登入RTC房间失败事件，表示baidu_chat_agent_engine_call失败。
10} AGentCallState;
11
12typedef enum AGentConnectState {
13 AGENT_CONNECTION_STATE_DISCONNECTED = 1, //网络断开，应用层结合业务可重连操作
14 AGENT_CONNECTION_STATE_CONNECTING, //网络正在连接中
15 AGENT_CONNECTION_STATE_CONNECTED, //网络已连接
16 AGENT_CONNECTION_STATE_RECONNECTING //网络重连中
17} AGentConnectState;进阶:常见问题及解决办法
SDK海外节点需要设置修改对应的接入点参数，具体参数和接口说明如下：
1# 修改baidu_chat_agents_engine.h中your_appId和localhost参数。
2typedef enum Region {
3 REGION_BD_DEV = 0, // 百度客户对接测试
4 REGION_MAINLAND = 1, // 中国大陆
5 REGION_EUROPE, // 欧洲(正在建设中)
6 REGION_AMERICA, // 美国
7 REGION_OVERSEAS, // 香港
8 REGION_GLOBAL // 全球(正在建设中)
9} Region;
10
11# 修改brtc_esp32_chat_agent_demo.c中params->region参数。
12void setUserParameters(AgentEngineParams *params) {
13...
14params->region = REGION_AMERICA; //美国节点
15...
16}语音识别不准确，一般是MIC收音问题：噪音或杂音太大，或者是声音能量值偏小（建议声音能量均值在40～50%），建议在端上优化降噪或增益效果；如端侧无法处理可尝试开启云上3A功能优化。
方法1:设备端上调优降噪ANS、增益AGC
./src/brtc_esp32_chat_agent_demo.c通过es7210_adc_set_gain调整MIC的增益参数。
1# 调整增益接口
2static int create_rec_pipeline(void)
3{
4...
5 es7210_adc_set_gain(ES7210_INPUT_MIC3, GAIN_0DB);
6 es7210_adc_set_gain(ES7210_INPUT_MIC2 | ES7210_INPUT_MIC1, GAIN_33DB); //调整增益接口函数，一般设置GAIN_33DB
7...
8}方法2:云上调优自动降噪ANS、自动增益AGC
- 开启云上自动降噪与自动增益，请参见云端音频3A功能最佳实践
-
问题：端设备自言自语对话（播放的声音，回采后重新回答）
这种现象一般是回声消除异常导致，建议在端上优化AEC，端侧无法处理可尝试云上优化；或是采用采用单工对话方式。
方法1:设备上调优回声消除AEC
./src/brtc_esp32_chat_agent_demo.c通过调用audio_pipeline_register注册函数可以打开AEC功能。
1# 调整增益接口
2static int create_rec_pipeline(void)
3{
4...
5 const char *link_tag[] = { "aec", "raw"};
6 audio_pipeline_register(rec_res.rec_pipe, rec_res.aec_stream , link_tag[0]); //打开AEC接口函数
7 audio_pipeline_register(rec_res.rec_pipe, rec_res.raw_stream , link_tag[1]);
8...
9}方法2:云上调优回声消除AEC
- 开启云上回声消除AEC功能，请参见云端音频3A功能最佳实践
方法3:切换到对话模式：按键说话、连续对话（唤醒词打断）
按键说话、连续对话（唤醒词打断），这两种是单工对话，不依赖回声消除功能，可解决这个问题。 可参考:语音对话集成模式介绍
在控制台上配置人设，高质量编写人设提示词
如何使用已定义的人设
创建智能体指定已定义的人设
1 - 在服务器上调用generateAIAgentCall接口，传入config参数`sceneRole:人设名称`。 人设名称就是控制台定义的人设名称。动态切换已定义的人设及音色
在服务器上调用operation?switchSceneRole接口， 指定对应的人设名称、音色名。
-
设备未授权提示及处理办法
设备连接到服务器后，服务器会下发鉴权请求，如鉴权失败，设备有未授权提示，且服务器主动与设备断开连接。造成这个原因一般有3种情况：
Plain Text1* 设备连接服务未正确传入license、DeviceID、UserID信息，或者license无效。 注意：DeviceID可能是SDK自动获取硬件码，无需填写；Websocket对接则需显示传入。DeviceID、UserID要求appid纬度唯一。 2* 网络原因导致服务端未及时收到鉴权的响应。 建议切换到良好的网络。 3* 多台设备非法共用同一个license。 云端会检测到异常，主动断开设备连接。 -
判断对话响应延时正常与否，及优化建议
-
更多的资料从哪里找
- 集成流程完整介绍
- 声纹使用最佳实践
- 定时器使用最佳实践
- 多语言使用最佳实践
- 产品功能特性表介绍
- 更多的服务端接口