Add docs/DATAFLOW.md

5de1d21 verified 10 days ago

19.5 kB

	# ScholarMind 数据流详细设计

	## 1. 端到端数据流

	```
	ScholarMind 数据流全景图

	┌─────────────────────────────────────────────────────────────────────────────────┐
	│ Phase 1: 数据摄入 (Ingestion) │
	│ │
	│ PDF文件 ──▶ MinIO存储 ──▶ Redis队列 ──▶ PDF路由器 │
	│ │ │
	│ ┌─────────────┼─────────────┐ │
	│ ▼ ▼ ▼ │
	│ PyMuPDF MinerU Pipeline MinerU 2.5 VLM │
	│ (数字PDF) (数字+图表) (扫描件/复杂) │
	│ │ │ │ │
	│ └─────────────┼─────────────┘ │
	│ ▼ │
	│ ParsedPaper JSON │
	│ (结构化内容块) │
	│ │ │
	│ ┌────────────┼────────────┐ │
	│ ▼ ▼ ▼ │
	│ PostgreSQL MinIO(原始) Redis(状态) │
	│ (元数据) (PDF+JSON) (进度) │
	└───────────────────────────┬─────────────────────────────────────────────────────┘
	│
	┌────────────────────────────▼────────────────────────────────────────────────────┐
	│ Phase 2: 知识抽取 (Extraction) │
	│ │
	│ ParsedPaper ──▶ 学术分块器(256 tokens) │
	│ │ │
	│ ├──▶ GLiNER NER (实体抽取, 本地GPU) │
	│ │ │ │
	│ │ ▼ │
	│ │ 实体列表: [(text, type, score), ...] │
	│ │ │ │
	│ │ ▼ │
	│ ├──▶ LLMGraphTransformer (关系抽取) │
	│ │ │ 输入: 文本块 + 实体提示 │
	│ │ │ LLM: local(Qwen2.5-14B) 或 API(GPT-4o-mini) │
	│ │ ▼ │
	│ │ 三元组列表: [(head, rel, tail, props), ...] │
	│ │ │ │
	│ │ ▼ │
	│ └──▶ Graphusion 融合引擎 │
	│ │ - 嵌入相似度实体合并 (>0.92) │
	│ │ - LLM冲突消解 │
	│ │ - 缺失关系推断 │
	│ ▼ │
	│ 规范化三元组 │
	└────────────────────────────┬────────────────────────────────────────────────────┘
	│
	┌────────────────────────────▼────────────────────────────────────────────────────┐
	│ Phase 3: 索引构建 (Indexing) │
	│ │
	│ 并行三路索引构建: │
	│ │
	│ 路径A: 向量索引 │
	│ 文本块 ──▶ Embedding Model ──▶ Dense Vector ──┐ │
	│ 文本块 ──▶ BM42/SPLADE ──▶ Sparse Vector ─────┼──▶ Qdrant Collection │
	│ 元数据 ──────────────────────────────────────┘ (papers, 1M+ vectors) │
	│ │
	│ 路径B: 知识图谱 │
	│ 规范化三元组 ──▶ Neo4j Batch Import ──▶ Neo4j Graph │
	│ 实体嵌入 ──▶ Neo4j Vector Index ──▶ 图内向量搜索 │
	│ 全文索引 ──▶ Neo4j Fulltext Index ──▶ 图内文本搜索 │
	│ │
	│ 路径C: RAPTOR层次树 │
	│ 文本块 ──▶ SBERT嵌入 ──▶ GMM聚类 ──▶ LLM摘要 ──▶ 重新嵌入 ──▶ 递归 │
	│ Level 0 (原始) → Level 1 (段落) → Level 2 (主题) → Level 3 (领域) │
	│ 所有层级节点 ──▶ Qdrant Collection (raptor_tree) │
	└────────────────────────────┬────────────────────────────────────────────────────┘
	│
	┌────────────────────────────▼────────────────────────────────────────────────────┐
	│ Phase 4: 检索与问答 (Query) │
	│ │
	│ 用户查询 │
	│ │ │
	│ ├──▶ 意图分类 (Router LLM) │
	│ │ │ │
	│ │ ├── factual → 向量+BM25检索 (Qdrant) │
	│ │ ├── reasoning → 图谱遍历 (Neo4j) + 向量检索 │
	│ │ └── global → RAPTOR高层摘要 + 社区检索 │
	│ │ │
	│ ├──▶ HyDE查询增强 │
	│ │ LLM生成假设答案 → 嵌入 → 在文档空间搜索 │
	│ │ │
	│ └──▶ 多路结果 ──▶ RRF融合 ──▶ bge-reranker-large重排 ──▶ Top-5 │
	│ │
	│ Top-5 + 查询 ──▶ Generator LLM ──▶ 答案 + 引用 │
	│ │ │
	│ ▼ │
	│ 答案 ──▶ Validator LLM (自检) ──┬── 置信度>0.8 → 返回 │
	│ └── 置信度<0.8 → 补充检索 (max 3轮) │
	└─────────────────────────────────────────────────────────────────────────────────┘
	```

	## 2. 知识图谱查询流示例

	### 示例1: "BERT模型在哪些数据集上超过了GPT-2?"

	```
	查询 → 意图分类: reasoning
	→ 图谱查询:

	MATCH (bert:Method {name: "BERT"})-[r1:EVALUATED_ON]->(d:Dataset)
	<-[r2:EVALUATED_ON]-(gpt2:Method {name: "GPT-2"})
	WHERE r1.score > r2.score AND r1.metric = r2.metric
	RETURN d.name as dataset,
	r1.metric as metric,
	r1.score as bert_score,
	r2.score as gpt2_score
	ORDER BY (r1.score - r2.score) DESC

	→ 结果:
	┌──────────┬──────────┬────────────┬────────────┐
	│ dataset │ metric │ bert_score │ gpt2_score │
	├──────────┼──────────┼────────────┼────────────┤
	│ GLUE │ accuracy │ 82.1 │ 75.4 │
	│ SQuAD │ F1 │ 93.2 │ 89.1 │
	│ ... │ ... │ ... │ ... │
	└──────────┴──────────┴────────────┴────────────┘

	+ 向量检索补充: 相关论文段落作为supporting evidence
	→ LLM综合生成答案
	```

	### 示例2: "Transformer架构近3年的主要改进方向有哪些?"

	```
	查询 → 意图分类: global
	→ RAPTOR Level 2-3 检索:
	"Transformer改进" 相关的高层摘要节点
	→ 图谱查询:

	MATCH (t:Concept {name: "Transformer"})<-[:IMPROVES_ON]-(m:Method)
	WHERE m.year >= 2022
	RETURN m.name, m.description, m.year
	ORDER BY m.year DESC

	→ LLM综合: 从摘要+图谱结构生成趋势分析
	```

	## 3. 并发处理模型

	```
	┌──────────────────────────────────────────────────────────┐
	│ 并发处理架构 │
	├──────────────────────────────────────────────────────────┤
	│ │
	│ FastAPI (asyncio) ────── 查询请求处理 │
	│ │ 并发: 100+ concurrent requests │
	│ │ │
	│ Celery Workers ─────── PDF解析任务 │
	│ │ GPU Worker: 1 per GPU │
	│ │ CPU Worker: 4-8 per node │
	│ │ │
	│ vLLM Server ────────── LLM推理 │
	│ │ Async batching (自动) │
	│ │ max_num_seqs: 32 │
	│ │ │
	│ Qdrant ─────────────── 向量检索 │
	│ │ RPS: 3000+ (p99 < 10ms) │
	│ │ │
	│ Neo4j ──────────────── 图谱查询 │
	│ │ Connection pool: 50 │
	│ │ Query timeout: 5s │
	│ │ │
	│ Redis ──────────────── 缓存 + 队列 │
	│ LLM响应缓存 │
	│ 任务队列 │
	│ Session状态 │
	└──────────────────────────────────────────────────────────┘

	关键设计决策:
	1. MinerU VLM Worker: 每GPU一个进程 (vLLM内部已做batch)
	2. GLiNER: GPU batch inference, 共享单个GPU
	3. LLM调用: 异步 (litellm.acompletion), 自动batch
	4. 图谱写入: 批量UNWIND导入 (1000 triplets/batch)
	5. 向量写入: Qdrant batch upload (100 points/batch)
	```

	## 4. 缓存策略

	```
	┌──────────────────────────────────────────────────────────┐
	│ 多级缓存策略 │
	├──────────────────────────────────────────────────────────┤
	│ │
	│ L1: LLM响应缓存 (Redis, TTL: 24h) │
	│ Key: hash(model + messages + temperature) │
	│ 命中率预估: 30-40% (学术查询重复度高) │
	│ │
	│ L2: 嵌入缓存 (Redis, TTL: 7d) │
	│ Key: hash(text + model_name) │
	│ 避免重复计算嵌入向量 │
	│ │
	│ L3: 查询结果缓存 (Redis, TTL: 1h) │
	│ Key: hash(query + mode + top_k) │
	│ 完整检索结果缓存 │
	│ │
	│ L4: 图谱子图缓存 (Application Memory, LRU) │
	│ 热门实体的2跳子图预加载 │
	│ 容量: top 1000 entities │
	│ │
	│ 失效策略: │
	│ - 新论文导入 → 清除相关query缓存 (L3) │
	│ - 图谱更新 → 清除图谱缓存 (L4) │
	│ - 模型更换 → 清除LLM+嵌入缓存 (L1+L2) │
	└──────────────────────────────────────────────────────────┘
	```

	## 5. 错误处理与监控

	```
	┌──────────────────────────────────────────────────────────┐
	│ 可观测性架构 │
	├──────────────────────────────────────────────────────────┤
	│ │
	│ Metrics (Prometheus + Grafana): │
	│ - pdf_parse_duration_seconds (histogram) │
	│ - pdf_parse_total{status="success\|failed"} (counter) │
	│ - query_latency_seconds{mode="factual\|reasoning\|global"}│
	│ - llm_tokens_total{model, task} (counter) │
	│ - llm_cost_usd_total{model} (counter) │
	│ - qdrant_search_latency_seconds (histogram) │
	│ - neo4j_query_latency_seconds (histogram) │
	│ - cache_hit_ratio{level="L1\|L2\|L3\|L4"} (gauge) │
	│ │
	│ Logging (Structured JSON → ELK/Loki): │
	│ - 每次查询完整trace (query→retrieval→generation) │
	│ - PDF解析异常详情 │
	│ - LLM调用详情 (token count, latency, model) │
	│ │
	│ Alerts: │
	│ - PDF解析失败率 > 5% → 检查PDF质量/MinerU状态 │
	│ - 查询P99延迟 > 10s → 检查LLM/向量库负载 │
	│ - LLM成本日超 $X → 切换更多流量到本地模型 │
	│ - Neo4j内存 > 80% → 扩容或清理旧数据 │
	│ │
	│ Health Checks: │
	│ GET /health → 检查所有依赖服务状态 │
	│ - Redis: PING │
	│ - Qdrant: collection info │
	│ - Neo4j: RETURN 1 │
	│ - LiteLLM: /health │
	│ - MinerU Worker: Celery inspect │
	└──────────────────────────────────────────────────────────┘
	```