阿里云虚拟数字人全栈对接实战：从开通到多端集成与成本优化

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是调用OpenAPI和SDK的凭证，需要在阿里云控制台的AccessKey管理页面创建。出于安全考虑，强烈建议使用RAM子账号的AccessKey而非主账号。RAM（访问控制）是阿里云提供的管理用户身份与资源访问权限的服务，使用RAM可以避免与其他用户共享阿里云账号密钥，并可按需为用户授予最小权限。具体操作步骤为：登录RAM控制台，在左侧导航栏选择「身份管理」>「用户」，单击「创建用户」输入登录名称和显示名称。创建完成后为RAM用户授权，至少需要授予虚拟数字人（LingMou）的相关权限策略。

3. 控制台数字人项目创建与配置

完成服务开通后，需要进入虚拟数字人开放平台创建项目并完成相关配置。

3.1 创建数字人项目

进入虚拟数字人开放平台控制台，选择「开发者中心」-「项目管理」，点击「新建项目」。选择数字人形象、应用场景（如资讯播报、智能客服等），填写项目信息，关联合适的实例。配置项目包括数字人形象、动作库、页面布局和效果预览等。

3.2 数字人形象与声音配置

在项目编辑页左侧导航栏点击「形象」，可选择平台提供的2D公共形象或自己创建的定制形象。点击「声音」可以试听并选择公共音色，或选择已在声音库中创建成功的自定义音色。点击「背景」可选择内置背景、纯色背景或上传自定义背景。

3.3 人设与大模型配置

点击左侧导航栏「人设」进行数字人的人物设定配置，将结合大语言模型进行语义理解和回复文本生成。平台支持配置打断关键词和唤醒关键词，实现精细化交互控制。目前支持的大模型包括通义千问、阿里云百炼平台及自研大模型。通义千问-Plus适用于通用对话场景，通义千问-Character强化了话题推进、倾听共情等能力，多用于角色扮演、情感陪伴等场景。使用百炼模型需要填写阿里云百炼API-Key。平台还支持知识库检索（从百炼知识库检索相关内容）、联网搜索、真实时间同步以及短期记忆轮数配置。对于复杂的Agent类需求，可选择对接阿里云百炼应用中心，填入百炼应用ID即可访问在百炼平台创建的Agent。

3.4 获取项目配置参数

项目创建完成后，需要获取以下关键参数用于后续的API调用和SDK集成：租户ID（TenantId）是当前登录的阿里云账号在虚拟数字人开放平台的唯一标识；配置ID即对话数字人的项目ID，可通过控制台对话互动页面点击项目右下角「更多」选项查看；实例ID需要在数字人实时交互服务购买完成后，前往阿里云「我的订单」页面查询；License可在控制台右下角「API服务」处的SDK-License管理中申请。

4. 服务端OpenAPI核心接口调用

虚拟数字人开放平台的服务端API采用阿里云标准OpenAPI接入方案，目前API SDK支持Java、Python等多种开发语言。

4.1 SDK引入与依赖配置

以Java为例，需要在Maven项目的pom.xml中添加虚拟数字人开放平台服务端SDK依赖。需要注意的是，SDK版本需升级至1.0.5及以上。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>lingmou20250527</artifactId>
    <version>1.0.5</version>
</dependency>

4.2 创建实时数字人会话（CreateChatSession）

CreateChatSession是创建实时数字人会话的核心接口，调用后获取对话初始化信息，包括RTC参数和IM参数。该接口的入参在2026年4月有过变更，建议开发者参考最新API文档。

import com.aliyun.lingmou20250527.Client;
import com.aliyun.lingmou20250527.models.CreateChatSessionRequest;
import com.aliyun.lingmou20250527.models.CreateChatSessionResponse;
import com.aliyun.teaopenapi.models.Config;
public class CreateChatSessionExample {
    public static void main(String[] args) throws Exception {
        Config config = new Config()
            .setAccessKeyId("your-access-key-id")
            .setAccessKeySecret("your-access-key-secret")
            .setEndpoint("lingmou.aliyuncs.com");
        
        Client client = new Client(config);
        
        CreateChatSessionRequest request = new CreateChatSessionRequest()
            .setTenantId("your-tenant-id")
            .setSessionId("your-session-id")
            .setConfigId("your-config-id")
            .setInstanceId("your-instance-id");
        
        CreateChatSessionResponse response = client.createChatSession(request);
        System.out.println("Session ID: " + response.getBody().getData().getSessionId());
        System.out.println("RTC Token: " + response.getBody().getData().getToken());
    }
}

4.3 提交离线视频合成任务

离线视频合成适用于不需要实时交互的场景，开发者提交文本后，服务端异步生成数字人播报视频。提交任务接口会立即返回一个TaskUuid作为本次任务的唯一标识，后续可根据TaskUuid调用查询和取消任务接口。视频合成速率大约为1:2，即1分钟视频预计2分钟左右可以合成完毕。

