概览

本项目旨在高效集成百度大模型实时互动平台，主要实现平台要求的UserServer端能力，为客户端SDK提供必要的服务端支持。核心功能为互动实例全生命周期管理：通过generateAIAgentCall创建实例并初始化SDK，使用stopAIAgentInstance销毁实例释放资源。

注意：

百度提供服务端Demo代码示例，详见 服务端Demo示例代码，用户可选使用压缩包中的rtc-aiagent-userserver.zip源码来搭建UserServer服务，也可以参考该源码，根据需要自行使用Go/Python等语言搭建UserServer服务

项目概述

项目架构

模块说明

• 客户端是集成大模型互动SDK的终端应用，支持多种互动SDK，如Android APP、RTOS、H5、iOS APP等。
• UserServer服务端，客户服务器，用于管理设备，向大模型互动平台发起创建AIAgentInstance请求，获得互动服务的实例信息，以及发起销毁AIAgentInstance请求，销毁互动实例。
• 大模型互动平台，以多模态互动、超低延时、全链路语音增强和丰富生态为核心，为开发者提供了一站式的大模型智能交互服务，支持语音互动、视频互动、数字人互动、任务交互等场景。

互动实例生命周期

• 创建AIAgentInstance过程：

  1. 客户端发起createInstance调用，请求创建AIAgentInstance
  2. UserServer服务接收到创建请求后，首先根据应用的ak、sk、请求url，计算生成鉴权Authorization，并添加到请求头中，然后向大模型互动平台发起创建请求generateAIAgentInstance
  3. 大模型互动平台将创建好的实例信息发送给UserServer服务端
  4. UserServer服务端将实例信息发送给客户端

• 销毁AIAgentInstance过程：

  5. 客户端发起destroyInstance调用，请求销毁互动实例
  6. UserServer服务端接收到销毁请求后，首先根据应用的ak、sk、请求url，计算生成鉴权Authorization，并添加到请求头中，然后向大模型互动平台发起销毁请求stopAIAgentInstance
  7. 大模型互动平台将销毁结果返回至UserServer服务端
  8. UserServer服务端将销毁结果返回给客户端

依赖资源

• 百度智能云大模型实时互动应用：需要提前在百度智能云平台注册并开通实时音视频RTC产品，在大模型实时互动下创建互动应用，详见：创建互动应用，获取 appId、ak、sk 等认证信息，用于后续接口调用和鉴权
• Java环境：服务端基于JDK 17开发，需要在本地和Linux环境中安装并配置好JDK 17
• 构建工具：需要安装Maven 3.6.3或更高版本

使用流程

11. 安装环境 → 2. 启动UserServer服务端 → 3. 创建对话 → 4. 测试功能 → 5. 关闭对话

UserServer服务端部署

源码导入/开发/打包指南（Windows/Mac）【可选】

提示：

可直接选择压缩包中的jar文件启动程序，也可以选择本地源码打开项目，开发、编译，启动程序

1. 解压项目文件，将下载的项目压缩包解压到任意目录（建议路径不要包含中文或空格）

   • 注意：UserServer端服务压缩包为: rtc-aiagent-userserver.zip

2. 开发环境要求：

   • JDK17版本，Maven构建工具3.6.3及以上，IDE开发环境，如vs code、IntelliJ IDEA等

3. 环境变量配置：

   • 项目启动需要先配置BCE_APP_AK、BCE_APP_SK等环境变量，配置完成之后，请注意重启IDEA使变量生效

4. 启动应用（以IntelliJ IDEA）

   • 导入项目，菜单栏选择File > Open，导入项目之后需要等待maven下载完依赖
   • 在项目文件导航栏中找到：UserServerApplication.java
   • 选择Run/Debug启动

5. maven打包

   Bash 复制

   1## 执行maven打包命令，并将生成的jar包上传到服务器, 用于后续服务端部署
   2mvn clean package -DskipTests

Linux服务器部署

使用启动脚本部署

1# 1. 将压缩包中的jar文件上传到服务器指定目录中
2
3# 2. 编辑user_server.sh脚本文件，并将其上传到服务器
4  JAVA_HOME="${your_jdk_path_here}"  # 请替换为实际的JDK路径
5	JAR_FILE="${your_jar_file_path_here}"  # 请替换为实际的JAR文件路径
6
7  # 必须要配置，其余可选
8  export BCE_APP_AK=${your_bce_app_ak_here}  # 请替换为实际的BCE App Access Key
9  export BCE_APP_SK=${your_bce_app_sk_here}  # 请替换为实际的BCE App Secret Key
10
11# 3. 给启动脚本添加执行权限
12chmod +x user_server.sh
13
14# 4. 运行启动脚本
15./user_server.sh

使用java -jar直接启动

1# 示例模版：
2BCE_APP_AK=your_AK \
3BCE_APP_SK=your_SK \
4/home/work/.deck/1.0/oraclejdk/17.0.1/bin/java -jar rtc-aiagent-userserver-version.jar \
5> app.log 2>&1 &

API接口调用

创建AIAgentInstance

1. UserServer服务端部署完成之后，参考以下接口创建AIAgentInstance

1public AiAgentGenerateResponse generateH5AiAgentCall(@RequestBody AgentGenerateRequest request) ;

2. 请求调用样例，其中config为自定义配置信息，参考官网参数说明， app_id为大模型实时互动应用的app_id

1curl --location 'http://localhost:8936/api/v1/aiagent/generateAIAgentCall' \
2--header 'Content-Type: application/json' \
3--data '{
4  "app_id": "你的app_id",
5  "config": "你的配置信息"
6}'

3. 接口响应样例, 其中"ai_agent_instance_id"为创建的实例

