# 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 未启用

```python
# 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