Projects/antiwear-gateway

Fork 0

Files

ZF sun 4f93eaf251 Update 华为云MetaStudio交互数字人配置指南.md

2026-04-24 10:01:40 +08:00

23 KiB

Raw Blame History

华为云数字内容生产线 MetaStudio 智能交互数字人配置指南

本文档记录基于华为云 MetaStudio 智能交互 + 第三方大脑（华为云官方称为"第三方大模型"）的交互数字人配置方案，智能大脑使用 Dify 平台。

重要公告：华为云 MetaStudio 3D 数字人产品已停售；Flexus 分身数字人仅支持视频制作，不支持智能交互。本文档智能交互部分仅涵盖 分身数字人 相关配置。

一、整体架构

用户 ──→ 华为云 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 开通华为云服务

登录华为云官网，依次开通以下服务：

MetaStudio（数字内容生产线）
- 进入 MetaStudio 控制台
- 开通服务，按需选择资源包
语音交互服务 SIS（语音交互）
- 如需语音对话，开通：
  - 语音合成 TTS：将文字转为自然语音
  - 语音识别 ASR：将用户语音转为文字
- ASR/TTS 计费属于独立计费项，请以华为云控制台实时价格为准
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 快速部署（一键脚本）

华为云官方提供自动部署脚本，在中转服务器上执行：

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-platform/human/digital-human.sh \
  && bash /tmp/digital-human.sh {Dify_IP} {API_KEY}

参数	说明	示例
`Dify_IP`	Dify 服务地址（末尾带 `/v1`）	`https://atwdify.antiwearvalve.com/v1`
`API_KEY`	Dify API 密钥（纯密钥，不要 `Bearer` 前缀）	`app-PDkSHiHZsZIluoZF7N2OlNZM`

3.2 手动部署（Docker Compose）

如需手动部署：

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 必填项：

# Dify 服务地址（末尾不要加 /chat-messages）
DIFY_URL=https://your-dify-domain.com/v1

# Dify API 密钥（纯密钥，不要加 Bearer 前缀）
DIFY_API_KEY=app-xxxxxxxxxxxxxxxx

3.3 配置防火墙

允许外部访问中转服务端口（默认 8000）：

# 云服务器安全组：放行 TCP 8000 端口（源地址 0.0.0.0/0）
# 或使用云防火墙配置规则

3.4 验证中转服务

# 健康检查
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` = 非流式阻塞返回

响应（非流式）：

{
  "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 /`（健康检查）

{"status":"ok"}

四、配置 Dify 应用

Dify 是交互数字人的"大脑"，负责知识库检索和大语言模型对话生成。

4.1 创建 Dify 应用

登录 Dify 平台
创建应用，选择类型：
- 聊天助手：适合问答场景（推荐）
- Agent：适合复杂任务处理
- Workflow：适合流程化对话

4.2 配置知识库

进入应用 → 知识库
上传文档，支持格式：PDF、Word（.docx）、TXT、Markdown、网页 URL
文档分段策略：

策略	说明	适用场景
自动分段	AI 自动识别段落	通用场景
固定长度分段	每 N 个字符一段	结构化文档
自定义分段	手动设置分段点	精准控制

设置 Embedding 模型（推荐使用与 LLM 同供应商的服务）

4.3 配置提示词（对话技能）

在应用 提示词 中配置，控制数字人回答风格：

你是华为云交互数字人客服，名为"小华"。
你的职责是：
1. 热情、专业地回答用户关于产品和服务的问题
2. 回答简洁有条理，不超过3句话
3. 遇到无法回答的问题，引导用户转人工服务
4. 禁止回答与公司业务无关的问题

4.4 获取 API Key

进入 Dify 应用 → API 标签页
复制 API Key（格式如 app-xxxxxxxxxxxxxxxx）
将 API Key 填入中转服务 .env 中的 DIFY_API_KEY

4.5 多轮对话说明

session_id：由 MetaStudio 终端生成，每次对话中保持一致
conversation_id：由 Dify 返回，存储在中转服务 Redis 中
会话超时：默认 86400 秒（24 小时），可按需调整 Redis expire 时间

五、配置 MetaStudio 智能交互

控制台路径：登录 MetaStudio → 进入工作台 → 点击「分身智能交互」卡片 → 在对话项目编辑页面配置各环节参数。

5.1 进入控制台与创建对话项目

操作步骤：

登录 MetaStudio 控制台，进入 MetaStudio 服务概览页面
点击「前往 MetaStudio 工作台」
在工作台页面点击「分身智能交互」卡片
进入智能交互对话项目编辑页面，依次配置以下参数

创建与编辑入口：如已有对话项目，在「我的创作 → 智能交互」列表中点击对应项目名称进入编辑。

5.2 角色配置

在编辑页面左侧「角色」区域，配置数字人形象：

配置项	说明
定制数字人	点击跳转到形象制作页面，发起分身数字人定制任务
搜索框	输入数字人名称，精准筛选已创建的数字人
筛选条件	支持按角色、性别、姿势、行业、区域和分辨率筛选
数字人卡片列表	点击卡片自动替换为对应形象

形象类型说明：

类型	说明
分身数字人	基于真人形象采集打造，交互自然，推荐正式客服场景
照片数字人	上传照片即可生成，适合快速验证

重要：Flexus 分身数字人仅支持视频制作，不支持智能交互，详见 Flexus 分身数字人限制说明。3D 数字人产品已停售，均不在可选范围内。

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 账号	奇妙问平台账号	需联系奇妙问客户经理注册开通，详见奇妙问配置说明
ASR 密钥	奇妙问平台密钥	同上

ASR 说明：如仅需文字输入模式，可不配置 ASR 服务，使用 MetaStudio 自带的文字输入入口进行对话测试。

