阿里云虚拟数字人全栈对接指南:从开通到多端集成(含代码示例)
目录
- 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需从控制台资产中心获取,不同形象支持动作不同。