import com.aliyun.lingmou20250527.models.SubmitBroadcastVideoTaskRequest;
import com.aliyun.lingmou20250527.models.SubmitBroadcastVideoTaskResponse;
public class SubmitBroadcastTaskExample {
    public static void main(String[] args) throws Exception {
        // 配置同上方
        Client client = new Client(config);
        
        SubmitBroadcastVideoTaskRequest request = new SubmitBroadcastVideoTaskRequest()
            .setTenantId("your-tenant-id")
            .setSceneId("your-scene-id")
            .setSpeechText("欢迎使用阿里云虚拟数字人服务，今天我们将为大家介绍数字人的对接流程。");
        
        SubmitBroadcastVideoTaskResponse response = client.submitBroadcastVideoTask(request);
        String taskUuid = response.getBody().getData().getTaskUuid();
        System.out.println("Task UUID: " + taskUuid);
    }
}

4.4 Python SDK调用示例

虚拟数字人开放平台同样支持Python语言，可通过pip安装官方SDK后调用。

from aliyunsdkcore.client import AcsClient
from aliyunsdklingmou.request.v20250527 import CreateChatSessionRequest
client = AcsClient(
    'your-access-key-id',
    'your-access-key-secret',
    'cn-hangzhou'
)
request = CreateChatSessionRequest.CreateChatSessionRequest()
request.set_TenantId('your-tenant-id')
request.set_ConfigId('your-config-id')
request.set_InstanceId('your-instance-id')
response = client.do_action_with_exception(request)
print(response)

5. Web端SDK集成

Web端集成是数字人应用最常见的场景之一。阿里云提供了lm-avatar-chat-sdk（灵眸数字人对话Web SDK），支持云端推流数字人和端到端渲染数字人两种模式。

5.1 NPM安装与依赖

根据使用的包管理器选择对应命令安装lm-avatar-chat-sdk，当前最新版本为1.1.4。

npm install lm-avatar-chat-sdk
// 或
pnpm install lm-avatar-chat-sdk
// 或
yarn add lm-avatar-chat-sdk

5.2 云渲染数字人集成

云渲染数字人底层通过阿里云RTC进行音视频流的传输，需要挂载在一个video元素上。

<!-- HTML挂载元素 -->
<video id="cloudAvatarContainer" muted></video>

import { createAvatar, TYAvatarType, TYVoiceChatMode } from 'lm-avatar-chat-sdk';
// 初始化参数
const avatarInitParams = {
    rootContainer: '#cloudAvatarContainer',
    appId: 'your-app-id',
    channel: 'your-channel',
    userId: 'your-user-id',
    token: 'your-rtc-token',
    // 其他RTC参数从CreateChatSession接口获取
};
// 创建云端渲染数字人
const avatar = createAvatar(TYAvatarType.cloudAvatar, avatarInitParams);
// 启动对话，支持tap2talk和duplex两种模式
avatar.start({
    mode: TYVoiceChatMode.tap2talk
});

语音交互模式分为两种：tap2talk模式下，SDK内部的语音服务会实时识别用户语音输入，但打断数字人需要通过额外事件触发，如点击屏幕或按钮。duplex双工模式下，数字人在说话状态下仍可接受用户的语音打断信号，但容易受外部环境音影响导致频繁打断，建议在相对安静的环境下使用。

5.3 端渲染数字人集成

端渲染数字人SDK会创建一个canvas用于渲染数字人画面，需要挂载在一个div元素上。目前纯端渲染全链路模式只支持3D端渲染数字人。

<!-- HTML挂载元素 -->
<div id="localAvatarContainer"></div>

import { createAvatar, TYAvatarType, TYVoiceChatMode } from 'lm-avatar-chat-sdk';
// 端渲染需要额外的资产信息
const avatarInitParams = {
    rootContainer: '#localAvatarContainer',
    appId: 'your-app-id',
    channel: 'your-channel',
    userId: 'your-user-id',
    token: 'your-rtc-token',
    assetModel: {
        // 端渲染数字人资产信息
        modelId: 'your-model-id',
        // 其他资产参数
    }
};
const avatar = createAvatar(TYAvatarType.clientAvatar, avatarInitParams);
avatar.start({
    mode: TYVoiceChatMode.duplex
});

5.4 事件回调与状态管理

SDK提供丰富的事件回调机制，开发者可按需绑定。

// 首帧渲染完成回调
avatar.onFirstFrameReceived(() => {
    console.log('数字人渲染完毕');
});
// 可进行语音交互回调
avatar.onReadyToSpeech(() => {
    console.log('可以进行语音交互了');
});
// 错误处理回调
avatar.onErrorReceived((err) => {
    console.log('数字人内部发生错误:' + err.code + ' ' + err.message);
    if (err.terminate) {
        // 服务端已退出，执行业务前端退出逻辑
    }
});
// 状态变化回调
avatar.onStateChanged((tyState) => {
    console.log('当前数字人状态:' + tyState);
});
// 音量变化回调
avatar.onVolumeChanged((data) => {
    if (data.source === 'mic') {
        console.log('用户音量:' + data.volume);
    } else {
        console.log('数字人音量:' + data.volume);
    }
});
// 消息回调
avatar.onMessageReceived((msg) => {
    if (msg.type === 'speaking') {
        console.log('用户的对话文本:', msg.text);
    } else {
        console.log('数字人的反馈文本:', msg.text);
    }
});

