v1.0.0 MVP — 基于 LangGraph 的统一问答引擎
Python LangChain LangGraph Neo4j FastAPI React Gradio
以疾病为中心的医疗知识图谱 + 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、Neo4j、Node.js，只需 Docker：
git clone <your-repo-url>
cd MedicalGraphRAGSystem
# 1. 配置 API Key
cp .env.example .env # Windows: copy .env.example .env
# 编辑 .env，填入 SiliconFlow API Key（注册: https://siliconflow.cn）
# 2. 一键启动（首次 5-10 分钟导入图谱，之后秒启）
docker compose up -d
# 3. 查看启动进度
docker compose logs -f
# 4. 浏览器打开
# http://localhost:8000首次启动会自动下载镜像 + 导入 4.4 万实体数据，请耐心等待。
详细运维命令与故障排查 → docs/DOCKER.md
| 组件 | 版本建议 |
|---|---|
| Python | 3.10+ |
| Neo4j | 4.x / 5.x（已导入医疗图谱数据） |
| Node.js | 18+（仅前后端分离前端） |
| LLM | Ollama 本地 / OpenAI 兼容 API（如 SiliconFlow） |
⚠️ 必须使用虚拟环境（venv）。本项目依赖 LangChain 1.0 生态，与 0.x 不兼容。直接全局安装会导致依赖冲突并运行失败。
git clone <your-repo-url>
cd MedicalGraphRAGSystem
# 创建虚拟环境（仅首次）
python -m venv .venv
# 激活虚拟环境（每次开发前执行）
# Windows (PowerShell):
.venv\Scripts\activate
# Windows (CMD):
.venv\Scripts\activate.bat
# Linux / macOS:
source .venv/bin/activate
# 验证：确认 python 指向 .venv 中的解释器
# Windows: where python
# Linux/macOS: which python# 确保已激活 venv（终端提示符前应有 (.venv)）
pip install -r requirements.txtcp .env.example .env # Windows: copy .env.example .env编辑 .env，至少配置以下项：
NEO4J_URI=bolt://127.0.0.1:7687 # 本地开发注意用 127.0.0.1
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
LLM_PROVIDER=openai # 或 ollama
OPENAI_API_KEY=sk-your-key-here
OPENAI_BASE_URL=https://api.siliconflow.cn/v1
LLM_MODEL=deepseek-ai/DeepSeek-V4-Propython -m knowledge_graph.main可选参数：
python -m knowledge_graph.main --clear # 先清空旧数据再导入
python -m knowledge_graph.main --step nodes # 只创建节点
python -m knowledge_graph.main --step rels # 只创建关系三种入口，任选其一：
| 入口 | 命令 | 适用场景 |
|---|---|---|
| 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 - 每次启动前记得激活 venv：
.venv\Scripts\activate(Windows) /source .venv/bin/activate(Linux/macOS)
更详细的排错步骤见 docs/QUICK_START.md。
requirements.txt 使用 ~= 兼容版本锁定（如 langchain~=1.3 表示 >=1.3,<2.0），确保 LangChain 生态包都保持在 1.x 主版本内，避免 0.x/1.x 混装导致的 AttributeError。日常开发中请勿手动 pip install --upgrade 单个 langchain 包，应整体升级并验证。
python scripts/generate_diagrams.py若 PNG 生成失败，将自动回退为 docs/assets/workflow.html（Mermaid 图）。
MedicalGraphRAGSystem/
├── docker-compose.yml # 全栈 Docker 编排（一键启动）
├── .dockerignore # Docker 构建忽略
├── .editorconfig # 编辑器统一配置
├── .env.example # 环境变量模板
├── pyproject.toml # 项目配置（ruff/pytest）
├── LICENSE # MIT 许可证
├── settings.py # 统一配置（Neo4j / LLM / 路径）
├── requirements.txt # Python 依赖
├── basic_qa.py # [兼容入口] 委托 qa_engine
├── app.py # [重构] Gradio 美化演示
│
├── server/ # [重构] FastAPI 服务（SSE + 邻居查询）
│ ├── Dockerfile
│ └── README.md # API 文档与启动参数
│
├── web/ # [重构] React 前端
│ ├── Dockerfile # 多阶段构建镜像
│ ├── nginx.conf # Nginx 反向代理配置
│ └── README.md # 前端说明
│
├── qa_engine/ # LangGraph 统一问答引擎 ⭐
│ ├── README.md # 工作流架构与接口说明
│ ├── nodes/ # 分析、路由、模板路径、GraphRAG 路径
│ ├── graph_builder.py # 工作流图构建与 MemorySaver 检查点
│ ├── stream.py # 异步流式 SSE 事件
│ ├── session.py # 多轮对话会话管理
│ ├── collect.py # 流式结果收集
│ ├── graph_utils.py # 图谱数据解析工具
│ ├── workflow_diagram.py # Mermaid 工作流图源码
│ └── cli.py # CLI 入口 + 工作流图导出
│
├── KBQA/ # [保留] 模板问答 / ChatBot（18 种意图）
│ └── README.md
├── graphrag/ # [保留] 子图检索组件（5 阶段管线）
│ └── README.md
├── knowledge_graph/ # [保留] 图谱构建（7 节点 11 关系）
│ └── README.md
├── data_spider/ # [保留] 数据采集（已固化，无需重新爬取）
│ └── README.md
│
├── tests/ # 单元测试与集成测试
│ └── README.md
├── scripts/ # 辅助脚本
│ ├── generate_diagrams.py # 一键生成工作流图
│ └── docker-init.py # Docker 图谱自动导入
├── samples/ # 测试用例（覆盖全部路由模式）
│ └── README.md
│
├── docs/ # 项目文档
│ ├── DOCKER.md # Docker 运维手册
│ ├── ARCHITECTURE.md # 分层架构说明
│ ├── REFACTORING.md # 重构说明
│ ├── QUICK_START.md # 快速启动指南
│ └── assets/ # 工作流图资源
├── doc/ document/ img/ # 原项目文档与图片（未改动）
├── data/ # 医疗 JSON 数据（45 MB）
├── dict/ # 实体词典（7 类，约 4.4 万词条）
│
├── CHANGELOG.md # 版本变更日志
├── CONVENTIONS.md # 项目技术规范
├── README_ORIGINAL.md # 原 GitHub README（完整保留）
└── 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 说明，内容未修改）。
本次重构将原作者（liuhuanyong）开源的分散 KBQA / GraphRAG 问答逻辑收敛为统一的 qa_engine/ LangGraph 工作流，FastAPI 与 React 统一走 stream_qa 入口，前端合并为单一聊天面板。
- 重构动机、前后对比、技术决策：docs/REFACTORING.md
- 分层架构与 API 说明：docs/ARCHITECTURE.md
- 版本变更日志：CHANGELOG.md
- 各模块详细说明：qa_engine/ · graphrag/ · KBQA/ · server/ · knowledge_graph/
- 原始项目：QABasedOnMedicaKnowledgeGraph — 作者 刘焕勇 (liuhuanyong)，从零构建医疗知识图谱与规则问答 baseline。
- 原 README 全文保留于 README_ORIGINAL.md。
- 数据仅供学习研究，请勿商用；侵权请联系原作者删除。
- 本重构版在保留原数据与旧模块的前提下，新增 LangGraph 引擎与现代 Web 栈，不构成医疗建议。
原作者联系与公众号信息见 README_ORIGINAL.md 末尾。