1{
2    "context": {
3        "cid": 1,
4        "token": "0046115809cd65f5ce93411ea64e6a7ec501465d5da1753340447c79d17f11753426847"
5    },
6    "ai_agent_instance_id": 2414409945251840
7}

销毁AIAgentInstance

1. 互动结束之后，参考以下接口销毁AIAgentInstance

1public void stopH5AiAgentCall(@RequestBody AgentStopRequest request); 

2. 请求调用样例，其中"ai_agent_instance_id"为生成的样例id

1curl --location 'http://localhost:8936/api/v1/aiagent/stopAIAgentInstance' \
2--header 'Content-Type: application/json' \
3--data '{
4  "app_id": "你的app_id",
5  "ai_agent_instance_id": "2414409945251840"
6}'

3. 销毁响应只返回成功，没有responseBody

以H5 SDK接入UserServer服务示例

1. 官网下载H5 SDK并解压缩，通过IDE打开项目，找到agent.js文件

   Javascript 复制

   1// 将地址配置为UserServer端地址，本例设置为本地服务地址
   2var AgentApiHost = 'http://localhost:8936/api';

2. 启动H5服务，或者打开brtc_agent.html， 发起创建和销毁AiAgentInstance实例，测试效果。

互动示例：

填入AppID，点击开始通话，创建AIAgentInstance实例，并开始使用

退出要先点击结束通话， 然后再关闭页面，否则会造成云资源泄漏，导致额外的资源消耗

创建智能体自定义配置示例

客户可根据业务需求灵活创建不同类型的智能体互动实例，通过指定不同的config配置来实现定制化功能。源码提供第三方LLM和TTS配置模版，可以参考以下接口实现：

1. buildGenerateWithQianfan-接入百度千帆大模型服务
2. buildGenerateWithQwen-接入通义千问大模型服务
3. buildConfigureVolcTts-配置火山引擎语音合成服务

通过组合不同的config参数配置，客户可以轻松实现以下定制功能：选择第三方大模型服务提供商、自定义TTS语音合成引擎等。

使用第三方LLM（以Qwen模型为例）

1. 参照接口buildGenerateWithQwen

1public RtcGenerateResponse buildGenerateWithQwen(RtcGenerateRequest request);

2. 添加Qwen模型API-KEY环境变量

1#  Qwen模型配置
2qwen:
3  model: qwen-plus
4  api-key: ${DASHSCOPE_API_KEY}
5  base-url: https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions

2. 设置Config为Qwen模型即可

1// 构建千问配置 - 按照OPENAI协议格式
2Map<String, Object> config = new HashMap<>();
3config.put("llm", "OPENAI");
4config.put("llm_url", openAiConfig.getQwen().getBaseUrl());
5config.put("llm_cfg", model);
6config.put("llm_token", openAiConfig.getQwen().getApiKey());

使用第三方TTS（以火山VOLC为例）

1. 参照接口buildConfigureVolcTts

1public RtcGenerateResponse buildConfigureVolcTts(RtcGenerateRequest request); 

2. 添加火山VOLC环境变量

1  # TTS配置
2  volc:
3    apid: ${VOLC_APID}
4    apikey: ${VOLC_AK}

3. 设置VOLC配置信息

1// 构建VOLC TTS配置 - 使用常量和配置文件
2Map<String, Object> ttsConfigMap = new HashMap<>();
3ttsConfigMap.put("vcn", VOLC_VCN);
4ttsConfigMap.put("vol", VOLC_VOL);
5ttsConfigMap.put("spd", VOLC_SPD);
6ttsConfigMap.put("apid", openAiConfig.getVolc().getApid());
7ttsConfigMap.put("apikey", openAiConfig.getVolc().getApikey());

常见问题

Linux系统安装JDK17步骤

1. 获取JDK安装包，在服务器执行以下命令可以直接下载，或者通过官网下载并上传到服务器

1wget https://download.oracle.com/java/17/archive/jdk-17.0.8_linux-x64_bin.tar.gz

2. 解压JDK安装包，执行以下命令将jdk解压到/opt目录

1tar -zxvf jdk-17.0.8_linux-x64_bin.tar.gz -C /opt

3. 测试JDK安装效果，执行以下命令，观察输出是否正常

1/opt/jdk-17.0.8/bin/java -version

Linux系统服务启动问题

• 端口被占用怎么办？

  Bash 复制

  1# 查看端口占用
  2netstat -tulpn | grep 8936
  3
  4# 如果端口被其他应用占用，建议源码打开项目修改application.yml中的项目端口，重新打包
  5server:
  6  port: 8936

• 服务启动失败怎么办？

  • 检查Java是否安装成功：java -version
  • 检查环境变量是否设置正确

环境变量配置(Mac)

1. 在终端中执行以下命令，查看默认Shell类型

   Bash 复制

   1echo $SHELL

2. 根据默认Shell类型进行操作

   Shell 复制

   1# 执行以下命令来将环境变量设置追加到~/.zshrc文件中
   2
   3# 用您的百度实时音视频RTC应用AK代替YOUR_BCE_APP_AK
   4echo "export BCE_APP_AK='YOUR_BCE_APP_AK'" >> ~/.zshrc
   5
   6# 执行以下命令，使变更生效
   7source ~/.zshrc
   8
   9# 重新打开一个终端窗口，运行以下命令检查环境变量是否生效
   10echo $BCE_APP_AK

   Shell 复制

   1# 执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中
   2
   3# 用您的百度实时音视频RTC应用AK代替YOUR_BCE_APP_AK
   4echo "export BCE_APP_AK='YOUR_BCE_APP_AK'" >> ~/.bash_profile
   5
   6# 执行以下命令，使变更生效
   7source ~/.bash_profile
   8
   9# 重新打开一个终端窗口，运行以下命令检查环境变量是否生效
   10echo $BCE_APP_AK