docs/ADR.md

# ScholarMind 技术选型决策记录 (ADR)

## ADR-001: PDF解析引擎选择 MinerU 2.5 VLM

### 背景
需要解析1000+篇学术PDF论文，包含大量公式、表格、复杂多栏布局。

### 决策
主引擎: MinerU 2.5 VLM；快速通道: PyMuPDF (纯数字PDF)

### 依据
| 指标 | MinerU 2.5 | Marker | Nougat | 要求 |
|------|-----------|--------|--------|------|
| 文本精度 (Edit Distance↓) | **0.047** | 0.080 | 0.365 | <0.1 |
| 公式识别 (CDM↑) | **88.46** | 17.6 | 15.1 | >70 |
| 表格识别 (TEDS↑) | **88.22** | 67.6 | 39.9 | >75 |
| 吞吐 (A100 pg/s) | 2.12 | ~5 | ~0.5 | >1 |

MinerU 2.5 在所有关键指标上全面领先，是学术论文解析唯一达到生产级精度的开源方案。

### 来源
- OmniDocBench (CVPR 2025, arxiv:2412.07626)
- MinerU 2.5 论文 (arxiv:2509.22186)

---

## ADR-002: 知识抽取采用两阶段策略 (GLiNER + LLM)

### 背景
需要从论文中抽取学术实体(方法、数据集、指标等)和关系，支持本地和API模型。

### 决策
Stage 1: GLiNER (零样本NER, 440M参数, 本地)
Stage 2: LLMGraphTransformer (关系抽取, 本地/API LLM)
Stage 3: Graphusion (实体融合+冲突消解)

### 依据
- **GLiNER vs ChatGPT NER**: GLiNER F1=47.8 vs ChatGPT F1=36.5 (20个NER基准平均)
- **GLiNER**: 零样本、自定义标签、440M参数本地运行，不依赖API
- **LLMGraphTransformer**: LangChain原生集成，支持strict_mode约束抽取schema
- **Graphusion**: 比naive抽取在下游QA准确率提升9.2% (arxiv:2410.17600)

### 替代方案
- REBEL (seq2seq, 400M): 在Wikipedia上训练，不适合学术文本
- ReLiK: 学术界SOTA但生态集成不如LangChain方案
- 纯LLM抽取: 成本高(1000篇×API费用), 且小模型(<13B)噪声大

### 来源
- GLiNER (arxiv:2311.08526)
- Graphusion (arxiv:2410.17600)
- SciER数据集 (arxiv:2410.21155)

---

## ADR-003: 图数据库选择 Neo4j 5.x Community

### 背景
存储学术知识图谱，支持实体/关系查询、子图检索、向量搜索。

### 决策
Neo4j 5.x Community Edition

### 依据
- **LangChain/LlamaIndex原生集成**: 开箱即用的GraphRAG支持
- **Cypher查询语言**: 最成熟的图查询生态
- **向量索引**: Neo4j 5.x 原生支持向量索引，无需额外组件
- **全文索引**: 内置Lucene全文搜索
- **APOC/GDS插件**: 社区检测、PageRank等图算法
- **生态工具**: Neo4j Browser (可视化), neo4j-labs/llm-graph-builder (参考实现)

### 替代方案
- ArangoDB: 多模型优势，但LangChain集成不如Neo4j
- NebulaGraph: 更适合10亿+节点规模，当前场景(~100K节点)不需要
- Kuzu: 嵌入式轻量，但生产特性(HA、备份)不足

### 规模评估
1000篇论文预计: ~50K实体节点, ~200K关系边 → Neo4j Community轻松承载

---

## ADR-004: 向量数据库选择 Qdrant

### 背景
存储文本嵌入向量，支持Dense+Sparse混合检索。

### 决策
Qdrant (Rust核心, 原生Hybrid搜索)

### 依据
- **性能**: 3000+ RPS, p99<10ms (HNSW+标量量化)
- **原生Hybrid**: 同一Collection支持Dense+Sparse向量，无需外部BM25
- **简单部署**: 单Docker容器，无Zookeeper/etcd依赖
- **Disk-based HNSW**: 内存友好，适合1M+向量
- **Payload过滤**: 支持元数据过滤(paper_id, section, year等)

### 替代方案
- Milvus: 更适合>10M向量的分布式场景，运维复杂度更高
- Weaviate: API设计好但资源占用较高
- ChromaDB: 无分片/HA，不适合生产
- FAISS: 仅库不是服务，需要自建API层

### 规模评估
1000篇论文 × ~40 chunks/paper × 1536维 = ~40K向量 → Qdrant单节点轻松承载

---

## ADR-005: 检索策略采用三路混合 + RRF + Cross-Encoder

### 背景
学术问答涉及事实查询、多跳推理、全局分析等多种类型。

### 决策
1. 三路检索: Dense向量 + Sparse BM25 + 知识图谱
2. 融合: Reciprocal Rank Fusion (RRF)
3. 重排: BAAI/bge-reranker-large (Cross-Encoder)
4. 查询增强: HyDE (假设文档嵌入)

### 依据
- **RAG+GraphRAG融合 > 单一方案**: +6.4%准确率 (arxiv:2502.11371)
- **bge-reranker-large**: 实验验证的共识最优重排器 (arxiv:2502.11371)
- **HyDE**: 零成本+10 NDCG提升 (arxiv:2212.10496)
- **256 token分块**: 实验验证最佳分块大小 (arxiv:2502.11371)
- **RAPTOR层次树**: 专为层级文档设计, +20%准确率 (arxiv:2401.18059)

---

## ADR-006: Agent编排选择 LangGraph

### 背景
需要多Agent协作处理复杂学术问答，支持条件分支和循环。

### 决策
LangGraph (有状态图Agent编排)

### 依据
- **有状态图**: 天然支持条件路由、循环(自检→补充检索)
- **持久化**: 可持久化Agent状态，支持长对话
- **流式输出**: 原生支持SSE/WebSocket流式
- **LangChain生态**: 与LangChain检索器、工具无缝集成
- **生产级**: LangGraph Server提供REST API部署

### 替代方案
- smolagents: 更简单但缺乏复杂状态管理
- AutoGen: 偏向多Agent对话，不如图结构灵活
- CrewAI: 角色定义好但底层编排不如LangGraph灵活

---

## ADR-007: LLM接入层选择 LiteLLM

### 背景
需要同时支持本地(vLLM/Ollama)和外部API(OpenAI/Anthropic/DeepSeek)，不同任务使用不同模型。

### 决策
LiteLLM Proxy Server (统一OpenAI兼容接口)

### 依据
- **统一接口**: 100+ LLM提供商统一为OpenAI格式
- **路由策略**: latency-based, cost-based, model-specific
- **Fallback**: 本地模型失败自动切换API
- **成本追踪**: 内置token计数和费用统计
- **缓存**: Redis缓存重复请求
- **速率限制**: 防止API配额耗尽

### 任务-模型映射
| 任务 | 模型选择 | 原因 |
|------|---------|------|
| 知识抽取(NER/RE) | 本地 Qwen2.5-14B | 批量处理，成本敏感 |
| 答案生成 | GPT-4o-mini | 生成质量要求高 |
| 意图分类 | 本地 Llama-3.1-8B | 简单任务，延迟敏感 |
| 实体融合 | GPT-4o-mini | 需要强推理能力 |
| HyDE查询改写 | 本地 Llama-3.1-8B | 简单改写，延迟敏感 |