杰理791X SDK接入大模型互动服务的最佳实践

更新时间：2025-12-18

编辑预览
该文档介绍杰理791X平台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，查看互动应用

3.运行云对接服务示例

将本节步骤2获取到的AK/SK参数替换下面执行命令中的对应部分

                Shell
                
            

                ## 访问BCE国内节点启动命令
BCE_APP_AK=your_ak \
BCE_APP_SK=your_sk \
nohup java -Djava.net.preferIPv4Stack=true -jar rtc-aiagent-userserver-version.jar \
--server.address=0.0.0.0 > app.log 2>&1 &
            

                Shell
                
            

                ## 访问BCE香港节点启动命令
BCE_APP_AK=your_ak \
BCE_APP_SK=your_sk \
BCE_ENDPOINT=http://rtc-aiagent-out.baidubce.com \
nohup java -Djava.net.preferIPv4Stack=true -jar rtc-aiagent-userserver-version.jar \
--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。

Http

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}'

Http

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端口，如需停止/重启服务，可参考以下命令

                Shell
                
                # 查看占用端口的进程Id
lsof -i:8936

kill -9 [进程id]

第三步:下载和运行设备端代码示例

准备工作

1.下载设备SDK和DEMO代码

官网下载RTOS-杰理AC7911BB和RTOS-杰理AC7911BA代码示例，解压缩之后可以获取到对应的SDK和Demo代码。

Demo示例运行环境配置如下：

1). 编译的版本：demo和RTOS SDK libbrtc.a基于origin/release/AC79NN_SDK_V1.2.0分支开发的。

2).下载链接中的demo/rtc-rtos-toyapp是基于JL_AC79_DevKitBoard V1.2板卡调试好的demo工程。

2.修改参数配置项

rtc-rtos-toyapp解压后需要更换成客户申请的appId/licenskey以及客户搭建的服务端的locahost参数即可运行，具体如下：

                Shell
                
                # 修改baidu_chat_agents_engine.h中your_appId和localhost参数。
#define BDCloudDefaultRTCAppID  "your_appId", your_appId换成客户开通的appId。
#define SERVER_HOST_ONLINE "http://localhost:8936/api/v1/aiagent", localhost换成客户搭建云服务时的localhost。

                Shell
                
                # 修改brtc_wrapper.c中licenskey参数,your_licenskey换成客户申请的licensekey。
void setUserParameters(AgentEngineParams *params) {
snprintf(params->license_key, sizeof(params->license_key), "%s", "your_licenskey");
}

3.音视频采集及播放代码说明

src/ac79_depandency/app_sdk_audiorecorder.c代码中app_sdk_audio_record_start函数开启读取音频PCM数据、编码发送函数，其中音频采样率是16k，单通道，位宽16bit，每帧PCM长度：640byte。

src/ac79_depandency/app_sdk_localdata_audio_play.c代码中的app_sdk_audio_play_start函数开启播放PCM的函数接口，接收到的PCM格式是采样率是16k，单通道，位宽16bit，每帧PCM长度：640byte。

音频采集和播放的具体参数和接口如下：

                Shell
                
            

                # 音频采集和播放的代码说明
int app_sdk_audio_record_start(...)  //启动音频录制接口函数，设置相关参数
{
...
#ifdef BRTC_ENABLE_G722
   req.enc.sample_rate = 16000;
   req.enc.output_buf_len = 640 *4 ;
   req.enc.frame_size = 640;
   req.enc.volume = 70;
#endif
...
}

static int vfs_fwrite(void *file, void *data, u32 len)  //录制音频PCM回调接口
{
...
   if(g_reocrd_feed_cb){
       if (g_record_real) {
           g_reocrd_feed_cb(data,len); //录制音频PCM数据发送给SDK编码
       }
   }
...
}

int app_sdk_audio_play_start(...) //启动音频播放接口函数，设置相关参数
{
...
#ifdef BRTC_ENABLE_G722
       req.dec.output_buf_len  = 640;
       req.dec.channel         = 1;
       req.dec.sample_rate     = 16000;
#endif
...
}

static int vfs_fread(void *file, void *data, u32 len) //播放音频PCM回调接口
{
...
   if(g_play_feed_cb)
   {
       g_play_feed_cb(data,len);
   }
...
}
            

