327 lines
11 KiB
Markdown
Executable File
327 lines
11 KiB
Markdown
Executable File
# Gene Family MAS V2 - 架构文档
|
|
|
|
**版本**: 2.0.0
|
|
**最后更新**: 2026-04-17
|
|
|
|
---
|
|
|
|
## 系统架构概览
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 前端层 (Vue3) │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ RAG查询界面 │ │ Agent状态组件 │ │ 知识图谱可视化│ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ API层 (FastAPI) │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ RAG路由 │ │ RAPTOR路由 │ │ 时序KG路由 │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ 高级RAG路由 │ │ 知识图谱路由 │ │ 推理路由 │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 服务层 (Services) │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ RAG编排器 │ │ RAPTOR检索器 │ │ 时序查询引擎 │ │
|
|
│ │ (Self-RAG) │ │ (层次检索) │ │ (时间维度) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ MultiHopRAG │ │ 实体链接 │ │ 引用溯源 │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 数据层 (Data Layer) │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ 向量存储 │ │ 知识图谱 │ │ 时序KG │ │
|
|
│ │ (InMemory/ │ │ (Neo4j/ │ │ (内存/JSON) │ │
|
|
│ │ Qdrant) │ │ NetworkX) │ │ │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ 文档存储 │ │ 反馈数据库 │ │ 配置存储 │ │
|
|
│ │ (PDF/JSON) │ │ (SQLite) │ │ (YAML) │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 核心模块详解
|
|
|
|
### 1. RAG系统
|
|
|
|
#### 1.1 基础RAG
|
|
|
|
```
|
|
src/rag/
|
|
├── base.py # 基础类和接口
|
|
├── vector_store.py # 向量存储
|
|
├── embeddings.py # 嵌入模型
|
|
├── retriever.py # 检索器
|
|
└── hybrid_retriever.py # 混合检索器
|
|
```
|
|
|
|
**流程**:
|
|
1. 查询分析 (QueryAnalyzer)
|
|
2. 检索策略选择 (RetrievalStrategyAgent)
|
|
3. 执行检索 (HybridRetriever)
|
|
4. 结果评估 (ResultEvaluator)
|
|
|
|
#### 1.2 Agent编排RAG
|
|
|
|
```
|
|
src/rag/agentic/
|
|
├── orchestrator.py # Agent编排器 (LangGraph)
|
|
├── query_analyzer.py # 查询分析
|
|
├── retrieval_strategy.py # 检索策略
|
|
└── result_evaluator.py # 结果评估
|
|
```
|
|
|
|
**Self-RAG流程**:
|
|
```
|
|
查询 -> 分析 -> 检索 -> 评估 -> 反思 -> [重写?] -> 生成答案
|
|
↑___________________________|
|
|
```
|
|
|
|
**MultiHopRAG流程**:
|
|
```
|
|
查询 -> 分析 -> 判断复杂? -> 是 -> 多跳检索 -> 整合结果
|
|
|
|
|
└-> 否 -> 普通检索
|
|
```
|
|
|
|
#### 1.3 高级RAG功能
|
|
|
|
```
|
|
src/rag/advanced/
|
|
├── query_expansion.py # 查询扩展
|
|
├── entity_linking.py # 实体链接
|
|
├── citation_tracker.py # 引用溯源
|
|
├── dynamic_kg_builder.py # 动态知识图谱
|
|
├── cross_paper_fusion.py # 跨论文融合
|
|
├── neo4j_graph_algorithms.py # 图算法
|
|
└── raptor/ # RAPTOR层次索引
|
|
├── tree_builder.py
|
|
├── retriever.py
|
|
└── summarizer.py
|
|
```
|
|
|
|
### 2. RAPTOR层次索引
|
|
|
|
**树结构**:
|
|
```
|
|
Root (全局摘要)
|
|
/ \
|
|
Summary L3 Summary L3
|
|
/ \ / \
|
|
Summary L2 Summary L2 Summary L2 Summary L2
|
|
/ \ / \ / \ / \
|
|
Leaf Leaf Leaf Leaf Leaf Leaf Leaf Leaf
|
|
```
|
|
|
|
**检索策略**:
|
|
- **Top-Down**: 从根节点开始，逐层向下匹配
|
|
- **Cross-Level**: 在所有层同时匹配
|
|
- **Multi-Level**: 返回不同层级的结果
|
|
|
|
### 3. 时序知识图谱
|
|
|
|
**数据模型**:
|
|
```
|
|
TemporalEntity:
|
|
- entity_id
|
|
- name
|
|
- entity_type
|
|
- valid_time: TimePeriod (start, end)
|
|
- properties
|
|
|
|
TemporalRelation:
|
|
- relation_id
|
|
- source_id
|
|
- target_id
|
|
- relation_type
|
|
- timestamp: TimePoint
|
|
- temporal_type: BEFORE/AFTER/DURING/CONCURRENT
|
|
```
|
|
|
|
**查询类型**:
|
|
- 时间范围查询
|
|
- 实体历史查询
|
|
- 研究进展时间线
|
|
- 时间线可视化
|
|
|
|
---
|
|
|
|
## 数据流
|
|
|
|
### RAG查询数据流
|
|
|
|
```
|
|
用户查询
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ 查询分析 │ -> 识别意图、提取实体
|
|
└──────────────┘
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ 检索策略 │ -> 选择检索模式
|
|
└──────────────┘
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ 向量检索 │ -> 相似度搜索
|
|
│ BM25检索 │ -> 关键词匹配
|
|
│ 子串检索 │ -> 精确匹配
|
|
└──────────────┘
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ 结果融合 │ -> 加权排序
|
|
└──────────────┘
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ Self-RAG反思 │ -> 评估充分性
|
|
└──────────────┘
|
|
│
|
|
├-> 不充分 -> 重写查询 -> 重新检索
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ 生成答案 │ -> LLM生成
|
|
└──────────────┘
|
|
│
|
|
▼
|
|
┌──────────────┐
|
|
│ 添加引用 │ -> 引用溯源
|
|
└──────────────┘
|
|
│
|
|
▼
|
|
用户响应
|
|
```
|
|
|
|
---
|
|
|
|
## API设计
|
|
|
|
### RESTful API规范
|
|
|
|
- **基础路径**: `/api/v1`
|
|
- **资源命名**: 使用名词复数，如 `/rag`, `/entities`
|
|
- **HTTP方法**:
|
|
- GET: 查询
|
|
- POST: 创建/操作
|
|
- DELETE: 删除
|
|
- **响应格式**: JSON
|
|
- **错误处理**: HTTP状态码 + 错误详情
|
|
|
|
### 主要API分组
|
|
|
|
| 分组 | 路径前缀 | 功能 |
|
|
|------|----------|------|
|
|
| RAG | `/rag` | 检索增强生成 |
|
|
| RAPTOR | `/raptor` | 层次索引 |
|
|
| 时序KG | `/temporal` | 时序知识图谱 |
|
|
| 高级RAG | `/advanced` | 高级RAG功能 |
|
|
| 知识图谱 | `/kg` | 知识图谱操作 |
|
|
|
|
---
|
|
|
|
## 扩展性设计
|
|
|
|
### 1. 模块化设计
|
|
|
|
- 每个功能模块独立，通过接口交互
|
|
- 支持插件式扩展
|
|
|
|
### 2. 配置驱动
|
|
|
|
- 所有组件可通过配置调整
|
|
- 支持运行时配置更新
|
|
|
|
### 3. 存储抽象
|
|
|
|
- 向量存储: 支持InMemory、Qdrant等
|
|
- 知识图谱: 支持Neo4j、NetworkX等
|
|
|
|
---
|
|
|
|
## 性能考虑
|
|
|
|
### 1. 缓存策略
|
|
|
|
- 查询结果缓存
|
|
- 嵌入向量缓存
|
|
- 知识图谱节点缓存
|
|
|
|
### 2. 异步处理
|
|
|
|
- LLM调用异步
|
|
- 文件上传异步
|
|
- 长时间任务后台处理
|
|
|
|
### 3. 资源管理
|
|
|
|
- 向量存储内存管理
|
|
- 连接池管理
|
|
- 垃圾回收优化
|
|
|
|
---
|
|
|
|
## 安全考虑
|
|
|
|
### 1. 输入验证
|
|
|
|
- 所有API参数验证
|
|
- SQL注入防护
|
|
- XSS防护
|
|
|
|
### 2. 访问控制
|
|
|
|
- API密钥认证 (可选)
|
|
- 请求限流
|
|
- CORS配置
|
|
|
|
### 3. 数据保护
|
|
|
|
- 敏感配置加密存储
|
|
- 日志脱敏
|
|
- 数据传输加密
|
|
|
|
---
|
|
|
|
## 监控与日志
|
|
|
|
### 1. 指标收集
|
|
|
|
- 请求延迟
|
|
- 成功率
|
|
- 资源使用率
|
|
|
|
### 2. 日志分级
|
|
|
|
- DEBUG: 开发调试
|
|
- INFO: 正常运行
|
|
- WARNING: 警告
|
|
- ERROR: 错误
|
|
|
|
### 3. 健康检查
|
|
|
|
- `/health` 端点
|
|
- 依赖服务检查
|
|
- readiness/liveness探针
|
|
|
|
---
|
|
|
|
**文档维护**: xialab的幸运星 |