262 lines
7.0 KiB
Markdown
262 lines
7.0 KiB
Markdown
# 华为交互数字人 - HwICSUiSdk 标准集成项目
|
||
|
||
这是一个基于 HwICSUiSdk 的华为交互数字人标准集成示例项目，展示了如何在前端项目中集成和使用数字人交互功能。
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
antiwear-web/
|
||
├── hwICSUiSdk/ # SDK 目录（已提供）
|
||
│ ├── HwICSUiSdk.esm.js # ESM 模块入口
|
||
│ ├── HwICSUiSdk.d.ts # TypeScript 类型定义
|
||
│ ├── HwICSUiSdk.css # SDK 样式
|
||
│ └── ...
|
||
├── server/ # 后端服务
|
||
│ ├── index.js # 后端主入口
|
||
│ └── package.json # 后端依赖
|
||
├── scripts/
|
||
│ ├── main.js # 主逻辑代码
|
||
│ └── api.js # 前端 API 调用模块
|
||
├── styles/
|
||
│ └── main.css # 自定义样式
|
||
├── index.html # 主页面
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 环境要求
|
||
|
||
- Node.js 14+ (后端服务)
|
||
- 现代浏览器（Chrome、Firefox、Edge、Safari 最新版本）
|
||
- 支持 WebRTC 和 WebSocket
|
||
- 需要麦克风权限（用于语音交互）
|
||
|
||
### 2. 获取华为云 AK/SK
|
||
|
||
访问密钥（AK/SK，Access Key ID/Secret Access Key）是您在华为云的长期身份凭证，用于 API 请求签名认证。
|
||
|
||
#### 获取步骤
|
||
|
||
1. 登录 [华为云控制台](https://console.huaweicloud.com)
|
||
2. 将鼠标移至右上角用户名处，在下拉列表中单击 **"我的凭证"**
|
||
3. 单击 **"访问密钥"** 区域
|
||
4. 单击 **"新增访问密钥"**
|
||
5. 输入描述信息后单击 **"确定"**
|
||
6. 单击 **"立即下载"** 下载密钥文件（credentials.csv）
|
||
|
||
> **注意**：
|
||
> - 每个用户最多可创建 **2个** 访问密钥
|
||
> - 每个访问密钥仅能下载 **一次**，请妥善保管
|
||
> - 访问密钥永久有效，建议定期更换
|
||
|
||
下载的 CSV 文件内容示例：
|
||
```
|
||
username,user_id,access_key,secret_access_key
|
||
username@example.com,xxxxxxx,AKXXXXXXXXXX,skXXXXXXXXXX...
|
||
```
|
||
|
||
其中：
|
||
- **AK**（Access Key）：对应环境变量 `HUAWEI_AK`
|
||
- **SK**（Secret Access Key）：对应环境变量 `HUAWEI_SK`
|
||
|
||
#### 获取项目 ID（Project ID）
|
||
|
||
项目 ID 获取方式：
|
||
1. 登录华为云控制台
|
||
2. 进入 "我的凭证" > "项目 ID"
|
||
3. 或访问 [获取项目ID](https://support.huaweicloud.com/api-metastudio/metastudio_02_0006.html)
|
||
|
||
### 3. 后端服务配置
|
||
|
||
#### 方式一：使用 AK/SK 认证（推荐）
|
||
|
||
设置环境变量：
|
||
```bash
|
||
# Windows
|
||
set HUAWEI_AK=your_access_key
|
||
set HUAWEI_SK=your_secret_key
|
||
set HUAWEI_PROJECT_ID=your_project_id
|
||
```
|
||
|
||
```bash
|
||
# Linux/Mac
|
||
export HUAWEI_AK=your_access_key
|
||
export HUAWEI_SK=your_secret_key
|
||
export HUAWEI_PROJECT_ID=your_project_id
|
||
```
|
||
|
||
#### 方式二：使用用户名密码认证
|
||
|
||
```bash
|
||
# Windows
|
||
set HUAWEI_USERNAME=your_username
|
||
set HUAWEI_PASSWORD=your_password
|
||
set HUAWEI_DOMAIN_NAME=your_domain_name
|
||
set HUAWEI_PROJECT_ID=your_project_id
|
||
```
|
||
|
||
```bash
|
||
# Linux/Mac
|
||
export HUAWEI_USERNAME=your_username
|
||
export HUAWEI_PASSWORD=your_password
|
||
export HUAWEI_DOMAIN_NAME=your_domain_name
|
||
export HUAWEI_PROJECT_ID=your_project_id
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
#### 启动后端服务
|
||
|
||
```bash
|
||
cd server
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
后端服务将在 `http://localhost:3001` 启动。
|
||
|
||
#### 启动前端项目
|
||
|
||
在另一个终端窗口：
|
||
|
||
```bash
|
||
# 使用 Python 3
|
||
python -m http.server 8080
|
||
|
||
# 或使用 Node.js 的 http-server
|
||
npx http-server -p 8080
|
||
|
||
# 或使用 VS Code Live Server 插件
|
||
```
|
||
|
||
然后在浏览器中访问 `http://localhost:8080`
|
||
|
||
### 5. 配置参数
|
||
|
||
#### 默认参数（已预填）
|
||
| 参数 | 默认值 |
|
||
|------|--------|
|
||
| 服务器地址 | `metastudio-api.cn-north-4.myhuaweicloud.com` |
|
||
| 机器人ID | `2c9084bf9c9cc1c0019db2c4ca2a5c89` |
|
||
| 项目ID | `c67bf5e7d1f84d20a6eefff2c1ee9cd4` |
|
||
|
||
### 6. 使用流程
|
||
|
||
1. **启动后端服务**：`cd server && npm start`
|
||
2. **启动前端服务器**：`python -m http.server 8080`
|
||
3. **获取授权码**：点击页面上的 "🔑 获取授权码" 按钮
|
||
4. **初始化 SDK**：点击 "初始化 SDK" 开始使用
|
||
|
||
## 📖 功能说明
|
||
|
||
### 核心功能
|
||
|
||
1. **SDK 初始化与销毁**
|
||
- 初始化：配置服务器地址、机器人ID等参数
|
||
- 销毁：释放资源，清理数字人实例
|
||
|
||
2. **对话控制**
|
||
- 开始对话：启动数字人交互会话
|
||
- 停止对话：结束当前会话
|
||
|
||
3. **语音交互**
|
||
- 开始说话：启动语音识别，用户语音输入
|
||
- 停止说话：结束语音识别
|
||
|
||
4. **文本交互**
|
||
- 发送文本消息给数字人
|
||
|
||
5. **其他控制**
|
||
- 打断说话：立即中断数字人当前说话
|
||
- 静音/取消静音：控制远程音频
|
||
|
||
### 事件监听
|
||
|
||
SDK 提供了丰富的事件回调：
|
||
|
||
| 事件 | 说明 |
|
||
|------|------|
|
||
| ERROR | 错误事件 |
|
||
| JOB_INFO_CHANGE | 任务信息变更 |
|
||
| SPEAKING_START | 数字人开始说话 |
|
||
| SPEAKING_STOP | 数字人停止说话 |
|
||
| SPEECH_RECOGNIZED | 语音识别结果 |
|
||
| SEMANTIC_RECOGNIZED | 语义识别结果 |
|
||
| ENTER_SLEEP | 进入休眠状态 |
|
||
| ENTER_ACTIVE | 进入激活状态 |
|
||
| JOB_END | 任务结束 |
|
||
|
||
## 🔧 开发指南
|
||
|
||
### 前端 API 调用
|
||
|
||
后端服务提供了以下接口：
|
||
|
||
#### 获取一次性授权码
|
||
```
|
||
POST /api/once-code
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"once_code": "OATAXWpTNDPGjVyzxNLKvumcv297Q7uUz5CCltLtFDE1uqnPAPmS4jm61XnMQGuV"
|
||
}
|
||
```
|
||
|
||
错误响应：
|
||
```json
|
||
{
|
||
"error_code": "CONFIG_MISSING",
|
||
"error_msg": "请配置环境变量 (AK/SK 或用户名密码)"
|
||
}
|
||
```
|
||
|
||
### 后端接口
|
||
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| /api/once-code | POST | 获取一次性授权码 |
|
||
| /health | GET | 健康检查 |
|
||
|
||
## ⚙️ 配置选项
|
||
|
||
SDK 支持多种配置项：
|
||
|
||
| 配置项 | 类型 | 默认值 | 说明 |
|
||
|--------|------|--------|------|
|
||
| ENABLE_CAPTION | boolean | true | 启用字幕显示 |
|
||
| ENABLE_CHAT_BTN | boolean | true | 启用聊天按钮 |
|
||
| ENABLE_HOT_ISSUES | boolean | true | 启用热点问题 |
|
||
| SHOW_LANGUAGE_UI | boolean | true | 显示语言切换UI |
|
||
| ENABLE_DEVICE_SETTING | boolean | true | 启用设备设置 |
|
||
| ENABLE_NETWORK_CHECK | boolean | true | 启用网络检查 |
|
||
| AUTO_PLAY_REMOTE_VIDEO | boolean | true | 自动播放远程视频 |
|
||
| DEFAULT_MUTE_REMOTE_AUDIO | boolean | false | 默认静音远程音频 |
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **HTTPS 要求**：在生产环境中，WebRTC 功能需要在 HTTPS 环境下运行
|
||
2. **浏览器权限**：首次使用需要授权麦克风和摄像头权限
|
||
3. **资源释放**：页面卸载时务必调用 `destroy()` 方法释放资源
|
||
4. **错误处理**：建议对所有异步操作添加错误处理
|
||
5. **后端服务**：获取授权码需要启动后端服务并配置正确的环境变量
|
||
|
||
## 🔍 调试技巧
|
||
|
||
1. 使用浏览器开发者工具查看控制台日志
|
||
2. 调整日志级别查看详细信息：
|
||
```javascript
|
||
HwICSUiSdk.setLogLevel('debug'); // debug | info | warn | error | none
|
||
```
|
||
3. 查看网络面板监控 WebSocket 连接
|
||
|
||
## 📄 许可证
|
||
|
||
本项目仅供学习和参考使用。
|
||
|
||
## 🤝 技术支持
|
||
|
||
如有问题，请参考 HwICSUiSdk 官方文档或联系技术支持。
|