260 lines
11 KiB
Markdown
260 lines
11 KiB
Markdown
# 火山引擎 RTC AIGC 前端接入逻辑梳理
|
||
|
||
## 一、整体架构概览
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 前端 (React) │
|
||
│ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
|
||
│ │ MainPage │──>│ useJoin │──>│ RtcClient │ │
|
||
│ │(入口页面) │ │(加房hook)│ │(SDK 封装) │ │
|
||
│ └──────────┘ └──────────┘ └─────┬─────┘ │
|
||
│ │ │ │
|
||
│ ┌────▼─────┐ ┌─────────▼──────────┐ │
|
||
│ │ Redux │ │ @volcengine/rtc │ │
|
||
│ │ Store │ │ (火山引擎 RTC SDK) │ │
|
||
│ └──────────┘ └─────────┬──────────┘ │
|
||
│ │ │
|
||
└──────────────────────────────────────┼───────────────────────┘
|
||
│
|
||
┌──────────────────▼──────────────────┐
|
||
│ Backend (FastAPI) │
|
||
│ /getScenes /proxy /api/chat_cb │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
## 二、核心模块说明
|
||
|
||
### 2.1 配置层 (`config/index.ts`)
|
||
|
||
```typescript
|
||
// 后端 API 代理地址
|
||
export const AIGC_PROXY_HOST = 'http://localhost:3001';
|
||
```
|
||
|
||
### 2.2 API 层 (`app/api.ts` + `app/base.ts`)
|
||
|
||
定义了 3 个 API：
|
||
|
||
| API | 路径 | 说明 |
|
||
|-----|------|------|
|
||
| `getScenes` | `POST /getScenes` | 获取场景配置（含 RTC 凭证 AppId/RoomId/UserId/Token） |
|
||
| `StartVoiceChat` | `POST /proxy?Action=StartVoiceChat` | 启动 AI 语音对话（传 `{ SceneID }` ） |
|
||
| `StopVoiceChat` | `POST /proxy?Action=StopVoiceChat` | 停止 AI 语音对话（传 `{ SceneID }` ） |
|
||
|
||
**请求封装逻辑** (`app/base.ts`)：
|
||
- `generateAPIs()` 根据 API 配置自动生成请求函数
|
||
- POST 请求格式：`fetch(AIGC_PROXY_HOST + apiPath + ?Action=xxx, { method: 'post', body: JSON })`
|
||
- 响应统一结构：`{ ResponseMetadata: { Action, RequestId, Error? }, Result }`
|
||
- `resultHandler()` 检查 Error 字段，成功返回 `Result`，失败抛异常
|
||
|
||
### 2.3 RTC 客户端封装 (`lib/RtcClient.ts`)
|
||
|
||
单例模式，核心属性/方法：
|
||
|
||
```
|
||
RTCClient (单例)
|
||
├── basicInfo: { app_id, room_id, user_id, token } // 由 getScenes 返回后注入
|
||
├── engine: IRTCEngine // RTC 引擎实例
|
||
├── audioBotEnabled: boolean // AI Bot 是否启用
|
||
│
|
||
├── createEngine() // 创建引擎 + 注册 AI 降噪扩展
|
||
├── addEventListeners() // 绑定 15 个 RTC 事件回调
|
||
├── joinRoom() // 加入房间（自动发布/订阅音频, RoomProfile=chat）
|
||
├── leaveRoom() // 离房并销毁引擎
|
||
├── startAudioCapture() // 开始麦克风采集
|
||
├── stopAudioCapture() // 停止麦克风采集
|
||
├── startAgent(sceneId) // 调用 StartVoiceChat API → 启动 AI Bot
|
||
├── stopAgent(sceneId) // 调用 StopVoiceChat API → 停止 AI Bot
|
||
├── commandAgent() // 通过 Binary Message 向 Bot 发送控制指令（打断等）
|
||
└── getDevices() // 枚举音频/视频设备
|
||
```
|
||
|
||
### 2.4 状态管理 (`store/slices/`)
|
||
|
||
#### room slice — 核心状态
|
||
```typescript
|
||
{
|
||
scene: string; // 当前场景 ID
|
||
sceneConfigMap: Record<string, SceneConfig>; // 场景配置（botName, isVision 等）
|
||
rtcConfigMap: Record<string, RTCConfig>; // RTC 凭证（AppId, RoomId, UserId, Token）
|
||
isJoined: boolean; // 是否已加房
|
||
isAIGCEnable: boolean; // AI Bot 是否启用
|
||
isAITalking: boolean; // AI 正在说话
|
||
isAIThinking: boolean; // AI 正在思考
|
||
isUserTalking: boolean; // 用户正在说话
|
||
msgHistory: Msg[]; // 对话历史
|
||
localUser: LocalUser; // 本地用户（含 publishAudio 状态）
|
||
remoteUsers: IUser[]; // 远端用户列表
|
||
networkQuality: NetworkQuality; // 网络质量
|
||
}
|
||
```
|
||
|
||
#### device slice — 设备状态
|
||
```typescript
|
||
{
|
||
audioInputs: MediaDeviceInfo[]; // 麦克风列表
|
||
videoInputs: MediaDeviceInfo[]; // 摄像头列表
|
||
selectedMicrophone?: string; // 选中的麦克风 ID
|
||
selectedCamera?: string; // 选中的摄像头 ID
|
||
devicePermissions: { audio, video }; // 设备权限
|
||
}
|
||
```
|
||
|
||
### 2.5 消息处理 (`utils/handler.ts`)
|
||
|
||
AI Bot 通过 RTC 的 **Binary Message** 机制推送消息，采用 **TLV 编码格式**：
|
||
|
||
```
|
||
| type (4字节) | length (4字节, big-endian) | value (JSON字符串) |
|
||
```
|
||
|
||
消息类型：
|
||
|
||
| Type 标识 | 含义 | 数据结构 |
|
||
|-----------|------|----------|
|
||
| `conv` | 状态简报 | `{ Stage: { Code, Description } }` — Code: 1=LISTENING, 2=THINKING, 3=SPEAKING, 4=INTERRUPTED, 5=FINISHED |
|
||
| `subv` | 字幕 | `{ data: [{ text, definite, userId, paragraph }] }` |
|
||
| `tool` | Function Call | `{ tool_calls: [{ id, function: { name } }] }` |
|
||
| `ctrl` | 控制指令(发送) | `{ Command, InterruptMode, Message }` |
|
||
| `func` | Function Call 响应(发送) | `{ ToolCallID, Content }` |
|
||
|
||
### 2.6 事件监听 (`lib/listenerHooks.ts`)
|
||
|
||
监听 15 个 RTC 事件：
|
||
|
||
| 事件 | 处理逻辑 |
|
||
|------|----------|
|
||
| `onError` | 处理 DUPLICATE_LOGIN 等错误 |
|
||
| `onUserJoined` | AI Bot 加入房间，更新远端用户列表 |
|
||
| `onUserLeave` | 远端用户离开 |
|
||
| `onUserPublishStream` | 远端用户发布流（AI Bot 开始说话） |
|
||
| `onUserUnpublishStream` | 远端用户取消发布 |
|
||
| `onLocalAudioPropertiesReport` | 本地音量检测（用于 UI 动画） |
|
||
| `onRemoteAudioPropertiesReport` | 远端音量检测 |
|
||
| `onRoomBinaryMessageReceived` | **核心！** 接收 AI Bot 的 TLV 消息 → 交给 MessageHandler 解析 |
|
||
| `onNetworkQuality` | 网络质量监测 |
|
||
| `onAudioDeviceStateChanged` | 设备热插拔 |
|
||
| `onAutoplayFailed` / `onPlayerEvent` | 自动播放失败处理 |
|
||
| `onTrackEnded` | 屏幕共享关闭 |
|
||
| `onLocalStreamStats` / `onRemoteStreamStats` | 流统计信息 |
|
||
|
||
## 三、完整调用流程
|
||
|
||
### 3.1 页面初始化
|
||
|
||
```
|
||
1. MainPage 挂载
|
||
2. 调用 getScenes API → 获取场景列表
|
||
3. 存入 Redux：sceneConfigMap、rtcConfigMap
|
||
4. 同时将 rtcConfig 注入 RtcClient.basicInfo（含 AppId/RoomId/UserId/Token）
|
||
5. 展示 Antechamber（通话前）界面
|
||
```
|
||
|
||
### 3.2 用户点击"通话"按钮 → `useJoin.disPatchJoin()`
|
||
|
||
```
|
||
1. 检测浏览器兼容性 → VERTC.isSupported()
|
||
2. 创建 RTC 引擎 → RtcClient.createEngine()
|
||
└─ 内部：VERTC.createEngine(appId) + 注册 AI 降噪扩展
|
||
3. 绑定事件监听 → RtcClient.addEventListeners(listeners)
|
||
4. 加入房间 → RtcClient.joinRoom()
|
||
└─ engine.joinRoom(token, roomId, userInfo, {
|
||
isAutoPublish: true,
|
||
isAutoSubscribeAudio: true,
|
||
roomProfileType: 'chat'
|
||
})
|
||
5. 枚举音频设备 → RtcClient.getDevices({ audio: true })
|
||
6. 更新 Redux 状态 → localJoinRoom, updateSelectedDevice, updateMediaInputs
|
||
7. 开启麦克风 → switchMic()
|
||
└─ publishStream(AUDIO) + startAudioCapture()
|
||
8. 启动 AI Bot → handleAIGCModeStart()
|
||
└─ RtcClient.startAgent(sceneId)
|
||
└─ 内部调用 POST /proxy?Action=StartVoiceChat { SceneID }
|
||
9. 更新状态 → isAIGCEnable = true, isJoined = true
|
||
10. UI 切换：Antechamber → Room 界面
|
||
```
|
||
|
||
### 3.3 AI 对话过程
|
||
|
||
```
|
||
用户说话 → 麦克风采集 → RTC SDK 自动推流到远端
|
||
↓
|
||
火山引擎 RTC 服务端
|
||
↓
|
||
ASR（语音识别）→ LLM（大模型）→ TTS（语音合成）
|
||
↓
|
||
Bot 将音频流推回房间 + 发送 Binary Message（字幕/状态）
|
||
↓
|
||
前端接收：
|
||
- 音频流 → RTC SDK 自动播放（isAutoSubscribeAudio: true）
|
||
- Binary Message → onRoomBinaryMessageReceived → TLV 解码 → MessageHandler
|
||
├─ conv(状态): THINKING → 更新 isAIThinking
|
||
│ SPEAKING → 更新 isAITalking
|
||
│ FINISHED → isAITalking = false
|
||
│ INTERRUPTED → 标记消息为已打断
|
||
└─ subv(字幕): text/definite/paragraph → 更新 msgHistory
|
||
```
|
||
|
||
### 3.4 打断 AI
|
||
|
||
```
|
||
方式一：语音打断（isInterruptMode = true 时自动生效，服务端检测）
|
||
方式二：点击"打断"按钮 → RtcClient.commandAgent({
|
||
agentName: botName,
|
||
command: 'interrupt',
|
||
}) → engine.sendUserBinaryMessage(botName, TLV 编码({
|
||
Command: 'interrupt',
|
||
InterruptMode: 0,
|
||
Message: ''
|
||
}))
|
||
```
|
||
|
||
### 3.5 用户挂断 → `useLeave()`
|
||
|
||
```
|
||
1. 停止音频/视频/屏幕采集
|
||
2. 停止 AI Bot → RtcClient.stopAgent(sceneId)
|
||
└─ POST /proxy?Action=StopVoiceChat { SceneID }
|
||
3. 离开房间 → RtcClient.leaveRoom()
|
||
└─ engine.leaveRoom() + VERTC.destroyEngine(engine)
|
||
4. 清除 Redux 状态 → clearHistoryMsg, clearCurrentMsg, localLeaveRoom, isAIGCEnable=false
|
||
5. UI 切换：Room → Antechamber
|
||
```
|
||
|
||
## 四、TLV 协议编解码
|
||
|
||
### 编码 `string2tlv(str, type)`
|
||
|
||
```
|
||
输入: str = '{"Command":"interrupt"}', type = 'ctrl'
|
||
|
||
输出 ArrayBuffer:
|
||
[0-3] type 字符编码: 'c','t','r','l' → [99, 116, 114, 108]
|
||
[4-7] length (big-endian): JSON 字节长度
|
||
[8-...) value: UTF-8 编码的 JSON 字符串
|
||
```
|
||
|
||
### 解码 `tlv2String(buffer)`
|
||
|
||
```
|
||
输入: ArrayBuffer
|
||
输出: { type: 'subv', value: '{"data":[...]}' }
|
||
```
|
||
|
||
## 五、关键依赖
|
||
|
||
| 包名 | 用途 |
|
||
|------|------|
|
||
| `@volcengine/rtc` | 火山引擎 RTC Web SDK |
|
||
| `@volcengine/rtc/extension-ainr` | AI 降噪扩展（可选，不影响核心功能） |
|
||
|
||
## 六、接入要点总结
|
||
|
||
1. **后端需提供 3 个接口**：`getScenes`（返回 RTC 凭证和场景配置）、`StartVoiceChat`、`StopVoiceChat`
|
||
2. **RTC 加房参数**：`isAutoPublish: true, isAutoSubscribeAudio: true, roomProfileType: chat`
|
||
3. **AI 消息通道**：通过 RTC Binary Message (`onRoomBinaryMessageReceived`) 收发，TLV 编码
|
||
4. **AI Bot 是一个"远端用户"**：它加入同一房间，发布音频流，通过 Binary Message 推送字幕和状态
|
||
5. **打断机制**：通过 `sendUserBinaryMessage` 向 Bot 发送 `ctrl` 类型的 TLV 指令
|