其他参数

配置项	建议值	说明
尾静音时长	`≥ 500ms`	云端对音频进行 VAD 检测，静默超过此值结束语音识别，建议不低于 500ms
热词	按需配置	语音识别不准确的专业词汇可作为热词反馈至语音模型，提高识别准确率

配置检查

点击「配置检查」，系统自动验证当前配置是否正确，如有错误会显示相应提示。

5.5 对话配置

在编辑页面点击「对话配置」页签，配置语言与声音参数：

配置项	取值范围	说明
语言	中文 / 英文	支持同时添加并设置默认语言，可通过界面右上角图标切换
声音	需与语言匹配	中文选中文音色，英文选英文音色
语速	0.5X ~ 2X	推荐 1.0X（正常语速）
音量	90 ~ 240	建议调大初始音量以保证播放效果适中
音高	50 ~ 200	音高增加声音更尖锐，降低更低沉
静默退出时长	5 ~ 1440 分钟	无操作超过设定时间后自动关闭对话窗口

5.6 发布设置

在编辑页面右上角点击「发布」：

配置项	说明
激活码	发布成功后自动生成，用于激活对话链接
并发数	同时访问的最大用户数量，超过时报 `MSS.20010135` 错误（对话资源不足），需根据实际需求配置
有效期	从发布开始的智能交互可用时长

发布后操作：

点击「发布」，成功后弹出对话框
点击「发布链接」→ 在"智能交互激活"界面输入激活码激活对话
或点击「复制分享」→ 一键复制发布链接和激活码，分享给用户

修改已发布的项目：返回编辑页面，点击「修改」按钮即可重新编辑配置（发布后激活码会更新）。

5.7 终端类型说明

MetaStudio 智能交互支持以下终端接入方式，同一对话项目可适配多种终端：

终端	说明	适用场景
PC 端（网页）	通过浏览器访问发布链接，麦克风权限授权后即可语音对话	官网客服、展厅大屏
手机端	在移动浏览器中打开，支持语音输入	微信/企业微信嵌入、APP 内嵌 H5
大屏端	通过专用大屏终端 SDK 接入，适合触摸大屏设备	展厅、营业厅、政务服务大厅

5.8 预览与测试

配置完成后，使用控制台内置的模拟器进行预览测试：

在编辑页面右侧预览区选择终端类型（电脑端 / 手机端）
在模拟器中输入文字或点击麦克风进行语音测试
验证 Dify 回复是否正确返回、数字人播报是否正常
如有问题，点击「配置检查」排查，或参考第六节常见问题

六、常见问题

Q1：中转服务返回 500 错误？

排查步骤：

检查 .env 中 DIFY_URL 是否正确（末尾是否为 /v1）
检查 DIFY_API_KEY 是否有效
确认服务器能访问 Dify 地址：

curl -I $DIFY_URL

Q2：多轮对话上下文丢失？

排查步骤：

检查 Redis 是否正常运行：docker ps | grep redis
检查 session_id 是否每次请求都相同（终端需保持 session 不变）
检查 Redis 会话过期时间（默认 86400 秒）

# 查看 Redis 日志
docker compose logs redis

Q3：ASR 并发数超限如何处理？

现象：用户语音输入无响应，终端提示"无法识别语音"或"服务繁忙"。

排查步骤：

登录华为云控制台，查看 语音交互服务 → ASR 的用量监控
确认当前并发使用量是否已达到套餐上限

紧急程度	处理方式
临时紧急	在控制台申请临时扩容（需企业认证）
短期解决	降级为文字输入模式，减少 ASR 调用
长期解决	升级套餐或购买额外并发包

预防措施：

在华为云监控控制台配置 ASR 并发告警（阈值建议设为套餐上限的 80%）
在 digital-human.py 中可增加请求排队逻辑，超时返回友好提示

Q4：流式响应延迟高？

排查步骤：

检查 Dify 服务响应时间（单独测试 Dify 接口）
检查服务器与 Dify 服务器之间的网络延迟
确认 digital-human.py 中 generate_streaming_messages 实时 yield
检查 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 与中转服务之间的流式响应格式

23 KiB Raw Blame History Unescape Escape

华为云数字内容生产线 MetaStudio 智能交互数字人配置指南

目录

一、整体架构

二、前置准备

2.1 开通华为云服务

2.2 ASR 并发数限制说明

2.3 准备资源清单

三、部署 Dify 中转服务

3.1 快速部署（一键脚本）

3.2 手动部署（Docker Compose）

3.3 配置防火墙

3.4 验证中转服务

3.5 中转服务接口说明

POST /digital-human（核心接口）

GET /（健康检查）

四、配置 Dify 应用

4.1 创建 Dify 应用

4.2 配置知识库

4.3 配置提示词（对话技能）

4.4 获取 API Key

4.5 多轮对话说明

五、配置 MetaStudio 智能交互

5.1 进入控制台与创建对话项目

5.2 角色配置

5.3 背景配置

5.4 互动问答配置（第三方大脑）

基础参数

流式与多轮对话参数

ASR 服务配置

其他参数

配置检查

5.5 对话配置

5.6 发布设置

5.7 终端类型说明

5.8 预览与测试

六、常见问题

Q1：中转服务返回 500 错误？

Q2：多轮对话上下文丢失？

Q3：ASR 并发数超限如何处理？

Q4：流式响应延迟高？

Q5：API 返回 APIGW.0308 错误码（QPS 流控限制）？

核心接口 QPS 限制（单租户）：

低频限制接口（1次/秒）：

附录

A. 华为云 MetaStudio 官方文档

B. 部署检查清单

C. 名词解释

23 KiB

Raw Blame History

`POST /digital-human`（核心接口）

`GET /`（健康检查）