2D互动数字人接入指南

能力介绍

2D互动数字人是虚拟数字人开放平台提供能够支持用户与2D数字人进行实时语音交互的数字人产品能力，需要配合智能对话机器人产品使用。

目前互动数字人支持文本、语音两种交互方式，同时在数字人说话中可以支持通过特定话术进行打断，实现更加友好的双工语音对话体验。

使用场景

适用于一些需要真人与数字人进行交互的场景，如线下大屏，数字人客服等场景。

前置条件

下述介绍接入2D互动数字人需要提前完成的步骤，每个步骤都需要完成才能顺利接入2D互动数字人。

1. 申请阿里云账号

• 具体参考准备工作

2. 申请购买权限，完成购买开通服务

• 具体参考开通服务

3. 开通智能对话机器人

• 开通智能对话机器人

• 进入智能对话机器人后台，创建机器人，机器人类型选择“在线文本机器人”

• 配置对应知识库

• 从智能对话机器人控制台获取对应机器人的机器人id

4. 进入虚拟数字人开放平台创建并配置应用

互动数字人的创建和配置与播报数字人大体相同，具体创建和配置流程可以参考：创建并配置数字人应用，下面针对互动数字人特有的一些配置做一些介绍。

4.1 智能对话机器人配置

• 在上述图中所示位置添加第三步获取到的智能对话机器人的机器人id，密钥ID和密钥Secret是阿里云账号的AccessKey ID和AccessKey Secret（点击获取，建议通过子账号的方式获取AK&SK）。

技术接入

下面介绍接入互动数字人的完整步骤以及涉及到API

1. 了解虚拟数字人开放平台服务端API接入方式

虚拟数字人开放平台的服务端API采用OpenAPI形式对外输出，具体对接方案见：服务端 API 接入篇。

2. SDK版本要求

3. 调用OpenAPI启动一路数字人实例

下面介绍通过Java调用OpenAPI启动一路数字人实例的代码示例，获取到返回的sessionId以及token。

代码示例：

参考OpenAPI官网调试页面，可在线直接填写参数并执行测试。

4. 通过WebSocket对接互动数字人

互动数字人需要客户端通过WebSocket协议与服务端进行语音流的传输，下面将为您介绍如何通过WebSocket对接互动数字人。

1. 与虚拟数字人开放平台建立WebSocket长连接

• 如何与虚拟数字人开放平台建立WebSocket长连接，请参考：通用WebSocket接入指南。

2. 通过WebSocket发送互动数字人对话请求

在建立与虚拟数字人开放平台WebSocket服务端连接之后，客户端需要按照互动数字人的对话协议发送对应的请求数据。

2.1 启动对话，初始化对话配置

通过websocket发送启动对话消息，协议如下：

5{
  "messageId": "<messageId>", // 必传，消息id，需要保证唯一，可以直接生成16位随机数
  "receiverId": "ability", // 必传，固定值
  "receiverType": "server", // 必传，固定值
  "sticky": true, // 必传，固定值
  "receiverAppId": "<appId>", // 必传，数字人应用的开发者信息中的appId
  "content": {
  "type": "start", // 必传，固定值，表示是启动对话
  "sessionId": "<sessionId>", // 必传，StartInstance接口返回的sessionId
  "format": "<format>", // 可选，音频数据格式，目前支持pcm和wav，不传默认pcm 
  "sampleRate": "<sampleRate>" // 可选，音频采样率，目前支持16000和8000，不传默认16000
  }
 }

• 参考websocket接入文档，发送该消息需要在消息体前面增加一个5，表示是业务消息。

2.2 等待服务端启动完成

服务端收到启动对话消息之后会进行对话的启动，启动完成之后会下发一条启动完成的消息，结构如下：

5{ 
  "content": {
  "sessionId": "8afe971f-0f9c-466a-996b-6beeafd7ae72",
  "type": "startResult", // type=startResult表示启动结果消息
  "status": true // status表示启动成功或者失败，false表示失败，如果遇到失败可重新发送启动消息
  },
  "messageId": "473220b6-9062-4b5f-bae6-910f622c943e", // 通信的一些协议参数，可直接忽略，重点关注content内容
  "tenantId": 20004,
  ...
 }

收到该消息，且status=true之后，才能进行后续的语音流的发送，在此之前发送语音流会被服务端直接丢弃。

2.3 持续发送语音流数据

