阿里云虚拟数字人全栈对接实战：从开通到多端集成与性能优化
1. 虚拟数字人核心概念与场景选型
阿里云虚拟数字人（Digital Virtual Human，简称DVH）是基于达摩院在语音、图像、3D美术、自然语言处理等领域的技术优势，以AI驱动实时渲染为核心能力构建的多模态交互数字人服务。虚拟数字人开放平台以标准PaaS接口与后台运营工具的形式，将数字人能力输出给开发者，方便集成进不同的终端与场景。在正式对接之前，开发者需要理解几个核心维度，以便做出正确的技术选型。
1.1 形象形态：2D与3D
2D数字人基于真人照片或视频生成，形象轻量化，适合Web、H5、移动端等场景，成本相对较低。3D数字人是高精度三维模型，动作表情更细腻，适合大屏、VR、高端直播等对视觉品质要求较高的场景。平台同时提供预置的公共形象库，也支持开发者上传自定义形象进行训练。
1.2 渲染模式：云渲染与端渲染
云渲染模式下，数字人的渲染、唇形合成、动作驱动全流程在阿里云服务器完成，终端仅拉取视频流，适合高画质、低并发场景。端渲染模式下，数字人资产与轻量推理模型下发至终端，本地完成渲染与驱动，适合高并发、低延迟场景，如APP内嵌数字人。目前端渲染SDK主要支持3D数字人。
1.3 交互模式：播报与互动
播报模式是数字人单向播报文本或音频，无交互能力，适用于资讯播报、公告等场景。互动模式支持文本或语音双向对话，集成ASR（语音识别）、LLM（大语言模型）、TTS（语音合成）能力，适用于智能客服、咨询等场景。互动数字人需要结合智能对话机器人一起使用。
1.4 场景选型建议
Web/H5资讯播报推荐2D数字人+云渲染+播报模式，通过Web SDK集成。网页智能客服推荐2D数字人+云渲染+互动模式。线下大屏互动推荐3D数字人+端渲染，通过Android SDK集成。APP内嵌数字人推荐2D数字人+端渲染。离线视频生成则使用OpenAPI调用离线合成接口。
需要先登录阿里云控制台，点击：阿里云控制台
2. 服务开通与前置权限配置
对接阿里云虚拟数字人前，需完成账号注册、服务开通、权限配置三大前置步骤。
2.1 账号注册与服务开通
首先注册阿里云账号并完成实名认证，企业账号可开通更高并发权限。进入阿里云官网搜索「虚拟数字人」，进入产品详情页后点击「立即开通」。计费模式支持按量付费和包年包月两种，新用户推荐先使用按量付费进行测试。开通关联服务方面，互动模式需要开通智能对话机器人、智能语音交互（ASR/TTS）；离线合成需要开通智能创作服务。数字人平台为每个阿里云客户提供7天数字人对话免费体验权益，在免费体验期内可在控制台创建10个2D数字人实时对话项目。
2.2 AccessKey创建与权限配置
登录阿里云控制台，进入AccessKey管理页面，创建或使用已有的AccessKey ID和AccessKey Secret。为了安全起见，强烈建议使用RAM子账号而非主账号进行API调用。具体操作是：在RAM控制台创建子账号，授予AliyunAvatarFullAccess或更细粒度的权限策略，然后为该子账号生成AccessKey。
2.3 控制台数字人项目创建
进入虚拟数字人控制台的对话互动页面，点击「立即创建」新建数字人对话项目。创建时需要选择数字人形象（2D或3D）、渲染类型（云渲染或端渲染）、集成类型（全链路集成或音频驱动集成）。创建完成后，在项目详情中可获取项目ID（即对话数字人的项目ID）。
3. 服务端OpenAPI核心接口调用
虚拟数字人开放平台的服务端API采用OpenAPI形式对外输出，目前API SDK支持Java、Python等多种开发语言。整体接入流程包括：获取对话数字人项目ID、获取平台颁发的license、获取订单实例ID、通过CreateChatSession接口获取入会信息。
3.1 Java SDK调用示例
以下是通过Java SDK调用CreateChatSession接口创建实时数字人会话的完整代码示例。
import com.aliyun.avatar20250127.Client;
import com.aliyun.avatar20250127.models.CreateChatSessionRequest;
import com.aliyun.avatar20250127.models.CreateChatSessionResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
public class CreateChatSessionExample {
public static void main(String[] args) throws Exception {
// 1. 配置认证信息
Config config = new Config()
.setAccessKeyId("your-access-key-id")
.setAccessKeySecret("your-access-key-secret")
.setRegionId("cn-beijing"); // 服务地址：华北2（北京）
Client client = new Client(config);
// 2. 构建请求参数
CreateChatSessionRequest request = new CreateChatSessionRequest()
.setProjectId("your-project-id") // 对话数字人的项目ID
.setLicense("your-license") // 平台颁发的license
.setInstanceId("your-instance-id"); // 订单实例ID
// 3. 发起调用
RuntimeOptions runtime = new RuntimeOptions();
CreateChatSessionResponse response = client.createChatSessionWithOptions(request, runtime);
// 4. 获取返回结果：sessionId和rtcParams
String sessionId = response.getBody().getData().getSessionId();
String rtcParams = response.getBody().getData().getRtcParams();
System.out.println("SessionId: " + sessionId);
System.out.println("RtcParams: " + rtcParams);
}
}3.2 Python SDK调用示例
以下是通过Python SDK调用CreateChatSession接口的示例。
from alibabacloud_avatar20250127.client import Client
from alibabacloud_avatar20250127.models import CreateChatSessionRequest
from alibabacloud_teaopenapi.models import Config
from alibabacloud_teautil.models import RuntimeOptions
def create_chat_session():
# 1. 配置认证信息
config = Config(
access_key_id='your-access-key-id',
access_key_secret='your-access-key-secret',
region_id='cn-beijing'
)
client = Client(config)
# 2. 构建请求参数
request = CreateChatSessionRequest(
project_id='your-project-id',
license='your-license',
instance_id='your-instance-id'
)
# 3. 发起调用
runtime = RuntimeOptions()
response = client.create_chat_session_with_options(request, runtime)
# 4. 获取返回结果
session_id = response.body.data.session_id
rtc_params = response.body.data.rtc_params
print(f'SessionId: {session_id}')
print(f'RtcParams: {rtc_params}')
return session_id, rtc_params
if __name__ == '__main__':
create_chat_session()4. Web端SDK集成
Web端集成主要使用lm-avatar-chat-sdk这个JavaScript库，支持云端推流数字人和端到端渲染数字人两种模式。该SDK通过阿里云RTC提供音视频流传输能力，具备低延迟、高性能、高并发、跨平台等优势。
4.1 NPM安装与依赖
根据使用的包管理器选择对应的命令安装依赖包。
npm i lm-avatar-chat-sdk
# 或
pnpm i lm-avatar-chat-sdk
# 或
yarn i lm-avatar-chat-sdk4.2 云渲染数字人集成
云渲染数字人底层通过阿里云RTC进行音视频流的传输，需要挂载在一个video元素上。
<!-- HTML模板中添加video容器 -->
<video id='cloudAvatarContainer' muted></video>import { createAvatar, TYAvatarType, IAvatarInitConfig, TYVoiceChatMode } from 'lm-avatar-chat-sdk';
// 从服务端获取的入会参数
const avatarInitParams = {
rootContainer: 'cloudAvatarContainer',
appId: 'your-app-id',
channel: 'your-channel',
timestamp: 'your-timestamp',
token: 'your-token',
clientUserId: 'your-client-user-id',
clientUserName: 'your-client-user-name',
serverUserId: 'your-server-user-id',
avatarUserId: 'your-avatar-user-id',
sessionId: 'your-session-id'
} as IAvatarInitConfig;
// 创建云渲染数字人实例
const avatar = createAvatar(TYAvatarType.cloudAvatar, avatarInitParams);
// 启动对话，支持tap2talk和duplex两种交互模式
avatar.start({
mode: TYVoiceChatMode.tap2talk
});
// 监听事件回调
avatar.on('onError', (error) => {
console.error('数字人出错:', error);
});
avatar.on('onStateChange', (state) => {
console.log('状态变化:', state);
});4.3 端渲染数字人集成
端渲染数字人通过阿里云RTC提供音频和模型脸部肢体动作数据，SDK在浏览器上通过拉取数据并使用WebGL渲染数字人。端渲染需要额外的资产信息。
<!-- HTML模板中添加div容器 -->
<div id='localAvatarContainer'></div>import { createAvatar, TYAvatarType, IAvatarInitConfig, TYVoiceChatMode, IAvatarAssetModelType } from 'lm-avatar-chat-sdk';
// 端渲染需要额外的资产信息
const avatarInitParams = {
rootContainer: 'localAvatarContainer',
appId: 'your-app-id',
channel: 'your-channel',
timestamp: 'your-timestamp',
token: 'your-token',
clientUserId: 'your-client-user-id',
clientUserName: 'your-client-user-name',
serverUserId: 'your-server-user-id',
avatarUserId: 'your-avatar-user-id',
sessionId: 'your-session-id',
// 端渲染特有：资产信息
assetInfo: {
modelType: IAvatarAssetModelType.type3D,
modelUrl: 'your-model-url'
}
} as IAvatarInitConfig;
// 创建端渲染数字人实例
const avatar = createAvatar(TYAvatarType.clientAvatar, avatarInitParams);
avatar.start({
mode: TYVoiceChatMode.duplex // 双工模式支持实时打断
});4.4 重要注意事项
受浏览器底层WebSocket、录音权限、WebRTC等限制，本地开发环境仅支持使用localhost运行。生产环境上页面协议请使用HTTPS，否则会出现录音权限获取失败、拉流播放失败等问题。若使用SDK对公众提供人工智能生成合成服务，需遵守《互联网信息服务深度合成管理规定》及相关标准要求，履行人工智能生成合成内容标识的义务。
5. Android端SDK集成
Android端SDK支持云渲染和端渲染两种模式。端渲染SDK无需借助音视频流媒体服务，直接利用终端设备对3D数字人进行渲染，免去了音视频的推拉流，降低了交互延迟。
5.1 SDK集成步骤
将下载得到的AliyunAvatarSDK.aar放入app模块下的libs文件夹中，并在app/build.gradle文件中添加导入。
dependencies {
implementation files('libs/AliyunAvatarSDK.aar')
// 其他依赖...
}5.2 权限配置
SDK和数字人交互需要录音权限，在AndroidManifest.xml中声明。
<uses-permission android:name='android.permission.RECORD_AUDIO' />
<uses-permission android:name='android.permission.INTERNET' />5.3 初始化与启动
// 获取从服务端OpenAPI返回的入会参数
String sessionId = 'your-session-id';
String rtcParams = 'your-rtc-params';
// 初始化数字人SDK
AvatarSDK avatarSDK = new AvatarSDK(context);
avatarSDK.init(sessionId, rtcParams);
// 设置事件监听
avatarSDK.setOnEventListener(new AvatarEventListener() {
@Override
public void onStateChanged(int state) {
// 处理状态变化
}
@Override
public void onError(int errorCode, String errorMsg) {
// 处理错误
}
});
// 启动数字人
avatarSDK.start();6. 实时对话与离线合成实现
6.1 实时对话模式
2D数字人实时对话服务提供了云端渲染和端侧渲染两种渲染方式，以及全链路集成和音频驱动集成两种集成方式。全链路集成将数字人实时对话需要的ASR、LLM、TTS以及数字人驱动能力打包在一起，通过SDK方式集成后提供能力。音频驱动集成适用于已有语音实时对话或有特殊化原子能力诉求的客户，仅需要接入数字人驱动的部分。
语音交互模式分为两种：tap2talk模式和duplex双工模式。在tap2talk模式下，SDK内部的语音服务会实时识别用户的语音输入，但用户想打断数字人需要通过额外事件来触发。在duplex双工模式下，数字人在说话状态下仍可以接受用户的语音打断信号。双工模式容易受到外部环境音的影响导致触发频繁打断，建议在相对安静的环境下使用。
6.2 离线视频合成
数字人离线视频合成服务提供根据指定文本让数字人进行文本播报的能力，平台会基于数字人播报的文本智能同步驱动数字人做出相应的嘴型、表情和动作，同时将渲染的数字人画面合成指定格式的视频文件。支持通过API以及SaaS页面两种方式向服务端发送文本。服务端接收到数据后处理成数字人的声音、表情、口型、动作，然后将对应数据合成指定格式的视频，并提供对应的视频下载地址。每位阿里云用户可在平台免费生成视频的时长为10分钟。
7. 常见错误排查与兼容性适配
7.1 常见错误类型
在实际对接过程中，开发者可能会遇到以下几类常见问题：
- 权限错误：AccessKey无权限调用对应接口，需检查RAM策略是否正确授予AliyunAvatarFullAccess或相应权限。
- 参数错误：projectId、license、instanceId等参数获取不正确，需在控制台确认项目ID和订单信息。
- 网络错误：Web端本地开发必须使用localhost，生产环境必须使用HTTPS协议。
- RTC连接失败：检查token是否过期，sessionId和rtcParams是否有效。
7.2 兼容性适配建议
Web端SDK要求浏览器支持WebRTC和WebGL，建议使用Chrome、Firefox、Safari等主流浏览器的最新版本。Android端SDK支持Android 14及以上版本。iOS端SDK支持iOS 14及以上版本。
8. 安全加固与成本优化策略
8.1 RAM最小权限原则
强烈建议使用RAM子账号进行API调用，遵循最小权限原则。具体操作包括：在RAM控制台创建专门用于数字人服务的子账号；仅授予AliyunAvatarFullAccess或更细粒度的自定义策略；定期轮换AccessKey Secret；禁止在代码中硬编码AccessKey，应使用环境变量或配置中心管理。
8.2 Token鉴权机制
CreateChatSession接口返回的token和sessionId具有一定的时效性，需要在有效期内使用。建议在服务端生成token后通过安全通道传递给客户端，避免token在传输过程中泄露。
8.3 成本优化策略
数字人服务支持按量付费和包年包月两种计费模式。新用户推荐先使用按量付费进行测试，待业务稳定后再评估是否转为包年包月。成本优化的核心要点包括：
- 并发路数规划：根据业务峰值合理规划并发路数，避免过度购买造成浪费。
- 渲染模式选择：端渲染模式无需云端渲染资源消耗，适合高并发场景。
- 免费额度利用：充分利用7天免费体验权益和10分钟免费视频生成额度。
9. 工作流集成与数字人节点配置
阿里云AI实时互动工作流支持集成数字人节点，能够将工作流中的语音输入转化为具有二维或三维形象的数字人。目前实时工作流支持的数字人来源包括阿里灵境数字人和相芯数字人。
9.1 阿里灵境数字人集成
使用阿里灵境数字人需要通过提交工单获取灵境租户ID、交互配置ID、鉴权AK以及鉴权SK。获取后在AI实时互动工作流界面创建实时工作流，单击数字人节点，选择对接阿里灵境数字人并填入对应参数。
9.2 相芯数字人集成
相芯数字人以其细腻逼真的面部细节呈现和流畅自然的动作表现著称。集成相芯数字人需要提前获取AppId、AppKey以及AvatarId。需要先开通相芯科技3D数字人服务，联系客服获取AvatarId。然后在工作流中填入对应参数完成配置。
10. 总结与展望
阿里云虚拟数字人开放平台提供了从2D到3D、从云渲染到端渲染、从播报到互动的完整产品矩阵，开发者可以根据业务场景灵活选型。通过服务端OpenAPI获取会话凭证、Web/Android SDK实现终端集成、工作流节点实现业务编排，可以快速构建各类数字人应用。
随着AI技术的快速发展，数字人正在从单向播报向多模态实时交互演进。阿里云将通义大模型能力与数字人深度结合，在电商直播、智能客服、企业培训等场景已有规模化落地实践。未来，数字人将更加智能化、个性化，成为人机交互的重要入口。
常见问答
问1：阿里云虚拟数字人支持哪些开发语言？
答：服务端OpenAPI支持Java、Python、Node.js等多种开发语言。Web端使用JavaScript/TypeScript（lm-avatar-chat-sdk）。移动端支持Android（Java/Kotlin）和iOS（Objective-C/Swift）。
问2：CreateChatSession接口返回的sessionId和token有效期是多久？
答：sessionId和token具有时效性，需要在有效期内使用。建议在每次会话前重新调用接口获取最新参数，不要复用过期凭证。
问3：Web端集成时本地调试正常，部署到服务器后无法使用怎么办？
答：这是由于浏览器安全策略限制所致。本地开发必须使用localhost，生产环境必须使用HTTPS协议。请检查部署环境是否配置了有效的SSL证书。
问4：云渲染和端渲染如何选择？
答：云渲染适合高画质、低并发场景，数字人渲染在云端完成，终端仅播放视频流。端渲染适合高并发、低延迟场景，数字人资产下发至终端本地渲染。建议根据业务并发量和画质要求选择。
问5：数字人服务如何计费？有哪些省钱建议？
答：支持按量付费和包年包月两种模式。省钱建议包括：测试阶段使用按量付费；业务稳定后评估转为包年包月；高并发场景优先选择端渲染模式；充分利用7天免费体验权益。
问6：如何保证数字人API调用的安全性？
答：建议使用RAM子账号代替主账号，遵循最小权限原则；AccessKey Secret禁止硬编码在代码中，应使用环境变量；定期轮换AccessKey；token通过安全通道传输。
