138 lines
5.6 KiB
Markdown
138 lines
5.6 KiB
Markdown
# CamTalk
|
||
|
||
多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后，以文字和语音形式给出自然回应。
|
||
|
||
## 架构
|
||
|
||
三层系统，前端做轻量预处理，后端做智能编排，云端 AI 服务按需调用：
|
||
|
||
```
|
||
浏览器客户端 Go 网关 :8080 云端 AI 服务
|
||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||
│ 媒体采集 │ │ WebSocket Handler│ │ STT（语音识别） │
|
||
│ VAD 语音检测 │ WebSocket│ Session Manager │ HTTP │ LLM（多模态推理） │
|
||
│ 关键帧检测 │ ◄──────► │ AI Orchestrator │ ◄──────► │ TTS（语音合成） │
|
||
│ UI 渲染 │ │ REST API │ │ │
|
||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||
```
|
||
|
||
**关键模式**：LLM 文本流和 TTS 音频流并行推送，用户先看到文字、紧接着听到语音，感知延迟 < 0.5 秒。
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|------|------|
|
||
| 前端 | React 18, TypeScript, Vite, @ricky0123/vad-web |
|
||
| 后端 | Go, Gin, gorilla/websocket, Viper, Zap |
|
||
| STT | Deepgram（默认） / MiMo ASR |
|
||
| LLM | GPT-4o（默认，通过 OpenAI 兼容接口可切换） |
|
||
| TTS | OpenAI TTS（默认） / MiMo TTS |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
CamTalk/
|
||
├── frontend/ # 浏览器客户端
|
||
│ └── src/
|
||
│ ├── components/ # UI 组件
|
||
│ │ ├── CameraManager/ # 摄像头流采集
|
||
│ │ ├── MicManager/ # 麦克风音频采集
|
||
│ │ ├── EdgeProcessor/ # VAD + 关键帧检测
|
||
│ │ ├── WebSocketManager/ # WS 连接管理
|
||
│ │ ├── ChatPanel/ # 消息展示
|
||
│ │ ├── VideoPreview/ # 摄像头画面预览
|
||
│ │ ├── ConfigPanel/ # 配置面板
|
||
│ │ └── Toast/ # 通知提示
|
||
│ ├── hooks/ # 自定义 Hooks
|
||
│ │ ├── useVisionSession.ts # 核心会话 Hook
|
||
│ │ └── useObservationMode.ts # 观察模式
|
||
│ ├── lib/ # 工具库
|
||
│ │ ├── websocket.ts # WebSocket 连接管理
|
||
│ │ ├── audio.ts # 音频编码
|
||
│ │ ├── ttsPlayer.ts # TTS 播放器
|
||
│ │ └── sampling.ts # 采样策略
|
||
│ └── types/ # TypeScript 类型定义
|
||
├── backend/ # Go 网关
|
||
│ ├── cmd/server/ # 入口
|
||
│ └── internal/
|
||
│ ├── ai/ # AI 服务抽象层
|
||
│ │ ├── llm/ # LLM 服务（OpenAI 兼容）
|
||
│ │ ├── stt/ # STT 服务（Deepgram/MiMo）
|
||
│ │ └── tts/ # TTS 服务（OpenAI/MiMo）
|
||
│ ├── orchestrator/ # AI 编排器（STT→LLM→TTS 管道）
|
||
│ ├── session/ # 会话管理（Memory/Redis）
|
||
│ ├── ws/ # WebSocket Handler
|
||
│ ├── api/ # REST API
|
||
│ ├── config/ # 配置管理
|
||
│ ├── models/ # 数据模型
|
||
│ ├── errors/ # 错误码
|
||
│ └── logger/ # 日志
|
||
├── docs/ # 设计文档
|
||
└── CLAUDE.md # Claude Code 指引
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 前置条件
|
||
|
||
- Node.js >= 18
|
||
- Go >= 1.24
|
||
|
||
### 前端
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev # Vite 开发服务器 http://localhost:5173
|
||
```
|
||
|
||
### 后端
|
||
|
||
```bash
|
||
cd backend
|
||
go mod download
|
||
go run ./cmd/server # 启动网关 :8080
|
||
```
|
||
|
||
### 配置
|
||
|
||
后端配置文件位于 `backend/config.yaml`，支持环境变量覆盖（前缀 `CAMTALK_`）。
|
||
|
||
```bash
|
||
# 最小启动（需要至少一个 AI 服务的 API Key）
|
||
cd backend
|
||
CAMTALK_AI_LLM_API_KEY=sk-xxx \
|
||
CAMTALK_AI_STT_API_KEY=xxx \
|
||
go run ./cmd/server
|
||
```
|
||
|
||
配置优先级：环境变量 > `config.{env}.yaml` > `config.yaml` > `.env`
|
||
|
||
## WebSocket 协议
|
||
|
||
连接地址：`ws://localhost:8080/ws`
|
||
|
||
所有消息为 JSON 文本帧，统一信封格式 `{type, request_id?, timestamp?}`。
|
||
|
||
**客户端 → 服务端**：`query`、`config`、`interrupt`、`ping`
|
||
**服务端 → 客户端**：`connected`、`stt_result`、`llm_chunk`、`llm_done`、`tts_audio`、`error`、`pong`
|
||
|
||
完整协议见 [docs/03-接口文档.md](docs/03-接口文档.md)。
|
||
|
||
## 文档
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| [01-项目概述](docs/01-项目概述.md) | 项目目标与核心挑战 |
|
||
| [02-系统架构](docs/02-系统架构.md) | 三层架构、技术栈、部署方案 |
|
||
| [03-接口文档](docs/03-接口文档.md) | WebSocket 协议、REST API、配置管理 |
|
||
| [04-技术选型](docs/04-技术选型.md) | AI 服务栈、持久化层、前端边缘处理选型 |
|
||
| [05-用户故事](docs/05-用户故事.md) | 用户场景与优先级 |
|
||
| [06-语音交互](docs/06-语音交互.md) | VAD → STT → LLM → TTS 全链路 |
|
||
| [07-视觉理解](docs/07-视觉理解.md) | 帧采样、关键帧检测、多模态输入 |
|
||
| [08-成本控制](docs/08-成本控制.md) | 采样策略、端云协同、模型分级 |
|
||
|
||
## License
|
||
|
||
[MIT](LICENSE) © XEngineers
|