g-ai-robot3 数字人组件文档

简介

封装了 QA 问答与语音问答能力，基于 Vue 3，可在业务中快速集成数字人对话体验。

特性

- 支持文本问答与语音实时交互
- 可配置对话框主题、气泡、数字人画布与样式
- 内置工作流关键词触发
- 统一 API 前缀便于本地代理

安装

``bash
npm install g-ai-robot3 --save
`

快速开始

在页面中使用组件（最小必填配置）：

`vue


`

高级示例：工作流与业务联动（富阳智能体使用示例）

`vue



`

前端代理与跨域示例（Vite）

`ts
// vite.config.ts
export default defineConfig({
server: {
proxy: {
"/api21216": {
target: "http://your-backend-host", // 默认https://model.keepsoft.net:39002
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api21216/, ""),
},
},
},
});
`

必填参数（Required）

| 参数 | 说明 | 类型 | 默认值 | 注意事项 |
| ----------- | ------------ | ------ | ------------------- | --------------------------------------- |
| cozeInfo | 智能体配置 | object | { bot_id: '...' } | bot_id必须替换为实际的智能体 id |
| apiPrefix | API 基础路径 | string | - | 必须配置为你的代理前缀（如/api21216） |
| apiPrefix | API 基础路径 | string | '/api21216' | 可通过本地代理或环境变量覆盖 |

说明：其他参数均有默认值，按需覆盖即可（建议保持数字人宽高与样式一致以避免拉伸）。
| canvasHeight | 画布高度 | number | 180 | 必须与 videoStyle、digitalStyle.height 一致 |
| videoStyle | 视频样式 | CSSProperties | { width: '180px', visibility: 'hidden' } | width 与 canvasWidth 一致 |
| digitalStyle | 数字人样式 | CSSProperties | { width: '180px', height: '180px' } | 与 canvasWidth/canvasHeight 保持一致 |
| canvasStyle | 画布样式 | CSSProperties | { width: '180px', height: '180px' } | 与 canvasWidth/canvasHeight 保持一致 |

基础配置

| 参数 | 说明 | 类型 | 默认值 |
| ------------------ | ------------------------------------ | ------- | -------------------------------------- |
| isDebug | 是否开启调试模式（打印语音输出） | boolean | false |
| dialogBoxTheme | 对话框主题 | string | 'light' |
| suspensionStyle | 对话框高度 | string | '33vh' |
| showMsgBubble | 是否显示消息气泡 | boolean | true |
| isExhibitionPro | 是否为数字展厅项目 | boolean | false |
| isShowDialogIcon | 是否显示对话框图标 | boolean | false |
| stream | 是否启用流式传输（已废弃） | string | 'True' |
| title | 对话框标题 | string | 'GR水利大模型' |
| greet | 欢迎语（文本对话框） | string | '您好,我是GR水利大模型智能小助手...' |
| welcomeMessage | 欢迎消息（气泡对话框） | string | '您好,我是GR水利大模型智能小助手...' |
| waitTxt | 等待提示文本 | string | '贵仁科技AI正在生成回答' |
| systemName | 系统标识 | string | 'g-ai-robot3' |
| placementBottom | 对话框底部距离 | number | 100 |
| placementLeft | 对话框左侧距离 | number | 450 |
| useAudio | 是否启用音频功能 | boolean | true |
| space | 监听间隔（ms）已废弃 | number | 3000 |
| mode | 交互模式（默认 video，其他已废弃） | string | 'video' |
| modelType | 模型类型（'local' 或 'online'） | string | 'online' |
| showModelTypeToggle | 显示模型类型切换开关 | boolean | false |

API 配置

| 参数 | 说明 | 类型 | 默认值 |
| ----------------------- | ----------------------------- | ------ | ------------------------------------------ |
| apiPrefix | API 基础路径（可自定义跨域） | string | '/api21216' |
| createConversationUrl | 创建会话接口 | string | ${apiPrefix}/chatGlm/createConversation |
| wakeupAudio | 音频打标接口 | string | ${apiPrefix}/asr/saveWakeUpAudio |
| interrupt | 中断请求接口 | string | ${apiPrefix}/chatGlm/cancelChat |
| qaServer | 问答服务接口 | string | ${apiPrefix}/chatGlm/searchTextNew |
| audioWs | 语音 WebSocket 服务 | string | wss://model.keepsoft.net:39002/funasrWs |
| voiceprintWs | 声纹识别 WebSocket 服务 | string | wss://model.keepsoft.net:39002/speakerWs |
| instructWs | 指令 WebSocket 服务（已废弃） | string | wss://model.keepsoft.net:39002/commandWs |

数字人配置

| 参数 | 说明 | 类型 | 默认值 |
| --------------------- | -------------- | ------------- | ------------------------------------------ |
| videoStyle | 视频样式 | CSSProperties | { width: '180px', visibility: 'hidden' } |
| digitalStyle | 数字人样式 | CSSProperties | { width: '180px', height: '180px' } |
| bubbleStyle | 气泡样式 | CSSProperties | { width: '30%', height: '30%' } |
| canvasWidth | 画布宽度 | number | 180 |
| canvasHeight | 画布高度 | number | 180 |
| canvasCartoonWidth | 卡通形象宽度 | number | 200 |
| canvasCartoonHeight | 卡通形象高度 | number | 320 |
| offer | 数字人形象接口 | string | ${apiPrefix}/metahuman/offer |
| humanaudio | 数字人音频接口 | string | ${apiPrefix}/metahuman/humanaudio |
| stop_audio | 停止音频接口 | string | ${apiPrefix}/metahuman/stop_audio |
| textDriven | 文本驱动接口 | string | ${apiPrefix}/intelligentVoice/tts |

消息气泡配置

| 参数 | 说明 | 类型 | 默认值 |
| ----------------- | -------------------- | ------------- | ----------------------------------- |
| showMsgNumber | 显示消息数量 | number | 5 |
| bubbleTheme | 气泡主题 | string | 'dark' |
| useCustomDialog | 是否使用自定义对话框 | boolean | false |
| BubbleWidth | 气泡容器样式 | CSSProperties | { width: '220px', bottom: '85%' } |
| BubbleWidth | 气泡宽度 | number | 220 |
| BubbleBottom | 气泡底部距离 | number | 85 |

- 组件会将后端返回的关联问题（如 questions 列表）整合为可点击项，点击后自动填充并发送。

用途：引导用户进行更深入或相关的追问，提升对话效率。

关键词触发事件（工作流）

`ts
eventFun: [
{
keywords: ["打开灌区"], // 触发关键词，关键词为工作流名称
trigger: "after", // 触发时机，after 表示在 AI 回答后触发
fun: (a: any) => {
console.log("打开灌区"，a); // a为工作流设置的返回内容
},
},
{
keywords: ["打开技术舱"],
trigger: "after",
fun: (a: any) => {
console.log("打开技术舱"，a);
},
},
];
`

常见问题

- 画布或视频尺寸不一致：请确保 canvasWidth/canvasHeight 与 videoStyle/digitalStyle/canvasStyle 一致。
- 音频或 WS 连接失败：检查 audioWs/voiceprintWs 地址可达性。

语音唤醒词与结束/暂停

- 支持的唤醒词（对应五位数字人）：
- 小贵小贵
- 小慧小慧
- 小智小智
- 小 G 同学
- 小 R 同学
- 使用方式：在空闲状态直接说出唤醒词，系统会回复“我在，请问有什么可以帮您。”并进入对话。
- 结束词：再见、拜拜、小贵拜拜、小贵再见（任意其一即可识别，结束对话，需重新唤醒）
- 暂停词：暂停、停止、小贵暂停、小贵停止（任意其一即可识别，暂停说话，继续监听，无需重新唤醒）

许可证

本项目遵循仓库中的 LICENSE` 许可。