docs: 更新README文档，添加项目说明和功能细节
- 添加项目定制化开发说明和公司信息 - 补充详细功能说明，包括语音唤醒、字幕样式、多语言支持等 - 增加生产部署指南和唤醒模型更新步骤 - 完善注意事项和技术支持信息
This commit is contained in:
178
README.md
178
README.md
@@ -1,5 +1,7 @@
|
|||||||
# 华为交互数字人 - HwICSUiSdk 标准集成项目
|
# 华为交互数字人 - HwICSUiSdk 标准集成项目
|
||||||
|
|
||||||
|
> **项目说明**：本项目是华为交互数字人 HwICSUiSdk 标准集成项目的定制化开发版本，专为**安特威**公司打造，由**江苏云上企数字科技有限公司**研发。
|
||||||
|
|
||||||
这是一个基于 HwICSUiSdk 的华为交互数字人标准集成示例项目，展示了如何在前端项目中集成和使用数字人交互功能。
|
这是一个基于 HwICSUiSdk 的华为交互数字人标准集成示例项目，展示了如何在前端项目中集成和使用数字人交互功能。
|
||||||
|
|
||||||
## 📁 项目结构
|
## 📁 项目结构
|
||||||
@@ -165,17 +167,36 @@ npx http-server frontend -p 8080
|
|||||||
2. **对话控制**
|
2. **对话控制**
|
||||||
- 开始对话：启动数字人交互会话
|
- 开始对话：启动数字人交互会话
|
||||||
- 停止对话：结束当前会话
|
- 停止对话：结束当前会话
|
||||||
|
- 对话保活：自动保持对话活跃，防止超时断开
|
||||||
|
|
||||||
3. **语音交互**
|
3. **语音交互**
|
||||||
|
- 语音自动唤醒：无需点击，语音唤醒数字人（唤醒词："云笙云笙"）
|
||||||
- 开始说话：启动语音识别，用户语音输入
|
- 开始说话：启动语音识别，用户语音输入
|
||||||
- 停止说话：结束语音识别
|
- 停止说话：结束语音识别
|
||||||
|
|
||||||
4. **文本交互**
|
4. **字幕样式设置**
|
||||||
- 发送文本消息给数字人
|
- 支持设置容器、提示文字、消息、热点问题标题、热点问题列表的样式
|
||||||
|
- 包括字体大小、颜色、粗细、行高、背景颜色、透明度、圆角、内边距
|
||||||
|
- 样式设置自动保存到本地存储，刷新页面后自动恢复
|
||||||
|
- 支持重置为默认样式
|
||||||
|
|
||||||
5. **其他控制**
|
5. **字幕容器控制**
|
||||||
- 打断说话：立即中断数字人当前说话
|
- 拖拽字幕容器到任意位置
|
||||||
- 静音/取消静音：控制远程音频
|
- 调整字幕容器大小
|
||||||
|
- 位置和尺寸自动记忆，刷新页面后自动恢复
|
||||||
|
|
||||||
|
6. **多语言支持**
|
||||||
|
- 支持中文和英文语音切换
|
||||||
|
- 根据后端配置自动加载可用语言列表
|
||||||
|
|
||||||
|
7. **面板管理**
|
||||||
|
- 所有弹出面板支持拖拽到任意位置
|
||||||
|
- 面板默认居中显示
|
||||||
|
- 自适应高度（除字幕样式面板外）
|
||||||
|
|
||||||
|
8. **其他控制**
|
||||||
|
- 全屏显示：支持数字人全屏模式
|
||||||
|
- 查看日志：显示 SDK 事件和调试信息
|
||||||
|
|
||||||
### 事件监听
|
### 事件监听
|
||||||
|
|
||||||
@@ -235,19 +256,152 @@ SDK 支持多种配置项：
|
|||||||
| ENABLE_CAPTION | boolean | true | 启用字幕显示 |
|
| ENABLE_CAPTION | boolean | true | 启用字幕显示 |
|
||||||
| ENABLE_CHAT_BTN | boolean | true | 启用聊天按钮 |
|
| ENABLE_CHAT_BTN | boolean | true | 启用聊天按钮 |
|
||||||
| ENABLE_HOT_ISSUES | boolean | true | 启用热点问题 |
|
| ENABLE_HOT_ISSUES | boolean | true | 启用热点问题 |
|
||||||
| SHOW_LANGUAGE_UI | boolean | true | 显示语言切换UI |
|
| SHOW_LANGUAGE_UI | boolean | false | 显示语言切换UI |
|
||||||
| ENABLE_DEVICE_SETTING | boolean | true | 启用设备设置 |
|
| ENABLE_DEVICE_SETTING | boolean | false | 启用设备设置 |
|
||||||
| ENABLE_NETWORK_CHECK | boolean | true | 启用网络检查 |
|
| ENABLE_NETWORK_CHECK | boolean | false | 启用网络检查 |
|
||||||
| AUTO_PLAY_REMOTE_VIDEO | boolean | true | 自动播放远程视频 |
|
| AUTO_PLAY_REMOTE_VIDEO | boolean | true | 自动播放远程视频 |
|
||||||
| DEFAULT_MUTE_REMOTE_AUDIO | boolean | false | 默认静音远程音频 |
|
| DEFAULT_MUTE_REMOTE_AUDIO | boolean | false | 默认静音远程音频 |
|
||||||
|
| ENABLE_LOCAL_WAKEUP | boolean | true | 启用本地语音唤醒 |
|
||||||
|
| USE_WORKER_WAKEUP | boolean | false | 使用Worker线程运行唤醒模块 |
|
||||||
|
|
||||||
## 📝 注意事项
|
### 唤醒词
|
||||||
|
|
||||||
|
| 唤醒词 | 说明 |
|
||||||
|
|--------|------|
|
||||||
|
| 云笙云笙 | 主唤醒词 |
|
||||||
|
| 谢谢再见 | 结束对话 |
|
||||||
|
| 稍等一下 | 打断/等待 |
|
||||||
|
|
||||||
|
## <20> 生产部署
|
||||||
|
|
||||||
|
### 前端部署
|
||||||
|
|
||||||
|
1. **构建静态文件**
|
||||||
|
```bash
|
||||||
|
# 使用 Python 打包
|
||||||
|
cd frontend
|
||||||
|
python -c "import http.server; print('请使用 nginx/apache 等服务器部署')"
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **推荐部署方式**
|
||||||
|
|
||||||
|
推荐使用 Nginx 或 Apache 部署前端静态文件：
|
||||||
|
|
||||||
|
**Nginx 配置示例**
|
||||||
|
```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";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **HTTPS 要求**
|
||||||
|
- WebRTC 功能必须使用 HTTPS 环境
|
||||||
|
- 建议使用有效的 SSL 证书
|
||||||
|
- 自签名证书仅适用于本地开发
|
||||||
|
|
||||||
|
4. **跨域配置**
|
||||||
|
- 后端服务需配置 CORS 允许前端域名访问
|
||||||
|
- 或使用 Nginx 反向代理
|
||||||
|
|
||||||
|
### 后端部署
|
||||||
|
|
||||||
|
1. **环境变量配置**
|
||||||
|
```bash
|
||||||
|
# 生产环境建议使用 systemd 管理后端服务
|
||||||
|
export NODE_ENV=production
|
||||||
|
export PORT=3001
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **进程管理**
|
||||||
|
```bash
|
||||||
|
# 使用 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` - 唤醒词模型数据
|
||||||
|
|
||||||
|
### 更新模型步骤
|
||||||
|
|
||||||
|
1. **获取新模型文件**
|
||||||
|
- 联系华为技术支持获取新的唤醒词模型
|
||||||
|
- 或通过华为云控制台下载
|
||||||
|
|
||||||
|
2. **替换文件**
|
||||||
|
```bash
|
||||||
|
# 备份旧文件
|
||||||
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **验证更新**
|
||||||
|
- 刷新页面
|
||||||
|
- 查看日志确认模型加载成功：
|
||||||
|
```
|
||||||
|
[INFO] kws_manager.cpp:197 InitModelManager: Init kws model success.
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **更新唤醒词**
|
||||||
|
- 唤醒词配置在后端，修改后需重新获取授权码
|
||||||
|
- 确认新的唤醒词并通知用户
|
||||||
|
|
||||||
|
### 常见问题
|
||||||
|
|
||||||
|
| 问题 | 解决方案 |
|
||||||
|
|------|----------|
|
||||||
|
| 模型加载失败 | 检查文件路径是否正确，确认文件完整性 |
|
||||||
|
| 唤醒无响应 | 确认麦克风权限，查看日志中的错误信息 |
|
||||||
|
| 模型版本不匹配 | 确保 wasmData.js 和 modelData.js 版本一致 |
|
||||||
|
|
||||||
|
## <20><> 注意事项
|
||||||
|
|
||||||
1. **HTTPS 要求**：在生产环境中，WebRTC 功能需要在 HTTPS 环境下运行
|
1. **HTTPS 要求**：在生产环境中，WebRTC 功能需要在 HTTPS 环境下运行
|
||||||
2. **浏览器权限**：首次使用需要授权麦克风和摄像头权限
|
2. **浏览器权限**：首次使用需要授权麦克风权限
|
||||||
3. **资源释放**：页面卸载时务必调用 `destroy()` 方法释放资源
|
3. **资源释放**：页面卸载时务必调用 `destroy()` 方法释放资源
|
||||||
4. **错误处理**：建议对所有异步操作添加错误处理
|
4. **错误处理**：建议对所有异步操作添加错误处理
|
||||||
5. **后端服务**：获取授权码需要启动后端服务并配置正确的环境变量
|
5. **后端服务**：获取授权码需要启动后端服务并配置正确的环境变量
|
||||||
|
6. **唤醒词**：语音唤醒需要先初始化 SDK，对着麦克风说"云笙云笙"即可唤醒数字人
|
||||||
|
7. **样式保存**：字幕样式和容器位置会自动保存到浏览器本地存储
|
||||||
|
|
||||||
## 🔍 调试技巧
|
## 🔍 调试技巧
|
||||||
|
|
||||||
@@ -260,8 +414,8 @@ SDK 支持多种配置项：
|
|||||||
|
|
||||||
## 📄 许可证
|
## 📄 许可证
|
||||||
|
|
||||||
本项目仅供学习和参考使用。
|
本项目仅供**安特威**公司相关人员学习和参考使用。
|
||||||
|
|
||||||
## 🤝 技术支持
|
## 🤝 技术支持
|
||||||
|
|
||||||
如有问题，请参考 HwICSUiSdk 官方文档或联系技术支持。
|
如有问题，请参考 HwICSUiSdk 官方文档或联系**江苏云上企数字科技有限公司**技术支持。
|
||||||
|
|||||||
Reference in New Issue
Block a user