# PaperRAG MCP Server — 个人科研论文知识库（Personal Research Paper Knowledge Base）

> 基于可插拔 Modular RAG 架构打造的私人论文数据库：摄取 PDF 论文 → 混合检索（Hybrid Search + Rerank）→ MCP 协议暴露给 AI 助手，附带 Dashboard 可视化管理和自动化评估体系。

---

## 📖 目录

- [项目概述](#-项目概述)
- [快速开始](#-快速开始)
- [测试体系与评估基线](#-测试体系与评估基线)
- [常见问题](#-常见问题)

---

## 🏗️ 项目概述

### 这个项目是什么

一个服务于**个人论文阅读与管理**的 RAG 系统：把下载的学术论文（PDF）摄入知识库，通过 **BM25 稀疏检索 + 稠密向量检索（RRF 融合）+ Cross-Encoder 精排** 找到最相关的段落，并作为 MCP Server 供 Claude Code / Cursor / Copilot 等 AI 助手直接调用——"问 AI 论文里的问题"。

当前知识库已摄入 17 篇目标检测/图神经网络方向论文（约 1670 个 chunk），并配套 64 题黄金测试集（`tests/fixtures/paper_test_set.json`）进行质量回归。

### 核心能力一览

| 模块 | 能力 | 说明 |
|------|------|------|
| **Ingestion Pipeline** | PDF → Markdown → Chunk → Refine → Enrich → Embedding → Upsert | 全链路数据摄取，支持多模态图片描述（Image Captioning） |
| **Hybrid Search** | Dense (向量) + Sparse (BM25) + RRF Fusion + Rerank | 粗排召回 + 精排重排的两段式检索架构 |
| **MCP Server** | 标准 MCP 协议暴露 Tools | `query_knowledge_hub`、`list_collections`、`get_document_summary` |
| **Dashboard** | Streamlit 六页面管理平台 | 系统总览 / 数据浏览 / 论文导入 / 摄取追踪 / 查询追踪 / 评估面板 |
| **Evaluation** | Ragas + Custom 评估体系 | hit_rate / MRR / faithfulness 三指标，拒绝"凭感觉"调优 |
| **Observability** | 全链路白盒化追踪 | Ingestion 与 Query 两条链路的每一个中间状态透明可见 |

### 技术亮点

**🔌 全链路可插拔架构**：LLM / Embedding / Reranker / Splitter / VectorStore / Evaluator 每一个核心环节均定义了抽象接口，支持"乐高积木式"替换，通过配置文件一键切换后端，零代码修改。

**🔍 混合检索 + 重排**：BM25 稀疏检索解决专有名词精确匹配 + Dense Embedding 解决同义词语义匹配，RRF 融合后可选 Cross-Encoder / LLM Rerank 精排，平衡查全率与查准率。

**🖼️ 多模态图像处理**：采用 Image-to-Text 策略，利用 Vision LLM 自动生成图片描述并缝合进 Chunk，复用纯文本 RAG 链路即可实现"搜文字出图"。

**📡 MCP 生态集成**：遵循 Model Context Protocol 标准，可直接对接 Claude Code、Cursor、GitHub Copilot 等 MCP Client，零前端开发，一次开发处处可用。

**📊 可视化管理 + 自动化评估**：Streamlit Dashboard 提供完整的数据管理与链路追踪能力，集成 Ragas 等评估框架，建立基于数据的迭代反馈回路。

**🧪 三层测试体系**：Unit / Integration / E2E 分层测试共 1363 个用例，覆盖独立模块逻辑、模块间交互、完整链路（MCP Client / Dashboard）。

---

## 🚀 快速开始

### 1. 环境准备

```bash
# 安装依赖（建议使用 .venv）
pip install -e .

# 或使用 Setup Skill 一键配置（Provider 选择 → API Key → 依赖 → 配置）
setup
```

编辑 `config/settings.yaml` 填入 LLM / Embedding 的 API Key（默认 OpenAI）。

### 2. 统一入口（main.py）

```bash
# 启动 MCP Server（供 AI 助手连接，stdio 传输）
python main.py

# 启动 Dashboard 前端（默认 http://localhost:8501）
python main.py dashboard --port 8501
```

### 3. 摄入论文

```bash
# 通过 Dashboard「论文导入」页上传，或 CLI：
python scripts/ingest.py --path <论文目录或文件> --collection default
```

### 4. 集成到 AI 助手

在 Claude Code / Cursor 等的 MCP 配置中注册本项目：

```json
{
  "mcpServers": {
    "rag-kb": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "<项目路径>"
    }
  }
}
```

配置完成后即可让 AI 直接调用 `query_knowledge_hub` 等工具查询论文内容。

---

## 📊 测试体系与评估基线

### 测试规模

| 层级 | 数量 | 说明 |
|------|------|------|
| Unit（单元测试） | 1205 | 组件级逻辑（chunker / loaders / retrievers / evaluators 等） |
| Integration（集成测试） | ~120 | 真实组件协作（摄取管道 / 混合检索 / Chroma 往返 / MCP 协议） |
| E2E（端到端测试） | ~38 | 完整链路（MCP Client 协议 / Dashboard AppTest / 数据摄取） |

```bash
pytest tests/unit -q          # 单元测试
pytest tests/integration -q   # 集成测试（部分需真实 LLM 凭据）
pytest tests/e2e -q           # 端到端测试
```

### 论文测试集评估基线（2026-09-11 实测）

64 题黄金测试集（17 篇论文）三指标：

| 指标 | 数值 | 说明 |
|------|------|------|
| Hit Rate@10 | **0.8281** | 53/64 题在 top-10 中命中答案 chunk |
| MRR | **0.562** | 平均命中位置约第 2 位 |
| Faithfulness | **0.8824** | 生成答案对检索上下文的忠实度（Ragas LLM-as-Judge） |

```bash
# 检索指标（零 LLM 成本）
python scripts/evaluate.py --test-set tests/fixtures/paper_test_set.json --top-k 10 --json

# 三指标（需 ragas；--generate-answers 自动生成答案）
python scripts/evaluate.py --test-set tests/fixtures/paper_test_set.json --top-k 10 --generate-answers --json
```

> ⚠️ 测试集 chunk id 与当前入库数据绑定，**重新入库后需重新验证**：`python scripts/verify_paper_testset.py` 逐题验证检索，再用 `python scripts/build_paper_testset.py` 重建测试集。

---

## ❓ 常见问题

### 1. 如何切换 Provider（OpenAI / DeepSeek / Ollama / Azure）？

项目使用**工厂模式（Factory Pattern）**，Provider 切换只需：① 新增/选用 Provider 类；② 在工厂注册；③ 更新 `settings.yaml`。直接让 AI 帮你完成，或运行 Setup Skill 引导配置。

### 2. 想摄取 PDF 以外的文档格式（Word / Markdown / HTML 等）？

Loader 层采用可插拔抽象设计（`BaseLoader`），默认实现 PDF Loader。新增格式只需让 AI 参考现有 PDF Loader 实现一个对应 Loader。

### 3. 如何集成到 AI 工具中（Claude Code / Cursor / Copilot 等）？

本项目是标准 MCP Server，任何支持 MCP 协议的 AI 工具都能集成——按工具要求填写 MCP 配置（见快速开始第 4 步），或直接问 AI 生成配置。

### 4. 项目报错 / Bug 怎么办？

三层测试体系覆盖主链路，遇到问题：① 把错误信息直接丢给 AI 修复；② 运行 `qa-tester` Skill 执行全量 QA 计划（QA_TEST_PLAN.md，A~P 共 16 章）；③ 检查 `logs/traces.jsonl` 追踪链路定位瓶颈。

### 5. 善用内置 Skill

| Skill | 用途 |
|-------|------|
| `setup` | 一键环境配置（Provider / API Key / 依赖 / 启动） |
| `qa-tester` | 全量 QA 自动测试（A~P 章节验收清单） |
| `auto-coder` | 后续增量功能的 spec 驱动自动开发 |
| `package` | 清理打包（自动脱敏 API Key、保留论文测试集） |