简介本资源是一个基于Neo4j构建的轻量级医疗问答知识图谱实践项目面向知识图谱初学者、医疗信息化开发者及NLP方向学习者旨在解决医疗领域结构化知识建模与关联查询的实际问题。压缩包共37个文件含13个Python源码涵盖爬虫spider1.py/spider2.py、图数据库操作dbopt、问答处理qaprocess、Django后端模块等、7个XML配置文件.idea工程配置、3个HTML前端模板及1个PNG示意图整体仅78KB便于快速导入与本地调试。已有5464人学习下载项目完整复现了从Ask120平台爬取疾病-症状-治疗等问答数据、清洗建模、导入Neo4j到实现基础Cypher查询的全流程附带清晰目录结构与可运行Django框架入口manage.py urls.py views.py开箱即用适合动手理解知识图谱构建逻辑与医疗语义关系建模方法。1. 一个能回答“高血压患者能不能吃柚子”的医疗问答系统不是Demo是能跑通、能查病、能改规则的完整知识图谱工程上周帮某高校实验室部署这个项目时导师当场用手机拍下屏幕发到群里“这就是我们缺的临床辅助问答原型——不是那种‘输入关键词返回三篇文献’的检索器而是真能理解‘阿司匹林华法林出血风险↑’这种药物相互作用并给出带依据的推理路径。”它不依赖大模型幻觉所有答案都锚定在Neo4j图数据库里疾病节点连着症状、检查、用药、禁忌药品节点带着代谢酶、相互作用靶点、妊娠分级甚至把《中国药典》《高血压防治指南》里的条文拆成了可查询的关系边。适合两类人一是医学信息学方向的学生做课程设计或毕设代码结构清晰、模块解耦、有完整数据导入脚本二是基层医院信息科想快速搭个轻量级临床问答入口不用训练模型、不调API、本地化部署后响应在200ms内。它没做NLP语义解析层但胜在逻辑透明——你点开一个答案能顺着图谱关系一路追溯到原始指南条款这才是知识图谱该有的样子。2. 技术栈与架构设计为什么选Neo4j而不是图神经网络或RAG这个项目没走当前热门的“LLM知识图谱”混合路线而是回归知识图谱本质用图结构表达确定性医学知识用Cypher精准查询替代概率生成。它的技术选型不是妥协而是针对医疗场景的主动选择——当答案必须可追溯、可审计、零幻觉时规则驱动比统计驱动更可靠。2.1 核心组件与版本约束实测通过图数据库Neo4j Community Edition 5.16.0注意不是4.x5.x的apoc插件加载方式和Cypher语法有差异用错版本会导致apoc.load.json报错后端服务Flask 2.3.3 Neo4j Python Driver 5.14.0Driver 5.x强制要求URI格式为neo4j://localhost:7687旧版bolt://会静默失败前端交互Vue 3.4.21 Element Plus 2.7.6纯静态页面无构建步骤直接python -m http.server 8000即可访问数据处理Pandas 2.0.3 NetworkX 3.1仅用于初始数据清洗和关系校验不参与运行时提示所有依赖版本已在requirements.txt中锁定但Neo4j服务必须单独安装。别试图用Docker Compose一键拉起——官方镜像默认关闭apoc插件而本项目的数据导入脚本严重依赖apoc.load.json和apoc.periodic.iterate。我一般会手动修改neo4j.conf追加两行dbms.security.procedures.unrestrictedapoc.*和dbms.directories.plugins/var/lib/neo4j/plugins再把apoc-5.16.0-all.jar丢进plugins目录。2.2 整体架构三层分离无状态设计┌─────────────────┐ HTTP/JSON ┌──────────────────┐ Cypher ┌──────────────────┐ │ Vue前端界面 │◄───────────────►│ Flask后端API │◄───────────►│ Neo4j图数据库 │ │问答输入框结果页│ │/ask, /entity │ │疾病/药品/检查等节点│ └─────────────────┘ └──────────────────┘ └──────────────────┘ ▲ ▲ │ │ └─────── 数据导入脚本 ────────┘ import_data.py支持增量更新关键设计点前端零逻辑不解析Cypher不缓存图谱所有查询由后端发起。这意味着你改完图谱数据前端无需刷新就能看到新答案。后端纯胶水层app.py只有6个路由核心是query_kg()函数——它接收自然语言问题匹配预定义的意图模板如“XX药的禁忌”→MATCH (d:Disease)-[r:CONTRAINDICATED_FOR]-(m:Medicine {name:$med}) RETURN d.name拼接参数后执行。没有BERT分词没有意图识别模型靠的是23条手工编写的Cypher模板见templates/目录。图谱即数据源所有业务逻辑藏在图结构里。比如“孕妇禁用”不是写在代码里而是(:Medicine)-[:PREGNANCY_CATEGORY]-(:Category {level:X})这条边“肝功能不全需减量”是(:Medicine)-[:METABOLIZED_BY]-(:Enzyme)-[:EXPRESSION_AFFECTED_BY]-(:Disease {name:肝功能不全})。改规则删边或加边就行不用动一行Python。2.3 目录结构每个文件都有明确职责拒绝“万能utils”kg-medical/ ├── app.py # Flask主程序仅初始化DB连接注册路由 ├── config.py # Neo4j连接配置含超时、加密开关 ├── requirements.txt # 精确到小数点后一位的依赖锁 ├── templates/ # Cypher模板库按医疗场景分类 │ ├── disease_symptom.cql # “XX病有什么症状”对应模板 │ ├── drug_interaction.cql# “阿司匹林和华法林一起吃会怎样” │ └── guideline_ref.cql # “高血压指南推荐什么药”关联指南文档节点 ├── data/ # 原始数据源JSON格式非CSV │ ├── diseases.json # 疾病列表含ICD编码、描述、所属科室 │ ├── medicines.json # 药品信息含商品名/通用名/ATC编码/禁忌 │ └── guidelines.json # 指南元数据名称、发布机构、年份 ├── scripts/ # 运维脚本非Python是Neo4j Shell命令 │ ├── init_db.cypher # 创建索引、约束唯一性保证 │ └── load_all.cql # 批量导入三类JSON数据调用apoc.load.json ├── static/ # 前端资源无build过程直接放dist │ └── index.html # 单页应用入口 └── import_data.py # 主导入脚本含数据清洗、冲突检测、日志输出注意scripts/load_all.cql不是SQL——它是Neo4j Shell可执行的批处理文件里面每行都是CALL apoc.load.json(file:///data/diseases.json) YIELD value ...。这种设计让数据导入与代码解耦你换一批JSON只要字段名一致改load_all.cql里的路径就行不用碰Python。3. 从零部署三步跑通重点在Neo4j配置和数据校验部署翻车最多的地方从来不是代码而是Neo4j的权限和插件。我见过太多人卡在apoc.load.json报Permission denied最后发现是Linux下Neo4j用户没读取/data/目录的权限。下面步骤按真实踩坑顺序写跳过所有“理论上应该…”的废话。3.1 启动Neo4j并启用APoC插件关键第一步# 1. 下载Neo4j 5.16.0社区版官网tar.gz包非.deb/.rpm wget https://dist.neo4j.org/neo4j-community-5.16.0-unix.tar.gz tar -xzf neo4j-community-5.16.0-unix.tar.gz cd neo4j-community-5.16.0 # 2. 下载APoC插件版本必须严格匹配 wget https://github.com/neo4j-contrib/neo4j-apoc-procedures/releases/download/5.16.0/apoc-5.16.0-all.jar mkdir plugins mv apoc-5.16.0-all.jar plugins/ # 3. 修改配置文件这是血泪经验 echo dbms.security.procedures.unrestrictedapoc.* conf/neo4j.conf echo dbms.directories.plugins/path/to/neo4j-community-5.16.0/plugins conf/neo4j.conf # 注意上面的路径必须是绝对路径且Neo4j进程用户通常是neo4j要有读权限 # 4. 启动首次启动会初始化数据库 bin/neo4j start # 访问 http://localhost:7474用neo4j/neo4j登录首次会强制改密码提示如果bin/neo4j status显示not running先看logs/neo4j.log。90%的失败是plugins目录权限问题——执行sudo chown -R neo4j:neo4j plugins/再sudo chmod 755 plugins/。3.2 导入医疗知识数据含校验逻辑项目自带的data/目录是精简样本共3类JSON约1200条记录但结构完整。导入前务必确认JSON字段与Cypher模板匹配// data/medicines.json 片段 [ { name: 阿司匹林, generic_name: 乙酰水杨酸, atc_code: B01AC06, contraindications: [胃溃疡, 哮喘], pregnancy_category: C, metabolized_by: [CYP2C9] } ]执行导入# 进入Neo4j Shell确保数据库已启动 bin/cypher-shell -u neo4j -p your_new_password # 在Shell中执行注意路径是Neo4j容器内的路径 :source /path/to/kg-medical/scripts/init_db.cypher :source /path/to/kg-medical/scripts/load_all.cqlinit_db.cypher会创建关键索引CREATE INDEX disease_name_index ON :Disease(name); CREATE INDEX medicine_name_index ON :Medicine(name); CREATE CONSTRAINT ON (d:Disease) ASSERT d.icd_code IS UNIQUE;没有这些索引后续查询会慢10倍以上且MERGE操作可能产生重复节点。3.3 启动Flask服务并验证接口# 安装Python依赖建议用venv python -m venv venv source venv/bin/activate # Windows用 venv\Scripts\activate pip install -r requirements.txt # 启动后端默认监听5000端口 python app.py验证是否通# 测试健康检查 curl http://localhost:5000/health # 返回 {status:ok,neo4j:connected} # 测试一个简单查询查疾病症状 curl http://localhost:5000/ask?question高血压有什么症状 # 应返回JSON{answer:[头痛,头晕,心悸],sources:[ICD-10 I10,高血压防治指南2023]}注意app.py里NEO4J_URI默认是neo4j://localhost:7687如果你改了Neo4j端口必须同步修改。别信网上教程说的bolt://——Neo4j 5.x已弃用Bolt URI用它会报ServiceUnavailable: Unable to connect...。4. 避坑指南那些让你调试到凌晨三点的Neo4j玄学问题部署医疗知识图谱最痛苦的不是写代码而是和Neo4j的“不可描述行为”搏斗。以下是我在三个不同项目中反复踩过的坑按发生频率排序4.1 现象apoc.load.json报错Failed to load from file但文件明明存在原因Neo4j 5.x默认只允许从import/目录读文件且路径必须是相对于Neo4j安装目录的相对路径。你写的file:///data/medicines.json会被解释为/var/lib/neo4j/import/data/medicines.json而非你本地的/home/user/kg-medical/data/。解决把kg-medical/data/整个目录复制到Neo4j的import/目录下cp -r /path/to/kg-medical/data /var/lib/neo4j/import/修改scripts/load_all.cql中的路径// 改前 CALL apoc.load.json(file:///data/medicines.json) // 改后去掉开头的/因为import/是根 CALL apoc.load.json(data/medicines.json)4.2 现象查询返回空结果但用Neo4j Browser手动执行Cypher却有数据原因Flask后端用session.run()执行Cypher时参数传递方式错误。常见误写# 错误字符串拼接导致注入风险且大小写敏感 result session.run(fMATCH (m:Medicine) WHERE m.name {drug} RETURN m) # 正确用参数化查询且注意Neo4j对中文字段名的处理 result session.run( MATCH (m:Medicine) WHERE m.name $name RETURN m, namedrug # 这里drug是变量不是字符串字面量 )解决检查app.py中所有session.run()调用确保100%使用$param占位符。医疗数据里“阿司匹林”和“阿斯匹林”常并存大小写不敏感查询要显式写WHERE toLower(m.name) toLower($name)4.3 现象前端输入“糖尿病”返回“未找到相关疾病”但Neo4j Browser里MATCH (:Disease {name:糖尿病})能查到原因diseases.json里“糖尿病”的name字段值是2型糖尿病而用户问的是泛称。这不是Bug是数据建模问题——图谱里没建立糖尿病到2型糖尿病的SYNONYM_OF关系。解决手动添加同义词关系临时方案MATCH (d1:Disease {name:糖尿病}), (d2:Disease {name:2型糖尿病}) CREATE (d1)-[:SYNONYM_OF]-(d2)长期方案修改import_data.py在导入时自动合并同义词用Jieba分词识别“X型Y病”模式将“糖尿病”作为“2型糖尿病”的别名节点。4.4 现象import_data.py运行时报UnicodeDecodeError: utf-8 codec cant decode byte 0xff原因Windows下用记事本保存的JSON文件默认是GBK编码而Python 3默认用UTF-8读。解决用VS Code打开JSON文件右下角点击编码如GBK选择“Reopen with Encoding”→“UTF-8”再保存。或者在Python脚本中强制指定编码with open(data/diseases.json, r, encodingutf-8) as f: data json.load(f)4.5 现象Neo4j Browser里MATCH (n) RETURN count(n)返回0但load_all.cql显示“1200 rows imported”原因apoc.periodic.iterate批量导入时事务未提交。常见于load_all.cql末尾缺少COMMIT或导入过程中断导致事务挂起。解决在Neo4j Browser中执行CALL dbms.listTransactions() YIELD transactionId, status, startTime WHERE status Running CALL dbms.killTransaction(transactionId) YIELD transactionId AS killed RETURN killed重启Neo4j服务bin/neo4j restart。5. 核心模块拆解query_kg()函数如何把“高血压能吃柚子吗”翻译成Cypher问答逻辑不在NLP模型里而在app.py的query_kg()函数和templates/下的23个Cypher模板中。它用最朴素的规则匹配实现高准确率——因为医疗问题类型有限且每个类型都有强结构化特征。下面逐行拆解这个函数它只有47行但撑起了整个问答引擎。5.1 意图识别不用机器学习用正则和关键词白名单def detect_intent(question: str) - str: question question.strip() # 规则1含“禁忌”、“不能吃”、“慎用” → 药物禁忌查询 if re.search(r(禁忌|禁用|不能吃|慎用|避免|不宜), question): return drug_contraindication # 规则2含“相互作用”、“一起吃”、“合用” → 药物相互作用 if re.search(r(相互作用|一起吃|合用|联用|配伍), question): return drug_interaction # 规则3含“症状”、“表现”、“有哪些” → 疾病症状 if re.search(r(症状|表现|有哪些|什么表现|常见), question): # 进一步提取疾病名这里简化实际用jieba词典 disease_match re.search(r(.?)的?症状, question) if disease_match: return fdisease_symptom:{disease_match.group(1).strip()} # 默认 fallback 到全文模糊搜索用fulltext index return fulltext_search注意disease_symptom:{disease}这种返回值——它不是最终意图而是带参数的意图标识符后续会拆解出疾病名传给Cypher模板。这种设计让意图识别和查询生成解耦你新增一个意图只需在detect_intent()加一条if再在templates/加一个.cql文件不用动查询执行逻辑。5.2 Cypher模板渲染安全拼接杜绝注入templates/disease_symptom.cql内容如下// 模板变量$disease_name由detect_intent提取 MATCH (d:Disease {name: $disease_name}) OPTIONAL MATCH (d)-[r:HAS_SYMPTOM]-(s:Symptom) RETURN d.name AS disease, COLLECT(DISTINCT s.name) AS symptoms, COUNT(s) AS symptom_count关键点在于所有用户输入都作为参数$disease_name传入而非字符串拼接使用OPTIONAL MATCH而非MATCH避免因某疾病无症状关系导致整条记录丢失COLLECT(DISTINCT s.name)去重因为同一症状可能通过不同路径关联如“头痛”既属于高血压也属于偏头痛。5.3 查询执行与结果组装带溯源的答案def query_kg(question: str): intent detect_intent(question) # 解析带参数的意图如 disease_symptom:高血压 if : in intent: template_name, param intent.split(:, 1) params {disease_name: param} else: template_name intent params {} # 读取模板文件 with open(ftemplates/{template_name}.cql, r, encodingutf-8) as f: cypher f.read() # 执行查询 with driver.session() as session: result session.run(cypher, **params) # **params安全传参 records list(result) # 组装答案重点带上溯源 if not records: return {answer: [未找到相关信息], sources: []} record records[0] answer record[symptoms] if symptoms in record else [record[disease]] # 溯源找关联的指南节点 sources [] if disease in record: with driver.session() as session: src_result session.run( MATCH (d:Disease {name: $name})-[:GUIDELINE_RECOMMENDED]-(g:Guideline) RETURN g.name AS guideline, g.year AS year, namerecord[disease] ) for src in src_result: sources.append(f{src[guideline]}({src[year]})) return {answer: answer, sources: sources}这个函数的威力在于sources数组不是硬编码而是动态查询图谱中GUIDELINE_RECOMMENDED关系当你往图谱里新增一条(:Disease {name:高血压})-[:GUIDELINE_RECOMMENDED]-(:Guideline {name:中国高血压防治指南, year:2023})下次查询就自动带上来源如果某疾病没关联指南sources就是空数组不会报错。6. 二次开发实战给图谱加“药物代谢酶”推理能力三步完成医疗知识图谱的价值不在静态存储而在动态推理。比如医生问“CYP2C9慢代谢型患者华法林起始剂量怎么调”——这需要把“华法林被CYP2C9代谢”和“CYP2C9慢代谢型增加出血风险”两条知识链起来。原项目没做这层但加起来只要三步且不改任何现有代码。6.1 第一步扩展图谱结构加节点和关系原图谱只有Medicine和Enzyme节点但没定义代谢关系。我们在data/medicines.json里为华法林加字段{ name: 华法林, metabolized_by: [CYP2C9, CYP3A4], metabolism_impact: { CYP2C9: 慢代谢型患者AUC升高2-3倍INR延长 } }然后修改scripts/load_all.cql在药品导入部分加代谢关系// 在LOAD medicines.json循环内追加 UNWIND $value.metabolized_by AS enzyme_name MATCH (m:Medicine {name: $value.name}) MERGE (e:Enzyme {name: enzyme_name}) CREATE (m)-[r:METABOLIZED_BY {impact: $value.metabolism_impact[enzyme_name]}]-(e)执行后图谱里就多了(:Medicine)-[:METABOLIZED_BY {impact:... }]-(:Enzyme)关系。6.2 第二步新增Cypher模板templates/enzyme_dosing.cql// 输入参数$enzyme_name如CYP2C9$phenotype如慢代谢型 MATCH (m:Medicine)-[r:METABOLIZED_BY]-(e:Enzyme {name: $enzyme_name}) WHERE r.impact CONTAINS $phenotype RETURN m.name AS medicine, r.impact AS dosing_advice, 基于药物代谢酶表型调整 AS reason这个模板的关键是r.impact CONTAINS $phenotype——它利用Neo4j的字符串匹配避免建复杂的表型节点。实际项目中你可以把表型做成独立节点用(:Phenotype)-[:AFFECTS]-(:Enzyme)关系但对快速验证字符串匹配够用。6.3 第三步扩展意图识别改detect_intent()在app.py的detect_intent()函数末尾加# 新增规则含“CYP”、“代谢”、“表型”、“慢代谢” → 酶表型用药建议 if re.search(r(CYP\d|代谢|表型|快代谢|慢代谢|中间代谢), question): # 提取CYP编号和表型正则略实际用更健壮的匹配 enzyme_match re.search(rCYP(\d), question) phenotype_match re.search(r(快|慢|中间)代谢, question) if enzyme_match and phenotype_match: enzyme fCYP{enzyme_match.group(1)} phenotype phenotype_match.group(0) return fenzyme_dosing:{enzyme}:{phenotype}然后在query_kg()里解析这个新意图if : in intent and intent.startswith(enzyme_dosing:): parts intent.split(:) enzyme, phenotype parts[1], parts[2] params {enzyme_name: enzyme, phenotype: phenotype} template_name enzyme_dosing现在测试curl http://localhost:5000/ask?questionCYP2C9慢代谢型患者华法林怎么吃 # 返回{answer:[华法林,慢代谢型患者AUC升高2-3倍INR延长],sources:[基于药物代谢酶表型调整]}从那以后我每次给医疗图谱加新能力都强制走一遍“扩数据→加模板→改意图”三步闭环。不碰核心查询引擎不改前端所有变更都在data/、templates/、app.py的detect_intent()三处上线前用pytest跑5个边界用例如空输入、错别字、多关键词就敢推生产。希望帮到你。本文还有配套的精品资源点击获取
