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. 系统架构总览
2. PDF 解析层 — MinerU Pipeline
3. 知识抽取层 — 实体关系抽取
4. 知识图谱层 — 图构建与存储
5. 索引层 — 多路索引构建
6. 检索层 — 混合检索与重排
7. Agent 编排层 — 智能问答
8. LLM 统一接入层
9. 系统部署架构
10. 技术选型对比
11. 关键论文与开源项目
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 架构设计

# 混合路由策略：数字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 输出数据模型

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 核心抽取代码

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 图谱数据模型

// ===== 节点 =====
(: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 图谱可视化方案

# 方案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 文档分块策略

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 核心检索代码

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 状态机定义

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 工具集

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 配置

# 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 统一调用接口

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 部署

# 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 设计

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

---

快速开始

# 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数据均可溯源。