# 华为云数字内容生产线 MetaStudio 智能交互数字人配置指南 本文档记录基于华为云 MetaStudio 智能交互 + 第三方大脑(华为云官方称为"第三方大模型")的交互数字人配置方案,智能大脑使用 Dify 平台。 --- ## 目录 - [一、整体架构](#一整体架构) - [二、前置准备](#二前置准备) - [三、部署 Dify 中转服务](#三部署-dify-中转服务) - [四、配置 Dify 应用](#四配置-dify-应用) - [五、配置 MetaStudio 智能交互](#五配置-metastudio-智能交互) - [六、常见问题](#六常见问题) - [附录](#附录) --- ## 一、整体架构 ``` 用户 ──→ 华为云 MetaStudio 智能交互(控制台配置) │ │ 第三方大脑(大模型) ↓ ┌───────────────────────┐ │ digital-human.py │ ← 中转服务(部署在自有服务器) │ (FastAPI + Redis) │ └───────────┬───────────┘ │ HTTP / SSE 流式 ↓ ┌──────────┐ │ Dify │ ← 知识库 + LLM(大语言模型) │ 平台 │ └──────────┘ ``` **组件说明:** | 组件 | 作用 | 托管位置 | |:---|:---|:---| | MetaStudio 智能交互 | 数字人形象驱动、语音合成(TTS)、语音识别(ASR)、Web 端交互界面 | 华为云托管 | | 第三方大脑(第三方大模型) | MetaStudio 调用外部 LLM 获取对话内容 | 自有服务器 | | digital-human.py(中转服务) | 接收 MetaStudio 请求,转发至 Dify,转换响应格式 | 自有服务器 | | Redis | 存储 session_id → conversation_id 映射,支持多轮对话 | 自有服务器 | | Dify 平台 | 知识库检索 + 大语言模型对话生成 | 自有部署或 Dify Cloud | **中转服务 `POST /digital-human` 请求转发流程:** ``` MetaStudio 发起 HTTP POST /digital-human ↓(携带用户语音转文字后的 query) digital-human.py 接收请求 ↓(携带 conversation_id,从 Redis 查询) Dify /chat-messages 接口 ↓ Dify 返回 answer(或 SSE 流式 chunk) ↓ digital-human.py 转换为统一格式 ↓ MetaStudio 接收并驱动数字人播报 ``` --- ## 二、前置准备 ### 2.1 开通华为云服务 登录 [华为云官网](https://www.huaweicloud.com/),依次开通以下服务: 1. **MetaStudio(数字内容生产线)** - 进入 [MetaStudio 控制台](https://console.huaweicloud.com/metastudio/) - 开通服务,按需选择资源包 2. **语音交互服务 SIS(语音交互)** - 如需语音对话,开通: - **语音合成 TTS**:将文字转为自然语音 - **语音识别 ASR**:将用户语音转为文字 - ASR/TTS 计费属于独立计费项,请以华为云控制台实时价格为准 3. **OBS 对象存储** - MetaStudio 用于存储数字人形象、视频等资产(部分地区自动开通) ### 2.2 ASR 并发数限制说明 > 此说明仅供参考,具体套餐请以华为云控制台实时价格为准。 **并发数计算规则:** - 1 路并发 = 1 个终端同时进行语音识别 - 同一终端内,用户说话、等待回复均占用 1 路并发 - 多人同时使用 = 并发数叠加(如 10 人同时使用 = 10 路并发) **扩容建议:** - 预估并发 = 预计同时在线用户数 × 0.3(正常对话频率) - 建议预留 20% 余量,避免高峰时段超限 - 企业版可申请动态扩容,支持突发流量 > **注意**:ASR 并发数超限后,新请求将被直接拒绝,终端表现为"无法识别语音,请重试"。生产环境务必提前评估并发需求并购买对应套餐。 ### 2.3 准备资源清单 - [ ] 华为云账号 + 已完成实名认证 - [ ] MetaStudio 服务已开通 - [ ] 华为云 SIS(ASR + TTS)已开通 - [ ] 一台可对外提供 HTTP 服务的服务器(用于部署中转服务) - [ ] Dify 平台账号(自部署或 Dify Cloud) - [ ] Dify 应用已创建,知识库已配置 --- ## 三、部署 Dify 中转服务 中转服务 `digital-human.py` 负责将 MetaStudio 的第三方大脑请求转发给 Dify,并处理多轮对话上下文(Redis)。 ### 3.1 快速部署(一键脚本) 华为云官方提供自动部署脚本,在中转服务器上执行: ```bash wget -O /tmp/digital-human.sh \ https://documentation-samples.obs.cn-north-4.myhuaweicloud.com/solution-as-code-publicbucket/solution-as-code-moudle/building-a-dify-llm-application-development-platform/human/digital-human.sh \ && bash /tmp/digital-human.sh ``` **参数说明:** | 参数 | 含义 | 示例 | |:---|:---|:---| | `` | Dify 服务的主机地址或域名(**不包含 `/v1`**,脚本会自动拼接为 `http://<地址>/v1/chat-messages`) | `atwdify.antiwearvalve.com` | | `` | Dify API 密钥(纯密钥,脚本内部自动加上 `Bearer ` 前缀) | `app-xxxxxxxxxxxxxxxx` | **脚本自动完成以下操作:** | 步骤 | 说明 | |:---|:---| | 安装依赖 | `apt install rar redis-server`,`pip install redis fastapi uvicorn` | | 启动 Redis | 启用并启动 `redis-server`,设置开机自启 | | 下载源码 | 从华为云 OBS 下载 `digital-human.rar` 并解压到 `/` | | 替换配置 | 将传入的两个参数分别写入 `digital-human.py` 中的 `dify_url` 和 `dify_api_key` | | 注册服务 | 安装 systemd 服务 `digital-human.service`,设置开机自启并立即启动 | > **Dify 地址格式注意**:传入脚本的参数应为 Dify 服务的**主机地址(不含 `/v1`)**,例如 `atwdify.antiwearvalve.com`。脚本内部会自动拼接为 `http://<地址>/v1/chat-messages`。API Key 传入后,脚本会在其前自动加上 `Bearer ` 前缀。 ### 3.2 手动部署(Docker Compose) 如需手动部署: ```bash git clone https://github.com/ClawCopilot/digital-human-dify-relay.git cd digital-human-dify-relay # 配置环境变量 cp .env.example .env # 编辑 .env,填入 DIFY_URL 和 DIFY_API_KEY # 启动服务 docker compose up -d ``` `.env` 必填项: ```env # Dify 服务地址(末尾不要加 /chat-messages) DIFY_URL=https://your-dify-domain.com/v1 # Dify API 密钥(纯密钥,不要加 Bearer 前缀) DIFY_API_KEY=app-xxxxxxxxxxxxxxxx ``` ### 3.3 配置防火墙 允许外部访问中转服务端口(默认 8000): ```bash # 云服务器安全组:放行 TCP 8000 端口(源地址 0.0.0.0/0) # 或使用云防火墙配置规则 ``` ### 3.4 验证中转服务 ```bash # 健康检查 curl http://{中转服务器IP}:8000 # 应返回 {"status":"ok"} # 对话接口测试(非流式) curl -X POST http://{中转服务器IP}:8000/digital-human \ -H "Content-Type: application/json" \ -d '{ "messages": [{"content": "你好"}], "app_id": "your-app-id", "user": "test-user", "session_id": "test-001", "is_stream": false }' ``` > **注意**:`app_id` 请替换为您的实际 Dify 应用 ID。**切勿将 API Key 明文写入文档或代码仓库**。 ### 3.5 中转服务接口说明 #### `POST /digital-human`(核心接口) | 字段 | 类型 | 必填 | 说明 | |:---|:---|:---:|:---| | `messages` | `Array` | ✅ | 消息列表,取第一条 `content` 作为 Dify query | | `app_id` | `string` | ✅ | Dify 应用 ID | | `user` | `string` | ✅ | 用户标识,用于 Dify 会话上下文 | | `session_id` | `string` | ✅ | 会话 ID,多轮对话关联,空则自动生成 | | `is_stream` | `boolean` | ✅ | `true` = SSE 流式,`false` = 非流式阻塞返回 | **响应(非流式):** ```json { "id": "131424542124", "created": 20230512084843, "choices": [{"index": 0, "message": {"content": "您好!我是..."}}] } ``` **响应(流式,SSE):** ``` data: {"id":"1231414141541252525","created":20230512084843,"choices":[{"message":{"content":"您"}}]} data: {"id":"1231414141541252525","created":20230512084843,"choices":[{"message":{"content":"好"}}]} ... data: [DONE] ``` #### `GET /`(健康检查) ```json {"status":"ok"} ``` --- ## 四、配置 Dify 应用 Dify 是交互数字人的"大脑",负责知识库检索和大语言模型对话生成。 ### 4.1 创建 Dify 应用 1. 登录 Dify 平台 2. 创建应用,选择类型: - **聊天助手**:适合问答场景(推荐) - **Agent**:适合复杂任务处理 - **Workflow**:适合流程化对话 ### 4.2 配置知识库 1. 进入应用 → **知识库** 2. 上传文档,支持格式:PDF、Word(.docx)、TXT、Markdown、网页 URL 3. 文档分段策略: | 策略 | 说明 | 适用场景 | |:---|:---|:---| | 自动分段 | AI 自动识别段落 | 通用场景 | | 固定长度分段 | 每 N 个字符一段 | 结构化文档 | | 自定义分段 | 手动设置分段点 | 精准控制 | 4. 设置 Embedding 模型(推荐使用与 LLM 同供应商的服务) ### 4.3 配置提示词(对话技能) 在应用 **提示词** 中配置,控制数字人回答风格: ``` 你是华为云交互数字人客服,名为"小华"。 你的职责是: 1. 热情、专业地回答用户关于产品和服务的问题 2. 回答简洁有条理,不超过3句话 3. 遇到无法回答的问题,引导用户转人工服务 4. 禁止回答与公司业务无关的问题 ``` ### 4.4 获取 API Key 1. 进入 Dify 应用 → **API** 标签页 2. 复制 **API Key**(格式如 `app-xxxxxxxxxxxxxxxx`) 3. 将 API Key 填入中转服务 `.env` 中的 `DIFY_API_KEY` ### 4.5 多轮对话说明 - `session_id`:由 MetaStudio 终端生成,每次对话中保持一致 - `conversation_id`:由 Dify 返回,存储在中转服务 Redis 中 - 会话超时:默认 86400 秒(24 小时),可按需调整 Redis expire 时间 --- ## 五、配置 MetaStudio 智能交互 > **控制台路径**:登录 MetaStudio → 进入工作台 → 点击「分身智能交互」卡片 → 在对话项目编辑页面配置各环节参数。 --- ### 5.1 进入控制台与创建对话项目 **操作步骤:** 1. 登录 [MetaStudio 控制台](https://console.huaweicloud.com/metastudio/),进入 MetaStudio 服务概览页面 2. 点击「**前往 MetaStudio 工作台**」 3. 在工作台页面点击「**分身智能交互**」卡片 4. 进入智能交互对话项目编辑页面,依次配置以下参数 > **创建与编辑入口**:如已有对话项目,在「我的创作 → 智能交互」列表中点击对应项目名称进入编辑。 --- ### 5.2 角色配置 在编辑页面左侧「**角色**」区域,配置数字人形象: | 配置项 | 说明 | |:---|:---| | **定制数字人** | 点击跳转到形象制作页面,发起分身数字人定制任务 | | **搜索框** | 输入数字人名称,精准筛选已创建的数字人 | | **筛选条件** | 支持按角色、性别、姿势、行业、区域和分辨率筛选 | | **数字人卡片列表** | 点击卡片自动替换为对应形象 | **形象类型说明:** | 类型 | 说明 | |:---|:---| | 分身数字人 | 基于真人形象采集打造,交互自然,推荐正式客服场景 | | 照片数字人 | 上传照片即可生成,适合快速验证 | > **重要**:Flexus 分身数字人仅支持视频制作,**不支持智能交互**,详见 [Flexus 分身数字人限制说明](https://support.huaweicloud.com/productdesc-metastudio/metastudio_01_0022.html)。 --- ### 5.3 背景配置 在编辑页面左侧「**背景**」区域,配置交互场景背景: | 配置项 | 说明 | |:---|:---| | **本地导入** | 支持上传 PNG、JPG、JPEG、BMP 格式图片,或直接拖拽上传 | | **搜索框** | 输入背景名称精准搜索 | | **筛选条件** | 支持按来源筛选背景图片 | | **透明背景** | 第一张图为透明背景,点击后数字人预览区域切换为透明背景(用于叠加在任何画面内容之上) | > **注意**:上传后的背景图片不支持修改,如需更换请本地修改后再重新上传。 --- ### 5.4 互动问答配置(第三方大脑) > 本项目使用 **第三方大脑(大模型)** 场景,通过中转服务对接 Dify。 在编辑页面填写以下参数: #### 基础参数 | 配置项 | 填写内容 | 说明 | |:---|:---|:---| | **第三方应用** | 选择「**第三方大脑(大模型)**」 | — | | **应用名称** | 自定义,如:`智能客服数字人` | 便于识别的项目名称 | | **APPID** | `898675431` | 默认值,通常无需修改 | | **APPKEY** | 随意填写(当前 `digital-human.py` 中转服务未实现签名验证,留空或填任意值均可) | 用于 MetaStudio 请求签名验证占位,当前版本可忽略 | | **第三方语言模型地址** | 中转服务地址,如:`http://your-server:8000/digital-human` | MetaStudio 调用此地址获取对话答案 | > **地址格式说明**:中转服务地址必须能被华为云服务器访问。若使用 HTTPS,建议使用有效证书;若使用 HTTP,地址不能包含 `localhost` 或私有 IP(如 `192.168.x.x`)。 #### 流式与多轮对话参数 | 配置项 | 建议值 | 说明 | |:---|:---|:---| | **流式响应** | 根据 Dify 支持情况选择 | 开启后使用 SSE 流式问答(响应更快);关闭则使用非流式。需中转服务同步支持 | | **多轮语境理解能力** | `3`(推荐) | 数值越高,携带历史对话越多。设为 `1` 则不支持多轮对话 | **多轮语境配置规则:** - 设为 `1`:不携带历史对话,每次问答独立 - 设为非 `1`(如 `3`):携带历史对话,携带数量 = 当前问题 + 历史最新的 N-1 轮问答 #### ASR 服务配置 | 配置项 | 填写内容 | 说明 | |:---|:---|:---| | **ASR 服务** | 选择「**奇妙问**」 | 使用华为云奇妙问平台提供语音识别服务 | | **ASR 账号** | 奇妙问平台账号 | 需联系奇妙问客户经理注册开通,详见 [奇妙问配置说明](https://support.huaweicloud.com/intl/zh-cn/usermanual-metastudio/metastudio_05_0181.html) | | **ASR 密钥** | 奇妙问平台密钥 | 同上 | > **ASR 说明**:如仅需文字输入模式,可不配置 ASR 服务,使用 MetaStudio 自带的文字输入入口进行对话测试。 #### 其他参数 | 配置项 | 建议值 | 说明 | |:---|:---|:---| | **尾静音时长** | `≥ 500ms` | 云端对音频进行 VAD 检测,静默超过此值结束语音识别,建议不低于 500ms | | **热词** | 按需配置 | 语音识别不准确的专业词汇可作为热词反馈至语音模型,提高识别准确率 | #### 配置检查 点击「**配置检查**」,系统自动验证当前配置是否正确,如有错误会显示相应提示。 --- ### 5.5 对话配置 在编辑页面点击「**对话配置**」页签,配置语言与声音参数: | 配置项 | 取值范围 | 说明 | |:---|:---|:---| | **语言** | 中文 / 英文 | 支持同时添加并设置默认语言,可通过界面右上角图标切换 | | **声音** | 需与语言匹配 | 中文选中文音色,英文选英文音色 | | **语速** | 0.5X ~ 2X | 推荐 1.0X(正常语速) | | **音量** | 90 ~ 240 | 建议调大初始音量以保证播放效果适中 | | **音高** | 50 ~ 200 | 音高增加声音更尖锐,降低更低沉 | | **静默退出时长** | 5 ~ 1440 分钟 | 无操作超过设定时间后自动关闭对话窗口 | --- ### 5.6 发布设置 在编辑页面右上角点击「**发布**」: | 配置项 | 说明 | |:---|:---| | **激活码** | 发布成功后自动生成,用于激活对话链接 | | **并发数** | 同时访问的最大用户数量,超过时报 `MSS.20010135` 错误(对话资源不足),需根据实际需求配置 | | **有效期** | 从发布开始的智能交互可用时长 | **发布后操作:** 1. 点击「**发布**」,成功后弹出对话框 2. 点击「**发布链接**」→ 在"智能交互激活"界面输入激活码激活对话 3. 或点击「**复制分享**」→ 一键复制发布链接和激活码,分享给用户 > **修改已发布的项目**:返回编辑页面,点击「**修改**」按钮即可重新编辑配置(发布后激活码会更新)。 --- ### 5.7 终端类型说明 MetaStudio 智能交互支持以下终端接入方式,同一对话项目可适配多种终端: | 终端 | 说明 | 适用场景 | |:---|:---|:---| | **PC 端(网页)** | 通过浏览器访问发布链接,麦克风权限授权后即可语音对话 | 官网客服、展厅大屏 | | **手机端** | 在移动浏览器中打开,支持语音输入 | 微信/企业微信嵌入、APP 内嵌 H5 | | **大屏端** | 通过专用大屏终端 SDK 接入,适合触摸大屏设备 | 展厅、营业厅、政务服务大厅 | --- ### 5.8 预览与测试 配置完成后,使用控制台内置的模拟器进行预览测试: 1. 在编辑页面右侧预览区选择终端类型(电脑端 / 手机端) 2. 在模拟器中输入文字或点击麦克风进行语音测试 3. 验证 Dify 回复是否正确返回、数字人播报是否正常 4. 如有问题,点击「**配置检查**」排查,或参考 [第六节常见问题](#六常见问题) --- ## 六、常见问题 ### Q1:中转服务返回 500 错误? **排查步骤:** 1. 检查 `.env` 中 `DIFY_URL` 是否正确(末尾是否为 `/v1`) 2. 检查 `DIFY_API_KEY` 是否有效 3. 确认服务器能访问 Dify 地址: ```bash curl -I $DIFY_URL ``` ### Q2:多轮对话上下文丢失? **排查步骤:** 1. 检查 Redis 是否正常运行:`docker ps | grep redis` 2. 检查 `session_id` 是否每次请求都相同(终端需保持 session 不变) 3. 检查 Redis 会话过期时间(默认 86400 秒) ```bash # 查看 Redis 日志 docker compose logs redis ``` ### Q3:ASR 并发数超限如何处理? **现象**:用户语音输入无响应,终端提示"无法识别语音"或"服务繁忙"。 **排查步骤:** 1. 登录华为云控制台,查看 **语音交互服务 → ASR** 的用量监控 2. 确认当前并发使用量是否已达到套餐上限 | 紧急程度 | 处理方式 | |:---|:---| | 临时紧急 | 在控制台申请临时扩容(需企业认证) | | 短期解决 | 降级为文字输入模式,减少 ASR 调用 | | 长期解决 | 升级套餐或购买额外并发包 | **预防措施**: - 在华为云监控控制台配置 ASR 并发告警(阈值建议设为套餐上限的 80%) - 在 `digital-human.py` 中可增加请求排队逻辑,超时返回友好提示 ### Q4:流式响应延迟高? **排查步骤:** 1. 检查 Dify 服务响应时间(单独测试 Dify 接口) 2. 检查服务器与 Dify 服务器之间的网络延迟 3. 确认 `digital-human.py` 中 `generate_streaming_messages` 实时 yield 4. 检查 Redis 查询耗时(`session_id` 读取) ### Q5:API 返回 APIGW.0308 错误码(QPS 流控限制)? **现象**:API 调用时报错,提示"请求过于频繁"。 **原因**:触发了 MetaStudio API QPS 流控限制。 #### 核心接口 QPS 限制(单租户): | 接口分类 | 操作类型 | 华北-北京四 | 华东-上海一 | 亚太-新加坡 | |:---|:---|:---:|:---:|:---:| | 数字资产管理 | 查询资产列表/详情 | 20次/秒 | 10次/秒 | 10次/秒 | | 数字资产管理 | 创建/更新/删除资产 | 10次/秒 | 5次/秒 | 5次/秒 | | **智能交互对话** | **创建对话** | **5次/秒** | **3次/秒** | **不支持** | | 语音合成 TTS | 试听任务 | 5次/秒 | 3次/秒 | 3次/秒 | | 分身数字人 | 创建视频任务 | 5次/秒 | 3次/秒 | 3次/秒 | #### 低频限制接口(1次/秒): - 批量资产操作 - 导入导出相关操作 - 交互助手相关操作(角色、知识库、问答对) **解决方案**: | 场景 | 处理方式 | |:---|:---| | 轻微超限 | 在代码中增加请求间隔(如 `asyncio.sleep(0.2)`) | | 持续超限 | 将业务拆分到多个子账号,分散 QPS 压力 | | 长期需求 | 提交工单申请 QPS 配额提升 | > **说明**:华北-北京四区域 QPS 限制最宽松,是跨区域部署的首选区域。 --- ## 附录 ### A. 华为云 MetaStudio 官方文档 | 资源 | 地址 | |:---|:---| | MetaStudio 控制台 | https://console.huaweicloud.com/metastudio/ | | MetaStudio 产品文档 | https://support.huaweicloud.com/metastudio/ | | 产品功能说明 | https://support.huaweicloud.com/productdesc-metastudio/metastudio_01_0001.html | | 计费说明 | https://support.huaweicloud.com/productdesc-metastudio/metastudio_01_0006.html | | API 使用限制(QPS 流控) | https://support.huaweicloud.com/productdesc-metastudio/metastudio_01_0010.html | | 智能交互限制 | https://support.huaweicloud.com/productdesc-metastudio/metastudio_01_0017.html | | 华为云定价页面 | https://www.huaweicloud.com/price_detail.html | ### B. 部署检查清单 ``` □ 华为云 MetaStudio 已开通 □ 华为云 SIS(ASR + TTS)已开通(如需语音) □ 奇妙问 ASR 服务已开通(如使用奇妙问 ASR) □ 中转服务器防火墙已放行 TCP 8000 端口 □ digital-human.py 中转服务已启动(状态:healthy) □ Redis 连接正常 □ Dify 平台应用已创建,知识库文档已上传 □ Dify API Key 已填入 .env # MetaStudio 控制台配置 □ 登录 MetaStudio 工作台,点击「分身智能交互」卡片 □ 角色配置:已选择分身数字人形象(已上传至 MetaStudio) □ 背景配置:已上传背景图片或选择透明背景 □ 互动问答:已选择「第三方大脑(大模型)」 □ APPKEY:已填入中转服务签名密钥 □ 第三方语言模型地址:已正确填写(中转服务 URL,须公网可达) □ 流式响应:已按需开启/关闭 □ 多轮语境理解能力:已配置(推荐 3) □ ASR 服务:已选择「奇妙问」并填入账号和密钥 □ 尾静音时长:已设置为 ≥ 500ms □ 配置检查:已点击验证,无报错 # 对话配置 □ 语言和声音:已匹配(中文/英文音色对应) □ 语速:已调整(推荐 1.0X) □ 静默退出时长:已设置(建议 5 分钟) # 发布与测试 □ 发布设置:并发数和有效期已按需配置 □ 激活码:已获取并保存 □ 预览测试通过,数字人能正常对话 □ ASR 并发告警已配置(生产环境) ``` ### C. 名词解释 | 名词 | 说明 | |:---|:---| | 第三方大脑(第三方大模型) | MetaStudio 智能交互对外调用的外部 LLM 接口,本方案通过中转服务对接 Dify | | 中转服务 | digital-human.py,将 MetaStudio 请求转发至 Dify,并处理多轮对话上下文 | | CBS | 华为云对话机器人服务(Conversational Bot Service),MetaStudio 智能交互的默认大脑 | | QPS | 每秒请求数(Query Per Second),API 调用频率上限 | | ASR | 自动语音识别(Automatic Speech Recognition),将用户语音转为文字 | | TTS | 语音合成(Text To Speech),将文字转为自然语音 | | SSE | Server-Sent Events,服务端流式推送协议,MetaStudio 与中转服务之间的流式响应格式 |