Files

ZF sun 532c0e8685 docs: 更新README文档，添加项目说明和功能细节

- 添加项目定制化开发说明和公司信息
- 补充详细功能说明，包括语音唤醒、字幕样式、多语言支持等
- 增加生产部署指南和唤醒模型更新步骤
- 完善注意事项和技术支持信息

2026-05-07 09:26:54 +08:00

12 KiB

Raw Permalink Blame History

华为交互数字人 - HwICSUiSdk 标准集成项目

项目说明：本项目是华为交互数字人 HwICSUiSdk 标准集成项目的定制化开发版本，专为安特威公司打造，由江苏云上企数字科技有限公司研发。

这是一个基于 HwICSUiSdk 的华为交互数字人标准集成示例项目，展示了如何在前端项目中集成和使用数字人交互功能。

📁 项目结构

antiwear-web/
├── frontend/                # 前端项目
│   ├── index.html          # 主页面
│   ├── styles/
│   │   └── main.css        # 自定义样式
│   ├── scripts/
│   │   ├── main.js         # 主逻辑代码
│   │   └── api.js          # 前端 API 调用模块
│   └── hwICSUiSdk/         # SDK 目录（已提供）
│       ├── HwICSUiSdk.esm.js   # ESM 模块入口
│       ├── HwICSUiSdk.d.ts     # TypeScript 类型定义
│       ├── HwICSUiSdk.css      # SDK 样式
│       └── ...
├── backend/                 # 后端服务
│   └── server/
│       ├── index.js        # 后端主入口
│       ├── .env            # 环境变量配置
│       ├── package.json    # 后端依赖
│       └── APIGW-javascript-sdk-2.0.6/  # 华为云签名SDK
├── .gitignore              # Git 忽略配置
└── README.md               # 项目说明

🚀 快速开始

1. 环境要求

Node.js 14+ (后端服务)
现代浏览器（Chrome、Firefox、Edge、Safari 最新版本）
支持 WebRTC 和 WebSocket
需要麦克风权限（用于语音交互）

2. 获取华为云 AK/SK

访问密钥（AK/SK，Access Key ID/Secret Access Key）是您在华为云的长期身份凭证，用于 API 请求签名认证。

获取步骤

登录华为云控制台
将鼠标移至右上角用户名处，在下拉列表中单击 "我的凭证"
单击 "访问密钥" 区域
单击 "新增访问密钥"
输入描述信息后单击 "确定"
单击 "立即下载" 下载密钥文件（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 获取方式：

登录华为云控制台
进入 "我的凭证" > "项目 ID"
或访问获取项目ID

3. 后端服务配置

方式一：使用 AK/SK 认证（推荐）

设置环境变量：

# Windows
set HUAWEI_AK=your_access_key
set HUAWEI_SK=your_secret_key
set HUAWEI_PROJECT_ID=your_project_id

# Linux/Mac
export HUAWEI_AK=your_access_key
export HUAWEI_SK=your_secret_key
export HUAWEI_PROJECT_ID=your_project_id

方式二：使用用户名密码认证

# 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

# 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. 启动服务

启动后端服务

cd backend/server
npm install
npm start

后端服务将在 http://localhost:3001 启动。

启动前端项目

在另一个终端窗口：

# 使用 Python 3
cd frontend
python -m http.server 8080

# 或使用 Node.js 的 http-server
npx http-server frontend -p 8080

# 或使用 VS Code Live Server 插件

然后在浏览器中访问 http://localhost:8080

5. 配置参数

默认参数（已预填）

参数	默认值
服务器地址	`metastudio-api.cn-north-4.myhuaweicloud.com`
机器人ID	`2c9084bf9c9cc1c0019db2c4ca2a5c89`
项目ID	`c67bf5e7d1f84d20a6eefff2c1ee9cd4`

6. 使用流程

启动后端服务：cd backend/server && npm start
启动前端服务器：cd frontend && python -m http.server 8080
获取授权码：点击页面上的 "🔑 获取授权码" 按钮
初始化 SDK：点击 "初始化 SDK" 开始使用

📖 功能说明

核心功能

SDK 初始化与销毁
- 初始化：配置服务器地址、机器人ID等参数
- 销毁：释放资源，清理数字人实例
对话控制
- 开始对话：启动数字人交互会话
- 停止对话：结束当前会话
- 对话保活：自动保持对话活跃，防止超时断开
语音交互
- 语音自动唤醒：无需点击，语音唤醒数字人（唤醒词："云笙云笙"）
- 开始说话：启动语音识别，用户语音输入
- 停止说话：结束语音识别
字幕样式设置
- 支持设置容器、提示文字、消息、热点问题标题、热点问题列表的样式
- 包括字体大小、颜色、粗细、行高、背景颜色、透明度、圆角、内边距
- 样式设置自动保存到本地存储，刷新页面后自动恢复
- 支持重置为默认样式
字幕容器控制
- 拖拽字幕容器到任意位置
- 调整字幕容器大小
- 位置和尺寸自动记忆，刷新页面后自动恢复
多语言支持
- 支持中文和英文语音切换
- 根据后端配置自动加载可用语言列表
面板管理
- 所有弹出面板支持拖拽到任意位置
- 面板默认居中显示
- 自适应高度（除字幕样式面板外）
其他控制
- 全屏显示：支持数字人全屏模式
- 查看日志：显示 SDK 事件和调试信息

