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:
@@ -8,14 +8,16 @@
|
||||
|
||||
```
|
||||
技术选型
|
||||
├── AI 编排框架
|
||||
│ └── CloudWeGo Eino Graph（声明式 DAG 编排，替代手写 goroutine 管道）
|
||||
├── AI 服务栈
|
||||
│ ├── STT: Deepgram（默认） / MiMo ASR
|
||||
│ ├── LLM: GPT-4o（默认） / 通义千问等 OpenAI 兼容模型
|
||||
│ └── TTS: OpenAI TTS（默认） / MiMo TTS
|
||||
│ ├── STT: MiMo ASR（默认） / Deepgram
|
||||
│ ├── LLM: DashScope qwen3-vl-plus（默认） / GPT-4o 等 OpenAI 兼容模型
|
||||
│ └── TTS: MiMo TTS（默认） / OpenAI TTS
|
||||
├── 持久化层
|
||||
│ ├── 数据库: PostgreSQL（pgx/v5，手写 SQL）
|
||||
│ ├── 迁移: 嵌入式 SQL 文件，自动执行
|
||||
│ └── 存储模式: Memory（默认）+ Write-Through 到 PG / Redis（可切换）
|
||||
│ └── 存储模式: 三级存储 TieredManager（L1 Memory → L2 Redis → L3 PostgreSQL）
|
||||
├── 认证与用户系统
|
||||
│ ├── 认证方案: JWT (HS256), access 15min + refresh 7day
|
||||
│ ├── JWT 库: golang-jwt/jwt/v5
|
||||
@@ -30,37 +32,77 @@
|
||||
|
||||
---
|
||||
|
||||
## 一、AI 服务栈选型
|
||||
## 一、AI 编排框架选型
|
||||
|
||||
### 候选方案对比
|
||||
|
||||
| 框架 | 语言 | 特点 | CamTalk 适用性 |
|
||||
|------|------|------|---------------|
|
||||
| **CloudWeGo Eino** | Go | Go 原生、类型安全、流式原生、Graph DAG 编排 | ✅ 完美匹配 |
|
||||
| LangChain Go | Go | 生态丰富但较重，抽象层多 | ❌ 过度抽象 |
|
||||
| 自研编排 | Go | 完全可控 | ❌ 维护成本高 |
|
||||
|
||||
### 选择 Eino 的理由
|
||||
|
||||
| 维度 | 手写 goroutine（旧方案） | Eino Graph（新方案） |
|
||||
|------|------------------------|---------------------|
|
||||
| 编排方式 | 手动 `go func()` + `sync.WaitGroup` | 声明式 DAG，类型安全 |
|
||||
| 流式处理 | 自定义 `chan` 传递 | `StreamReader` + `Pipe`，自动转换 |
|
||||
| 错误处理 | 各节点独立处理，不一致 | Graph 级别统一错误传播 |
|
||||
| 回调/AOP | 日志散落各处 | `callbacks.Handler` 统一注入 |
|
||||
| 配置灵活性 | Pipeline 创建时固定 | 每请求 `Option` 动态注入 |
|
||||
| 可测试性 | 需启动 goroutine | `Graph.Invoke()` 直接测试 |
|
||||
| 扩展性 | 修改 Pipeline 代码 | 添加节点 + 边，无侵入 |
|
||||
|
||||
### 核心依赖
|
||||
|
||||
```
|
||||
github.com/cloudwego/eino v0.9.9 # 核心框架
|
||||
github.com/cloudwego/eino-ext/components/model/openai v0.1.13 # OpenAI 兼容 ChatModel
|
||||
```
|
||||
|
||||
**核心理由**：
|
||||
1. Go 原生，泛型支持，编译时类型检查
|
||||
2. 原生流式处理（`StreamReader`），适合 LLM token 级推送
|
||||
3. Graph 支持分支、并行、循环，满足当前和未来需求
|
||||
4. Callback 机制实现 AOP（日志、指标、消息推送）
|
||||
5. eino-ext 提供 OpenAI ChatModel 实现，直接对接 DashScope
|
||||
|
||||
> 详细的 Eino 框架使用文档见 [11-Eino框架技术文档](11-Eino框架技术文档.md)，重构方案见 [10-Eino重构方案](10-Eino重构方案.md)，实施记录见 [12-Eino重构实施记录](12-Eino重构实施记录.md)。
|
||||
|
||||
---
|
||||
|
||||
## 二、AI 服务栈选型
|
||||
|
||||
### STT（语音识别）
|
||||
|
||||
| 方案 | 延迟 | 成本 | 特点 |
|
||||
|------|------|------|------|
|
||||
| **Deepgram**（默认） | <500ms | 按分钟计费 | 流式识别，延迟极低，WebSocket 接口 |
|
||||
| **MiMo ASR**（小米） | ~1s | 按量计费 | 国产替代，兼容 OpenAI chat/completions 格式，HTTP 非流式 |
|
||||
| **MiMo ASR**（默认） | ~1s | 按量计费 | 国产替代，兼容 OpenAI chat/completions 格式，HTTP 非流式 |
|
||||
| **Deepgram** | <500ms | 按分钟计费 | 流式识别，延迟极低，WebSocket 接口 |
|
||||
| Whisper API | 1-3s | 按分钟计费 | 准确率高，支持多语言 |
|
||||
| FunASR | <500ms | 自部署免费 | 阿里开源，中文优化 |
|
||||
|
||||
当前默认使用 Deepgram nova-2，可通过 `ai.stt.provider` 配置切换到 MiMo ASR。
|
||||
当前默认使用 MiMo ASR（mimo-v2.5-asr），可通过 `ai.stt.provider` 配置切换到 Deepgram。
|
||||
|
||||
### LLM（多模态大模型）
|
||||
|
||||
| 方案 | 成本 | 特点 |
|
||||
|------|------|------|
|
||||
| **GPT-4o**（默认） | $2.5/1M tokens | 视觉理解能力强，API 成熟，流式推理 |
|
||||
| 通义千问 qwen3-vl-plus | 按量计费 | 阿里云，通过 OpenAI 兼容接口调用 |
|
||||
| **DashScope qwen3-vl-plus**（默认） | 按量计费 | 阿里云，通过 OpenAI 兼容接口调用，视觉理解能力强 |
|
||||
| GPT-4o | $2.5/1M tokens | OpenAI，API 成熟，流式推理 |
|
||||
| Claude Sonnet | $3/1M tokens | Anthropic，长上下文能力强 |
|
||||
|
||||
代码通过 OpenAI 兼容接口调用，可灵活切换到任何兼容服务商。配置 `ai.llm.provider`、`ai.llm.model`、`ai.llm.endpoint` 即可。
|
||||
LLM 通过 Eino 框架的 `eino-ext/components/model/openai` ChatModel 组件接入，支持任何 OpenAI 兼容接口。配置 `ai.llm.provider`、`ai.llm.model`、`ai.llm.endpoint` 即可切换。
|
||||
|
||||
### TTS（语音合成）
|
||||
|
||||
| 方案 | 成本 | 特点 |
|
||||
|------|------|------|
|
||||
| **OpenAI TTS**（默认） | $15/1M 字符 | 音质自然，支持流式，默认模型 tts-1，语音 alloy |
|
||||
| MiMo TTS（小米） | 按量计费 | 国产替代，通过配置切换 |
|
||||
| **MiMo TTS**（默认） | 按量计费 | 国产替代，通过配置切换，模型 mimo-v2.5-tts |
|
||||
| OpenAI TTS | $15/1M 字符 | 音质自然，支持流式，默认模型 tts-1，语音 alloy |
|
||||
|
||||
当前默认使用 OpenAI TTS（tts-1, alloy），可通过 `ai.tts.provider` 配置切换。
|
||||
当前默认使用 MiMo TTS（mimo-v2.5-tts），可通过 `ai.tts.provider` 配置切换到 OpenAI TTS。
|
||||
|
||||
---
|
||||
|
||||
@@ -149,17 +191,19 @@ ORDER BY created_at DESC
|
||||
LIMIT 20;
|
||||
```
|
||||
|
||||
### 冷热分离架构
|
||||
### 冷热分离架构（三级存储）
|
||||
|
||||
```
|
||||
Go Gateway
|
||||
├── 写入路径 → Redis（实时会话状态）
|
||||
│ → PostgreSQL（对话历史 + 用量）
|
||||
└── 读取路径 → Redis（当前上下文，快）
|
||||
→ PostgreSQL（历史记录，慢）
|
||||
Go Gateway (TieredManager)
|
||||
├── L1: Memory（进程内缓存，微秒级）
|
||||
├── L2: Redis（分布式缓存，毫秒级）
|
||||
└── L3: PostgreSQL（持久化存储，冷数据）
|
||||
|
||||
读取路径：L1 → L2 → L3，逐级回源，命中后向上回填
|
||||
写入路径：L1 → L2（同步） → L3（异步）
|
||||
```
|
||||
|
||||
建议异步写入——实时消息先写 Redis（快），异步批量刷入 PostgreSQL（慢），不影响对话体验。
|
||||
`TieredManager` 自动管理三级存储，后台 goroutine 每 30 秒 ping Redis 健康状态，Redis 故障时自动降级为 L1+L3 模式。
|
||||
|
||||
### 决策流程
|
||||
|
||||
|
||||
Reference in New Issue
Block a user