Projects/antiwear-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 新增华为云MetaStudio交互数字人完整配置指南

Browse Source
This commit is contained in:
ZF Sun
2026-04-23 12:00:35 +08:00
parent cfeb1b2b1a
commit 9db4ca88e9
1 changed files with 726 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

726
docs/华为云MetaStudio交互数字人配置指南.md Normal file
View File

@@ -0,0 +1,726 @@
# 华为云交互数字人 MetaStudio 配置完整指南
本文档详细说明如何在华为云 MetaStudio 平台配置交互数字人，涵盖从创建到发布的全流程操作。
---
## 目录
- [一、基础概念](#一基础概念)
- [二、前置准备](#二前置准备)
- [三、创建数字人项目](#三创建数字人项目)
- [四、角色选择与配置](#四角色选择与配置)
- [五、终端配置](#五终端配置)
- [六、互动文档配置](#六互动文档配置)
- [七、对话配置](#七对话配置)
- [八、多语言配置](#八多语言配置)
- [九、发布与上线](#九发布与上线)
- [十、常见问题](#十常见问题)
---
## 一、基础概念
### 1.1 交互数字人类型
| 类型 | 说明 | 适用场景 |
|:---|:---|:---|
| 2D 数字人 | 真人录制驱动，成本低，部署快 | 客服、讲解、播报 |
| 3D 数字人 | 高精度建模，交互强，表现力丰富 | 品牌代言、展厅展示 |
### 1.2 核心组件
- **数字人模型**：2D/3D 虚拟形象
- **智能语音对话**：与数字人实时语音/文字交互
- **知识库**：数字人回答的知识来源
- **互动文档**：数字人主动播报的内容脚本
- **终端渠道**：数字人落地展示的平台
### 1.3 名词解释
| 名词 | 说明 |
|:---|:---|
| 知识库 | 数字人回答问题的语料来源，支持文档上传、网页抓取等 |
| 互动文档 | 数字人主动播报的脚本，可配置触发时机 |
| 对话技能 | 控制数字人在特定场景下的对话逻辑 |
| 终端 | 数字人对外展示的渠道，如网页、H5、APP |
| WebRTC | 实时音视频通信协议，用于数字人实时交互 |
---
## 二、前置准备
### 2.1 开通华为云服务
登录 [华为云官网](https://www.huaweicloud.com/)，依次开通以下服务：
1. **MetaStudio（数字内容生产线）**
- 进入 [MetaStudio 控制台](https://console.huaweicloud.com/metastudio/)
- 开通服务，按需选择资源包
2. **语音交互服务（可选）**
- 如需语音对话，开通 "语音合成 TTS" 和 "语音识别 ASR"
3. **IEF（智能边缘平台，可选）**
- 如需本地部署数字人终端
### 2.2 准备资源
- 华为云账号 + IAM 用户（建议创建子账号授权）
- 已备案的域名（生产环境）
- Dify 平台账号（用于对接数字人中转服务）
---
## 三、创建数字人项目
### 3.1 进入 MetaStudio 控制台
1. 登录 [MetaStudio 控制台](https://console.huaweicloud.com/metastudio/)
2. 左侧菜单选择 **数字人** → **交互数字人**
3. 点击 **创建项目**
### 3.2 项目基础信息
| 字段 | 说明 |
|:---|:---|
| 项目名称 | 如：`公司官网数字人客服` |
| 项目描述 | 简要描述项目用途 |
| 地域 | 选择最近地域（如：华北-北京四） |
| 数字人类型 | 2D / 3D，根据需求选择 |
### 3.3 选择数字人模板
华为 MetaStudio 提供以下模板类型：
| 模板 | 特点 | 适用场景 |
|:---|:---|:---|
| 客服助手模板 | 开箱即用，配置简单 | 官网客服、产品咨询 |
| 讲解员模板 | 支持主动播报内容 | 展厅导览、品牌讲解 |
| 虚拟主播模板 | 支持内容自动播报 | 新闻播报、活动主持 |
| 自定义模板 | 从零配置，灵活度高 | 深度定制需求 |
建议首次使用选择 **客服助手模板**，快速熟悉流程。
---
## 四、角色选择与配置
### 4.1 选择数字人形象
在 **角色配置** 页面，选择数字人的外观形象：
#### 方式一：使用平台预设形象
MetaStudio 提供多种预设形象，分为：
| 分类 | 说明 |
|:---|:---|
| 2D 预设形象 | 真人模特，覆盖多种性别、肤色、服装风格 |
| 3D 预设形象 | 二次元、仿真人、超写实等多种风格 |
选择步骤：
1. 在 **形象市场** 中浏览预设形象
2. 点击 **预览**，查看数字人在不同场景下的表现
3. 点击 **使用**，将形象添加到当前项目
#### 方式二：定制专属形象（需申请）
如需使用真人定制：
1. 联系华为云商务，申请定制数字人形象
2. 提供多角度真人视频素材（10-15 分钟）
3. 华为云制作团队完成建模（约 5-10 个工作日）
### 4.2 角色参数配置
选定形象后，配置以下参数：
| 参数 | 说明 | 推荐值 |
|:---|:---|:---|
| 音色 | 数字人说话的声音类型 | 根据形象性别/场景选择 |
| 语速 | 播报语速 | 1.0x（正常） |
| 音调 | 声音高低 | 根据场景调整 |
| 音量 | 播报音量 | 80% |
| 口型匹配 | 是否启用口型动画 | 启用 |
| 动作姿态 | 待机/讲解时的肢体动作 | 选择对应场景动作集 |
### 4.3 背景配置
| 设置项 | 说明 |
|:---|:---|
| 背景类型 | 纯色 / 虚拟背景 / 透明（抠像） |
| 虚拟背景 | 可上传图片或使用平台提供的场景模板 |
| 分辨率 | 720P / 1080P / 4K |
> **建议**：如数字人部署在网页/H5 上，选择透明背景（WebGL 渲染模式），可叠加在任何网页内容上。
---
## 五、终端配置
终端决定了数字人在哪里展示。华为 MetaStudio 支持多种终端类型。
### 5.1 支持的终端类型
| 终端类型 | 说明 | 适用场景 |
|:---|:---|:---|
| **Web（网页端）** | 通过浏览器访问，支持 WebRTC | 官网、线上展厅 |
| **H5（移动端）** | 适配手机浏览器，无需下载 | 微信、小程序内嵌 |
| **APP（移动应用）** | 集成到企业自有 APP | APP 内嵌数字人 |
| **小程序** | 微信/支付宝小程序 | 微信生态内展示 |
| **线下大屏** | 支持 Linux/Windows 大屏终端 | 展厅、营业厅 |
| **API 接入** | 通过 WebSocket/API 调用 | 第三方平台集成 |
### 5.2 Web 终端配置
#### 创建 Web 终端
1. 在项目页面，点击 **添加终端** → **Web 网页**
2. 配置以下参数：
| 参数 | 说明 |
|:---|:---|
| 终端名称 | 如：`官网网页端` |
| 域名白名单 | 允许嵌入数字人的域名，如：`*.example.com` |
| 是否启用 HTTPS | **必须启用**，生产环境必须配置 |
| 终端尺寸 | 固定尺寸 / 全屏自适应 |
| 默认语言 | 终端默认语言 |
3. 点击 **生成嵌入代码**，获取 Iframe 或 Web SDK 代码
**Iframe 嵌入示例：**
```html
<iframe
src="https://your-domain.com/digital-human-embed?token=xxx"
width="100%"
height="600px"
allow="camera; microphone"
frameborder="0"
></iframe>
```
**Web SDK 嵌入示例：**
```html
<!-- 引入 SDK -->
<script src="https://cdn.example.com/metastudio-sdk-v2.js"></script>
<!-- 挂载节点 -->
<div id="digital-human-container"></div>
<script>
const dh = new MetaStudioDigitalHuman({
container: '#digital-human-container',
appId: 'your-app-id',
token: 'your-auth-token',
width: '100%',
height: '600px',
language: 'zh_CN',
onReady: () => console.log('数字人已就绪'),
onError: (err) => console.error('错误:', err),
});
dh.start();
</script>
```
### 5.3 H5 终端配置
适用于手机浏览器，无需安装 APP：
| 参数 | 说明 |
|:---|:---|
| 终端名称 | 如：`手机H5端` |
| 授权域名 | 微信/浏览器安全域名配置 |
| 是否支持微信内嵌 | 开启后使用微信 JSSDK |
获取分享链接或二维码，扫码即可体验。
### 5.4 终端通用参数
| 参数 | 说明 | 推荐值 |
|:---|:---|:---|
| 默认语言 | 终端启动时的语言 | `zh_CN` |
| 自动启动 | 页面加载后自动启动数字人 | 是 |
| 显示水印 | 是否显示华为云水印 | 生产环境关闭 |
| 会话超时 | 无交互自动休眠时间 | 5 分钟 |
---
## 六、互动文档配置
互动文档用于配置数字人**主动播报**的内容，可以是产品介绍、活动说明、迎宾语等。
### 6.1 创建互动文档
1. 在项目左侧菜单选择 **内容管理** → **互动文档**
2. 点击 **新建文档**
3. 填写文档名称（如：`产品介绍-旗舰机型`）
### 6.2 文档结构
互动文档采用**结构化脚本**格式，支持以下元素：
```json
{
"doc_id": "doc-001",
"doc_name": "产品介绍-旗舰机型",
"language": "zh_CN",
"content": [
{
"type": "greeting",
"text": "您好，欢迎来到我们的产品展厅！"
},
{
"type": "segment",
"title": "关于我们",
"text": "我们是国内领先的智能制造企业，专注于为客户提供高品质的智能产品解决方案。"
},
{
"type": "image",
"url": "https://cdn.example.com/product.jpg",
"description": "产品实物图"
},
{
"type": "segment",
"title": "核心优势",
"text": "我们的产品有三大核心优势：\n1. 高性能处理器\n2. 超长续航能力\n3. 智能交互体验"
},
{
"type": "qa",
"question": "产品价格是多少",
"answer": "具体价格请咨询我们的销售顾问，或拨打400-888-8888。"
},
{
"type": "video",
"url": "https://cdn.example.com/intro.mp4",
"description": "产品介绍视频"
},
{
"type": "goodbye",
"text": "感谢您的参观，如有任何问题，随时向我咨询！"
}
],
"triggers": [
{
"type": "keyword",
"keywords": ["产品", "介绍", "优势"],
"priority": 1
},
{
"type": "schedule",
"cron": "0 9 * * *", // 每天早上9点自动播报
"description": "每日早间播报"
}
]
}
```
### 6.3 触发时机配置
互动文档支持多种触发方式：
| 触发类型 | 说明 | 配置方式 |
|:---|:---|:---|
| **关键词触发** | 用户提到特定关键词时播报 | 配置关键词列表，设置优先级 |
| **定时播报** | 按 Cron 表达式定时触发 | 设置 Cron 表达式 |
| **欢迎语触发** | 用户首次进入时播报 | 全局开关控制 |
| **按钮触发** | 用户点击引导按钮时播报 | 生成互动按钮 |
| **手势触发** | 特定手势（如挥手）触发 | 需配置摄像头手势识别 |
### 6.4 多文档优先级
当多个文档的触发条件同时满足时，按以下优先级处理：
1. **问答匹配最高** — 用户问题与 Q&A 完全匹配
2. **关键词命中数最多** — 命中关键词最多的文档
3. **手动优先级设置** — 在文档属性中手动设置 1-100 优先级
---
## 七、对话配置
对话配置是数字人"智能"的核心，决定数字人如何理解和回答用户问题。
### 7.1 接入中转服务（推荐）
数字人对话推荐通过 `digital-human.py` 中转服务接入 Dify，无需每个终端单独对接：
```
数字人终端 --> digital-human.py 中转 --> Dify 知识库 --> LLM --> 响应
|
+--> Redis（多轮对话上下文）
```
**配置步骤：**
1. 在华为云 MetaStudio 终端配置中，填写中转服务地址：
```
中转服务地址：https://your-domain.com/digital-human
```
2. 中转服务 `POST /digital-human` 请求参数映射：
| 华为云参数 | 中转服务字段 | 说明 |
|:---|:---|:---|
| 用户 ID | `user` | 终端用户标识 |
| 会话 ID | `session_id` | 多轮对话上下文关联 |
| 用户输入 | `messages[0].content` | 用户问题内容 |
| 应用 ID | `app_id` | Dify 应用标识 |
| 流式模式 | `is_stream` | 是否启用流式响应 |
### 7.2 Dify 应用配置
#### 7.2.1 创建 Dify 应用
1. 登录 Dify 平台
2. 创建应用，选择类型：
- **聊天助手**：适合问答场景
- **Agent**：适合复杂任务处理
- **Workflow**：适合流程化对话
#### 7.2.2 知识库配置
1. 在 Dify 应用中，进入 **知识库**
2. 上传文档，支持格式：
- PDF
- Word（.docx）
- TXT
- Markdown
- 网页 URL
3. 文档分段策略：
| 策略 | 说明 | 适用场景 |
|:---|:---|:---|
| 自动分段 | AI 自动识别段落 | 通用场景 |
| 固定长度分段 | 每 N 个字符一段 | 结构化文档 |
| 自定义分段 | 手动设置分段点 | 精准控制 |
4. 设置Embedding 模型（推荐使用华为云或 OpenAI 的 Embedding 服务）
#### 7.2.3 对话技能配置
在 Dify 应用中配置 **提示词**，控制数字人回答风格：
```
你是华为云交互数字人客服，名为"小华"。
你的职责是：
1. 热情、专业地回答用户关于产品和服务的问题
2. 回答简洁有条理，不超过3句话
3. 遇到无法回答的问题，引导用户转人工服务
4. 禁止回答与公司业务无关的问题
```
### 7.3 多轮对话配置
通过 Redis 存储 `session_id` 与 `conversation_id` 映射，实现多轮对话：
```
用户: 你好，我想咨询产品
数字人: 您好！很高兴为您服务。请问您想了解哪类产品？
用户: 有没有适合企业使用的？
数字人: 当然有！我们有多款企业级产品，请问您更关注哪个方面？
（A）服务器 （B）存储 （C）网络
用户: A
数字人: 我们的服务器产品分为...
```
**配置要点：**
- `session_id`：由终端生成，必须唯一，用于关联同一用户的多轮会话
- `conversation_id`：由 Dify 生成，存储在 Redis 中
- 会话超时时间：建议设置 30 分钟无交互则清理会话
### 7.4 意图识别与槽位填充
高级配置：通过 Dify Workflow 配置意图识别：
```
用户输入
↓
意图分类（识别是"咨询产品"还是"投诉"还是"转人工"）
↓
分支处理
├── 咨询产品 → 知识库检索
├── 投诉 → 道歉+记录+转人工
└── 转人工 → 输出转接指令
```
---
## 八、多语言配置
多语言支持让数字人可以服务全球用户，是国际化场景的必备能力。
### 8.1 支持的语言列表
| 语言代码 | 语言名称 | 说明 |
|:---|:---|:---|
| `zh_CN` | 简体中文 | 默认 |
| `zh_TW` | 繁体中文 | 港澳台地区 |
| `en_US` | 英语 | 国际通用 |
| `ja_JP` | 日语 | 日本市场 |
| `ko_KR` | 韩语 | 韩国市场 |
| `fr_FR` | 法语 | 法国及法语区 |
| `de_DE` | 德语 | 德国及德语区 |
| `es_ES` | 西班牙语 | 西班牙及拉丁美洲 |
| `pt_BR` | 葡萄牙语 | 巴西及葡萄牙 |
| `ru_RU` | 俄语 | 俄罗斯市场 |
| `ar_SA` | 阿拉伯语 | 中东地区（RTL） |
### 8.2 终端语言配置
在终端配置中设置支持的语言列表：
```json
{
"supported_languages": [
{ "code": "zh_CN", "name": "简体中文", "default": true },
{ "code": "en_US", "name": "English", "default": false },
{ "code": "ja_JP", "name": "日本語", "default": false }
],
"default_language": "zh_CN",
"language_switch_position": "top-right"
}
```
### 8.3 数字人音色多语言配置
每种语言需配置对应的音色：
| 语言 | 音色名称 | 参数 |
|:---|:---|:---|
| 简体中文 | 小华-女声-自然 | `zh-CN-XiaoxiaoNeural` |
| 简体中文 | 小华-男声-正式 | `zh-CN-YunxiNeural` |
| 英语 | Emma-女声 | `en-US-EmmaNeural` |
| 英语 | Justin-男声 | `en-US-JustinNeural` |
| 日语 | Nanami-女声 | `ja-JP-NanamiNeural` |
**配置步骤：**
1. 进入 **角色配置** → **音色设置**
2. 点击 **添加音色**
3. 选择语言和音色类型
4. 预览并确认
### 8.4 多语言互动文档
每个语言创建独立的互动文档：
```
内容管理/
├── 互动文档/
│ ├── 产品介绍（中文） doc-zh-CN.json
│ ├── 产品介绍（英文） doc-en-US.json
│ ├── 产品介绍（日文） doc-ja-JP.json
│ └── 欢迎语（多语言） doc-welcome-all.json
```
**文档语言字段：**
```json
{
"doc_id": "doc-001",
"language": "en_US",
"content": [
{
"type": "greeting",
"text": "Hello! Welcome to our digital showroom. How can I assist you today?"
}
]
}
```
### 8.5 多语言对话路由
在 `digital-human.py` 中转服务实现多语言路由：
```python
# 根据用户语言选择 Dify 对应的应用
LANGUAGE_APP_MAP = {
"zh_CN": "app-zh-cn-xxx",
"en_US": "app-en-us-xxx",
"ja_JP": "app-ja-jp-xxx",
}
# 从请求中获取语言参数
lang = body.get("language", "zh_CN")
app_id = LANGUAGE_APP_MAP.get(lang, LANGUAGE_APP_MAP["zh_CN"])
```
### 8.6 翻译知识库
对于知识库文档较多的场景，建议：
| 方案 | 适用规模 | 说明 |
|:---|:---|:---|
| **多套独立知识库** | 少于 10 个应用 | 每种语言独立维护，简单可靠 |
| **统一知识库 + 翻译中间件** | 大规模多语言 | 知识库统一存储，翻译层按需转换 |
| **多语言 Embedding 模型** | 中等规模 | 使用支持多语言的 Embedding 模型 |
---
## 九、发布与上线
### 9.1 预览测试
在正式发布前，使用 MetaStudio 提供的**预览功能**：
1. 点击右上角 **预览**
2. 在模拟器中选择终端类型（PC / 手机 / 大屏）
3. 输入测试问题，验证回答是否正确
4. 检查多语言切换是否正常
5. 确认互动文档触发是否符合预期
### 9.2 发布配置
#### 基本信息
| 字段 | 说明 |
|:---|:---|
| 发布版本号 | 如：`v1.0.0`，建议遵循语义化版本 |
| 更新说明 | 本次更新的内容简述 |
| 发布环境 | 测试环境 / 预发布 / 正式环境 |
#### 终端发布
| 终端 | 发布前检查项 |
|:---|:---|
| Web | 域名已备案、HTTPS 证书有效、ICP 许可证（如需） |
| H5 | 微信/支付宝域名白名单已配置 |
| 小程序 | 小程序已在微信平台注册，AppID 填写正确 |
| APP | APP 已上架或已添加测试设备 |
#### 数字人内容审核
华为云对数字人内容有审核机制：
1. **内容合规检查**：禁止涉及政治、色情、暴力等内容
2. **品牌合规检查**：涉及商标、品牌需提供授权证明
3. **AI 安全检查**：对话内容通过 AI 安全审核
审核时间：工作日 1-3 个工作日。
### 9.3 发布上线
审核通过后，点击 **立即发布**：
```
发布中 → 部署终端 → 服务启动 → 上线成功
```
### 9.4 监控与运维
发布后通过华为云控制台监控：
| 监控项 | 说明 |
|:---|:---|
| 在线人数 | 当前同时在线的终端用户数 |
| 对话量 | 每小时/每天的对话请求数 |
| 平均响应时间 | Dify → 数字人响应的端到端延迟 |
| 错误率 | 5xx 错误占比 |
| Redis 连接状态 | 会话缓存是否正常 |
**告警配置：**
- 对话量突增 / 突降
- 错误率超过 5%
- 响应时间超过 10 秒
- Redis 连接失败
---
## 十、常见问题
### Q1：数字人形象无法加载？
**排查步骤：**
1. 检查网络是否正常
2. 检查浏览器控制台是否有 CORS 错误
3. 确认终端配置的域名与实际访问域名一致
4. 检查 HTTPS 证书是否有效
### Q2：对话回答不准确？
**排查步骤：**
1. 检查 Dify 知识库是否已正确关联应用
2. 检查文档分段是否合理
3. 在 Dify 的"日志"中查看实际检索到的内容
4. 调整提示词，减少"幻觉"回答
5. 适当提高检索相似度阈值（0.7-0.85 为宜）
### Q3：多轮对话上下文丢失？
**排查步骤：**
1. 检查 Redis 是否正常运行：`docker ps | grep redis`
2. 检查 `session_id` 是否每次请求都相同
3. 检查 Redis 会话过期时间（默认 86400 秒）
4. 查看容器日志是否有 Redis 连接错误
### Q4：流式响应延迟高？
**排查步骤：**
1. 检查 Dify 服务响应时间（独立测试 Dify）
2. 检查容器服务器与 Dify 服务器之间的网络延迟
3. 确认 `digital-human.py` 中 `generate_streaming_messages` 是否实时 yield
4. 检查 Redis 查询耗时（`session_id` 读取）
5. 考虑在 Dify 侧开启流式输出（`response_mode: streaming`）
### Q5：多语言切换不生效？
**排查步骤：**
1. 确认终端配置中已添加对应语言
2. 确认该语言的知识库文档已上传
3. 确认 `digital-human.py` 中有 `LANGUAGE_APP_MAP` 路由
4. 终端前端是否正确传递 `language` 参数
### Q6：互动文档触发时机不正确？
**排查步骤：**
1. 检查关键词列表是否覆盖用户可能表达的同义词
2. 确认文档优先级设置（数字越小优先级越高）
3. 检查定时触发 Cron 表达式是否正确
4. 在 Dify 日志中确认是否有匹配的知识库内容被检索到
---
## 附录
### A. 华为云 MetaStudio 官方文档
- 控制台地址：https://console.huaweicloud.com/metastudio/
- 产品文档：https://support.huaweicloud.com/metastudio/
### B. 中转服务快速验证命令
```bash
# 健康检查
curl http://localhost:8000/
# 非流式对话测试
curl -X POST http://localhost:8000/digital-human \
-H "Content-Type: application/json" \
-d '{
"messages": [{"content": "你好"}],
"app_id": "app-PDkSHiHZsZIluoZF7N2OlNZM",
"user": "test-user",
"session_id": "test-001",
"is_stream": false
}'
```
### C. 推荐配置清单
```
□ 华为云 MetaStudio 已开通
□ Dify 平台应用已创建
□ 知识库文档已上传并关联
□ .env 中 DIFY_URL / DIFY_API_KEY 已配置
□ 容器已启动（docker compose up -d --build）
□ 容器状态为 healthy
□ HTTPS 反向代理已配置
□ 域名白名单已在华为云终端配置
□ 多语言知识库和文档已准备
□ 发布审核已通过
□ 上线后监控告警已配置
```