# 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的幸运星