diff --git a/backend/server/README.md b/backend/server/README.md new file mode 100644 index 0000000..57d5dd6 --- /dev/null +++ b/backend/server/README.md @@ -0,0 +1,125 @@ +# 华为交互数字人后端服务 + +> **项目说明**：本项目是华为交互数字人 HwICSUiSdk 标准集成项目的定制化开发版本，专为**安特威**公司打造，由**江苏云上企数字科技有限公司**研发。 + +## 功能说明 + +后端服务主要为前端提供以下功能： + +1. **获取授权码** - 调用华为云 MetaStudio API 获取一次性授权码，用于前端 SDK 初始化 + +## 环境配置 + +### 1. 配置环境变量 + +复制 `.env.example` 文件为 `.env`： + +```bash +cp .env.example .env +``` + +编辑 `.env` 文件，填入您的华为云凭证： + +```env +HUAWEI_AK=your_access_key_here +HUAWEI_SK=your_secret_key_here +HUAWEI_PROJECT_ID=your_project_id_here +``` + +### 2. 获取华为云凭证 + +#### AK/SK（推荐） + +1. 登录 [华为云控制台](https://console.huaweicloud.com) +2. 进入 "我的凭证" > "访问密钥" +3. 创建或下载访问密钥 + +#### 项目 ID + +1. 登录华为云控制台 +2. 进入 "我的凭证" > "项目 ID" +3. 或访问 [获取项目ID](https://support.huaweicloud.com/api-metastudio/metastudio_02_0006.html) + +## 启动服务 + +### 安装依赖 + +```bash +npm install +``` + +### 启动服务 + +```bash +npm start +``` + +服务将在 `http://localhost:3001` 启动。 + +## API 接口 + +### 获取授权码 + +``` +POST /api/once-code +``` + +请求示例： +```bash +curl -X POST http://localhost:3001/api/once-code +``` + +响应示例： +```json +{ + "once_code": "OATAXWpTNDPGjVyzxNLKvumcv297Q7uUz5CCltLtFDE1uqnPAPmS4jm61XnMQGuV" +} +``` + +错误响应： +```json +{ + "error_code": "INTERNAL_ERROR", + "error_msg": "请配置环境变量: HUAWEI_AK 和 HUAWEI_SK" +} +``` + +### 健康检查 + +``` +GET /health +``` + +响应示例： +```json +{ + "status": "ok" +} +``` + +## 技术栈 + +- **Express** - Node.js Web 框架 +- **CORS** - 跨域资源共享 +- **dotenv** - 环境变量管理 +- **APIGW-javascript-sdk** - 华为云 API 签名认证 + +## 目录结构 + +``` +backend/server/ +├── index.js # 服务入口 +├── package.json # 依赖配置 +├── .env # 环境变量（不提交到版本库） +├── .env.example # 环境变量示例 +└── APIGW-javascript-sdk-2.0.6/ # 华为云签名SDK + ├── signer.js # 签名认证 + ├── node_demo.js # 示例代码 + └── licenses/ # 许可证 +``` + +## 注意事项 + +1. **安全性** - 请勿将 `.env` 文件提交到版本库 +2. **凭证保护** - 生产环境请使用更安全的方式管理凭证 +3. **跨域** - 默认允许所有来源跨域，生产环境请限制来源 diff --git a/frontend/README.md b/frontend/README.md new file mode 100644 index 0000000..944ab57 --- /dev/null +++ b/frontend/README.md @@ -0,0 +1,240 @@ +# 华为交互数字人前端 + +> **项目说明**：本项目是华为交互数字人 HwICSUiSdk 标准集成项目的定制化开发版本，专为**安特威**公司打造，由**江苏云上企数字科技有限公司**研发。 + +## 功能说明 + +### 核心功能 + +1. **SDK 初始化与销毁** + - 初始化：配置服务器地址、机器人ID等参数 + - 销毁：释放资源，清理数字人实例 + +2. **对话控制** + - 开始对话：启动数字人交互会话 + - 停止对话：结束当前会话 + - 对话保活：自动保持对话活跃，防止超时断开 + +3. **语音交互** + - 语音自动唤醒：无需点击，语音唤醒数字人（唤醒词："云笙云笙"） + - 开始说话：启动语音识别，用户语音输入 + - 停止说话：结束语音识别 + +4. **字幕样式设置** + - 支持设置容器、提示文字、消息、热点问题标题、热点问题列表的样式 + - 包括字体大小、颜色、粗细、行高、背景颜色、透明度、圆角、内边距 + - 样式设置自动保存到本地存储，刷新页面后自动恢复 + - 支持重置为默认样式 + +5. **字幕容器控制** + - 拖拽字幕容器到任意位置 + - 调整字幕容器大小 + - 位置和尺寸自动记忆，刷新页面后自动恢复 + +6. **多语言支持** + - 支持中文和英文语音切换 + - 根据后端配置自动加载可用语言列表 + +7. **面板管理** + - 所有弹出面板支持拖拽到任意位置 + - 面板默认居中显示 + - 自适应高度（除字幕样式面板外） + +8. **其他控制** + - 全屏显示：支持数字人全屏模式 + - 查看日志：显示 SDK 事件和调试信息 + +### 唤醒词 + +| 唤醒词 | 说明 | +|--------|------| +| 云笙云笙 | 主唤醒词 | +| 谢谢再见 | 结束对话 | +| 稍等一下 | 打断/等待 | + +## 快速开始 + +### 1. 环境要求 + +- Node.js 14+ +- 现代浏览器（Chrome、Firefox、Edge、Safari 最新版本） +- 支持 WebRTC 和 WebSocket +- 需要麦克风权限（用于语音交互） + +### 2. 启动前端服务 + +```bash +cd frontend +npm install +npm start +``` + +前端服务将在 `https://localhost:8080` 启动（使用自签名证书）。 + +### 3. 配置后端服务 + +确保后端服务已启动： + +```bash +cd backend/server +npm install +npm start +``` + +后端服务应在 `http://localhost:3001` 运行。 + +### 4. 使用流程 + +1. 打开浏览器访问 `https://localhost:8080` +2. 点击页面上的 "⚙️ 连接配置" 按钮 +3. 点击 "🔑 获取" 按钮获取授权码 +4. 点击 "初始化 SDK" 开始使用 + +## 目录结构 + +``` +frontend/ +├── index.html # 主页面 +├── server.js # HTTPS 服务器（开发环境） +├── package.json # 依赖配置 +├── styles/ +│ └── main.css # 自定义样式 +├── scripts/ +│ ├── main.js # 主逻辑代码 +│ └── api.js # 前端 API 调用模块 +├── hwICSUiSdk/ # SDK 目录 +│ ├── HwICSUiSdk.esm.js # ESM 模块入口 +│ ├── HwICSUiSdk.js # UMD 模块入口 +│ ├── HwICSUiSdk.d.ts # TypeScript 类型定义 +│ ├── HwICSUiSdk.css # SDK 样式 +│ ├── wasmData.js # WASM 虚拟机数据 +│ ├── modelData.js # 唤醒词模型数据 +│ └── images/ # SDK 图片资源 +└── cert/ # SSL 证书（开发用） + ├── localhost.pem + └── localhost-key.pem +``` + +## 配置选项 + +### 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线程运行唤醒模块 | + +## 事件监听 + +SDK 提供了丰富的事件回调： + +| 事件 | 说明 | +|------|------| +| ERROR | 错误事件 | +| JOB_INFO_CHANGE | 任务信息变更 | +| SPEAKING_START | 数字人开始说话 | +| SPEAKING_STOP | 数字人停止说话 | +| SPEECH_RECOGNIZED | 语音识别结果 | +| SEMANTIC_RECOGNIZED | 语义识别结果 | +| ENTER_SLEEP | 进入休眠状态 | +| ENTER_ACTIVE | 进入激活状态 | +| JOB_END | 任务结束 | + +## 调试技巧 + +1. **查看日志面板** + - 点击工具栏的 "📜" 按钮打开日志面板 + - 可查看 SDK 事件和调试信息 + +2. **调整日志级别** + 在控制台中执行： + ```javascript + HwICSUiSdk.setLogLevel('debug'); // debug | info | warn | error | none + ``` + +3. **浏览器开发者工具** + - 使用 Network 面板监控 WebSocket 连接 + - 使用 Console 面板查看控制台日志 + +## 注意事项 + +1. **HTTPS 要求** + - WebRTC 功能必须使用 HTTPS 环境 + - 开发环境使用自签名证书，浏览器可能需要授权 + +2. **浏览器权限** + - 首次使用需要授权麦克风权限 + +3. **唤醒词** + - 语音唤醒需要先初始化 SDK + - 对着麦克风说"云笙云笙"即可唤醒数字人 + +4. **样式保存** + - 字幕样式和容器位置会自动保存到浏览器本地存储 + +## 生产部署 + +### 构建 + +```bash +# 前端为纯静态文件，可直接部署到任意 Web 服务器 +``` + +### 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 Host $host; + } + + location /hwICSUiSdk/ { + expires 1y; + add_header Cache-Control "public, immutable"; + } +} +``` + +## 唤醒模型更新 + +### 模型文件位置 + +- `hwICSUiSdk/wasmData.js` - WASM 虚拟机数据 +- `hwICSUiSdk/modelData.js` - 唤醒词模型数据 + +### 更新步骤 + +1. 获取新的模型文件 +2. 替换 `wasmData.js` 和 `modelData.js` +3. 刷新页面，查看日志确认模型加载成功 + +### 常见问题 + +| 问题 | 解决方案 | +|------|----------| +| 模型加载失败 | 检查文件路径，确认文件完整性 | +| 唤醒无响应 | 确认麦克风权限，查看日志 | +| 模型版本不匹配 | 确保两个文件版本一致 |