docs/ARCHITECTURE.md

# 🏗️ ScholarMind — 生产级学术知识库问答 & 知识图谱系统

## 系统概述

ScholarMind 是一个面向 **1000+ 篇学术 PDF 论文** 的生产级智能知识系统，集成：
- **PDF 深度解析**：基于 MinerU 2.5 VLM 的高精度 OCR（公式/表格/图表）
- **知识图谱自动构建**：从论文中自动抽取实体与关系，构建领域知识图谱
- **混合检索问答**：GraphRAG + 向量检索 + BM25 稀疏检索的三路融合
- **多模型支持**：同时支持本地部署（vLLM/Ollama）和外部 API（OpenAI/Anthropic/DeepSeek）
- **Agent 编排**：基于 LangGraph 的多 Agent 协作，支持多跳推理

> **核心指标**：单 A100 80G 可在 ~80 分钟内完成 1000 篇论文（~10000 页）的全量解析

---

## 目录

1. [系统架构总览](#1-系统架构总览)
2. [PDF 解析层 — MinerU Pipeline](#2-pdf-解析层)
3. [知识抽取层 — 实体关系抽取](#3-知识抽取层)
4. [知识图谱层 — 图构建与存储](#4-知识图谱层)
5. [索引层 — 多路索引构建](#5-索引层)
6. [检索层 — 混合检索与重排](#6-检索层)
7. [Agent 编排层 — 智能问答](#7-agent-编排层)
8. [LLM 统一接入层](#8-llm-统一接入层)
9. [系统部署架构](#9-系统部署架构)
10. [技术选型对比](#10-技术选型对比)
11. [关键论文与开源项目](#11-关键论文与开源项目)
12. [项目结构](#12-项目结构)

---

## 1. 系统架构总览

```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              ScholarMind 系统架构                                    │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│  ┌──────────┐    ┌──────────────────────────────────────────────────────────────┐   │
│  │  用户层   │    │                    FastAPI Gateway                          │   │
│  │ Web UI   │───▶│  /upload  /query  /graph  /status  /chat  WebSocket SSE    │   │
│  │ API调用  │    └────────┬─────────────┬────────────────┬────────────────────┘   │
│  └──────────┘             │             │                │                         │
│                           ▼             ▼                ▼                         │
│  ┌─────────────────────────────────────────────────────────────────────────────┐   │
│  │                      Agent 编排层 (LangGraph)                               │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │   │
│  │  │ 路由Agent │  │ 检索Agent │  │ 推理Agent │  │ 图谱Agent │  │ 总结Agent │    │   │
│  │  │ (分类意图)│  │ (混合检索)│  │ (多跳推理)│  │ (图谱查询)│  │ (答案生成)│    │   │
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘    │   │
│  └───────┼──────────────┼──────────────┼──────────────┼──────────────┼─────────┘   │
│          │              │              │              │              │               │
│  ┌───────▼──────────────▼──────────────▼──────────────▼──────────────▼─────────┐   │
│  │                      LLM 统一接入层 (LiteLLM Proxy)                         │   │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────────┐  ┌──────────┐  ┌──────────┐   │   │
│  │  │  vLLM   │  │ Ollama  │  │ OpenAI/Claude│  │ DeepSeek │  │  Gemini  │   │   │
│  │  │ (本地)  │  │ (本地)  │  │  (外部API)   │  │ (外部API)│  │ (外部API)│   │   │
│  │  └─────────┘  └─────────┘  └─────────────┘  └──────────┘  └──────────┘   │   │
│  └────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                     │
│  ┌─────────────────────────────────────────────────────────────────────────────┐   │
│  │                          检索层 (Hybrid Retrieval)                          │   │
│  │                                                                             │   │
│  │  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │   │
│  │  │ Dense Vector │  │ Sparse BM25  │  │  Graph Query  │  │  Cross-Encoder│   │   │
│  │  │  (Qdrant)   │  │  (Qdrant)    │  │  (Neo4j)     │  │   Reranker   │   │   │
│  │  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘   │   │
│  │         └────────────────┴──────────────────┴─────────────────┘            │   │
│  │                              RRF / 加权融合                                 │   │
│  └────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                     │
│  ┌─────────────────────────────────────────────────────────────────────────────┐   │
│  │                          索引层 (Multi-Index)                               │   │
│  │                                                                             │   │
│  │  ┌───────────────┐  ┌──────────────────┐  ┌───────────────────────────┐   │   │
│  │  │  向量索引      │  │  知识图谱索引     │  │  RAPTOR 层次摘要树        │   │   │
│  │  │  Qdrant       │  │  Neo4j 5.x       │  │  (递归聚类→摘要→再嵌入)    │   │   │
│  │  │  Dense+Sparse │  │  Entity/Relation  │  │  Paper→Section→Paragraph  │   │   │
│  │  └───────┬───────┘  └────────┬─────────┘  └────────────┬──────────────┘   │   │
│  └──────────┼───────────────────┼──────────────────────────┼──────────────────┘   │
│             │                   │                          │                       │
│  ┌──────────▼───────────────────▼──────────────────────────▼──────────────────┐   │
│  │                      知识抽取层 (Knowledge Extraction)                      │   │
│  │                                                                             │   │
│  │  ┌──────────────────────┐  ┌────────────────────────────────────────┐      │   │
│  │  │  实体抽取 (NER)       │  │  关系抽取 (RE)                         │      │   │
│  │  │  GLiNER 440M         │  │  LLMGraphTransformer                   │      │   │
│  │  │  零样本, 自定义标签    │  │  + Graphusion 融合去重                  │      │   │
│  │  └──────────────────────┘  └────────────────────────────────────────┘      │   │
│  └────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                     │
│  ┌─────────────────────────────────────────────────────────────────────────────┐   │
│  │                      PDF 解析层 (MinerU Pipeline)                           │   │
│  │                                                                             │   │
│  │  ┌──────────┐  ┌───────────────────┐  ┌──────────┐  ┌─────────────────┐   │   │
│  │  │ PDF队列   │  │ MinerU 2.5 VLM   │  │ 格式转换  │  │   元数据提取     │   │   │
│  │  │ Celery   │─▶│ vLLM后端 2pg/s   │─▶│ JSON→MD  │─▶│ 标题/作者/DOI   │   │   │
│  │  │ +Redis   │  │ 布局+OCR+公式+表格 │  │ +结构化   │  │ +章节/引用      │   │   │
│  │  └──────────┘  └───────────────────┘  └──────────┘  └─────────────────┘   │   │
│  └────────────────────────────────────────────────────────────────────────────┘   │
│                                                                                     │
│  ┌─────────────────────────────────────────────────────────────────────────────┐   │
│  │                         存储层 (Storage)                                    │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │   │
│  │  │ PostgreSQL│  │  Qdrant  │  │  Neo4j   │  │  Redis   │  │ MinIO/S3 │   │   │
│  │  │ 元数据    │  │ 向量索引  │  │ 知识图谱  │  │ 缓存/队列 │  │ PDF存储  │   │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │   │
│  └────────────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

---

## 2. PDF 解析层

### 2.1 技术选型：MinerU 2.5 VLM

| 指标 | MinerU 2.5 | Marker | Nougat | PyMuPDF |
|------|-----------|--------|--------|---------|
| 学术论文文本精度(Edit Distance↓) | **0.047** | 0.080 | 0.365 | N/A(仅数字PDF) |
| 公式识别(CDM↑) | **88.46** | 17.6 | 15.1 | ❌ |
| 表格识别(TEDS↑) | **88.22** | 67.6 | 39.9 | ❌ |
| 吞吐(A100, pg/s) | **2.12** | ~5 | ~0.5 | ~100 |
| 扫描件支持 | ✅ | ⚠️ | ❌ | ❌ |

> **Benchmark 来源**: OmniDocBench (CVPR 2025, arxiv:2412.07626)

### 2.2 架构设计

```python
# 混合路由策略：数字PDF走PyMuPDF(快), 复杂PDF走MinerU 2.5(精)
class PDFRouter:
    """根据PDF特征智能选择解析引擎"""
    
    def route(self, pdf_path: str) -> str:
        import fitz
        doc = fitz.open(pdf_path)
        avg_chars = sum(len(p.get_text()) for p in doc) / len(doc)
        has_images = any(p.get_images() for p in doc)
        
        if avg_chars > 500 and not has_images:
            return "pymupdf_fast"      # 纯数字PDF，PyMuPDF秒级解析
        elif avg_chars > 200:
            return "mineru_pipeline"    # 数字PDF+图表，Pipeline模式(CPU)
        else:
            return "mineru_vlm"        # 扫描件/复杂布局，VLM模式(GPU)
```

### 2.3 批量处理流水线

```
                    ┌─────────────────────────────────────────┐
                    │           PDF 批量处理流水线               │
                    ├─────────────────────────────────────────┤
                    │                                         │
 ┌──────────┐      │  ┌──────────┐   ┌──────────────────┐   │   ┌──────────┐
 │ PDF 文件  │─────▶│  │ PDF路由器 │──▶│ Celery Worker池  │   │──▶│ 结构化   │
 │ 上传/批量 │      │  │ (特征检测) │   │                  │   │   │ JSON+MD  │
 └──────────┘      │  └──────────┘   │ W1: MinerU VLM   │   │   └──────────┘
                    │                 │ W2: MinerU VLM   │   │
 ┌──────────┐      │                 │ W3: Pipeline     │   │   ┌──────────┐
 │  Redis   │◀────▶│                 │ W4: PyMuPDF      │   │──▶│ 元数据   │
 │ 任务队列  │      │                 └──────────────────┘   │   │ 提取     │
 └──────────┘      │                                         │   └──────────┘
                    │  ┌──────────────────────────────────┐  │
                    │  │ 监控: 进度/失败重试/吞吐量统计     │  │
                    │  └──────────────────────────────────┘  │
                    └─────────────────────────────────────────┘

关键配置:
- MinerU VLM Worker: 每GPU一个进程, vLLM异步批处理
- gpu_memory_utilization: 0.7 (预留30%给OOM安全边际)
- max_num_batched_tokens: 16384 (提高GPU利用率)
- 失败重试: 最多3次, 指数退避
- 超时: 单PDF 300秒上限
```

### 2.4 输出数据模型

```python
from pydantic import BaseModel
from typing import List, Optional
from enum import Enum

class ContentType(str, Enum):
    TITLE = "title"
    TEXT = "text"
    TABLE = "table"
    EQUATION = "equation"
    EQUATION_BLOCK = "equation_block"
    IMAGE = "image"
    CODE = "code"
    LIST = "list"
    REFERENCE = "reference"

class ContentBlock(BaseModel):
    type: ContentType
    content: str             # Markdown/LaTeX/HTML
    page_idx: int
    bbox: List[float]        # [x0, y0, x1, y1]
    reading_order: int
    section_hierarchy: List[str]  # ["3", "3.1", "Methods"]

class PaperMetadata(BaseModel):
    paper_id: str
    title: str
    authors: List[str]
    abstract: str
    doi: Optional[str]
    year: Optional[int]
    venue: Optional[str]
    keywords: List[str]
    references: List[str]    # 引用的论文标题

class ParsedPaper(BaseModel):
    metadata: PaperMetadata
    content_blocks: List[ContentBlock]
    markdown: str
    page_count: int
    parse_engine: str        # "mineru_vlm" | "mineru_pipeline" | "pymupdf"
    parse_time_seconds: float
```

---

## 3. 知识抽取层

### 3.1 两阶段抽取策略

```
┌──────────────────────────────────────────────────────────────────┐
│                    知识抽取流水线                                  │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Stage 1: 快速实体抽取 (GLiNER, 本地, 440M参数)                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  输入: 论文文本块                                           │  │
│  │  模型: urchade/gliner_large-v2.1 (零样本NER)                │  │
│  │  标签: [Author, Method, Dataset, Metric, Task,             │  │
│  │         Model, Concept, Venue, Score, Tool]                │  │
│  │  输出: [(text, label, score, span), ...]                   │  │
│  │  速度: ~1000 chunks/min (CPU), ~5000 chunks/min (GPU)      │  │
│  └────────────────────────────────────────────────────────────┘  │
│                           │                                      │
│                           ▼                                      │
│  Stage 2: LLM关系抽取 (LLMGraphTransformer, 本地或API)           │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  输入: 文本块 + Stage1实体提示                               │  │
│  │  关系类型: [PROPOSED_BY, USED_FOR, EVALUATED_ON,           │  │
│  │     TRAINED_WITH, COMPARED_TO, PART_OF, ACHIEVED_SCORE,    │  │
│  │     HYPONYM_OF, CITED_BY, IMPROVES_ON]                     │  │
│  │  本地: Ollama(Qwen2.5-14B) 或 vLLM(Llama-3.1-8B)          │  │
│  │  API:  GPT-4o-mini 或 DeepSeek-V3                          │  │
│  │  输出: [(head, relation, tail, properties), ...]            │  │
│  └────────────────────────────────────────────────────────────┘  │
│                           │                                      │
│                           ▼                                      │
│  Stage 3: Graphusion 融合 (实体归一化 + 冲突消解)                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  - 嵌入相似度合并: "NMT" ↔ "neural machine translation"     │  │
│  │  - LLM冲突消解: 相同实体对的矛盾关系                         │  │
│  │  - 新三元组推断: 基于上下文补全缺失关系                       │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

### 3.2 学术论文实体-关系 Schema

```
实体类型 (Node Types):
┌─────────────┬────────────────────────────────┬──────────────────┐
│ 实体类型     │ 描述                           │ 属性              │
├─────────────┼────────────────────────────────┼──────────────────┤
│ Paper       │ 论文                            │ title, year, doi │
│ Author      │ 作者                            │ name, affiliation│
│ Method      │ 方法/算法                       │ name, description│
│ Dataset     │ 数据集                          │ name, size, domain│
│ Task        │ 任务                            │ name, domain     │
│ Metric      │ 评估指标                        │ name, value      │
│ Model       │ 具体模型实例                     │ name, params     │
│ Concept     │ 学术概念                        │ name, definition │
│ Tool        │ 工具/框架                       │ name, version    │
│ Venue       │ 发表场所                        │ name, type       │
└─────────────┴────────────────────────────────┴──────────────────┘

关系类型 (Edge Types):
┌─────────────────┬──────────────────────────────────────────────┐
│ 关系类型         │ 描述 (Head → Tail)                           │
├─────────────────┼──────────────────────────────────────────────┤
│ PROPOSED_BY     │ Method → Author (方法由作者提出)               │
│ PUBLISHED_IN    │ Paper → Venue (论文发表在某会议/期刊)          │
│ USED_FOR        │ Method → Task (方法用于某任务)                 │
│ EVALUATED_ON    │ Method → Dataset (方法在某数据集上评估)         │
│ ACHIEVED_SCORE  │ Method → Metric (方法达到某指标值)             │
│ TRAINED_WITH    │ Model → Dataset (模型在某数据集上训练)          │
│ COMPARED_TO     │ Method → Method (方法之间的对比)               │
│ IMPROVES_ON     │ Method → Method (方法A改进了方法B)             │
│ PART_OF         │ Concept → Concept (概念层级关系)               │
│ CITES           │ Paper → Paper (引用关系)                      │
│ AUTHORED_BY     │ Paper → Author (论文作者)                     │
│ HYPONYM_OF      │ Concept → Concept (上下位关系)                │
│ USES_TOOL       │ Method → Tool (方法使用某工具)                 │
└─────────────────┴──────────────────────────────────────────────┘
```

### 3.3 核心抽取代码

```python
from gliner import GLiNER
from langchain_experimental.graph_transformers import LLMGraphTransformer
from langchain_core.documents import Document

class KnowledgeExtractor:
    """两阶段知识抽取器"""
    
    def __init__(self, llm_backend: str = "local_ollama"):
        # Stage 1: 快速NER
        self.ner_model = GLiNER.from_pretrained("urchade/gliner_large-v2.1")
        self.entity_labels = [
            "author", "method", "dataset", "metric", 
            "task", "model", "concept", "tool", "venue", "score"
        ]
        
        # Stage 2: LLM关系抽取
        self.llm = self._init_llm(llm_backend)
        self.graph_transformer = LLMGraphTransformer(
            llm=self.llm,
            allowed_nodes=["Author","Method","Dataset","Metric","Task","Model","Concept","Tool","Venue"],
            allowed_relationships=[
                "PROPOSED_BY","USED_FOR","EVALUATED_ON","ACHIEVED_SCORE",
                "TRAINED_WITH","COMPARED_TO","IMPROVES_ON","PART_OF",
                "CITES","AUTHORED_BY","HYPONYM_OF","USES_TOOL","PUBLISHED_IN"
            ],
            node_properties=["description", "year"],
            relationship_properties=["score_value", "metric_name", "confidence"],
            strict_mode=True,
        )
    
    def _init_llm(self, backend: str):
        """统一LLM初始化 — 支持本地和外部API"""
        if backend == "local_ollama":
            from langchain_community.llms import Ollama
            return Ollama(model="qwen2.5:14b-instruct", temperature=0)
        elif backend == "local_vllm":
            from langchain_openai import ChatOpenAI
            return ChatOpenAI(
                base_url="http://localhost:8000/v1",
                api_key="token",
                model="meta-llama/Llama-3.1-8B-Instruct",
                temperature=0
            )
        elif backend == "openai":
            from langchain_openai import ChatOpenAI
            return ChatOpenAI(model="gpt-4o-mini", temperature=0)
        elif backend == "deepseek":
            from langchain_openai import ChatOpenAI
            return ChatOpenAI(
                base_url="https://api.deepseek.com/v1",
                model="deepseek-chat",
                temperature=0
            )
    
    async def extract(self, text: str, paper_id: str) -> dict:
        """两阶段抽取"""
        # Stage 1: GLiNER快速NER
        entities = self.ner_model.predict_entities(
            text, self.entity_labels, threshold=0.5
        )
        
        # Stage 2: LLM关系抽取 (传入实体作为提示)
        entity_hint = ", ".join([f"{e['text']}({e['label']})" for e in entities[:20]])
        doc = Document(
            page_content=text,
            metadata={"paper_id": paper_id, "entity_hints": entity_hint}
        )
        graph_docs = await self.graph_transformer.aconvert_to_graph_documents([doc])
        
        return {
            "entities": entities,
            "graph_documents": graph_docs,
            "paper_id": paper_id
        }
```

---

## 4. 知识图谱层

### 4.1 图数据库选型：Neo4j 5.x

| 图数据库 | 许可证 | 查询语言 | Python驱动 | 生态集成 | 适用规模 |
|---------|--------|---------|-----------|---------|---------|
| **Neo4j 5.x** | Community AGPL | Cypher | `neo4j` | LangChain/LlamaIndex原生 | <1亿节点 |
| ArangoDB | Apache 2.0 | AQL | `python-arango` | 多模型(文档+图) | <1亿节点 |
| NebulaGraph | Apache 2.0 | nGQL | `nebula3-python` | LlamaIndex原生 | 10亿+节点 |
| Kuzu | MIT | Cypher | `kuzu` | 嵌入式, 轻量 | <1000万节点 |

> **推荐 Neo4j 5.x**：LangChain/LlamaIndex 原生集成最完善，Cypher 查询生态最成熟，适合1000篇论文规模

### 4.2 图谱数据模型

```cypher
// ===== 节点 =====
(:Paper {id, title, year, doi, venue, abstract, embedding})
(:Author {id, name, affiliation, h_index})
(:Method {id, name, description, year_proposed, embedding})
(:Dataset {id, name, domain, size, description})
(:Task {id, name, domain, description})
(:Metric {id, name, description})
(:Concept {id, name, definition, embedding})

// ===== 关系 =====
(:Paper)-[:AUTHORED_BY {order}]->(:Author)
(:Paper)-[:PUBLISHED_IN {year}]->(:Venue)
(:Paper)-[:CITES]->(:Paper)
(:Paper)-[:PROPOSES]->(:Method)
(:Method)-[:USED_FOR]->(:Task)
(:Method)-[:EVALUATED_ON {score, metric}]->(:Dataset)
(:Method)-[:IMPROVES_ON {delta, metric}]->(:Method)
(:Method)-[:COMPARED_TO {result}]->(:Method)
(:Concept)-[:PART_OF]->(:Concept)
(:Concept)-[:HYPONYM_OF]->(:Concept)

// ===== 索引 =====
CREATE VECTOR INDEX paper_embedding FOR (p:Paper) ON (p.embedding)
  OPTIONS {indexConfig: {`vector.dimensions`: 1536, `vector.similarity_function`: 'cosine'}};
CREATE VECTOR INDEX method_embedding FOR (m:Method) ON (m.embedding)
  OPTIONS {indexConfig: {`vector.dimensions`: 1536, `vector.similarity_function`: 'cosine'}};
CREATE FULLTEXT INDEX paper_fulltext FOR (p:Paper) ON EACH [p.title, p.abstract];
```

### 4.3 图谱构建流水线

```
解析后的论文 ──▶ 知识抽取 ──▶ 三元组规范化 ──▶ Neo4j 写入
                                    │
                        ┌───────────┴───────────┐
                        │   Graphusion 融合引擎   │
                        ├─────────────────────────┤
                        │ 1. 实体归一化            │
                        │    - 嵌入相似度 > 0.92   │
                        │    - LLM确认合并          │
                        │    "BERT" = "bert model" │
                        │                         │
                        │ 2. 关系冲突消解           │
                        │    - 同一实体对多关系      │
                        │    - 取置信度最高的        │
                        │                         │
                        │ 3. 缺失关系推断           │
                        │    - 基于图结构模式        │
                        │    - LLM补全              │
                        └─────────────────────────┘
```

### 4.4 图谱可视化方案

```python
# 方案1: Neo4j Browser (开发阶段)
# 内置Cypher查询 + 交互式图可视化

# 方案2: vis-network (前端集成)
# pip install pyvis
from pyvis.network import Network

def visualize_subgraph(nodes, edges, output_path="graph.html"):
    net = Network(height="800px", width="100%", directed=True)
    color_map = {
        "Method": "#ff6b6b", "Dataset": "#4ecdc4", 
        "Task": "#45b7d1", "Author": "#96ceb4",
        "Paper": "#ffeaa7", "Concept": "#dfe6e9"
    }
    for node in nodes:
        net.add_node(node["id"], label=node["name"], 
                     color=color_map.get(node["type"], "#95a5a6"))
    for edge in edges:
        net.add_edge(edge["from"], edge["to"], label=edge["type"])
    net.show(output_path)

# 方案3: React + D3-force (生产前端)
# 推荐 react-force-graph 或 neo4j-viz
```

---

## 5. 索引层

### 5.1 三路索引架构

```
                  解析后的论文内容
                        │
            ┌───────────┼───────────┐
            ▼           ▼           ▼
     ┌──────────┐ ┌──────────┐ ┌──────────┐
     │ 向量索引  │ │ 图谱索引  │ │ RAPTOR树 │
     │          │ │          │ │          │
     │ Qdrant   │ │ Neo4j    │ │ 层次摘要  │
     │ Dense +  │ │ Cypher + │ │ 递归聚类  │
     │ Sparse   │ │ Vector   │ │ → 摘要    │
     │          │ │ Index    │ │ → 再嵌入  │
     └──────────┘ └──────────┘ └──────────┘
     
     适合:         适合:         适合:
     事实查询      多跳推理      全局概览
     精确检索      关系追溯      主题总结
     相似论文      对比分析      趋势分析
```

### 5.2 文档分块策略

```python
class AcademicChunker:
    """学术论文专用分块器 — 保留章节层级"""
    
    def __init__(self, chunk_size: int = 256, overlap: int = 50):
        self.chunk_size = chunk_size  # 256 tokens (实验验证最佳, arxiv:2502.11371)
        self.overlap = overlap
    
    def chunk(self, parsed_paper: ParsedPaper) -> list:
        chunks = []
        
        for block in parsed_paper.content_blocks:
            if block.type == ContentType.TABLE:
                # 表格作为完整chunk, 附加描述
                chunks.append({
                    "text": f"[TABLE] {block.content}",
                    "metadata": {
                        "paper_id": parsed_paper.metadata.paper_id,
                        "type": "table",
                        "section": block.section_hierarchy,
                        "page": block.page_idx,
                    }
                })
            elif block.type == ContentType.EQUATION_BLOCK:
                # 公式块 + 上下文
                chunks.append({
                    "text": f"[EQUATION] {block.content}",
                    "metadata": {
                        "paper_id": parsed_paper.metadata.paper_id,
                        "type": "equation",
                        "section": block.section_hierarchy,
                    }
                })
            else:
                # 普通文本: 固定大小分块, 按句子边界对齐
                text_chunks = self._split_text(block.content)
                for tc in text_chunks:
                    chunks.append({
                        "text": tc,
                        "metadata": {
                            "paper_id": parsed_paper.metadata.paper_id,
                            "type": block.type.value,
                            "section": block.section_hierarchy,
                            "page": block.page_idx,
                        }
                    })
        
        return chunks
    
    def _split_text(self, text: str) -> list:
        """按句子边界分块, 保持256 token大小"""
        import re
        sentences = re.split(r'(?<=[.!?])\s+', text)
        chunks, current = [], []
        current_len = 0
        
        for sent in sentences:
            sent_len = len(sent.split())  # 简化的token计数
            if current_len + sent_len > self.chunk_size and current:
                chunks.append(" ".join(current))
                # 保留overlap
                overlap_sents = []
                overlap_len = 0
                for s in reversed(current):
                    if overlap_len + len(s.split()) > self.overlap:
                        break
                    overlap_sents.insert(0, s)
                    overlap_len += len(s.split())
                current = overlap_sents
                current_len = overlap_len
            current.append(sent)
            current_len += sent_len
        
        if current:
            chunks.append(" ".join(current))
        return chunks
```

### 5.3 RAPTOR 层次摘要树

```
论文集合 (1000篇)
    │
    ├── Level 0: 原始文本块 (256 tokens)
    │       │
    │       ▼ SBERT嵌入 → GMM聚类 → UMAP降维
    │
    ├── Level 1: 段落级摘要 (~50个聚类)
    │       │ LLM生成摘要 → 重新嵌入
    │       ▼ 再次聚类
    │
    ├── Level 2: 主题级摘要 (~15个聚类)
    │       │ "Transformer架构的改进方向"
    │       ▼ "大规模预训练数据集综述"
    │
    └── Level 3: 领域级摘要 (~5个聚类)
            "NLP领域近年主要研究方向与突破"

查询时: 从所有层级中检索最相关节点 (Collapsed Tree模式)
优势: 既能回答细节问题(Level 0), 也能回答全局问题(Level 2-3)
```

---

## 6. 检索层

### 6.1 混合检索架构

```
                     用户查询
                        │
                ┌───────┴───────┐
                ▼               ▼
         ┌──────────┐   ┌──────────────┐
         │  HyDE    │   │ 查询分类器    │
         │ 假设文档  │   │ (Router LLM) │
         │ 生成+嵌入 │   │              │
         └────┬─────┘   └──────┬───────┘
              │                │
              │    ┌───────────┼───────────┐
              │    ▼           ▼           ▼
              │  factual    reasoning    global
              │  (事实)     (推理)      (全局)
              │    │           │           │
              ▼    ▼           ▼           ▼
         ┌──────────┐  ┌──────────┐  ┌──────────┐
         │ 向量+BM25 │  │ 图谱遍历  │  │ RAPTOR   │
         │ Qdrant   │  │ Neo4j    │  │ 摘要树    │
         │ Hybrid   │  │ Cypher   │  │ 全局检索  │
         └────┬─────┘  └────┬─────┘  └────┬─────┘
              │             │              │
              └─────────────┴──────────────┘
                            │
                    ┌───────▼───────┐
                    │  RRF 融合排序   │
                    │ (Reciprocal   │
                    │  Rank Fusion) │
                    └───────┬───────┘
                            │
                    ┌───────▼───────┐
                    │ Cross-Encoder │
                    │   Reranker   │
                    │ bge-reranker │
                    │   -large     │
                    └───────┬───────┘
                            │
                        Top-5 结果
                            │
                    ┌───────▼───────┐
                    │  LLM 答案生成  │
                    │ + 引用溯源     │
                    └───────────────┘
```

### 6.2 核心检索代码

```python
from qdrant_client import QdrantClient, models
from neo4j import GraphDatabase

class HybridRetriever:
    """三路混合检索器"""
    
    def __init__(self):
        self.qdrant = QdrantClient("localhost", port=6333)
        self.neo4j = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))
        self.reranker = self._load_reranker()
        self.embed_model = self._load_embedder()
    
    async def retrieve(self, query: str, mode: str = "hybrid", top_k: int = 20) -> list:
        """
        mode: "factual" | "reasoning" | "global" | "hybrid"
        """
        results = []
        
        if mode in ("factual", "hybrid"):
            # 1. Dense + Sparse 向量检索
            query_vec = self.embed_model.encode(query)
            vec_results = self.qdrant.search(
                collection_name="papers",
                query_vector=models.NamedVector(name="dense", vector=query_vec),
                limit=top_k,
                with_payload=True,
            )
            results.extend([{"text": r.payload["text"], "score": r.score, 
                           "source": "vector", "metadata": r.payload} for r in vec_results])
        
        if mode in ("reasoning", "hybrid"):
            # 2. 图谱检索 — 实体+关系路径
            graph_results = self._graph_search(query, limit=top_k // 2)
            results.extend(graph_results)
        
        if mode in ("global", "hybrid"):
            # 3. RAPTOR 层次摘要检索
            raptor_results = self._raptor_search(query, limit=top_k // 3)
            results.extend(raptor_results)
        
        # 4. RRF 融合排序
        fused = self._rrf_fusion(results)
        
        # 5. Cross-Encoder 重排
        reranked = self._rerank(query, fused[:top_k])
        
        return reranked[:5]
    
    def _graph_search(self, query: str, limit: int = 10) -> list:
        """Neo4j 子图检索"""
        # 先用向量索引找到最相关的实体节点
        # 再用Cypher遍历1-2跳邻居
        cypher = """
        CALL db.index.vector.queryNodes('method_embedding', $limit, $query_vec)
        YIELD node, score
        MATCH (node)-[r]-(neighbor)
        RETURN node, r, neighbor, score
        ORDER BY score DESC LIMIT $limit
        """
        with self.neo4j.session() as session:
            result = session.run(cypher, query_vec=self.embed_model.encode(query).tolist(), limit=limit)
            return [{"text": self._format_graph_result(r), "score": r["score"], 
                     "source": "graph"} for r in result]
    
    def _rrf_fusion(self, results: list, k: int = 60) -> list:
        """Reciprocal Rank Fusion — 多路结果融合"""
        doc_scores = {}
        for rank, r in enumerate(sorted(results, key=lambda x: x["score"], reverse=True)):
            doc_key = r["text"][:200]  # 去重key
            if doc_key not in doc_scores:
                doc_scores[doc_key] = {"result": r, "rrf_score": 0}
            doc_scores[doc_key]["rrf_score"] += 1.0 / (k + rank + 1)
        
        return [v["result"] | {"score": v["rrf_score"]} 
                for v in sorted(doc_scores.values(), key=lambda x: x["rrf_score"], reverse=True)]
    
    def _rerank(self, query: str, results: list) -> list:
        """BAAI/bge-reranker-large 交叉编码器重排"""
        pairs = [(query, r["text"]) for r in results]
        scores = self.reranker.predict(pairs)
        for r, s in zip(results, scores):
            r["rerank_score"] = float(s)
        return sorted(results, key=lambda x: x["rerank_score"], reverse=True)
```

---

## 7. Agent 编排层

### 7.1 LangGraph 多Agent架构

```
                        ┌──────────────┐
                        │   用户查询    │
                        └──────┬───────┘
                               │
                        ┌──────▼───────┐
                        │  路由 Agent   │
                        │  (意图分类)   │
                        └──────┬───────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
       ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
       │ 简单问答     │ │ 多跳推理     │ │ 全局分析     │
       │             │ │             │ │             │
       │ 向量检索    │ │ 图谱遍历    │ │ RAPTOR+KG  │
       │ → 生成答案  │ │ → 链式推理  │ │ → 综合总结  │
       │ → 引用溯源  │ │ → 证据收集  │ │ → 趋势洞察  │
       └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
              │                │                │
              └────────────────┼────────────────┘
                               │
                        ┌──────▼───────┐
                        │  自检 Agent   │
                        │ (答案验证)    │
                        │ 是否充分?     │
                        │ 是否有幻觉?   │
                        └──────┬───────┘
                               │
                   ┌───────────┼───────────┐
                   │ 充分       │ 不充分     │
                   ▼           ▼           │
            ┌──────────┐ ┌──────────┐     │
            │ 输出答案  │ │ 补充检索  │─────┘
            │ + 引用   │ │ (更多源)  │ (最多3轮)
            │ + 图谱   │ └──────────┘
            └──────────┘
```

### 7.2 LangGraph 状态机定义

```python
from typing import TypedDict, Annotated, Literal
from langgraph.graph import StateGraph, END
from langgraph.graph.message import add_messages

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]
    query: str
    query_type: Literal["factual", "reasoning", "global"]
    retrieved_docs: list
    graph_context: list
    answer: str
    citations: list
    confidence: float
    iteration: int

def build_agent_graph():
    graph = StateGraph(AgentState)
    
    # 添加节点
    graph.add_node("router", route_query)
    graph.add_node("retriever", hybrid_retrieve)
    graph.add_node("graph_explorer", explore_knowledge_graph)
    graph.add_node("generator", generate_answer)
    graph.add_node("validator", validate_answer)
    graph.add_node("supplementer", supplement_retrieval)
    
    # 定义边
    graph.set_entry_point("router")
    graph.add_edge("router", "retriever")
    graph.add_edge("retriever", "graph_explorer")
    graph.add_edge("graph_explorer", "generator")
    graph.add_edge("generator", "validator")
    
    # 条件边: 验证通过→结束, 不通过→补充检索(最多3轮)
    graph.add_conditional_edges(
        "validator",
        lambda state: "end" if state["confidence"] > 0.8 or state["iteration"] >= 3 else "supplement",
        {"end": END, "supplement": "supplementer"}
    )
    graph.add_edge("supplementer", "retriever")
    
    return graph.compile()

async def route_query(state: AgentState) -> AgentState:
    """LLM意图分类"""
    classification_prompt = f"""
    将以下学术问题分类为三种类型之一:
    - factual: 具体事实查询 (某个方法的效果、某篇论文的作者)
    - reasoning: 需要多步推理 (方法A和B的区别、某技术的发展脉络)
    - global: 全局性分析 (某领域的研究趋势、主要挑战)
    
    问题: {state['query']}
    类型: """
    
    query_type = await llm.ainvoke(classification_prompt)
    return {"query_type": query_type.content.strip()}

async def validate_answer(state: AgentState) -> AgentState:
    """Self-RAG 模式: LLM自检答案质量"""
    validation_prompt = f"""
    评估以下答案的质量(0-1分):
    问题: {state['query']}
    答案: {state['answer']}
    检索依据: {state['retrieved_docs'][:3]}
    
    评分标准:
    - 是否完整回答了问题
    - 是否有依据支撑
    - 是否存在幻觉
    
    返回JSON: {{"confidence": 0.X, "issues": ["..."]}}
    """
    result = await llm.ainvoke(validation_prompt)
    confidence = parse_confidence(result.content)
    return {"confidence": confidence, "iteration": state["iteration"] + 1}
```

### 7.3 Agent 工具集

```python
from langchain.tools import tool

@tool
def vector_search(query: str, top_k: int = 5) -> str:
    """在论文向量库中进行语义搜索"""
    results = retriever.search_vectors(query, top_k)
    return format_search_results(results)

@tool
def graph_query(cypher: str) -> str:
    """执行Cypher查询, 在知识图谱中检索实体和关系"""
    with neo4j_driver.session() as session:
        result = session.run(cypher)
        return format_graph_results(result)

@tool
def find_related_methods(method_name: str) -> str:
    """查找与指定方法相关的所有方法(改进、对比、使用)"""
    cypher = """
    MATCH (m:Method {name: $name})-[r]-(related)
    RETURN type(r) as relation, labels(related) as type, 
           related.name as name, r.score_value as score
    ORDER BY r.score_value DESC
    LIMIT 20
    """
    return execute_and_format(cypher, {"name": method_name})

@tool  
def get_paper_summary(paper_id: str) -> str:
    """获取论文的摘要和核心贡献"""
    return paper_store.get_summary(paper_id)

@tool
def compare_methods(method_a: str, method_b: str) -> str:
    """对比两个方法在相同数据集上的表现"""
    cypher = """
    MATCH (a:Method {name: $a})-[r1:EVALUATED_ON]->(d:Dataset)<-[r2:EVALUATED_ON]-(b:Method {name: $b})
    RETURN d.name as dataset, r1.score as score_a, r2.score as score_b, 
           r1.metric as metric
    """
    return execute_and_format(cypher, {"a": method_a, "b": method_b})

@tool
def research_trend(topic: str, years: int = 5) -> str:
    """分析某个研究主题在近N年的发展趋势"""
    raptor_results = raptor_index.search(topic, level="high")
    graph_stats = get_temporal_graph_stats(topic, years)
    return synthesize_trend(raptor_results, graph_stats)
```

---

## 8. LLM 统一接入层

### 8.1 架构设计

```
                    ┌──────────────────────────────────┐
                    │      LiteLLM Proxy Server         │
                    │      (统一 OpenAI 兼容接口)        │
                    ├──────────────────────────────────┤
                    │                                  │
                    │  model_list:                     │
                    │  ┌────────────────────────────┐  │
                    │  │ "local/qwen2.5-14b"        │──│──▶ Ollama :11434
                    │  │ "local/llama-3.1-8b"       │──│──▶ vLLM   :8000
                    │  │ "gpt-4o-mini"              │──│──▶ OpenAI API
                    │  │ "claude-3-5-sonnet"        │──│──▶ Anthropic API
                    │  │ "deepseek-chat"            │──│──▶ DeepSeek API
                    │  │ "gemini-2.0-flash"         │──│──▶ Google API
                    │  └────────────────────────────┘  │
                    │                                  │
                    │  功能:                            │
                    │  - 统一 /chat/completions 接口     │
                    │  - 自动fallback (本地→API)         │
                    │  - 负载均衡 (多vLLM实例)            │
                    │  - 速率限制 & 成本追踪              │
                    │  - 缓存 (相同query复用)             │
                    └──────────────────────────────────┘
```

### 8.2 LiteLLM 配置

```yaml
# litellm_config.yaml
model_list:
  # ===== 本地模型 =====
  - model_name: "local/qwen2.5-14b"
    litellm_params:
      model: "openai/Qwen2.5-14B-Instruct"
      api_base: "http://localhost:11434/v1"  # Ollama
      api_key: "ollama"
    model_info:
      max_tokens: 32768
      input_cost_per_token: 0  # 本地免费
      
  - model_name: "local/llama-3.1-8b"
    litellm_params:
      model: "openai/meta-llama/Llama-3.1-8B-Instruct"
      api_base: "http://localhost:8000/v1"  # vLLM
      api_key: "token"
    model_info:
      max_tokens: 131072

  # ===== 外部API =====
  - model_name: "gpt-4o-mini"
    litellm_params:
      model: "gpt-4o-mini"
      api_key: "os.environ/OPENAI_API_KEY"
      
  - model_name: "deepseek-chat"
    litellm_params:
      model: "deepseek/deepseek-chat"
      api_key: "os.environ/DEEPSEEK_API_KEY"

# 路由策略
router_settings:
  routing_strategy: "latency-based-routing"  # 选择延迟最低的
  num_retries: 3
  fallbacks:
    - "local/qwen2.5-14b": ["gpt-4o-mini"]  # 本地失败→API
    - "gpt-4o-mini": ["deepseek-chat"]       # OpenAI失败→DeepSeek
  
  # 不同任务用不同模型
  model_group_alias:
    "extraction": "local/qwen2.5-14b"      # 知识抽取: 本地(省钱)
    "generation": "gpt-4o-mini"             # 答案生成: API(高质量)
    "routing": "local/llama-3.1-8b"         # 意图分类: 本地小模型(快)
```

### 8.3 统一调用接口

```python
import litellm
from typing import Optional

class UnifiedLLM:
    """统一LLM调用层 — 自动路由本地/API"""
    
    def __init__(self, config_path: str = "litellm_config.yaml"):
        litellm.set_verbose = False
        # 启用缓存
        litellm.cache = litellm.Cache(type="redis", host="localhost", port=6379)
    
    async def complete(
        self, 
        messages: list,
        task: str = "generation",     # extraction | generation | routing
        temperature: float = 0,
        max_tokens: int = 4096,
        stream: bool = False,
    ) -> str:
        """
        统一调用接口, 根据task自动选择模型
        """
        model = self._select_model(task)
        
        response = await litellm.acompletion(
            model=model,
            messages=messages,
            temperature=temperature,
            max_tokens=max_tokens,
            stream=stream,
            metadata={"task": task},  # 用于成本追踪
        )
        
        if stream:
            return response  # 返回异步生成器
        return response.choices[0].message.content
    
    def _select_model(self, task: str) -> str:
        model_map = {
            "extraction": "local/qwen2.5-14b",
            "generation": "gpt-4o-mini",
            "routing": "local/llama-3.1-8b",
            "fusion": "gpt-4o-mini",        # Graphusion融合需要强模型
            "rewrite": "local/llama-3.1-8b", # HyDE查询改写
        }
        return model_map.get(task, "local/qwen2.5-14b")
```

---

## 9. 系统部署架构

### 9.1 Docker Compose 部署

```yaml
# docker-compose.yml
version: '3.8'

services:
  # ===== 核心服务 =====
  api:
    build: ./services/api
    ports: ["8080:8080"]
    environment:
      - REDIS_URL=redis://redis:6379
      - QDRANT_URL=http://qdrant:6333
      - NEO4J_URL=bolt://neo4j:7687
      - LITELLM_URL=http://litellm:4000
    depends_on: [redis, qdrant, neo4j, litellm]

  # ===== PDF解析服务 =====
  mineru-worker:
    build: ./services/mineru
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    environment:
      - MINERU_MODEL_SOURCE=local
      - CELERY_BROKER_URL=redis://redis:6379
    volumes:
      - mineru-models:/models
      - pdf-storage:/pdfs

  # ===== LLM服务 =====
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    ports: ["4000:4000"]
    volumes:
      - ./config/litellm_config.yaml:/app/config.yaml
    command: ["--config", "/app/config.yaml"]

  ollama:
    image: ollama/ollama:latest
    ports: ["11434:11434"]
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    volumes:
      - ollama-data:/root/.ollama

  # ===== 存储服务 =====
  qdrant:
    image: qdrant/qdrant:latest
    ports: ["6333:6333"]
    volumes:
      - qdrant-data:/qdrant/storage

  neo4j:
    image: neo4j:5-community
    ports: ["7474:7474", "7687:7687"]
    environment:
      - NEO4J_AUTH=neo4j/password
      - NEO4J_PLUGINS=["apoc", "graph-data-science"]
    volumes:
      - neo4j-data:/data

  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]

  postgres:
    image: postgres:16-alpine
    environment:
      - POSTGRES_DB=scholarmind
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres-data:/var/lib/postgresql/data

  minio:
    image: minio/minio:latest
    ports: ["9000:9000", "9001:9001"]
    command: server /data --console-address ":9001"
    volumes:
      - minio-data:/data

volumes:
  qdrant-data:
  neo4j-data:
  postgres-data:
  minio-data:
  ollama-data:
  mineru-models:
  pdf-storage:
```

### 9.2 硬件配置建议

```
┌──────────────────────────────────────────────────────────────┐
│                    硬件配置建议                                │
├────────────────┬────────────┬────────────┬──────────────────┤
│ 配置           │ 开发环境    │ 生产(小)    │ 生产(大)         │
├────────────────┼────────────┼────────────┼──────────────────┤
│ PDF解析 GPU    │ RTX 3090   │ A100 80G   │ 2×A100 80G      │
│ LLM推理 GPU    │ RTX 4090   │ A100 80G   │ 2×H100 80G      │
│ CPU            │ 16核       │ 32核       │ 64核             │
│ RAM            │ 64GB       │ 128GB      │ 256GB            │
│ SSD            │ 1TB NVMe   │ 2TB NVMe   │ 4TB NVMe        │
├────────────────┼────────────┼────────────┼──────────────────┤
│ 1000篇论文     │ ~3小时     │ ~80分钟    │ ~40分钟          │
│ 解析时间       │            │            │                  │
│ QA响应延迟     │ ~5s        │ ~2s        │ ~1s              │
│ 并发用户       │ 1-5        │ 10-50      │ 50-200           │
└────────────────┴────────────┴────────────┴──────────────────┘
```

### 9.3 API 设计

```python
from fastapi import FastAPI, UploadFile, BackgroundTasks
from fastapi.responses import StreamingResponse
from pydantic import BaseModel

app = FastAPI(title="ScholarMind API", version="1.0")

# ===== PDF上传与解析 =====
@app.post("/api/v1/papers/upload")
async def upload_papers(files: list[UploadFile], bg: BackgroundTasks):
    """批量上传PDF论文, 异步解析"""
    task_ids = []
    for f in files:
        task_id = await save_and_queue(f)
        task_ids.append(task_id)
    return {"task_ids": task_ids, "status": "processing"}

@app.get("/api/v1/papers/{task_id}/status")
async def get_parse_status(task_id: str):
    """查询解析进度"""
    return celery_app.AsyncResult(task_id).info

# ===== 知识库问答 =====
class QueryRequest(BaseModel):
    query: str
    mode: str = "hybrid"           # factual | reasoning | global | hybrid
    llm_backend: str = "auto"      # auto | local | openai | deepseek
    top_k: int = 5
    stream: bool = False
    include_citations: bool = True
    include_graph: bool = False     # 是否返回相关子图

@app.post("/api/v1/query")
async def query_knowledge_base(req: QueryRequest):
    """知识库问答"""
    if req.stream:
        return StreamingResponse(
            agent.astream(req), media_type="text/event-stream"
        )
    result = await agent.ainvoke(req)
    return {
        "answer": result["answer"],
        "citations": result["citations"],
        "confidence": result["confidence"],
        "graph_snippet": result.get("graph_snippet"),
    }

# ===== 知识图谱 =====
@app.get("/api/v1/graph/entity/{name}")
async def get_entity(name: str, depth: int = 2):
    """获取实体及其N跳子图"""
    subgraph = await graph_service.get_subgraph(name, depth)
    return subgraph

@app.get("/api/v1/graph/path")
async def find_path(source: str, target: str, max_hops: int = 4):
    """查找两个实体之间的最短路径"""
    path = await graph_service.shortest_path(source, target, max_hops)
    return path

@app.get("/api/v1/graph/stats")
async def graph_statistics():
    """知识图谱统计信息"""
    return await graph_service.get_stats()

# ===== 图谱可视化 =====
@app.get("/api/v1/graph/visualize")
async def visualize_graph(center: str, depth: int = 2, layout: str = "force"):
    """返回可视化数据 (vis.js格式)"""
    data = await graph_service.get_vis_data(center, depth)
    return {"nodes": data["nodes"], "edges": data["edges"]}
```

---

## 10. 技术选型对比

### 10.1 完整技术栈

| 层 | 组件 | 选型 | 替代方案 | 选型理由 |
|----|------|------|---------|---------|
| PDF解析 | OCR引擎 | **MinerU 2.5 VLM** | Marker, Nougat, Docling | 学术论文SOTA(0.047 Edit Dist), 公式88.46 CDM |
| PDF解析 | 快速路径 | **PyMuPDF** | pdfplumber | 数字PDF秒级解析, 无GPU需求 |
| 知识抽取 | NER | **GLiNER** (440M) | spaCy, DeepKE | 零样本, 自定义标签, 本地运行 |
| 知识抽取 | RE | **LLMGraphTransformer** | REBEL, GLiREL, ReLiK | 支持本地+API LLM, Schema约束 |
| 知识抽取 | 融合 | **Graphusion** | 无 | 实体归一化+冲突消解, 比naive好9.2% |
| 知识图谱 | 图数据库 | **Neo4j 5.x** | ArangoDB, NebulaGraph | LangChain原生集成, Cypher生态最成熟 |
| 向量索引 | 向量库 | **Qdrant** | Milvus, Weaviate | Rust高性能, 原生Hybrid搜索, 简单部署 |
| 检索 | 重排器 | **bge-reranker-large** | Cohere, jina | 开源SOTA, 无API依赖 |
| 检索 | 查询增强 | **HyDE** | Query2Doc | +10 NDCG零成本提升 |
| 索引 | 层次索引 | **RAPTOR** | GraphRAG Communities | 适合层级文档, +20%准确率 |
| RAG | 图增强 | **LightRAG** | NodeRAG, GraphRAG | 34k⭐, 增量更新, 多后端 |
| Agent | 编排 | **LangGraph** | smolagents, AutoGen | 有状态图, 条件分支, 生产级 |
| LLM | 统一接入 | **LiteLLM** | OpenRouter | 20k⭐, 所有提供商统一接口 |
| LLM | 本地推理 | **vLLM + Ollama** | SGLang, llama.cpp | vLLM高吞吐, Ollama易用 |
| 后端 | Web框架 | **FastAPI** | Flask, Django | 异步原生, 高性能, OpenAPI自动文档 |
| 队列 | 任务队列 | **Celery + Redis** | RQ, Dramatiq | 成熟稳定, 分布式支持 |
| 存储 | 对象存储 | **MinIO** | S3 | S3兼容, 本地部署 |
| 存储 | 关系数据库 | **PostgreSQL** | MySQL | JSON支持, 全文搜索 |
| 前端 | 图可视化 | **react-force-graph** | vis.js, D3 | React生态, 3D支持 |

### 10.2 性能预估

```
┌───────────────────────────────────────────────────────────────┐
│              1000篇论文系统性能预估 (A100 80G)                  │
├──────────────────────┬────────────────────────────────────────┤
│ PDF解析              │ ~80分钟 (MinerU 2.5, 2.12 pg/s)        │
│ 知识抽取(GLiNER NER) │ ~15分钟 (GPU batch)                    │
│ 知识抽取(LLM RE)     │ ~60分钟 (本地14B模型)                   │
│                      │ ~30分钟 (GPT-4o-mini API)               │
│ 向量索引构建          │ ~10分钟 (text-embedding-3-small)        │
│ 知识图谱构建          │ ~20分钟 (含融合)                        │
│ RAPTOR树构建          │ ~30分钟                                 │
├──────────────────────┼────────────────────────────────────────┤
│ 总计(端到端)         │ ~3.5小时 (全本地) / ~2.5小时 (混合API)   │
├──────────────────────┼────────────────────────────────────────┤
│ QA响应延迟 (P50)     │ ~1.5s (本地LLM) / ~0.8s (API)          │
│ QA响应延迟 (P99)     │ ~4s (本地LLM) / ~2s (API)              │
│ 图谱查询延迟          │ ~200ms (2跳子图)                       │
│ 向量检索延迟          │ ~50ms (Qdrant, 1M向量)                  │
└──────────────────────┴────────────────────────────────────────┘
```

---

## 11. 关键论文与开源项目

### 11.1 核心论文

| 论文 | ArXiv ID | 贡献 | 推荐度 |
|------|---------|------|--------|
| **MinerU 2.5** | 2509.22186 | 统一VLM文档解析SOTA | ⭐⭐⭐⭐⭐ |
| **OmniDocBench** | 2412.07626 | 文档解析基准 (CVPR 2025) | ⭐⭐⭐⭐ |
| **Graphusion** | 2410.17600 | 零样本KG构建+融合 | ⭐⭐⭐⭐⭐ |
| **GLiNER** | 2311.08526 | 零样本NER, 440M | ⭐⭐⭐⭐⭐ |
| **SciER** | 2410.21155 | 学术论文IE数据集+基准 | ⭐⭐⭐⭐ |
| **ReLiK** | 2408.00103 | 快速实体链接+关系抽取 | ⭐⭐⭐⭐ |
| **NodeRAG** | 2504.11544 | 异构图RAG SOTA | ⭐⭐⭐⭐⭐ |
| **LightRAG** | 2410.05779 | 轻量图RAG, 增量更新 | ⭐⭐⭐⭐⭐ |
| **Microsoft GraphRAG** | 2404.16130 | 社区摘要+全局检索 | ⭐⭐⭐⭐ |
| **RAPTOR** | 2401.18059 | 递归摘要树 | ⭐⭐⭐⭐ |
| **Self-RAG** | 2310.11511 | 自反思检索生成 | ⭐⭐⭐ |
| **HyDE** | 2212.10496 | 假设文档嵌入 | ⭐⭐⭐⭐ |
| **RAG vs GraphRAG** | 2502.11371 | RAG+GraphRAG融合实验 | ⭐⭐⭐⭐ |
| **LLM-KGC Survey** | 2510.20345 | LLM知识图谱构建综述 | ⭐⭐⭐⭐ |

### 11.2 核心开源项目

| 项目 | GitHub | Stars | 用途 |
|------|--------|-------|------|
| **MinerU** | opendatalab/MinerU | 61k+ | PDF深度解析 |
| **LightRAG** | hkuds/lightrag | 34k+ | 图增强RAG |
| **RAGFlow** | infiniflow/ragflow | 36k+ | 全栈RAG平台(含UI) |
| **LiteLLM** | BerriAI/litellm | 20k+ | LLM统一代理 |
| **Neo4j LLM Graph Builder** | neo4j-labs/llm-graph-builder | 3k+ | PDF→KG→QA |
| **Kotaemon** | Cinnamon/kotaemon | 18k+ | 文档QA(含GraphRAG) |
| **Dify** | langgenius/dify | 70k+ | AI应用开发平台 |
| **LangGraph** | langchain-ai/langgraph | 10k+ | Agent状态机编排 |
| **GLiNER** | urchade/GLiNER | 2k+ | 零样本NER |
| **Graphusion** | irenezihuili/graphusion | 27 | KG融合去重 |
| **RAPTOR** | parthsarthi03/raptor | 1.6k+ | 层次摘要树 |
| **NodeRAG** | Terry-Xu-666/NodeRAG | 412 | 异构图RAG |
| **Qdrant** | qdrant/qdrant | 22k+ | 向量数据库 |
| **vLLM** | vllm-project/vllm | 45k+ | 高吞吐LLM推理 |

---

## 12. 项目结构

```
scholarmind/
├── docker-compose.yml              # 一键部署
├── config/
│   ├── litellm_config.yaml         # LLM路由配置
│   ├── mineru_config.yaml          # MinerU解析配置
│   └── settings.py                 # 全局配置
│
├── services/
│   ├── api/                        # FastAPI 主服务
│   │   ├── main.py                 # 入口
│   │   ├── routers/
│   │   │   ├── papers.py           # PDF上传/解析API
│   │   │   ├── query.py            # 知识库问答API
│   │   │   ├── graph.py            # 知识图谱API
│   │   │   └── admin.py            # 管理API
│   │   └── middleware/
│   │       ├── auth.py             # 认证
│   │       └── rate_limit.py       # 限流
│   │
│   ├── parser/                     # PDF解析服务
│   │   ├── router.py               # PDF特征路由
│   │   ├── mineru_worker.py        # MinerU VLM Worker
│   │   ├── pymupdf_worker.py       # PyMuPDF 快速解析
│   │   ├── metadata_extractor.py   # 元数据提取
│   │   └── tasks.py                # Celery任务定义
│   │
│   ├── extractor/                  # 知识抽取服务
│   │   ├── ner_engine.py           # GLiNER NER
│   │   ├── re_engine.py            # LLM 关系抽取
│   │   ├── fusion_engine.py        # Graphusion 融合
│   │   └── schema.py               # 实体/关系Schema
│   │
│   ├── graph/                      # 知识图谱服务
│   │   ├── neo4j_client.py         # Neo4j 连接管理
│   │   ├── graph_builder.py        # 图构建
│   │   ├── graph_query.py          # 图查询
│   │   └── visualization.py        # 图可视化
│   │
│   ├── indexer/                    # 索引服务
│   │   ├── chunker.py              # 学术论文分块器
│   │   ├── vector_indexer.py       # Qdrant 向量索引
│   │   ├── raptor_builder.py       # RAPTOR 层次摘要树
│   │   └── embedder.py             # 嵌入模型管理
│   │
│   ├── retriever/                  # 检索服务
│   │   ├── hybrid_retriever.py     # 三路混合检索
│   │   ├── hyde.py                 # HyDE 查询增强
│   │   ├── reranker.py             # 交叉编码器重排
│   │   └── rrf.py                  # RRF 融合
│   │
│   ├── agent/                      # Agent编排服务
│   │   ├── graph_definition.py     # LangGraph 状态机
│   │   ├── nodes.py                # Agent节点定义
│   │   ├── tools.py                # Agent工具集
│   │   └── prompts.py              # Prompt模板
│   │
│   └── llm/                        # LLM统一接入
│       ├── unified_llm.py          # LiteLLM封装
│       ├── model_router.py         # 任务→模型路由
│       └── cache.py                # LLM缓存
│
├── models/                         # 数据模型
│   ├── paper.py                    # 论文数据模型
│   ├── graph.py                    # 图谱数据模型
│   └── query.py                    # 查询数据模型
│
├── tests/
│   ├── test_parser.py
│   ├── test_extractor.py
│   ├── test_retriever.py
│   └── test_agent.py
│
├── scripts/
│   ├── setup_neo4j.cypher          # Neo4j初始化脚本
│   ├── batch_parse.py              # 批量解析脚本
│   └── build_index.py              # 索引构建脚本
│
├── frontend/                       # 前端 (React/Next.js)
│   ├── components/
│   │   ├── ChatInterface.tsx       # 问答界面
│   │   ├── GraphViewer.tsx         # 知识图谱可视化
│   │   ├── PaperUploader.tsx       # PDF上传
│   │   └── SearchResults.tsx       # 搜索结果展示
│   └── ...
│
├── requirements.txt
├── Dockerfile
└── README.md
```

---

## 快速开始

```bash
# 1. 克隆项目
git clone https://github.com/your-org/scholarmind.git
cd scholarmind

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env: 设置 OPENAI_API_KEY, DEEPSEEK_API_KEY 等

# 3. 下载MinerU模型
pip install mineru
mineru-models-download -s huggingface -m all

# 4. 启动所有服务
docker-compose up -d

# 5. 下载本地LLM (可选)
docker exec -it scholarmind-ollama ollama pull qwen2.5:14b-instruct

# 6. 批量导入论文
python scripts/batch_parse.py --input /path/to/pdfs/ --workers 4

# 7. 构建索引
python scripts/build_index.py --vector --graph --raptor

# 8. 访问系统
# API: http://localhost:8080/docs
# Neo4j: http://localhost:7474
# MinIO: http://localhost:9001
```

---

## 许可证

MIT License

---

*架构设计基于 2024-2025 年最新研究成果和开源实践，所有论文引用和Benchmark数据均可溯源。*