612 lines
24 KiB
Markdown
612 lines
24 KiB
Markdown
# 华为云数字内容生产线 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服务器地址> <Dify API密钥>
|
||
```
|
||
|
||
**参数说明：**
|
||
|
||
| 参数 | 含义 | 示例 |
|
||
|:---|:---|:---|
|
||
| `<Dify服务器地址>` | Dify 服务的主机地址或域名（**不包含 `/v1`**，脚本会自动拼接为 `http://<地址>/v1/chat-messages`） | `atwdify.antiwearvalve.com` |
|
||
| `<Dify API密钥>` | 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 与中转服务之间的流式响应格式 |
|