Python LangChain LangGraph Neo4j FastAPI React
以疾病为中心的医疗知识图谱 + LangGraph 统一问答引擎，支持模板 Cypher 检索与 GraphRAG 子图检索，并提供 CLI、Gradio、前后端分离三种使用方式。
- 三级降级分析：Level 1 全 LLM → Level 2 LLM 实体 + 关键词意图 → Level 3 离线词典 NER
- 条件路由：简单问句走模板 Cypher 路径，复杂多实体问句自动切换 GraphRAG
- SSE 流式输出：答案逐字返回，
done事件携带 debug 与图谱数据 - LangSmith 可观测：可选开启链路追踪，记录路由、降级等级与子图统计
- 图谱可视化：React 力导向图 + 节点点击展开邻居
- 统一前端面板：
UnifiedChatPanel单入口，后端自动路由，无需手动切换模式 - 多轮对话：LangGraph
MemorySaver+session_id（CLI / Gradio / Web / API 一致） - 全路径图谱数据：模板 Cypher 结果与 GraphRAG 子图均写入
graph_data - 全链路智能兜底：模板失败→自动回退 GraphRAG →仍不可用→LLM 直接回答→静态提示，前端清晰展示流转路径（如「模板检索 → GraphRAG → AI 回答」），用户永远不会收到冰冷提示
flowchart LR
subgraph 数据层
A[data_spider/ 爬虫] --> B[knowledge_graph/ 图谱构建]
B --> C[(Neo4j)]
D[dict/ 实体词典] --> C
end
subgraph 问答层
E[qa_engine/ LangGraph] --> C
E --> F[LLM API]
end
subgraph 接入层
G[CLI basic_qa.py] --> E
H[Gradio app.py] --> E
I[server/ FastAPI] --> E
I --> J[web/ React]
end
flowchart TD
START([__start__]) --> A[1. 分析问题]
A -->|成功| R[2. 路由判断]
A -->|失败| ERR[X. 错误处理<br/>含LLM兜底]
R -->|graphrag| G1[G1 RAG实体抽取]
R -->|template| T1[T1 实体归一化]
R -->|失败| ERR
T1 -->|成功/回退| T2[T2 生成Cypher]
T1 -->|失败| ERR
T2 -->|成功/回退| T3[T3 执行查询]
T2 -->|失败| ERR
T3 -->|成功| T4[T4 格式化答案]
T3 -->|失败| ERR
T3 -->|模板无结果<br/>回退GraphRAG| G1
T4 -->|成功| END([__end__])
T4 -->|失败| ERR
G1 -->|成功| G2[G2 实体归一化]
G1 -->|失败| ERR
G2 -->|成功| G3[G3 子图检索]
G2 -->|失败| ERR
G3 -->|成功| G4[G4 上下文构建]
G3 -->|失败| ERR
G4 -->|成功| G5[G5 RAG生成回答]
G4 -->|失败| ERR
G5 -->|成功| END
G5 -->|失败| ERR
ERR --> END
LangGraph 工作流
重新生成：
python scripts/generate_diagrams.py
| 组件 | 版本建议 |
|---|---|
| Python | 3.10+ |
| Neo4j | 4.x / 5.x（已导入医疗图谱数据） |
| Node.js | 18+（仅前后端分离前端） |
| LLM | Ollama 本地 / OpenAI 兼容 API（如 SiliconFlow） |
git clone <your-repo-url>
cd MedicalGraphRAGSystem-master
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
# requirements.txt 已包含 langgraph / gradio / langsmith / langchain-ollama / langchain-openai 等
cp .env.example .env # Windows: copy .env.example .env
# 编辑 .env：Neo4j 密码、LLM 地址与密钥图谱数据导入（首次部署，耗时较长）：
data/medical.json（45 MB）已包含爬取好的数据，无需重新爬取。直接运行以下命令导入 Neo4j：
python -m knowledge_graph.main可选参数：
python -m knowledge_graph.main --clear # 先清空旧数据再导入
python -m knowledge_graph.main --step nodes # 只创建节点
python -m knowledge_graph.main --step rels # 只创建关系关键项见 [.env.example](.env.example)。最小配置示例：
NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
LLM_PROVIDER=ollama
LLM_MODEL=qwen3:8b
LLM_BASE_URL=http://localhost:11434| 入口 | 命令 | 适用场景 |
|---|---|---|
| CLI | python basic_qa.py 或 python basic_qa.py --stream |
终端调试、脚本集成 |
| Gradio | python app.py |
快速演示、调试面板可视化 |
| 前后端分离 | 终端 1：python -m server.app 终端 2：cd web && npm install && npm run dev |
生产式 Web UI、图谱交互 |
- Gradio 默认地址：
http://127.0.0.1:7860（以终端输出为准） - 前端开发：
http://localhost:5173，API 代理至http://localhost:8000
更详细的排错步骤见 docs/QUICK_START.md。
python scripts/generate_diagrams.py若 PNG 生成失败，将自动回退为 docs/assets/workflow.html（Mermaid 图）。
MedicalGraphRAGSystem-master/
├── qa_engine/ # [新增] LangGraph 统一问答引擎
│ ├── nodes/ # 分析、路由、模板路径、GraphRAG 路径
│ ├── graph_builder.py # 工作流图构建与 MemorySaver 检查点
│ ├── stream.py # 异步流式 SSE 事件
│ ├── session.py # 多轮对话会话管理（thread_id + 历史增强）
│ ├── collect.py # 流式结果收集（消费 stream_qa 至 done）
│ ├── graph_utils.py # 图谱数据解析工具
│ ├── workflow_diagram.py # Mermaid 工作流图源码
│ └── cli.py # CLI 入口 + 工作流图导出
├── server/ # [重构] FastAPI 服务（SSE + 邻居查询）
├── web/ # [重构] React 前端（UnifiedChatPanel）
├── tests/ # [新增] 单元测试与集成测试（16 个测试文件，约50个测试函数）
├── scripts/ # [新增] 辅助脚本
│ └── generate_diagrams.py # 一键生成工作流图
├── basic_qa.py # [兼容入口] 委托 qa_engine
├── app.py # [重构] Gradio 美化演示
├── settings.py # 统一配置（Neo4j / LLM / 路径）
├── KBQA/ # [保留] 原模板问答 / ChatBot
├── graphrag/ # [保留] 原子图检索组件
├── knowledge_graph/ # [保留] 图谱构建
├── data_spider/ # [保留] 数据采集（爬虫已失效，数据已固化）
│ └── README.md # 爬虫说明（网站已改版，无需重新爬取）
├── dict/ # 实体词典（7 类，约 4.4 万词条）
├── data/ # 医疗 JSON 数据（45 MB，约 8,800 条）
├── doc/ document/ img/ # 原项目文档与图片（未改动）
├── technical_communication_docs/ # 技术交流文档（架构演讲等）
├── docs/ # [新增] 重构与架构文档
│ ├── REFACTORING.md
│ ├── ARCHITECTURE.md
│ ├── QUICK_START.md
│ └── assets/
│ ├── workflow.png # LangGraph 工作流图
│ ├── workflow.mmd # Mermaid 源码
│ └── workflow.html # HTML 预览
├── README_ORIGINAL.md # 原 GitHub README（完整保留）
├── CONVENTIONS.md # 项目技术规范
└── README.md # 本文件
- 在 LangSmith 注册并创建 API Key
- 在
.env中设置：
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=ls-your-key-here
LANGCHAIN_PROJECT=MedicalGraphQA- 启动任意入口（CLI / Gradio / FastAPI）后，在 LangSmith 控制台查看 Trace
CLI 启动时会调用 setup_langsmith()；未配置时自动跳过，不影响问答。
本项目医疗知识图谱来源于垂直医药网站结构化采集，以疾病为核心：
| 指标 | 规模 |
|---|---|
| 实体 | 约 4.4 万（7 类：疾病、症状、药品等） |
| 关系 | 约 30 万（11 类：症状、用药、饮食、检查等） |
完整实体/关系类型表、问答示例与免责声明见 README_ORIGINAL.md（原作者 liuhuanyong 说明，内容未修改）。
近期完成系统性重构：将分散的 KBQA / GraphRAG 问答逻辑收敛为 **qa_engine/ LangGraph 工作流**，FastAPI 与 React 统一走 stream_qa，前端合并为单一聊天面板。
- 重构动机、前后对比、技术决策：docs/REFACTORING.md
- 分层架构与 API 说明：docs/ARCHITECTURE.md
- 原始项目：QABasedOnMedicaKnowledgeGraph — 作者 刘焕勇 (liuhuanyong)，从零构建医疗知识图谱与规则问答 baseline。
- 原 README 全文保留于 README_ORIGINAL.md。
- 数据仅供学习研究，请勿商用；侵权请联系原作者删除。
- 本重构版在保留原数据与旧模块的前提下，新增 LangGraph 引擎与现代 Web 栈，不构成医疗建议。
原作者联系与公众号信息见 README_ORIGINAL.md 末尾。