5.5 核心控制方法

// 暂停/恢复收音
avatar.muteLocalMic(true);  // 暂停
avatar.muteLocalMic(false); // 恢复
// 打断数字人当前说话
avatar.interrupt();
// 退出数字人会话
avatar.exit();

5.6 接入注意事项

受浏览器底层WebSocket、录音权限、WebRTC等限制，本地开发环境仅支持使用localhost运行。生产环境页面协议必须使用HTTPS，否则会出现录音权限获取失败、拉流播放失败等问题。本地启动Demo时需使用默认的localhost域名，因为浏览器仅在安全上下文（HTTPS或http://localhost）中允许进行RTC通信。

6. Android端SDK集成

阿里云虚拟数字人开放平台提供适用于Android的数字人流媒体服务SDK。当调用服务端OpenAPI StartInstance接口获取RTC和IM参数信息后，可在Android应用中搭建数字人拉流和双工对话功能。

6.1 SDK集成

将下载得到的AliyunAvatarSDK.aar放入app模块下的libs文件夹中，并在app/build.gradle文件中添加依赖。

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'])
    // 其他依赖
}

6.2 云渲染音频驱动模式

云端渲染-音频驱动数字人通过阿里云RTC提供鉴权通道，SDK支持通过外部传入音频，完成数字人的口型推理、面部驱动、渲染等全流程。该模式不具备完整的语音交互，仅支持调用侧传入音频进行驱动，支持在数字人播报时进行打断。

6.3 纯端渲染全链路模式

纯端渲染-全链路数字人通过阿里云RTC提供鉴权通道，SDK在Android App上拉取音频并在端侧完成数字人的口型推理、面部驱动、渲染等全流程。端渲染SDK无需借助音视频流媒体服务，直接利用终端设备对3D数字人进行渲染，免去了音视频的推拉流，降低了交互延迟。

7. 实时工作流中的数字人集成

阿里云智能媒体服务（IMS）的AI实时互动工作流支持集成数字人节点，将工作流中的语音输入转化为具有二维或三维形象的数字人。

7.1 阿里灵境数字人集成

实时工作流目前支持的数字人来源包括阿里灵境数字人和相芯数字人。需要注意的是，通义星尘数字人已于2025年8月31日正式下线。使用阿里灵境数字人需通过提交工单获取租户ID、交互配置ID、鉴权AK和鉴权SK。然后在AI实时互动工作流界面创建实时工作流，单击数字人节点，选择对接阿里灵境数字人，填入上述参数后保存。

7.2 相芯数字人集成

相芯数字人以其细腻逼真的面部细节和流畅自然的动作表现著称，适合在线客服、虚拟主播等场景。集成相芯数字人需要先开通相芯科技3D数字人服务，联系客服获取AppId、AppKey和AvatarId。然后在控制台工作流中单击数字人节点，选择对接数字人插件，填入获取的参数后保存。

8. 常见错误排查

8.1 启动数字人实例提示「没有闲置资源」

该提示表示购买的数字人实例路数全部在使用中，导致无法启动新的数字人实例。解决方案是等待已有实例释放，或购买更多并发路数。

8.2 录音权限与拉流失败

生产环境必须使用HTTPS协议，本地开发使用localhost。检查浏览器是否授予了麦克风权限。

8.3 API调用返回错误

确认AccessKey具有正确的RAM权限策略。确认SDK版本已升级至1.0.5及以上。确认传入的TenantId、ConfigId、InstanceId等参数正确无误。

9. 安全加固与成本优化

9.1 RAM最小权限原则

推荐使用RAM身份（RAM用户或RAM角色）来访问虚拟数字人服务，避免使用主账号AccessKey。RAM用户需要由主账号或拥有管理员权限的RAM用户创建，且必须在获得授权后才能登录控制台或使用API访问资源。虚拟数字人（LingMou）为RAM权限策略定义了完整的操作（Action）、资源（Resource）和条件（Condition）。

9.2 Token鉴权与回调安全

RTC入房Token作为鉴权凭证，需妥善保管。虚拟数字人开放平台的回调事件通知支持HTTP接口方式，并提供了鉴权原理。

9.3 成本优化策略

阿里云虚拟数字人支持按量付费和包年包月两种计费模式。新用户推荐先使用按量付费进行测试和验证。按量付费适用于初期探索和波动性业务，包年包月适用于长期稳定运行的 production 环境。并发路数决定了同时可运行的数字人实例数量，需根据业务峰值合理规划。离线视频合成按合成时长计费，合成速率约为1:2。建议在控制台监控面板中持续关注调用量和使用费用，及时调整套餐配置。

10. 总结

阿里云虚拟数字人开放平台提供了从2D到3D、从云渲染到端渲染、从播报到互动的完整产品矩阵，覆盖Web、Android、iOS等多端集成场景。开发者通过服务开通、RAM权限配置、控制台项目创建、服务端OpenAPI调用、端侧SDK集成五个核心步骤，即可快速完成数字人应用的搭建。在安全方面应遵循RAM最小权限原则，在成本方面需根据业务场景合理选择计费模式和并发路数。