Voxie

Voxie 是一个基于 rtc-aigc-demo 二次改造的 Web 端语音/视觉陪伴 Demo。

当前版本在原始链路能力基础上，增加了更贴近产品形态的角色设定与陪伴配置能力，包括：

• 自定义陪伴对象的人设、头像、背景图和对用户的称呼
• 本地维护多套 Companion Profiles，并支持切换当前激活角色
• 通过 Node 服务读取和持久化 Server/scenes/*.json 场景配置
• 支持语音对话、视觉理解、字幕模式，以及按配置启用数字人能力

环境要求

• Node.js 16.0+
• 建议准备两个 Terminal，分别启动前端和 Node 服务

项目结构

.
├── src/                 # Web 前端
├── public/              # 静态资源
├── Server/              # 本地 Node 代理服务
│   ├── app.js           # 代理 OpenAPI、场景读取、角色资料保存
│   ├── scenes/          # 场景 JSON 配置
│   └── README.md        # 服务端补充说明
└── README.md

配置说明

1. 场景配置

项目默认从 Server/scenes/*.json 读取可用场景，Custom.json 可以作为参考模版。

每个场景主要包含以下几部分：

• SceneConfig：前端展示和角色信息，例如名称、头像、背景图、性格描述、对用户的称呼等
• AccountConfig：调用 OpenAPI 所需的 AK/SK
• RTCConfig：RTC 配置，通常包含 AppId、AppKey
• VoiceChat：语音对话配置，包括 ASR、LLM、TTS、Vision、Avatar 等参数

说明：

• RTCConfig.RoomId、RTCConfig.UserId、RTCConfig.Token 可以留空，Node 服务会在获取场景时自动生成
• VoiceChat.AppId、VoiceChat.RoomId、TargetUserId 等字段缺失时，服务端会按当前场景配置自动补齐一部分必要参数
• 修改或新增 Server/scenes/*.json 后，建议重启 Node 服务，确保最新配置被重新加载

2. 环境变量

Server/app.js 会自动尝试读取以下文件中的环境变量：

• 项目根目录 .env.local
• 项目根目录 .env
• Server/.env.local
• Server/.env

常见可选变量包括：

• VOLC_ACCESS_KEY_ID / VOLC_SECRET_KEY
• RTC_APP_ID / RTC_APP_KEY
• ARK_ENDPOINT_ID
• ARK_API_KEY
• TOS_ACCESS_KEY_ID / TOS_SECRET_KEY
• REACT_APP_AIGC_PROXY_HOST

其中：

• 前端默认在开发环境请求 http://localhost:3001
• 生产环境下如果未配置 REACT_APP_AIGC_PROXY_HOST，前端会默认走同源请求

快速开始

1. 启动 Node 服务

在项目根目录执行：

cd Server
yarn
yarn dev

默认监听地址：

http://localhost:3001

2. 启动前端

回到项目根目录执行：

yarn
yarn dev

3. 打开页面

前端启动后，按终端提示打开本地页面即可。

首次跑通前，请先确认：

• RTC、ASR、TTS、LLM 等能力已开通
• Server/scenes/Custom.json 中的关键参数已正确填写，或已通过环境变量补齐

使用方式

1. 配置角色

编辑 Server/scenes/Custom.json，可以设置：

• 角色名、头像、背景图
• 对用户的称呼
• 性格描述和系统提示词
• ASR / TTS / LLM / Vision / Avatar 等能力参数

2. 管理陪伴角色

进入页面后，可以基于当前场景继续新增、编辑、切换或删除陪伴角色。

相关数据会通过 Node 服务接口保存，并同步到 Server/scenes/*.json 中对应场景的 CompanionStore 或场景资料字段。

3. 接入自己的服务端

如果你已经有自己的后端：

• 优先修改前端环境变量 REACT_APP_AIGC_PROXY_HOST，将请求指向你的服务地址
• 对接时可参考 src/app/api.ts 中当前使用的接口：/getScenes、/saveSceneProfile、/getCompanionProfiles、/saveCompanionProfiles、/removeAvatarBg、/uploadAsset、/proxy

常见问题

问题	解决方案
启动后页面拿不到场景数据	先确认 Node 服务是否已经启动，并检查前端请求的 REACT_APP_AIGC_PROXY_HOST 是否指向正确地址。开发环境默认请求 http://localhost:3001。
启动智能体后一直停留在“AI 准备中，请稍候”	优先检查服务是否已正确开通，场景 JSON 中的 AK/SK、RTC、LLM、TTS、Avatar 等参数是否完整且可用；如果启用了数字人，也请确认对应资源和并发额度正常。
浏览器报 Uncaught (in promise) r: token_error	检查 RTC 相关配置是否匹配，包括 AppId、AppKey、RoomId、UserId、Token。如果这些值由服务端自动生成，通常重启 Node 服务并重新进入页面即可刷新。
修改了 Server/scenes/*.json 但页面没有生效	Node 服务启动时会读取场景文件。修改后请重启 Server，再刷新页面。
麦克风或摄像头开启失败，报 getUserMedia 相关错误	检查当前页面是否处于安全上下文，也就是 localhost 或 HTTPS。浏览器限制 getUserMedia 只能在安全上下文中使用。
设备看起来正常，但实际采集不到音视频	可能是浏览器或系统层面的设备权限没有授予，可参考 Web 排查设备权限获取失败问题。
接口返回 Invalid 'Authorization' header	一般表示场景配置里的 AccountConfig.accessKeyId / AccountConfig.secretKey 不正确，或者签名使用的 AK/SK 与当前账号不匹配。
我想接自己的后端	配置 REACT_APP_AIGC_PROXY_HOST 即可；如果你的接口协议与当前 Demo 不一致，再按需调整 src/app/api.ts 中的接口定义。

相关文档

• 开通服务
• 对话式 AI 场景介绍
• 场景搭建方案
• OpenAPI 更新