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:
@@ -27,7 +27,7 @@ graph TB
|
||||
subgraph Gateway["Go 网关"]
|
||||
WS["WebSocket Handler<br/>连接管理 / 消息分发"]
|
||||
Session["Session Manager<br/>会话状态 / 对话历史"]
|
||||
Orch["AI Orchestrator<br/>STT→LLM→TTS 流式并行"]
|
||||
Orch["AI Orchestrator<br/>Eino Graph 声明式编排"]
|
||||
Auth["Auth 模块<br/>JWT / bcrypt"]
|
||||
REST["REST API<br/>健康检查 / 对话管理"]
|
||||
Store["Store 层<br/>Repository 接口"]
|
||||
@@ -70,34 +70,38 @@ graph TB
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant B as 浏览器
|
||||
participant G as Go 网关
|
||||
participant G as Go 网关（Eino Graph）
|
||||
participant S as STT
|
||||
participant L as LLM
|
||||
participant L as LLM（ChatModel）
|
||||
participant T as TTS
|
||||
|
||||
B->>B: VAD 检测到语音结束
|
||||
B->>G: query {image, audio}
|
||||
G->>S: 音频流
|
||||
S-->>G: 流式文本
|
||||
Note over G: EinoOrchestrator 启动 Graph.Stream()
|
||||
|
||||
G->>S: STT Lambda：音频 → 文本
|
||||
S-->>G: 识别文本
|
||||
G-->>B: stt_result {text}
|
||||
|
||||
G->>L: [图像 + 文本 + 上下文]
|
||||
loop LLM 流式输出
|
||||
G->>G: History Lambda：组装提示词 + 历史 + 多模态消息
|
||||
|
||||
G->>L: ChatModel Node：流式推理
|
||||
loop LLM 流式输出（Callback OnEndWithStreamOutput）
|
||||
L-->>G: token delta
|
||||
G-->>B: llm_chunk {delta}
|
||||
end
|
||||
G-->>B: llm_done {full_text, tokens}
|
||||
|
||||
par LLM 输出的同时
|
||||
G->>G: 句子切分器检测到完整句子
|
||||
G->>T: 句子文本
|
||||
T-->>G: 音频 chunk
|
||||
G-->>B: tts_audio {audio}
|
||||
end
|
||||
G->>G: Msg2Str + Splitter Lambda：句子切分
|
||||
G->>T: TTS Lambda：逐句合成
|
||||
T-->>G: 音频 chunk
|
||||
G-->>B: tts_audio {audio}
|
||||
|
||||
G->>G: Done Lambda：发送完成通知
|
||||
G-->>B: llm_done {full_text, tokens}
|
||||
G-->>B: tts_audio {final: true}
|
||||
```
|
||||
|
||||
**关键优化**：LLM 文本流和 TTS 音频流**并行推送**——客户端先逐 token 展示文字，同时 TTS 逐句子合成并推送音频，用户感知延迟大幅降低。
|
||||
**关键优化**：Eino Graph 以 Stream 模式运行，ChatModel 的 token 流通过 Callback 的 `OnEndWithStreamOutput` 实时推送到客户端（`llm_chunk`），同时 Splitter 节点将 token 流切分为句子，TTS 节点逐句合成并推送音频。LLM 文本流和 TTS 音频流**并行推送**，用户感知延迟大幅降低。
|
||||
|
||||
## 技术栈
|
||||
|
||||
@@ -118,7 +122,8 @@ sequenceDiagram
|
||||
| 语言 | Go | 高并发 goroutine 模型，适合长连接管理 |
|
||||
| HTTP 框架 | Gin | 高性能 HTTP 路由，中间件生态成熟 |
|
||||
| WebSocket | gorilla/websocket | Go 生态最成熟的 WebSocket 库 |
|
||||
| 会话存储 | Memory（默认） / Redis | 进程内存零依赖，Redis 支持多实例部署 |
|
||||
| 会话存储 | Memory / Redis / PostgreSQL 三级存储 | 进程内存零依赖，Redis 支持多实例，PG 持久化。TieredManager 自动降级 |
|
||||
| AI 编排 | CloudWeGo Eino Graph | 声明式 DAG 编排，Stream 模式，Callback AOP |
|
||||
| 持久化存储 | PostgreSQL | 对话历史、用户数据、会话元数据 |
|
||||
| 配置管理 | Viper + godotenv | 支持 YAML + .env + 环境变量覆盖 |
|
||||
| 日志 | Zap | 高性能结构化日志 |
|
||||
@@ -127,11 +132,11 @@ sequenceDiagram
|
||||
|
||||
| 能力 | 默认方案 | 备选方案 |
|
||||
|------|---------|---------|
|
||||
| 多模态 LLM | GPT-4o | 通义千问等 OpenAI 兼容模型 |
|
||||
| 语音识别 STT | Deepgram | MiMo ASR（小米） |
|
||||
| 语音合成 TTS | OpenAI TTS | MiMo TTS（小米） |
|
||||
| 多模态 LLM | DashScope qwen3-vl-plus | GPT-4o 等 OpenAI 兼容模型 |
|
||||
| 语音识别 STT | MiMo ASR（小米） | Deepgram |
|
||||
| 语音合成 TTS | MiMo TTS（小米） | OpenAI TTS |
|
||||
|
||||
> Go 网关的 AI 服务层统一封装不同服务商的调用接口，通过配置切换 provider。
|
||||
> Go 网关的 AI 服务层统一封装不同服务商的调用接口，通过配置切换 provider。LLM 通过 Eino 框架的 `eino-ext/components/model/openai` 组件接入，支持任何 OpenAI 兼容接口。
|
||||
|
||||
## 后端模块
|
||||
|
||||
@@ -148,14 +153,20 @@ graph LR
|
||||
|
||||
subgraph Business["业务层"]
|
||||
SM["Session Manager<br/>会话生命周期"]
|
||||
ORCH["Orchestrator<br/>STT→LLM→TTS 编排"]
|
||||
ORCH["EinoOrchestrator<br/>Eino Graph 编排"]
|
||||
AS["Auth Service<br/>注册/登录/刷新/登出"]
|
||||
end
|
||||
|
||||
subgraph Eino_Layer["Eino 编排层"]
|
||||
PG["PipelineGraph<br/>7 节点 DAG"]
|
||||
CB["Callback Handler<br/>LLM token 推送"]
|
||||
ST["PipelineState<br/>跨节点状态"]
|
||||
end
|
||||
|
||||
subgraph AI_Layer["AI 服务层"]
|
||||
STT_S["STT Service<br/>Deepgram / MiMo"]
|
||||
LLM_S["LLM Service<br/>OpenAI 兼容"]
|
||||
TTS_S["TTS Service<br/>OpenAI / MiMo"]
|
||||
STT_S["STT Service<br/>MiMo / Deepgram"]
|
||||
LLM_S["ChatModel<br/>eino-ext OpenAI 兼容"]
|
||||
TTS_S["TTS Service<br/>MiMo / OpenAI"]
|
||||
end
|
||||
|
||||
subgraph Data["数据层"]
|
||||
@@ -174,9 +185,12 @@ graph LR
|
||||
WSH --> ORCH
|
||||
APH --> SM
|
||||
APH --> AS
|
||||
ORCH --> STT_S
|
||||
ORCH --> LLM_S
|
||||
ORCH --> TTS_S
|
||||
ORCH --> PG
|
||||
PG --> CB
|
||||
PG --> ST
|
||||
PG --> STT_S
|
||||
PG --> LLM_S
|
||||
PG --> TTS_S
|
||||
SM --> MR
|
||||
SM --> SR
|
||||
AS --> UR
|
||||
@@ -186,7 +200,8 @@ graph LR
|
||||
|------|------|
|
||||
| WebSocket Handler | 管理客户端连接生命周期，JWT 认证，conversation_id 恢复，单播消息推送 |
|
||||
| Session Manager | 维护用户会话状态、对话历史。Memory（默认）/ Redis（可切换），30 分钟 TTL，Write-Through 到 PG |
|
||||
| AI Orchestrator | 编排 STT→LLM→TTS 流式并行管道，context 取消 + 超时控制 + 句子切分 |
|
||||
| Eino 编排层 | 基于 CloudWeGo Eino Graph 的声明式 AI 编排。7 节点 DAG（STT→History→ChatModel→Msg2Str→Splitter→TTS→Done），Stream 模式调用，Callback 实现 LLM token 实时推送 |
|
||||
| AI Orchestrator | `EinoOrchestrator` 适配器，包装 Eino Graph 实现 `Orchestrator` 接口。context 取消 + 超时控制 |
|
||||
| AI Service Layer | AI 服务抽象层，多 provider 支持（Deepgram/MiMo/OpenAI 等） |
|
||||
| Auth | 用户认证与授权。JWT (HS256) 双 token 轮转，bcrypt 密码哈希，Gin 中间件 |
|
||||
| Store | 持久化存储层。UserRepository / MessageRepository / SessionRepository，内存 + PostgreSQL 双实现 |
|
||||
@@ -306,10 +321,23 @@ CREATE TABLE refresh_tokens (
|
||||
| 场景 | 存储方案 | 说明 |
|
||||
|------|---------|------|
|
||||
| 默认 | Memory（进程内） | 零依赖，快速启动。MemoryManager 支持 Write-Through 到 PG |
|
||||
| 持久化 | Memory + PostgreSQL | 通过 `storage.driver: postgres` 启用，MemoryManager 注入 PG Repository |
|
||||
| 持久化 | Memory + PostgreSQL | 通过 `storage.persistence.enabled: true` 启用，MemoryManager 注入 PG Repository |
|
||||
| 多实例 | Redis（独立） | 通过配置切换到 RedisManager，适合多实例部署 |
|
||||
| 三级存储 | TieredManager | L1 Memory → L2 Redis → L3 PostgreSQL，自动降级 |
|
||||
|
||||
冷热分离：Redis/Memory 存"热数据"（当前对话上下文，微秒级读写），PostgreSQL 存"冷数据"（历史记录）。MemoryManager 的 Write-Through 机制确保每次 AppendMessage 同时写入 PG，重启后可从 PG 恢复会话。
|
||||
**三级存储架构**（`TieredManager`）：
|
||||
|
||||
```
|
||||
TieredManager
|
||||
├── L1: Memory（进程内缓存，微秒级读写）
|
||||
├── L2: Redis（分布式缓存，毫秒级读写）
|
||||
└── L3: PostgreSQL（持久化存储，冷数据）
|
||||
```
|
||||
|
||||
- **读取路径**：L1 → L2 → L3，逐级回源，命中后向上回填
|
||||
- **写入路径**：L1 → L2（同步） → L3（异步）
|
||||
- **健康检查**：后台 goroutine 每 30 秒 ping Redis，故障时自动降级为 L1+L3 模式
|
||||
- **冷热分离**：L1/L2 存"热数据"（当前对话上下文），L3 存"冷数据"（历史记录）
|
||||
|
||||
## 认证设计
|
||||
|
||||
|
||||
Reference in New Issue
Block a user