阿里云虚拟数字人全栈对接指南：从开通到多端集成（含代码示例）
阿里云虚拟数字人全栈对接指南：从开通到多端集成（含代码示例）
目录
- 1. 虚拟数字人核心概念与场景选型
- 2. 服务开通与前置权限配置
- 3. 数字人形象创建与管理
- 4. 服务端OpenAPI核心接口调用（Java/Node.js）
- 5. Web端SDK集成（云渲染播报/互动）
- 6. Android端SDK集成（端渲染3D数字人）
- 7. 实时对话与离线合成实现
- 8. 常见错误排查与兼容性适配
- 9. 安全加固与成本优化策略
- 10. 总结与常见问答
1. 虚拟数字人核心概念与场景选型
阿里云虚拟数字人（Digital Virtual Human，简称DVH）是基于阿里云AI能力与实时音视频技术打造的数字人服务，支持2D/3D两种形象形态、云渲染/端渲染两种渲染模式，覆盖资讯播报、智能客服、直播带货、线下大屏互动等核心场景。
1.1 核心概念解析
- 2D数字人：基于真人照片/视频生成，形象轻量化，适配Web/H5/移动端，支持云渲染与端渲染，成本较低。
- 3D数字人：高精度三维模型，动作表情更细腻，适配大屏/VR/高端直播场景，仅支持云渲染（互动）与端渲染（大屏）。
- 云渲染：数字人渲染、唇形合成、动作驱动全流程在阿里云服务器完成，终端仅拉取视频流，适配高画质、低并发场景。
- 端渲染：数字人资产与轻量推理模型下发至终端，本地完成渲染与驱动，适配高并发、低延迟场景（如APP内嵌数字人）。
- 播报模式：数字人单向播报文本/音频，无交互能力，适用于资讯、公告场景。
- 互动模式：支持文本/语音双向对话，集成ASR（语音识别）、LLM（大语言模型）、TTS（语音合成）能力，适用于客服、咨询场景。
1.2 场景选型建议
| 场景 | 推荐形象 | 渲染模式 | 集成方式 |
|---|---|---|---|
| Web/H5资讯播报 | 2D | 云渲染 | WebSDK（播报） |
| 智能客服（网页） | 2D | 云渲染 | WebSDK（互动） |
| 线下大屏互动 | 3D | 端渲染 | AndroidSDK |
| APP内嵌数字人 | 2D | 端渲染 | AndroidSDK/iOSSDK |
| 离线视频生成 | 2D/3D | 云渲染 | OpenAPI（离线合成） |
2. 服务开通与前置权限配置
对接阿里云虚拟数字人前，需完成账号注册、服务开通、权限配置三大前置步骤，确保API调用与SDK集成的权限合法性。
需要先登录阿里云控制台，点击：阿里云控制台
2.1 账号注册与服务开通
- 注册阿里云账号，完成实名认证（企业/个人均可，企业账号可开通更高并发权限）。
- 进入阿里云官网，搜索「虚拟数字人」，进入产品详情页，点击「立即开通」，选择计费模式（按量付费/包年包月，新用户推荐按量付费测试）。
- 开通关联服务：互动模式需开通智能对话机器人、智能语音交互（ASR/TTS）；离线合成需开通智能创作服务。
2.2 AccessKey创建与权限配置
阿里云API与SDK均通过AccessKey（AK/SK）鉴权，需创建最小权限AccessKey，避免权限泄露风险。
- 登录阿里云控制台，点击右上角头像，进入「AccessKey管理」，创建AccessKey（保存AccessKey ID与AccessKey Secret，仅显示一次）。
- 配置RAM权限（推荐，避免主账号AK泄露）：进入「RAM访问控制」，创建用户，绑定自定义策略，授予虚拟数字人相关权限（AvatarFullAccess）。
- 获取核心参数：TenantId（租户ID，虚拟数字人控制台-开发者中心获取）、RegionId（地域ID，推荐cn-zhangjiakou）。
3. 数字人形象创建与管理
开通服务后，需创建数字人形象，支持「官方形象直接选用」与「自定义形象创建」两种方式，自定义形象需基于照片/视频训练生成。
3.1 官方形象选用（快速测试）
- 进入虚拟数字人控制台，点击「形象管理」，选择「官方形象」，筛选2D/3D、云渲染/端渲染形象。
- 点击形象预览，确认动作、表情适配场景，点击「添加到我的形象」，完成形象绑定。
3.2 自定义2D形象创建（照片训练）
通过1张正面高清照片生成2D数字人形象，训练时长约5-10分钟，适用于个性化IP场景。
- 控制台「形象管理」-「创建形象」-「2D形象」-「照片训练」，上传高清正面照片（无遮挡、光线均匀，分辨率≥1080*1920）。
- 填写形象名称、描述，选择背景是否透明，点击「提交训练」。
- 调用接口查询训练状态，返回COMPLETED即训练完成，获取AvatarId（形象ID，后续API调用必传）。
3.3 自定义3D形象创建（视频训练）
通过1-3分钟真人视频生成3D数字人形象，训练时长约1-2小时，适用于高端IP、直播场景。
- 控制台「形象管理」-「创建形象」-「3D形象」-「视频训练」，上传无水印、高清真人视频（正面、无遮挡、光线均匀）。
- 填写形象信息，提交训练，等待完成后获取AvatarId。
4. 服务端OpenAPI核心接口调用（Java/Node.js）
服务端是数字人对接的核心枢纽，负责启动数字人实例、发送播报文本、管理会话、关闭实例，所有SDK集成前必须先调用服务端接口获取会话参数。
4.1 环境准备
以Java为例，引入Maven依赖（Node.js可通过npm安装@alicloud/avatar20220130 SDK）。
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>avatar20220130</artifactId>
<version>1.0.0</version>
</dependency>4.2 核心接口1：StartInstance（启动数字人实例）
启动数字人实例，返回会话ID（SessionId）、RTC拉流参数、IM连接Token，是SDK初始化的前提。
import com.aliyun.tea.*;
import com.aliyun.avatar20220130.*;
import com.aliyun.avatar20220130.models.*;
public class StartInstanceDemo {
// 初始化客户端
public static Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
Config config = new Config()
.setAccessKeyId(accessKeyId)
.setAccessKeySecret(accessKeySecret);
config.endpoint = "avatar.cn-zhangjiakou.aliyuncs.com";
return new Client(config);
}
public static void main(String[] args) throws Exception {
String accessKeyId = "你的AK";
String accessKeySecret = "你的SK";
Long tenantId = 你的TenantId;
String avatarId = "你的形象AvatarId";
Client client = createClient(accessKeyId, accessKeySecret);
StartInstanceRequest request = new StartInstanceRequest()
.setTenantId(tenantId)
.setAvatarId(avatarId)
.setSceneType("BROADCAST") // BROADCAST-播报，CHAT-互动
.setResolution("1080p") // 分辨率：720p/1080p
.setFrameRate(30); // 帧率：25/30
StartInstanceResponse response = client.startInstance(request);
System.out.println("SessionId：" + response.getBody().getSessionId());
System.out.println("RTC Channel：" + response.getBody().getChannel());
System.out.println("IM Token：" + response.getBody().getToken());
}
}4.3 核心接口2：SendText（发送播报文本）
向数字人发送播报文本，支持纯文本与SSML格式（自定义发音、动作），互动模式下用于回复用户提问。
public class SendTextDemo {
public static void main(String[] args) throws Exception {
Client client = createClient("你的AK", "你的SK");
Long tenantId = 你的TenantId;
String sessionId = "启动实例返回的SessionId";
String uniqueCode = UUID.randomUUID().toString(); // 唯一标识
SendTextRequest request = new SendTextRequest()
.setTenantId(tenantId)
.setSessionId(sessionId)
.setText("大家好，我是阿里云虚拟数字人，很高兴为您服务！")
.setInterrupt(true) // 是否打断当前播报
.setUniqueCode(uniqueCode);
SendTextResponse response = client.sendText(request);
System.out.println("播报结果：" + response.getBody().getSuccess());
}
}4.4 核心接口3：StopInstance（关闭数字人实例）
数字人使用完毕后关闭实例，释放云端资源，避免计费浪费。
public class StopInstanceDemo {
public static void main(String[] args) throws Exception {
Client client = createClient("你的AK", "你的SK");
Long tenantId = 你的TenantId;
String sessionId = "启动实例返回的SessionId";
StopInstanceRequest request = new StopInstanceRequest()
.setTenantId(tenantId)
.setSessionId(sessionId);
StopInstanceResponse response = client.stopInstance(request);
System.out.println("关闭结果：" + response.getBody().getSuccess());
}
}5. Web端SDK集成（云渲染播报/互动）
Web端SDK（aliyun-avatar-sdk）基于阿里云RTC与WebSocket，支持云渲染2D数字人的播报与互动，仅兼容HTTPS协议页面。
5.1 集成准备
- 页面协议必须为HTTPS（localhost本地测试除外），否则无法获取麦克风权限、拉取视频流。
- 通过CDN引入SDK（新版仅支持CDN引入，不支持npm安装）。
<!-- 引入SDK -->
<script src="https://g.alicdn.com/xr-paas/avatar-dingrtc-sdk/0.0.5/index.js"></script>
<!-- 视频容器 -->
<div id="videoContainer" style="width:800px;height:600px;"></div>5.2 播报模式集成（BroadcastingAvatarSDK）
适用于资讯、公告场景，仅拉取数字人视频流，无交互能力。
<script>
// 服务端StartInstance返回的参数
const startInstanceRes = {
channel: {
AppId: "RTC AppId",
ChannelId: "RTC ChannelId",
ExpiredTime: "过期时间",
Token: "RTC Token",
UserId: "RTC UserId"
}
};
// 初始化播报SDK
const BroadcastingAvatarSDK = window.BroadcastingAvatarSDK;
const broadcastSDK = new BroadcastingAvatarSDK({
channel: {
appId: startInstanceRes.channel.AppId,
channelId: startInstanceRes.channel.ChannelId,
expiredTime: startInstanceRes.channel.ExpiredTime,
token: startInstanceRes.channel.Token,
userId: startInstanceRes.channel.UserId
},
videoContainer: document.getElementById("videoContainer"),
options: {
rtc: { muted: false, chromaKey: false }
},
onInitSuccess: () => {
console.log("RTC拉流成功，数字人加载完成");
},
onError: (e) => {
console.error("错误：", e);
}
});
// 初始化
broadcastSDK.init().then(() => {
console.log("初始化成功");
});
</script>5.3 互动模式集成（DialogAvatarSDK）
适用于客服、咨询场景，支持语音/文本双向对话，集成ASR识别与TTS合成。
<script>
// 服务端StartInstance返回的参数
const startInstanceRes = {
sessionId: "会话ID",
token: "IM Token",
channel: { /* RTC参数同播报模式 */ }
};
// 初始化互动SDK
const DialogAvatarSDK = window.DialogAvatarSDK;
const dialogSDK = new DialogAvatarSDK({
tenantId: "你的TenantId",
appId: "你的应用ID",
sessionId: startInstanceRes.sessionId,
token: startInstanceRes.token,
channel: startInstanceRes.channel,
videoContainer: document.getElementById("videoContainer"),
options: {
audio: { autoStartRecord: false, interval: 100 },
rtc: { muted: false }
},
onInitSuccess: () => {
console.log("IM连接+RTC拉流成功");
},
onASR: (text, sentenceId) => {
console.log("用户语音识别结果：", text);
// 调用后端接口，将text传给大模型，获取回复后调用SendText
},
onAnswer: (text, sentenceId) => {
console.log("数字人回复：", text);
}
});
// 初始化
dialogSDK.init().then(() => {
// 开启录音（语音对话）
dialogSDK.startRecording();
// 发送文本对话
dialogSDK.sendText("你好，请问有什么可以帮助您？");
});
</script>6. Android端SDK集成（端渲染3D数字人）
Android端SDK适用于大屏设备（Android 8.0+），支持端渲染3D数字人，本地完成渲染与驱动，延迟更低。
6.1 集成准备
- 硬件要求：高通845/RK3588及以上配置，仅支持大屏设备，不支持手机端。
- 导入aar包：将AvatarClientRenderSDK.aar放入app/libs目录，配置build.gradle依赖。
// app/build.gradle
dependencies {
implementation fileTree(include: ['*.aar'], dir: 'libs')
// 必选依赖
implementation 'androidx.lifecycle:lifecycle-common:2.4.0'
implementation 'com.alibaba:fastjson:1.2.83'
implementation 'com.squareup.okhttp3:okhttp:4.4.1'
implementation 'com.aliyun:tea-openapi:0.3.0'
}6.2 核心集成步骤
- 申请License：在虚拟数字人控制台-API服务页面申请端渲染License。
- 初始化SDK：传入License、AvatarId、会话参数，初始化渲染引擎。
- 加载数字人资产：下载并加载3D数字人模型、动作、表情资产。
- 发送指令：调用接口发送文本/动作指令，驱动数字人播报、做动作。
7. 实时对话与离线合成实现
7.1 实时对话全链路（互动模式）
实时对话集成ASR（语音识别）、LLM（大语言模型）、TTS（语音合成）、数字人驱动四大能力，流程如下：
- 用户说话→Web/Android端录音→ASR识别为文本。
- 前端将文本传给后端→后端调用LLM（如通义千问）生成回复文本。
- 后端调用SendText接口→驱动数字人播报回复文本。
- 数字人播报→TTS合成语音+唇形/动作同步→前端播放视频流。
7.2 离线视频合成（无实时会话）
适用于批量生成数字人视频（如短视频、课程视频），无需实时会话，调用离线合成接口，异步生成视频后下载。
// 离线合成接口调用（Java）
CreateOfflineVideoRequest request = new CreateOfflineVideoRequest()
.setTenantId(tenantId)
.setAvatarId(avatarId)
.setText("离线播报文本，支持长文本")
.setVoiceId("音色ID")
.setResolution("1080p")
.setFormat("mp4");
CreateOfflineVideoResponse response = client.createOfflineVideo(request);
// 异步查询合成状态，完成后获取视频下载地址8. 常见错误排查与兼容性适配
8.1 Web端常见错误
- 录音失败（无权限）：页面非HTTPS协议；浏览器未开启麦克风权限；移动端H5不支持微信/淘宝内置浏览器。
- 拉流无画面：StartInstance参数错误（大驼峰未转小驼峰）；RTC Token过期；网络防火墙拦截RTC端口。
- 数字人无声音：浏览器自动播放限制，需用户点击页面后播放；SDK初始化时muted设为true。
8.2 兼容性适配
- 浏览器：支持Chrome 83+、Edge 83+、Safari 11+；不支持火狐、华为Chrome、小程序。
- 设备：Web端适配PC/平板；Android端仅适配大屏设备；iOS端需原生集成SDK。
9. 安全加固与成本优化策略
9.1 安全加固
- 权限最小化：使用RAM子账号AK，仅授予数字人相关权限，禁止主账号AK泄露。
- HTTPS强制：所有Web端页面强制HTTPS，防止数据劫持。
- 会话管理：数字人会话超时自动关闭，定期清理无效会话。
9.2 成本优化
- 实例复用：避免频繁启停实例，复用会话降低计费次数。
- 分辨率适配：非大屏场景使用720p分辨率，减少带宽消耗。
- 按量付费测试：新用户优先按量付费，测试稳定后切换包年包月。
10. 总结与常见问答
阿里云虚拟数字人对接核心是「服务端控实例、SDK拉流渲染、能力集成做互动」，先开通服务、创建形象，再通过OpenAPI管理会话，最后集成Web/Android SDK实现渲染与交互。2D云渲染适合Web快速落地，3D端渲染适合大屏高交互场景，离线合成适合批量视频生成，开发者可根据场景灵活选型。
常见问答
Q1：虚拟数字人支持哪些形象类型？
A1：支持2D（照片/视频训练）、3D（视频训练）两种类型，2D适配轻量化场景，3D适配高精度场景。
Q2：Web端SDK是否支持微信小程序？
A2：不支持，小程序环境限制WebRTC与麦克风权限，需原生APP集成或使用H5页面（浏览器打开）。
Q3：数字人训练需要多长时间？
A3：2D照片训练约5-10分钟，3D视频训练约1-2小时，训练完成后可直接使用。
Q4：互动模式必须开通智能对话机器人吗？
A4：是的，互动模式依赖智能对话机器人的对话管理能力，需开通并配置机器人。
Q5：如何降低数字人对接成本？
A5：复用实例减少启停次数、适配720p分辨率降低带宽、新用户按量付费测试、选择包年包月套餐。
Q6：数字人是否支持自定义动作？
A6：支持，通过SSML标签或VAML文本传入动作Code，动作Code需从控制台资产中心获取，不同形象支持动作不同。