事件监听

SDK 提供了丰富的事件回调：

事件	说明
ERROR	错误事件
JOB_INFO_CHANGE	任务信息变更
SPEAKING_START	数字人开始说话
SPEAKING_STOP	数字人停止说话
SPEECH_RECOGNIZED	语音识别结果
SEMANTIC_RECOGNIZED	语义识别结果
ENTER_SLEEP	进入休眠状态
ENTER_ACTIVE	进入激活状态
JOB_END	任务结束

🔧 开发指南

前端 API 调用

后端服务提供了以下接口：

获取一次性授权码

POST /api/once-code

响应示例：

{
  "once_code": "OATAXWpTNDPGjVyzxNLKvumcv297Q7uUz5CCltLtFDE1uqnPAPmS4jm61XnMQGuV"
}

错误响应：

{
  "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	false	显示语言切换UI
ENABLE_DEVICE_SETTING	boolean	false	启用设备设置
ENABLE_NETWORK_CHECK	boolean	false	启用网络检查
AUTO_PLAY_REMOTE_VIDEO	boolean	true	自动播放远程视频
DEFAULT_MUTE_REMOTE_AUDIO	boolean	false	默认静音远程音频
ENABLE_LOCAL_WAKEUP	boolean	true	启用本地语音唤醒
USE_WORKER_WAKEUP	boolean	false	使用Worker线程运行唤醒模块

唤醒词

唤醒词	说明
云笙云笙	主唤醒词
谢谢再见	结束对话
稍等一下	打断/等待

<EFBFBD> 生产部署

前端部署

构建静态文件

# 使用 Python 打包
cd frontend
python -c "import http.server; print('请使用 nginx/apache 等服务器部署')"

推荐部署方式

推荐使用 Nginx 或 Apache 部署前端静态文件：

Nginx 配置示例

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    root /path/to/frontend;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://backend-server:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location /hwICSUiSdk/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

HTTPS 要求
- WebRTC 功能必须使用 HTTPS 环境
- 建议使用有效的 SSL 证书
- 自签名证书仅适用于本地开发
跨域配置
- 后端服务需配置 CORS 允许前端域名访问
- 或使用 Nginx 反向代理

后端部署

环境变量配置

# 生产环境建议使用 systemd 管理后端服务
export NODE_ENV=production
export PORT=3001

进程管理

# 使用 PM2 管理
npm install -g pm2
pm2 start backend/server/index.js --name digital-human-api

# 设置开机自启
pm2 save
pm2 startup

📦 唤醒模型更新

模型文件位置

唤醒模型相关文件位于 frontend/hwICSUiSdk/ 目录：

wasmData.js - WASM 虚拟机数据
modelData.js - 唤醒词模型数据

更新模型步骤

获取新模型文件
- 联系华为技术支持获取新的唤醒词模型
- 或通过华为云控制台下载

替换文件

# 备份旧文件
mv frontend/hwICSUiSdk/wasmData.js frontend/hwICSUiSdk/wasmData.js.bak
mv frontend/hwICSUiSdk/modelData.js frontend/hwICSUiSdk/modelData.js.bak

# 复制新文件
cp new_wasmData.js frontend/hwICSUiSdk/wasmData.js
cp new_modelData.js frontend/hwICSUiSdk/modelData.js

验证更新

刷新页面
查看日志确认模型加载成功：

[INFO] kws_manager.cpp:197 InitModelManager: Init kws model success.

更新唤醒词
- 唤醒词配置在后端，修改后需重新获取授权码
- 确认新的唤醒词并通知用户

常见问题

问题	解决方案
模型加载失败	检查文件路径是否正确，确认文件完整性
唤醒无响应	确认麦克风权限，查看日志中的错误信息
模型版本不匹配	确保 wasmData.js 和 modelData.js 版本一致

<EFBFBD><EFBFBD> 注意事项

HTTPS 要求：在生产环境中，WebRTC 功能需要在 HTTPS 环境下运行
浏览器权限：首次使用需要授权麦克风权限
资源释放：页面卸载时务必调用 destroy() 方法释放资源
错误处理：建议对所有异步操作添加错误处理
后端服务：获取授权码需要启动后端服务并配置正确的环境变量
唤醒词：语音唤醒需要先初始化 SDK，对着麦克风说"云笙云笙"即可唤醒数字人
样式保存：字幕样式和容器位置会自动保存到浏览器本地存储

🔍 调试技巧

使用浏览器开发者工具查看控制台日志

调整日志级别查看详细信息：

HwICSUiSdk.setLogLevel('debug'); // debug | info | warn | error | none

查看网络面板监控 WebSocket 连接

📄 许可证

本项目仅供安特威公司相关人员学习和参考使用。

🤝 技术支持

如有问题，请参考 HwICSUiSdk 官方文档或联系江苏云上企数字科技有限公司技术支持。

12 KiB Raw Permalink Blame History Unescape Escape