5{
  "messageId": "<messageId>", // 必传，消息id，需要保证唯一，可以直接生成16位随机数
  "receiverId": "ability", // 必传，固定值
  "receiverType": "server", // 必传，固定值
  "sticky": true, // 必传，固定值
  "receiverAppId": "<appId>", // 必传，数字人应用的开发者信息中的appId
  "content": {
  "type": "dataSend", // 必传，固定值，表示是发送语音数据
  "sessionId": "<sessionId>", // 必传，StartInstance接口返回的sessionId
  "audio": "<语音数据base64之后的文本>",// 可选，语音数据base64字符串（文本和语音必传一个）
  "text": "<text>" // 可选，文本，可直接发送文本与互动数字人进行对话
  }
 }

语音流的发送建议每隔100ms发送一次，发送最快不要小于50ms，发送太快可能会导致无法识别。语音数据在发送前需要进行base64编码。同时语音流需要连续发送，如果没有声音可以发送静音包，长时间不发送音频流可能会导致对话中断。

服务端在收到客户端发送的语音流之后，会调用语音转文本服务，最终拿到文本调用智能客服机器人的对话服务，如果客户端发送的是文本，则直接拿文本调用智能客户机器人的对话服务（调用的机器人实例是在互动数字人应用配置页面配置的机器人信息），最终拿到智能客服机器人的回复文本，触发数字人播报对应的回复文本。在这过程中服务端会返回客户端识别到的文本，以及智能客服机器人的回复文本，下面是返回的具体协议。

2.4 服务端返回语音文本识别结果

服务端在语音转文本服务识别到一句完整的句子时会将识别到的文本返回给客户端。

5{
  "content": {
  "type": "asrContent", // 表示是下发语音识别文本消息
  "sentenceId": "b60e43b53333437a9d312a62518a5b3c", // 本次识别到的内容的id
  "text": "你好。", // 本次识别到的文本
  "sessionId": "028f5247-d089-4fd2-800b-dab5148d5407", // 对应的sessionId
  "isFinished": true // true表示是一句话结束
  },
  "messageId": "221d0c82-c73e-4c13-9324-8c7947cf199a", // 通信的一些协议参数，可直接忽略，重点关注content内容
  "tenantId": 20004,
  ...
 }

2.5 服务端返回对话回复结果

服务端在语音转文本服务识别到一句完整的句子时会将识别到的文本调用智能客服机器人的对话服务，拿到对应的对话回复文本，从而驱动数字人播报对应的回复文本，同时服务端会将回复文本返回给客户端。

5{
  "content": {
  "type": "replyContent", // 表示是下发智能客服机器人回复的文本消息
  "sentenceId": "b60e43b53333437a9d312a62518a5b3c", // 本次识别到的内容的id
  "text": "我在听，请讲。", // 智能客服机器人回复的文本
  "sessionId": "028f5247-d089-4fd2-800b-dab5148d5407" // 对应的sessionId
  },
  "messageId": "221d0c82-c73e-4c13-9324-8c7947cf199a", // 通信的一些协议参数，可直接忽略，重点关注content内容
  "tenantId": 20004,
  ...
 }

2.6 停止对话

在完成一通对话之后，客户端可主动发起停止对话。

5{
  "messageId": "<messageId>", // 必传，消息id，需要保证唯一，可以直接生成16位随机数
  "receiverId": "ability", // 必传，固定值
  "receiverType": "server", // 必传，固定值
  "sticky": true, // 必传，固定值
  "receiverAppId": "<appId>", // 必传，数字人应用的开发者信息中的appId
  "content": {
  "type": "stop", // 必传，固定值，表示是停止对话
  "sessionId": "<sessionId>", // 必传，StartInstance接口返回的sessionId
  }
 }

在停止对话之后，需要对应的数字人实例没有停止的情况下，可以重新启动对话服务。

5. 接入RTC客户端进行拉流

接入RTC客户端可参考文档：3D数字人实时流媒体。需要使用到第二步中获取到的Channel信息。

6. 调用OpenAPI停止对应数字人实例

下面介绍通过Java调用OpenAPI启动一路数字人实例的代码示例，需要使用到第二步中获取的sessionId。

代码示例：

参考OpenAPI官网调试页面，可在线直接填写参数并执行测试。

7. sessionId丢失如何停止数字人实例

针对运行中的数字人实例，如果sessionId丢失将无法调用StopInstance接口停止，此时可通过调用QueryRunningIntance接口获取到正在运行中的数字人实例列表，从而获取到对应的sessionId。

代码示例：

参考OpenAPI官网调试页面，可在线直接填写参数并执行测试。