4.其他主要函数、事件代码说明

                Shell
                
            

                # 下载链接中的各文件说明：  
./demo/rtc-rtos-toyapp  智能体语音互动的demo程序代码， 演示了开启对话及退出对话的全流程。
./src/ac79_depandency 是杰里平台硬件相关的音频录制和播放接口
./include/baidu_chat_agents_engine.h 是BaiduRTC AGENT SDK的头文件。
./libs/libbrtc.a 是BaiduRTC AGENT  SDK的库文件。 
./README.md    说明文档；

brtc_wrapper.c 中主要函数说明如下：
1). baidu_create_chat_agent_engine 创建智能体引擎
2). baidu_chat_agent_engine_init 初始化参数和设置事件回调
3). baidu_chat_agent_engine_call 开启智能体对话  
4). baidu_chat_agent_engine_destroy 结束智能体对话和销毁 
            

                Shell
                
            

                # 智能体事件回调说明：  
typedef enum AGentCallState {
  AGENT_LOGIN_SUCCESS = 1,      //创建智能体与信令连接成功事件
  AGENT_LOGIN_OUT_SUCCESS = 2,   //登出RTC房间成功事件
  AGENT_CALL_SUCCESS = 3,      //登入RTC房间成功事件

  AGENT_LOGIN_FAIL = 401,     //创建智能体与信令连接失败事件，应用层可先退出，再重新登陆
  AGENT_LOGIN_OUT_FAIL = 402,  //登出RTC房间失败事件，表示baidu_chat_agent_engine_destroy失败
  AGENT_CALL_FAIL = 403      //登入RTC房间失败事件，表示baidu_chat_agent_engine_call失败。
} AGentCallState;

typedef enum AGentConnectState {
  AGENT_CONNECTION_STATE_DISCONNECTED = 1,  //网络断开，应用层结合业务可重连操作
  AGENT_CONNECTION_STATE_CONNECTING,      //网络正在连接中
  AGENT_CONNECTION_STATE_CONNECTED,       //网络已连接
  AGENT_CONNECTION_STATE_RECONNECTING      //网络重连中
} AGentConnectState;
            

进阶:常见问题及解决办法

三种对话模式说明

语音对话集成模式介绍

海外节点接入说明

SDK海外节点需要设置修改对应的接入点参数，具体参数和接口说明如下：

                Shell
                
            

                # 修改baidu_chat_agents_engine.h中your_appId和localhost参数。
typedef enum Region {
    REGION_BD_DEV = 0,      // 百度客户对接测试
    REGION_MAINLAND = 1,    // 中国大陆
    REGION_EUROPE,        // 欧洲(正在建设中)
    REGION_AMERICA,       // 美国
    REGION_OVERSEAS,      // 香港
    REGION_GLOBAL        // 全球(正在建设中)
} Region;

# 修改brtc_wrapper.c中params->region参数。
void setUserParameters(AgentEngineParams *params) {
...
params->region = REGION_AMERICA; //美国节点
...
}
            

问题：语音识别不准，怎么处理

语音识别不准确，一般是MIC收音问题：噪音或杂音太大，或者是声音能量值偏小（建议声音能量均值在40～50%），建议在端上优化降噪或增益效果；如端侧无法处理可尝试开启云上3A功能优化。

方法1:设备端上调优降噪ANS、增益AGC

src/ac79_depandency/app_sdk_audiorecorder.c通过req.enc.volume调整MIC的增益参数。

                Shell
                
            

                # 调整降噪ANS、增益AGC接口
int app_sdk_audio_record_start(...)
{
...
//初始噪声水平,用来加速降噪收敛,跟 mic 信号的信噪比有关。 Mic 信号信噪比高， 该值可以小一点， 反之则需要稍微大一点。default: 2.2e3f(0 ~ 32767)
    aec_param.ANS_NoiseLevel =      2.2e3f; 
#ifdef BRTC_ENABLE_G722
    req.enc.sample_rate = 16000;
    req.enc.output_buf_len = 640 *4 ;
    req.enc.frame_size = 640;
    req.enc.volume = 70;
#endif
...
}
            

方法2:云上调优自动降噪ANS、自动增益AGC

开启云上自动降噪与自动增益，请参见云端音频3A功能最佳实践
问题：端设备自言自语对话（播放的声音，回采后重新回答）

