diff --git a/docs/华为云MetaStudio交互数字人配置指南.md b/docs/华为云MetaStudio交互数字人配置指南.md new file mode 100644 index 0000000..83ae9df --- /dev/null +++ b/docs/华为云MetaStudio交互数字人配置指南.md @@ -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 + +``` + +**Web SDK 嵌入示例：** + +```html + + + + +
+ + +``` + +### 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 反向代理已配置 +□ 域名白名单已在华为云终端配置 +□ 多语言知识库和文档已准备 +□ 发布审核已通过 +□ 上线后监控告警已配置 +```