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 # 混合检索器
流程:
- 查询分析 (QueryAnalyzer)
- 检索策略选择 (RetrievalStrategyAgent)
- 执行检索 (HybridRetriever)
- 结果评估 (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的幸运星