PlantAI-rag/docs/PROJECT_ANALYSIS.md

Gene-Family-MAS-V2 项目分析报告

项目架构概览

RAG 阶段的两个子系统

系统	位置	类型	状态
V13 提取器	src/rag/extractors/v13/	纯Pipeline流程	✅ 生产使用
Agentic 系统	src/rag/agentic/	Agent编排框架	⚠️ 部分使用

---

一、V13 提取器（生产核心）

流程架构

Phase 1 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 → Phase 5 → Phase 5.5 → Phase 6
文档解析    附表处理   多组学提取   实体识别   关系抽取    后处理     审核      VLM图像

各模块功能

Phase	模块	功能	关键点
1	phase1_document_parser_mineru.py	MinerU PDF解析 + 章节识别	从 layout.json 解析章节标题
2	phase2_supplementary.py	附表下载 + Excel解析	PMID→PMCID→Europe PMC
2.5	geo_extractor.py	GEO/GSE数据提取	RNA-seq、Microarray等
3	phase3_entity_recognition.py	8种实体识别	基因家族、基因名、物种名等
4	phase4_relation_extraction.py	74个PC模式关系抽取	最核心模块，45KB
5	phase5_post_processing.py	去重、验证、chunks
5.5	phase5_review.py	规则审查 + 评估	A/B/C/D等级
6	phase6_vlm_image_extraction.py	VLM图像关系提取	阿里云百炼 qwen3.6-plus

入口点

• v13_extractor.py - 主提取器类 V13Extractor
• test_v13_1_simple.py - 快速测试入口

---

二、Agentic 系统（部分使用）

Agent 组件清单

Agent	文件	设计功能	实际状态
QueryAnalyzer	query_analyzer.py	意图识别 + 实体提取	✅ API使用
RetrievalStrategyAgent	retrieval_strategy.py	检索策略选择	✅ API使用
ResultEvaluator	result_evaluator.py	结果评估	⚠️ 只在Orchestrator内
IterativeRetriever	iterative_retriever.py	多跳迭代检索	❌ 仅测试脚本
RAGAgentOrchestrator	orchestrator.py	LangGraph编排	❌ fallback模式

实际调用链路

API (/api/v1/rag/chat)
    ├── mode="agentic" → _agentic_search()
    │   ├── QueryAnalyzer.analyze()        ✅ 被调用
    │   ├── RetrievalStrategyAgent.determine_strategy() ✅ 被调用
    │   └── 根据策略执行: exact/bm25/substring/hybrid
    │
    └── mode="hybrid/substring/bm25" → 直接调用对应搜索方法

关键发现：LangGraph 未启用

# orchestrator.py 第 14-18 行
try:
    from langgraph.graph import StateGraph, END
    LANGGRAPH_AVAILABLE = False  # V2: 禁用 LangGraph，使用 Fallback
except ImportError:
    LANGGRAPH_AVAILABLE = False

结论：Orchestrator 实际用的是 _run_fallback() 方法，而非真正的 LangGraph 状态机。

---

三、Agentic 系统使用情况分析

在生产中发挥作用的

Agent	使用位置	作用
QueryAnalyzer	api/rag_routes.py:29,383	分析查询意图，提取实体
RetrievalStrategyAgent	api/rag_routes.py:30,386	根据意图选择检索模式

未发挥作用的（死代码候选）

Agent	原因
IterativeRetriever	只在 scripts/test_phase2_complete.py 测试脚本中引用
RAGAgentOrchestrator (LangGraph部分)	LANGGRAPH_AVAILABLE = False 强制禁用
ResultEvaluator	只在 Orchestrator 的 fallback 流程中调用，但 fallback 流程本身未被生产使用

实际效果

Agentic 系统当前只是两步规则映射：

1. 查询分析 → 查询类型
2. 查询类型 → 检索策略

没有真正的 Agent 自主决策、迭代优化、结果评估闭环。

---

四、历史遗留代码

extractors/archive/ 目录（18个废弃提取器）

• extractor_pc_*.py - 各种 PC 模式实验版本
• extractor_complete_v1.py - 早期完整版
• extractor_production_v1.py - 早期生产版

extractors/ 目录（非v13）

• extract_v12_*.py - v12 版本（已被 v13 替代）
• smart_gene_family_extractor*.py - 早期智能提取器
• expression_relation_extractor.py - 表达关系提取器（功能已整合到v13）

---

五、建议

Agentic 系统处理建议

选择	说明
保留 QueryAnalyzer + RetrievalStrategyAgent	API实际使用，保留
简化 Orchestrator	删除 LangGraph 相关代码，只保留 fallback 逻辑
删除 IterativeRetriever	死代码，仅测试脚本引用
评估 ResultEvaluator	若无计划使用 LangGraph，可删除

或者完全重构

如果真想用 Agent 编排，应该：

1. 安装 LangGraph 并启用
2. 重新设计状态机流程
3. 让 Orchestrator 成为真正的生产入口

当前状态是"有 Agent 架构但没用 Agent 能力"。

---

六、结论

项目	结论
V13提取器	完整、稳定、生产使用
Agentic系统	两成用到，八成死代码
整体架构	混合设计，有冗余

务实建议：保留真正使用的部分（QueryAnalyzer、StrategyAgent），清理未使用的（IterativeRetriever、LangGraph相关），让代码更清晰。

---

生成时间: 2026-04-15