RAG-SKILLS2 学术论文 RAG 系统

基于 MinerU、Chart-R1 与 Qwen3 的学术论文检索增强生成系统。支持 PDF 解析、图表视觉推理、混合检索（向量 + BM25）、重排序与 RAGAS 评估。

功能概览

离线流水线：PDF → MinerU 解析 → Chart-R1 图表推理 → 父子块入库（Chroma + doc_store + BM25）
在线检索：混合检索 + Qwen3 重排 + LongContextReorder，通过 MCP 暴露 search_academic_papers 工具
评估：RAGAS（Context Recall / Faithfulness / Answer Relevancy）+ DeepSeek 评委

环境要求

| 项目 | 要求 | |------|------| | Python | >= 3.10（见 pyproject.toml） | | GPU | NVIDIA GPU，显存建议 >= 8GB（Qwen3-Embedding-4B、Qwen3-Reranker-4B、Chart-R1 均需 GPU） | | MinerU | 需单独部署，提供 PDF 解析 HTTP API |

快速开始

1. 克隆并安装依赖

git clone <your-repo-url>
cd RAG_SKILLS2
pip install -r requirements.txt

2. 配置环境变量

复制 .env.example 为 .env，按需填写：

cp .env.example .env
# 编辑 .env，至少配置 MINERU_API_URL、INPUT_DIR、OUTPUT_DIR、DEEPSEEK_API_KEY（评估用）

3. 启动 MinerU 服务

本项目依赖 MinerU 的 HTTP API 解析 PDF。请先按 MinerU 启动说明部署并启动 MinerU 服务。

4. 准备 PDF 并运行流水线

# 创建目录并放入 PDF
mkdir -p data/raw_papers data/processed data/vector_db data/doc_store data/processed_papers
# Windows: mkdir data\raw_papers data\processed data\vector_db data\doc_store data\processed_papers

# 将 PDF 放入 data/raw_papers/ 后运行全流程
python -m src.pipeline

5. 运行评估（需 DEEPSEEK_API_KEY）

python -m src.eval_pipeline --dataset data/test_dataset.json --out-dir reports

环境变量说明

| 变量 | 必填 | 说明 | 示例 | |------|------|------|------| | MINERU_API_URL | 是 | MinerU 解析 API 地址 | http://127.0.0.1:8000/file_parse | | INPUT_DIR | 否 | 原始 PDF 目录 | data/raw_papers | | OUTPUT_DIR | 否 | MinerU 解析产物目录 | data/processed | | VECTOR_DB_DIR | 否 | Chroma 向量库目录 | data/vector_db | | DOC_STORE_DIR | 否 | 父块文档库目录 | data/doc_store | | CHART_R1_MODEL_ID | 否 | Chart-R1 模型 ID | DocTron/Chart-R1 | | DEEPSEEK_API_KEY | 评估时必填 | DeepSeek API Key（RAGAS 评委） | - | | DEEPSEEK_BASE_URL | 否 | DeepSeek API 地址 | https://api.deepseek.com | | LOCAL_MODEL_PATH | 否 | HuggingFace 模型缓存根目录 | ~/.cache/huggingface/hub | | LANG_LIST | 否 | MinerU 解析语言列表（JSON） | ["ch","en"] | | HF_ENDPOINT | 否 | HuggingFace 镜像（国内可用 hf-mirror） | https://hf-mirror.com |

更多变量见 .env.example。

MCP 配置（Cursor / Claude Desktop）

在 Cursor 或 Claude Desktop 的 MCP 配置中添加本项目的 MCP 服务器，例如：

{
  "mcpServers": {
    "academic-rag": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/RAG_SKILLS2"
    }
  }
}

启动后即可通过 search_academic_papers 工具检索学术论文。需确保已运行流水线完成入库。

常用命令

| 场景 | 命令 | |------|------| | 全流程 | python -m src.pipeline | | 仅图表推理 + 入库 | python -m src.pipeline --skip-batch | | 仅入库 | python -m src.pipeline --skip-batch --skip-chart | | 评估（正式） | python -m src.eval_pipeline --dataset data/test_dataset.json --out-dir reports | | 评估（基线对比） | python -m src.eval_pipeline --dataset data/test_dataset.json --baseline |

更多说明见项目启动命令。

测试集格式

评估用 data/test_dataset.json 格式示例：

{
  "items": [
    {
      "id": "q0",
      "question": "PRISMA 流程图中最终纳入的研究数量是多少？",
      "ground_truths": ["128"],
      "category": "chart_logic"
    }
  ]
}

仓库内已包含示例 data/test_dataset.json，可据此扩展自己的测试集。

MCP Servers