docs: 更新技术文档,同步 Eino 重构和默认 provider 变更
- 架构设计:更新为 Eino Graph 声明式编排,增加三级存储架构说明 - 接口文档:AI 编排器章节重写为 Eino Graph,更新 LLM 服务接口 - 技术选型:新增 Eino 框架选型章节,修正 STT/LLM/TTS 默认方案 - 语音交互:Pipeline 描述改为 Eino Graph - 成本控制:模型引用修正为 qwen3-vl-plus - 技术名词解释:新增 Eino 框架相关术语 - README:增加 10/11/12 Eino 文档索引 - 10-Eino重构方案:状态更新为已实施 - CLAUDE.md:同步所有变更
This commit is contained in:
57
CLAUDE.md
57
CLAUDE.md
@@ -4,7 +4,7 @@
|
||||
|
||||
## 项目概述
|
||||
|
||||
CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互,AI 理解视觉场景和语音输入后,以文字和语音形式给出自然回应。项目目前处于设计文档阶段,源代码正在逐步构建。
|
||||
CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互,AI 理解视觉场景和语音输入后,以文字和语音形式给出自然回应。
|
||||
|
||||
> **文档优先原则:** 执行任何开发任务前,先读取 `docs/` 下的相关设计文档(架构、接口、技术选型等),以文档为最高依据。代码实现应与文档一致;若有偏差,优先更新文档(尤其是接口文档)。
|
||||
|
||||
@@ -13,12 +13,12 @@ CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头
|
||||
三层系统:
|
||||
|
||||
1. **浏览器客户端**(React 18 + TypeScript, Vite)—— 媒体采集、边缘预处理(VAD 通过 `@ricky0123/vad-web`、关键帧检测通过 Canvas 像素比较)、UI 渲染。核心 Hook:`useVisionSession()`
|
||||
2. **Go 网关**(Gin, gorilla/websocket, Viper, Zap)—— WebSocket 服务器、会话管理、AI 编排。每个 WebSocket 连接一个 goroutine。
|
||||
3. **云端 AI 服务** —— 通过 OpenAI 兼容接口可灵活切换。默认:GPT-4o(LLM)、Deepgram(STT)、OpenAI TTS。仅通过 Go 网关访问,浏览器不直连。
|
||||
2. **Go 网关**(Gin, gorilla/websocket, Viper, Zap)—— WebSocket 服务器、会话管理、AI 编排(基于 CloudWeGo Eino Graph)。每个 WebSocket 连接一个 goroutine。
|
||||
3. **云端 AI 服务** —— 通过 OpenAI 兼容接口可灵活切换。默认:DashScope qwen3-vl-plus(LLM)、MiMo ASR(STT)、MiMo TTS(TTS)。仅通过 Go 网关访问,浏览器不直连。
|
||||
|
||||
**关键模式**:LLM 文本流和 TTS 音频流并行推送给客户端,以最小化感知延迟。
|
||||
**关键模式**:AI 编排基于 Eino Graph 声明式 DAG(`START → STT → History → ChatModel → Msg2Str → Splitter → TTS → Done → END`),LLM token 通过 Callback 实时推送,TTS 逐句合成并行推送,最小化感知延迟。
|
||||
|
||||
**存储**:MVP 阶段使用进程内存(`MemoryManager`),Redis 实现已就绪可通过配置切换,PostgreSQL 为规划中。Repository 接口模式(`HistoryRepository`、`UsageRepository`),MVP 用内存实现。
|
||||
**存储**:三级存储架构(TieredManager)—— L1 Memory → L2 Redis → L3 PostgreSQL,自动降级。Repository 接口模式(UserRepository、MessageRepository、SessionRepository),PostgreSQL + 内存双实现。
|
||||
|
||||
## 技术栈
|
||||
|
||||
@@ -26,9 +26,10 @@ CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头
|
||||
|------|------|
|
||||
| 前端 | React 18, TypeScript, Vite, @ricky0123/vad-web |
|
||||
| 后端 | Go, Gin, gorilla/websocket, Viper, Zap |
|
||||
| LLM | GPT-4o(默认,通过 OpenAI 兼容接口可切换) |
|
||||
| STT | Deepgram(默认) / MiMo ASR |
|
||||
| TTS | OpenAI TTS(默认) / MiMo TTS |
|
||||
| AI 编排 | CloudWeGo Eino Graph(声明式 DAG 编排) |
|
||||
| LLM | DashScope qwen3-vl-plus(默认,通过 eino-ext OpenAI ChatModel 接入) |
|
||||
| STT | MiMo ASR(默认) / Deepgram |
|
||||
| TTS | MiMo TTS(默认) / OpenAI TTS |
|
||||
|
||||
## 构建与运行命令
|
||||
|
||||
@@ -49,13 +50,13 @@ go test -run TestName ./path # 运行单个测试
|
||||
go vet ./... # 静态分析
|
||||
```
|
||||
|
||||
基础设施:MVP 使用进程内存管理会话状态。Redis 已实现可通过配置切换,PostgreSQL 为规划中。
|
||||
基础设施:三级存储架构(L1 Memory → L2 Redis → L3 PostgreSQL),通过配置控制启用层级。
|
||||
|
||||
## WebSocket 协议
|
||||
|
||||
端点:`ws://localhost:8080/ws`
|
||||
端点:`ws://localhost:8080/ws?token=<access_token>&conversation_id=<uuid>`
|
||||
|
||||
所有消息为 JSON 文本帧,统一信封格式 `{type, request_id?, timestamp?}`。完整契约见 `docs/03-接口文档.md`。
|
||||
所有消息为 JSON 文本帧,统一信封格式 `{type, request_id?, timestamp?}`。完整契约见 `docs/02-接口文档.md`。
|
||||
|
||||
**客户端 → 服务端**:`query`(图像 Base64 + 音频 Base64)、`config`、`interrupt`、`ping`
|
||||
**服务端 → 客户端**:`connected`、`stt_result`、`llm_chunk`、`llm_done`、`tts_audio`、`error`、`pong`
|
||||
@@ -66,34 +67,50 @@ go vet ./... # 静态分析
|
||||
## REST API(辅助)
|
||||
|
||||
- `GET /api/health` — 健康检查(版本、运行时间、活跃会话数)
|
||||
- `POST /api/sessions` — 创建会话(可选,MVP 在 WS 连接时自动创建)
|
||||
- `DELETE /api/sessions/{id}` — 销毁会话
|
||||
- `POST /api/auth/register` — 注册
|
||||
- `POST /api/auth/login` — 登录
|
||||
- `POST /api/auth/refresh` — 刷新 Token
|
||||
- `POST /api/auth/logout` — 登出
|
||||
- `GET /api/conversations` — 对话列表
|
||||
- `POST /api/conversations` — 创建对话
|
||||
- `GET/PUT/PATCH/DELETE /api/conversations/:id` — 对话 CRUD
|
||||
- `GET /api/conversations/:id/messages` — 获取对话消息
|
||||
|
||||
## 错误码
|
||||
|
||||
`INVALID_MESSAGE`、`SESSION_NOT_FOUND`、`RATE_LIMITED`、`IMAGE_TOO_LARGE`、`AUDIO_TOO_SHORT`、`LLM_TIMEOUT`、`LLM_ERROR`、`STT_ERROR`、`TTS_ERROR`、`INTERNAL_ERROR`
|
||||
`INVALID_MESSAGE`、`SESSION_NOT_FOUND`、`RATE_LIMITED`、`IMAGE_TOO_LARGE`、`AUDIO_TOO_SHORT`、`LLM_TIMEOUT`、`LLM_ERROR`、`STT_ERROR`、`TTS_ERROR`、`INTERNAL_ERROR`、`USERNAME_TAKEN`、`INVALID_CREDENTIALS`、`INVALID_TOKEN`、`INVALID_INPUT`
|
||||
|
||||
## 前端组件结构
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| `AuthPage` | 登录/注册表单 |
|
||||
| `CameraManager` | 摄像头流采集 |
|
||||
| `MicManager` | 麦克风音频采集 |
|
||||
| `EdgeProcessor` | VAD + 关键帧检测(Canvas 像素比较) |
|
||||
| `WebSocketManager` | WebSocket 连接生命周期管理 |
|
||||
| `ChatPanel` | 消息展示 |
|
||||
| `ChatPanel` | 消息展示、流式回复、文本输入、场景选择 |
|
||||
| `VideoPreview` | 摄像头画面预览 |
|
||||
| `SessionSidebar` | 左侧抽屉式对话列表 |
|
||||
| `ConfigPanel` | 右侧抽屉式配置面板 |
|
||||
| `Toast` | 轻量通知提示 |
|
||||
|
||||
核心 Hook:`useVisionSession()` 封装一次完整的视觉对话会话。
|
||||
|
||||
## 后端模块结构
|
||||
|
||||
| 模块 | 职责 |
|
||||
|------|------|
|
||||
| WebSocket Handler | 连接管理、单播消息推送 |
|
||||
| Session Manager | 会话状态、对话历史(Memory/Redis,30 分钟 TTL) |
|
||||
| AI Orchestrator | STT→LLM→TTS 流式并行管道编排 |
|
||||
| AI Service Layer | AI 服务抽象层(STT/LLM/TTS 多 provider) |
|
||||
| REST API | 健康检查、会话管理(Gin 路由) |
|
||||
| WebSocket Handler | 连接管理、JWT 认证、单播消息推送 |
|
||||
| Session Manager | 会话状态、对话历史(三级存储:Memory/Redis/PostgreSQL,30 分钟 TTL) |
|
||||
| Eino 编排层 | 基于 Eino Graph 的声明式 AI 编排(7 节点 DAG,Stream 模式,Callback AOP) |
|
||||
| AI Orchestrator | `EinoOrchestrator` 适配器,包装 Graph 实现 `Orchestrator` 接口 |
|
||||
| AI Service Layer | AI 服务抽象层(STT/TTS 多 provider,LLM 通过 eino-ext ChatModel) |
|
||||
| Auth | JWT 双 token 轮转认证,bcrypt 密码哈希 |
|
||||
| Store | 持久化存储层(UserRepository/MessageRepository/SessionRepository,内存 + PostgreSQL) |
|
||||
| REST API | 健康检查、认证、对话管理(Gin 路由) |
|
||||
| Models | 数据模型定义 |
|
||||
| Migrations | 数据库版本化迁移(嵌入式 SQL) |
|
||||
| Model Router | 按请求选择 AI 模型(规划中) |
|
||||
| Rate Limiter | 按用户的令牌桶速率限制(规划中) |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user