Agentic-RAG
by Sun1206
README.md
# Agentic-RAG
Agentic RAG: An MCP-Based Multi-Agent Retrieval-Augmented Generation System
> 把论文变成可问答、可溯源知识库的检索增强生成（RAG）智能体：混合检索 + 知识图谱多跳推理 + 多 Agent 编排，按 MCP 协议对外提供工具，并用 RAGAS 做标准评估。
  
---
## 这是什么
输入一篇 PDF 论文，系统能：
- 解析论文成结构化文本（图表 / 公式 / 标题分离）
- 建向量库 + 知识图谱 + 层次摘要三层索引
- 回答关于论文的问题（事实 / 关系 / 总结），答案带来源页码和章节
- 多跳推理（"A 和 B 是什么关系"）
- 理解论文里的图表（多模态）
- 自检答案可信度（反思 + token 级幻觉检测）
和"直接调 LLM"的区别：这个系统不靠 LLM 硬背，而是**先从论文里检索证据再生成**，答案可溯源、幻觉可控。
---
## 效果
在 4 篇不同领域的公开论文上跑端到端问答，用金标准关键词命中率算 F1：
| 论文 | 领域 | F1 |
|---|---|---|
| bge_paper | Embedding 模型 | 91 ~ 100% |
| MiniMax-M1 技术报告 | LLM | 83% |
| Attention Is All You Need | NLP 经典 | 100% |
| ResNet | CV 经典 | 94% |
用 ragas 0.2.15 原版（LLM-as-judge，不是自定义指标）评 RAGAS 标准指标：
| 指标 | 含义 | 总体 |
|---|---|---|
| **Context Recall** | 金标准事实被检索回来的比例 | **97.9%** |
| **Faithfulness** | 答案断言被证据支撑的比例（越高幻觉越低）| **95.2%** |
---
## 快速开始
### 1. 环境
Python 3.12，建议建虚拟环境：
```bash
python3.12 -m venv env
source env/bin/activate # Windows: env\Scripts\activate
```
### 2. 安装依赖
```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```
（requirements.txt 顶部注释里也有阿里云 / 华为云 / 豆瓣源，任选。）
### 3. 下载模型
两个模型要从 HuggingFace 下载（体积大，所以没放进仓库）：
```bash
# Embedding 模型 bge-m3
git clone https://huggingface.co/BAAI/bge-m3 models/Xorbits/bge-m3
# 重排序模型 bge-reranker-v2-m3
git clone https://huggingface.co/BAAI/bge-reranker-v2-m3 models/bge-reranker-v2-m3
```
国内访问 HF 慢的话，用 ModelScope：
```bash
pip install modelscope
modelscope download --model BAAI/bge-m3 --local_dir models/Xorbits/bge-m3
modelscope download --model BAAI/bge-reranker-v2-m3 --local_dir models/bge-reranker-v2-m3
```
### 4. 配置 API Key
在项目根目录建一个 `.env` 文件（已在 `.gitignore` 里，不会被上传）：
```ini
MINIMAX_API_KEY=你的_MiniMax_API_Key
MINIMAX_API_HOST=https://api.minimaxi.com/v1
```
MiniMax API Key 在 https://platform.minimaxi.com 注册获取。代码里的 LLM 调用走 MiniMax-M3 的 OpenAI 兼容接口。
### 5. （可选）启动 Neo4j
知识图谱用内置内存图就能跑，不装 Neo4j 也行。想要 Neo4j 的话：
```bash
docker-compose up -d
```
默认连接 `bolt://localhost:7687`，账号密码在 `docker-compose.yml` 和 `.env` 里改。
### 6. 跑起来
```bash
# ① 入库：解析 data/ 下所有 PDF → 切块 → 向量化存进 ChromaDB
python script/run_embed_all.py
# ② 建知识图谱（以 bge_paper 为例）
python script/08_kg_extractor.py data/bge_paper.pdf
python script/09_kg_builder.py output/kg_triples/bge_paper.pdf.json
# ③ 直接 RAG 问答
python script/06_rag_query.py "what is bge-m3"
# ④ Agent 编排问答（推荐，走完整 路由→检索→推理→反思 链路）
python script/16_agent_orchestrator.py "what does MiniMax-M1 use"
# ⑤ 跑评估
python script/17_eval_framework.py
# ⑥ 起 Web 界面
python script/19_web_app.py
```
各脚本都支持 `--help` 看参数。每个 `test_XX_accuracy.py` 可单独验证对应模块的正确率。
---
## 系统架构
系统分五层：
- **用户层**：Gradio Web 界面 / FastAPI / 知识图谱可视化
- **MCP 协议层**：FastMCP 把能力封装成标准工具，可被 Claude 等 MCP 客户端直接调用
- **Agent 编排层**：路由 → 检索 → 推理 → 反思，Corrective RAG 范式
- **检索层**：向量 + 知识图谱 + 层次摘要三路召回，Cross-Encoder 两阶段精排
- **数据层**：ChromaDB / 内存图（可切 Neo4j）/ bge-m3 / bge-reranker
---
## 核心技术
### 1. 混合检索：向量 + BM25 + RRF + HyDE
纯向量检索有个老问题：对专有名词和数字不敏感。查"用了多少 H800 GPU"，向量可能召回一堆讲 GPU 的片段，漏掉那句"用了 512 张 H800"。
解法是逐步叠加策略：
```
纯向量（语义召回）→ +BM25（精确匹配）+RRF 融合 → +HyDE（假设答案检索）→ +Cross-Encoder 精排
```
- **RRF**（Reciprocal Rank Fusion）：向量分是 cosine（0~1），BM25 分是非归一化的，量纲不同没法直接加。RRF 只看排名不看绝对分：`score(d) = Σ 1/(k + rank)`，k 取 60。
- **HyDE**（Hypothetical Document Embeddings）：query 太短、chunk 太长，直接算相似度吃亏。先让 LLM 生成一个假设答案，用假设答案的向量去检索——它和 chunk 都是"答案形态"，语义更接近。
### 2. Cross-Encoder 两阶段精排
双塔（Bi-Encoder）：query 和 doc 分别编码算 cosine，快但精度有上限，两个向量没交互。
Cross-Encoder：query 和 doc 拼一起喂入 transformer 做交叉注意力，输出相关性分。精度高一个量级，但慢（每次都要过模型）。
所以走两阶段：
```
双塔粗召回 top-N → Cross-Encoder（bge-reranker-v2-m3）精排 top-5
（快，可预计算） （准，实时打分）
```
### 3. GraphRAG：让 RAG 会多跳推理
向量检索只能找"相似片段"，但"A 的作者还用过什么技术"这种问题答案分散在多个段落，靠相似度找不到。
解法是把论文里的实体关系抽成图，用图遍历做多跳推理：
```
论文文本 → LLM 抽三元组 → 实体消歧 → 建图 → text2cypher 查询
```
**实体消歧**是最难的环节（"MiniMax-M1"、"M1"、"the model" 可能是同一个实体），用了三层策略：子串包含 → 相似度阈值 → LLM 仲裁。
**text2cypher**（类比 text2SQL）：LLM 把自然语言翻译成图查询语句。Neo4j 连不上时，内置了一个内存图后端降级，本地也能跑。
### 4. 多 Agent 编排（Corrective RAG）
```
路由器(12) → 检索器(13) → 推理器(14) → 反思器(15)
```
- **路由器**：判定问题类型（事实 / 关系 / 总结）、该用哪些工具（向量 / 图谱 / 摘要）、跳数。规则优先，规则拿不准再请 LLM 仲裁。
- **检索器**：按路由策略多路召回 → RRF 融合 → MMR 多样性去重 → cross-encoder 精排。
- **推理器**：extraction-then-generation——先让 LLM 枚举片段中所有相关术语，再据此写答案，关键术语逐字保留。多次采样取忠实度最高的（自一致性）。
- **反思器**：把答案拆成原子断言，每条回检索片段找证据。有个"主语共指宽容"细节：答案里"它用了 lightning attention"和片段里"MiniMax-M1 用了 lightning attention"，"它"=MiniMax-M1，不该判幻觉。
### 5. MCP 协议工具层
把检索 / 图谱 / 多模态 / 联网搜索封装成标准 MCP（Model Context Protocol）工具。任何支持 MCP 的客户端（Claude Desktop、其他 Agent）都能直接调用，不用手写 API 集成。
---
## 项目结构
```
.
├── script/ # 全部代码（按流水线顺序编号）
│ ├── 01_config.py # 全局配置
│ ├── 02_pdf_parser.py # PDF 解析（多栏 / 图表 / 公式 / 标题）
│ ├── 03_chunker.py # 文本分块 + 章节归属
│ ├── 04_embedder.py # bge-m3 向量化 + ChromaDB
│ ├── 05_llm_client.py # MiniMax-M3 客户端封装
│ ├── 06_rag_query.py # 混合检索（向量+BM25+RRF+HyDE+rerank）
│ ├── 07_mcp_server.py # MCP 工具服务
│ ├── 08_kg_extractor.py # LLM 三元组抽取
│ ├── 09_kg_builder.py # 实体消歧 + 建图
│ ├── 10_kg_query.py # text2cypher + 图查询
│ ├── 11_summary_indexer.py # 层次摘要（document/section/paragraph）
│ ├── 12_router_agent.py # 路由 Agent
│ ├── 13_retriever_agent.py # 检索 Agent（多路+MMR+rerank）
│ ├── 14_reasoning_agent.py # 推理 Agent（自一致性）
│ ├── 15_reflection_agent.py # 反思 Agent（幻觉检测）
│ ├── 16_agent_orchestrator.py # Agent 编排器
│ ├── 17_eval_framework.py # RAGAS 评估框架
│ ├── 17b_ragas_official.py # ragas 原版（LLM-as-judge 对照）
│ ├── 18_eval_dataset.json # 评测数据集
│ ├── 19_web_app.py # Gradio Web 界面
│ ├── 20_api_server.py # FastAPI
│ ├── 21_kg_visualizer.py # 知识图谱可视化
│ ├── _reranker.py # Cross-Encoder 重排模块
│ ├── _memory_graph.py # 内存图后端（Neo4j 降级）
│ ├── _kg_gold.py # 测试金标准数据
│ ├── _eval_helpers.py # 评测工具函数
│ ├── run_embed_all.py # 一键入库脚本
│ └── test_*.py # 各模块准确率测试
├── data/ # 4 篇测试论文 PDF
├── images/ # 架构图与结果图
├── requirements.txt
├── docker-compose.yml # Neo4j（可选）
├── LICENSE
└── README.md
```
---
## 核心模块速查
| 模块 | 关键函数 | 作用 |
|---|---|---|
| `02_pdf_parser` | `parse_pdf`, `detect_all_figures`, `is_real_table` | 三层图表检测（位图/矢量/标注）+ 假表格过滤 |
| `06_rag_query` | `retrieve`, `rrf_fuse`, `generate_hyde`, `rerank_with_llm` | 混合检索主流程 |
| `09_kg_builder` | `disambiguate_entities`, `normalize_triples` | 三层实体消歧 + 关系归一化 + 引文过滤 |
| `10_kg_query` | `nl_to_cypher`, `standardize_projection`, `graph_search` | 自然语言 → Cypher → 执行 → 答案投影 |
| `11_summary_indexer` | `extractive_summary`, `retrieve_hierarchical` | 关键句抽取式摘要 + 三层 RRF 检索 |
| `13_retriever_agent` | `retrieve`, `mmr_rerank` | 多路召回 + MMR 多样性重排 |
| `15_reflection_agent` | `verify_answer`, `_claim_supported` | token 级幻觉检测（命名实体/数字从严）|
| `16_agent_orchestrator` | `answer` | 端到端编排：路由→检索→推理→反思 |
---
## 技术栈
| 组件 | 选型 | 用在哪 |
|---|---|---|
| LLM | MiniMax-M3 | 推理 / 三元组抽取 / text2cypher |
| Embedding | bge-m3 | 文本向量化 |
| Reranker | bge-reranker-v2-m3 | Cross-Encoder 精排 |
| 向量库 | ChromaDB | 语义检索 |
| 知识图谱 | NetworkX（内存图）/ Neo4j | 多跳推理 |
| 工具协议 | FastMCP | 标准化工具调用 |
| 界面 | Gradio / FastAPI | Web / REST API |
| 评估 | ragas 0.2.15 | RAGAS 标准指标 |
---
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues