MedicalGraphRAGSystem

基于知识图谱 + 向量混合检索 + LangGraph 智能路由的医疗问答系统

项目简介

本项目是一个医疗领域智能问答系统，以 Neo4j 知识图谱（4.4 万实体、30 万关系）为核心，结合 ChromaDB 向量语义检索和 LangGraph 智能路由，实现对不同类型医疗问题的自动分发和高质量回答。

系统架构

用户提问
  ↓
LangGraph 智能路由（自动判断问题类型）
  ├─ 精确医疗问题  → KBQA 管线（意图分类 + Cypher 查询 + 模板回答）
  ├─ 开放/模糊问题  → HybridRAG 管线（图谱子图 + 向量语义 混合检索 → LLM 生成）
  └─ 闲聊/无关问题  → LLM 直接回复

技术栈

层级	技术选型
知识图谱	Neo4j 5 + py2neo（7 类实体、11 类关系）
向量检索	ChromaDB + SiliconFlow BGE-M3 Embedding（1024 维）
LLM	DeepSeek API（OpenAI 兼容接口）
智能路由	LangGraph 状态机（条件分支编排）
后端	FastAPI + SSE 流式输出
前端	React + TypeScript + TailwindCSS + shadcn/ui
评测	自建 60 条测试集 + 自动化评测脚本

---

项目演进

本项目经历了三个阶段的迭代：

阶段	内容	来源
V1 - 基础 KBQA	爬虫 + Neo4j 图谱 + 规则问答（18 类意图）	liuhuanyong 原始项目
V2 - GraphRAG	LLM 实体抽取 + 子图检索 + LLM 生成 + React 前端	社区博主改造
V3 - 混合检索 + 智能路由	向量混合检索 + LangGraph 路由 + 评测体系	本次改造

V3 改造内容（我的工作）

Phase 1：向量混合检索层

• 新增 graphrag/vector_store.py — ChromaDB 向量库封装，SiliconFlow Embedding 集成
• 新增 graphrag/vector_builder.py — 从 Neo4j 提取 8,807 个疾病的 8 类文本属性，构建 61,526 条向量文档
• 新增 graphrag/hybrid_retriever.py — 图谱 + 向量混合检索器，三种策略自动切换：
  • 情况 A：实体匹配成功 → 图谱检索为主，向量检索补充
  • 情况 B：实体匹配失败 → 仅走向量语义检索，结果反查图谱
  • 情况 C：向量库不可用 → 降级为纯图谱检索
• 改造 graphrag/graphrag_bot.py — 实体抽取失败时 fallback 到向量检索，不再返回空答案

Phase 2：LangGraph 智能路由

• 新增 orchestrator/ 模块：
  • state.py — LangGraph 状态定义
  • router.py — LLM 路由节点（分类为 kbqa / graphrag / chitchat）
  • graph.py — LangGraph 状态机编排（条件分支 → 对应管线）
• 新增 server/app.py 中 /api/smart/chat 和 /api/smart/chat/stream 端点
• 新增前端智能问答面板 + 路由调试面板

Phase 3：评测体系

• 新增 evaluation/ 模块：
  • test_cases.json — 60 条测试用例，覆盖 4 类场景
  • metrics.py — 关键词召回率、路由准确率、有效回答率
  • evaluator.py — 自动化评测运行器，对比 3 种模式
• 自动生成 evaluation/report.md 评测报告

---

评测结果

60 条测试用例，覆盖精确问题、开放问题、模糊症状、闲聊 4 类场景：

总览

指标	KBQA（改造前）	GraphRAG	Smart（改造后）
关键词召回率	64.1%	83.2%	78.5%
有效回答率	89.1%	100%	91.7%
平均响应时间	4.8s	16.4s	11.4s
路由准确率	-	-	73.3%

分类细分

场景	KBQA	GraphRAG	Smart
精确问题（"糖尿病有什么症状"）	69.2%	80.4%	74.2%
开放问题（"糖尿病怎么治疗和预防"）	77.1%	93.3%	93.8%
模糊症状（"晚上翻来覆去睡不着"）	40.0%	73.3%	56.7%

核心结论：

• 向量混合检索使 GraphRAG 关键词召回率从 64% 提升至 83%（+30%）
• 模糊症状场景提升最显著：40% → 73%，验证了向量语义检索的价值
• GraphRAG 有效回答率达 100%，零空回答

---

项目结构

MedicalGraphRAGSystem/
├── KBQA/                    # 基础问答管线（意图分类 + Cypher 查询）
│   ├── chat_bot.py          # KBQA 问答主逻辑
│   ├── llm_engine.py        # LLM 引擎（实体抽取 + 意图识别）
│   ├── entity_normalizer.py # 实体归一化（三级匹配）
│   └── ...
├── graphrag/                # GraphRAG 管线
│   ├── graphrag_bot.py      # GraphRAG 编排器
│   ├── entity_extractor.py  # LLM 实体抽取
│   ├── subgraph_retriever.py# Neo4j 子图检索
│   ├── hybrid_retriever.py  # [新增] 图谱+向量混合检索
│   ├── vector_store.py      # [新增] ChromaDB 向量库封装
│   ├── vector_builder.py    # [新增] 向量索引构建脚本
│   ├── context_builder.py   # 上下文组装
│   └── generator.py         # LLM 答案生成
├── orchestrator/            # [新增] LangGraph 智能路由
│   ├── state.py             # 状态定义
│   ├── router.py            # LLM 路由节点
│   └── graph.py             # 状态机编排
├── evaluation/              # [新增] 评测体系
│   ├── test_cases.json      # 60 条测试用例
│   ├── evaluator.py         # 评测运行器
│   ├── metrics.py           # 指标计算
│   └── report.md            # 评测报告
├── server/                  # FastAPI 后端
│   ├── app.py               # API 端点定义
│   └── models.py            # Pydantic 数据模型
├── web/                     # React 前端
├── data/                    # 原始数据（medical.json）
├── settings.py              # 全局配置
└── requirements.txt         # Python 依赖

---

快速开始

环境要求

• Python 3.11+
• Neo4j 5.x
• Node.js 18+

1. 安装依赖

# 后端
pip install -r requirements.txt

# 前端
cd web && npm install

2. 配置环境变量

复制 .env.example 为 .env，填写：

# Neo4j
NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password

# LLM (DeepSeek)
LLM_PROVIDER=openai
LLM_MODEL=deepseek-chat
LLM_BASE_URL=https://api.deepseek.com/v1
OPENAI_API_KEY=your_deepseek_api_key

# Embedding (SiliconFlow)
EMBEDDING_API_KEY=your_siliconflow_api_key

3. 导入知识图谱

# 导入医疗数据到 Neo4j（约 4.4 万实体、30 万关系）
python quick_import.py

4. 构建向量索引

# 从 Neo4j 提取疾病属性，构建 ChromaDB 向量库
python -m graphrag.vector_builder

5. 启动服务

# 启动后端（默认 http://localhost:8000）
python -m server.app

# 启动前端（默认 http://localhost:5173）
cd web && npm run dev

6. 运行评测（可选）

# 确保后端已启动，运行 60 条自动化评测
python -m evaluation.evaluator
# 报告生成在 evaluation/report.md

---

API 接口

端点	说明
POST /api/chat	基础 KBQA 问答
POST /api/graphrag/chat	GraphRAG 问答
POST /api/smart/chat	智能路由问答（自动选择最优管线）
POST /api/chat/stream	KBQA 流式
POST /api/graphrag/chat/stream	GraphRAG 流式
POST /api/smart/chat/stream	智能路由流式
GET /api/health	健康检查

请求体：{"question": "糖尿病有什么症状"}

---

知识图谱规模

实体类型	数量	示例
Disease（疾病）	8,807	糖尿病、高血压
Symptom（症状）	5,998	胸痛、乏力
Drug（药品）	3,828	二甲双胍、氨氯地平
Food（食物）	4,870	番茄、竹笋
Check（检查）	3,353	血常规、CT
Department（科室）	54	内科、外科
Producer（在售药品）	17,201	各厂商药品
合计	44,111

关系总量：294,149（11 种关系类型）

---

详细文档

更多技术细节请参考 doc/ 目录：

• 项目改造计划 — 三阶段改造方案
• GraphRAG 技术设计 — 管线架构详解
• Web 应用技术设计 — 前后端设计
• 知识图谱构建 — 图谱 Schema 与构建流程
• 问答系统设计 — KBQA 管线详解
• 安装与使用指南 — 完整部署指南

---

致谢

• 原始项目：liuhuanyong/QABasedOnMedicalKnowledgeGraph
• V2 GraphRAG 改造：社区博主在原项目基础上增加了 LLM 实体抽取、子图检索、LLM 生成、React 前端等能力