这种现象一般是回声消除异常导致，建议在端上优化AEC，端侧无法处理可尝试云上优化；或是采用采用单工对话方式。

方法1:设备上调优回声消除AEC

./src/brtc_esp32_chat_agent_demo.c通过调用audio_pipeline_register注册函数可以打开AEC功能。

                Shell
                
            

                # 开启回声消除AEC功能
int app_sdk_audio_record_start(...)
{
...
    req.enc.aec_enable = 1;  //开启AEC功能
    extern void get_cfg_file_aec_config(struct aec_s_attr * aec_param);
    get_cfg_file_aec_config(&aec_param);

    if (aec_param.EnableBit == 0) {
        req.enc.aec_enable = 0;
        req.enc.aec_attr = NULL;
    }

    if (req.enc.aec_enable) {
        aec_param.output_way = 0;           //1:使用硬件回采 0:使用软件回采
        if (aec_param.output_way) {
            req.enc.channel_bit_map |= BIT(CONFIG_AISP_LINEIN_ADC_CHANNEL);             //配置回采硬件通道
            if (CONFIG_AISP_LINEIN_ADC_CHANNEL < CONFIG_PHONE_CALL_ADC_CHANNEL) {
                req.enc.ch_data_exchange = 1;     //如果回采通道使用的硬件channel比MIC通道使用的硬件channel靠前的话处理数据时需要交换一下顺序
            }
        }
    }
...
}
            

方法2:云上调优回声消除AEC

开启云上回声消除AEC功能，请参见云端音频3A功能最佳实践

方法3:切换到对话模式：按键说话、连续对话（唤醒词打断）

按键说话、连续对话（唤醒词打断），这两种是单工对话，不依赖回声消除功能，可解决这个问题。可参考:语音对话集成模式介绍

自定义函数(Function Calling)，提升函数命中率

参见高质量编写Function Calling说明

如何自定义人设及使用人设

在控制台上配置人设，高质量编写人设提示词

高质量编写人设提示词最佳实践

如何使用已定义的人设

创建智能体指定已定义的人设

Plain Text

1  - 在服务器上调用generateAIAgentCall接口，传入config参数`sceneRole:人设名称`。 人设名称就是控制台定义的人设名称。

动态切换已定义的人设及音色

在服务器上调用operation?switchSceneRole接口，指定对应的人设名称、音色名。

设备未授权提示及处理办法

设备连接到服务器后，服务器会下发鉴权请求，如鉴权失败，设备有未授权提示，且服务器主动与设备断开连接。造成这个原因一般有3种情况：

Plain Text

1* 设备连接服务未正确传入license、DeviceID、UserID信息，或者license无效。 注意：DeviceID可能是SDK自动获取硬件码，无需填写；Websocket对接则需显示传入。DeviceID、UserID要求appid纬度唯一。
2* 网络原因导致服务端未及时收到鉴权的响应。 建议切换到良好的网络。
3* 多台设备非法共用同一个license。 云端会检测到异常，主动断开设备连接。

判断对话响应延时正常与否，及优化建议

延时异常评估及优化建议
更多的资料从哪里找
集成流程完整介绍
声纹使用最佳实践
定时器使用最佳时间
多语言使用最佳时间
产品功能特性表介绍
更多的服务端接口

语音对话模式最佳实践

下载专区

百度智能云

RTC 实时音视频

RTC 实时音视频

杰理791X SDK接入大模型互动服务的最佳实践

基础:跑通全流程

第一步:控制台开通云服务，配置互动智能体

第二步:运行云对接服务示例

第三步:下载和运行设备端代码示例

进阶:常见问题及解决办法

三种对话模式说明

海外节点接入说明

问题：语音识别不准，怎么处理

方法1:设备端上调优降噪ANS、增益AGC

方法2:云上调优自动降噪ANS、自动增益AGC

问题：端设备自言自语对话（播放的声音，回采后重新回答）

方法1:设备上调优回声消除AEC

方法2:云上调优回声消除AEC

方法3:切换到对话模式：按键说话、连续对话（唤醒词打断）

自定义函数(Function Calling)，提升函数命中率

如何自定义人设及使用人设

在控制台上配置人设，高质量编写人设提示词

如何使用已定义的人设

设备未授权提示及处理办法

判断对话响应延时正常与否，及优化建议

更多的资料从哪里找