PlantAI-rag/docs/architecture/README.md

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