Skip to main content
Glama
Sun1206

Agentic-RAG

by Sun1206
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Agentic-RAG

Agentic RAG: An MCP-Based Multi-Agent Retrieval-Augmented Generation System

把论文变成可问答、可溯源知识库的检索增强生成（RAG）智能体：混合检索 + 知识图谱多跳推理 + 多 Agent 编排，按 MCP 协议对外提供工具，并用 RAGAS 做标准评估。

Python License RAG

这是什么

输入一篇 PDF 论文，系统能：

  • 解析论文成结构化文本（图表 / 公式 / 标题分离）

  • 建向量库 + 知识图谱 + 层次摘要三层索引

  • 回答关于论文的问题（事实 / 关系 / 总结），答案带来源页码和章节

  • 多跳推理（"A 和 B 是什么关系"）

  • 理解论文里的图表（多模态）

  • 自检答案可信度（反思 + token 级幻觉检测）

和"直接调 LLM"的区别：这个系统不靠 LLM 硬背，而是先从论文里检索证据再生成，答案可溯源、幻觉可控。

Related MCP server: MCP-based Academic Paper Retrieval RAG System

效果

在 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%

检索效果 RAGAS 指标 4 篇论文 F1

快速开始

1. 环境

Python 3.12，建议建虚拟环境：

python3.12 -m venv env
source env/bin/activate        # Windows: env\Scripts\activate

2. 安装依赖

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

（requirements.txt 顶部注释里也有阿里云 / 华为云 / 豆瓣源，任选。）

3. 下载模型

两个模型要从 HuggingFace 下载（体积大，所以没放进仓库）：

# 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：

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 里，不会被上传）：

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 的话：

docker-compose up -d

默认连接 bolt://localhost:7687，账号密码在 docker-compose.yml 和 .env 里改。

6. 跑起来

# ① 入库：解析 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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers