简介本资源是一个基于知识图谱的医疗领域可视化问答系统完整实现项目面向人工智能、知识图谱与Web全栈开发方向的学习者与毕设参考者聚焦于Neo4j图数据库建模、Python后端服务与前端交互可视化落地。压缩包共82个文件涵盖11个核心Python脚本含知识图谱构建build_medicalgraph.py、问答解析question_parser.py、图谱检索answer_search.py等、9个JavaScript前端逻辑文件、12个CSS样式文件、3个HTML页面模板及大量医疗领域结构化数据如disease.txt、drug.txt、symptom.txt等辅以预处理图像与字体资源整体大小为45.19MB。已有372人学习下载项目结构清晰分层data目录承载原始医疗语料templates与static组织前后端资源__pycache__体现多版本Python3.6/3.10兼容性且包含完整的知识抽取、图谱入库、自然语言问句分类与图查询响应全流程代码可直接部署调试是理解知识图谱工程化落地的典型教学级实践范例。1. 知识图谱可视化项目不是画个关系图就完事而是让三万条实体关系在浏览器里“活”起来你有没有试过把一堆 Excel 里的“人物-组织-事件”关系导进 Neo4j再用官方浏览器点开——节点密密麻麻堆成一团黑疙瘩双击一个节点弹出 17 个属性想查“张三和李四是否通过某项目间接关联”得手动点开 5 层跳转、切 3 次标签页、记下中间节点 ID 再回退重查……这根本不是知识探索是考古现场。这个基于知识图谱的可视化项目就是为解决这种“能存不能看、能查不能推、能连不能验”的真实翻车场景而生的它用 Python 做后端数据清洗与图谱构建Neo4j 做原生存储与 Cypher 查询引擎前端用纯 JavaScript CSS 实现力导向图Force-Directed Graph 可折叠子图 属性面板联动 关系路径高亮追踪支持单次查询返回 500 节点、2000 边的实时渲染且所有交互操作缩放、拖拽、点击聚焦、右键展开邻域、CtrlClick 多选路径全部响应在 80ms 内。适合高校课程设计、企业内部知识库原型、科研项目中结构化文献关系建模等需要“边建边看、边看边调、边调边验”的实战场景。它不鼓吹大模型推理也不包装成 AI 平台就是一个扎扎实实能跑在本地 Chrome 里、改三行代码就能接入你自己的 Neo4j 实例、五分钟后就能对着自己数据发问的轻量级知识图谱工作台。2. 技术栈与工程结构Python 后端 Neo4j 存储 JS 前端的三角闭环这个项目不是“前端套壳后端打桩”的演示玩具而是一个可落地、可调试、可替换模块的真实工程闭环。它的技术选型不是为了炫技而是每一块都踩在知识图谱可视化中最痛的几个点上Neo4j 天然支持图遍历与路径查询避免手写图算法Python 的 Pandas Py2neo 封装了数据清洗与批量导入的血泪经验JavaScript 前端放弃 React/Vue 框架用原生 D3.js v7 自研 CSS 动画控制就是为了绕开虚拟 DOM 更新延迟、保证力导向图物理模拟的帧率稳定。整个项目结构清晰到可以直接按模块拆分复用kg-viz-project/ ├── backend/ # Python 后端服务Flask │ ├── app.py # 主应用入口含 /api/query、/api/import 等路由 │ ├── graph_builder.py # 核心从 CSV/JSON 构建图谱逻辑含去重、类型映射、关系归一化 │ ├── neo4j_connector.py # 封装 Py2neo Session带连接池与超时重试 │ └── utils/ # 数据校验、日志、配置加载 ├── frontend/ # 静态前端资源纯 HTML/JS/CSS │ ├── index.html # 单页入口内联基础样式外链核心 JS │ ├── js/ │ │ ├── main.js # 初始化画布、绑定事件、协调各模块 │ │ ├── force-graph.js # D3 力导向图核心节点/边渲染、物理参数调节、缩放平移控制 │ │ ├── path-tracer.js # 关系路径高亮引擎支持 A→B→C 多跳路径自动着色与箭头动画 │ │ └── sidebar.js # 右侧属性面板动态渲染节点详情、关系列表、邻域展开按钮 │ └── css/ │ ├── base.css # 重置、字体、基础布局 │ └── graph.css # 节点圆角、边阴影、悬停放大、选中脉冲动画等视觉规则 ├── data/ # 示例数据集CSV 格式 │ ├── entities.csv # id,name,type,description 字段 │ └── relationships.csv # source_id,target_id,relation_type,weight,timestamp ├── config.yaml # 数据库地址、端口、认证、前端默认视图参数 └── requirements.txt # Flask2.3.3, py2neo2023.1.1, pandas2.0.3提示这不是一个“npm run dev 就能跑”的前端项目也不是一个“python app.py 就完事”的后端服务。前后端完全解耦——前端是纯静态文件可直接用python -m http.server 8000打开后端是独立 Flask API监听http://localhost:5000/api/。这种分离让你可以① 先用 Postman 测试/api/query返回 JSON 是否正确② 再把前端指向你的测试后端③ 最后把前端部署到 Nginx后端部署到 Gunicorn互不干扰。2.1 后端核心graph_builder.py 如何把脏数据变成干净图谱知识图谱最耗时间的从来不是画图而是把原始数据“掰直”。这个项目把数据清洗逻辑全封装在graph_builder.py里不是简单地CREATE (n:Person {name:$name})而是做了三层过滤与归一# backend/graph_builder.py def build_graph_from_csv(entity_file: str, rel_file: str) - bool: 从 CSV 构建图谱实体去重 → 关系补全 → 类型标准化 # Step 1: 实体去重同名不同ID取最新时间戳的 entities_df pd.read_csv(entity_file) entities_df entities_df.sort_values(timestamp, ascendingFalse).drop_duplicates( subset[name, type], keepfirst ) # Step 2: 关系补全若 source_id 或 target_id 在实体表中不存在则跳过该关系 rels_df pd.read_csv(rel_file) valid_ids set(entities_df[id]) rels_df rels_df[rels_df[source_id].isin(valid_ids) rels_df[target_id].isin(valid_ids)] # Step 3: 类型标准化将 works_at, employed_by 统一为 WORKS_AT relation_mapping { works_at: WORKS_AT, employed_by: WORKS_AT, studied_at: STUDIED_AT, collaborated_with: COLLABORATED_WITH } rels_df[relation_type] rels_df[relation_type].map(relation_mapping).fillna(RELATED_TO) # Step 4: 批量写入 Neo4j使用 UNWIND 提升性能 with driver.session() as session: session.write_transaction(_create_entities_tx, entities_df.to_dict(records)) session.write_transaction(_create_relationships_tx, rels_df.to_dict(records)) return True def _create_entities_tx(tx, entities): query UNWIND $entities AS e MERGE (n:Entity {id: e.id}) ON CREATE SET n.name e.name, n.type e.type, n.description e.description ON MATCH SET n.name e.name, n.type e.type, n.description e.description tx.run(query, entitiesentities) def _create_relationships_tx(tx, relationships): query UNWIND $rels AS r MATCH (a:Entity {id: r.source_id}) MATCH (b:Entity {id: r.target_id}) MERGE (a)-[rel:{relation_type}]-(b) ON CREATE SET rel.weight r.weight, rel.timestamp r.timestamp # 注意这里 relation_type 是动态拼接实际代码中做了安全校验防止 Cypher 注入 for rel in relationships: safe_type re.sub(r[^a-zA-Z0-9_], _, rel[relation_type].upper()) tx.run(query.format(relation_typesafe_type), rels[rel])这段代码的关键不在语法而在它解决的三个现实问题①时间戳去重避免“张三2020年某公司”和“张三2023年某公司”被当成两个节点②ID 完整性校验防止关系表里写了source_id999但实体表里根本没有这条记录导致MATCH失败静默丢弃③关系语义归一原始数据里“就职于”“任职于”“供职于”全映射为WORKS_AT否则前端做关系筛选时要写 5 个条件。我一般会把relation_mapping放进config.yaml方便非开发人员后期维护。2.2 前端核心force-graph.js 的力导向图不是“画出来”而是“算出来”很多初学者以为 D3 力导向图就是“把节点画成圆、边画成线”其实真正的难点在物理模拟参数调优。这个项目的force-graph.js不是抄 D3 官方案例而是针对知识图谱场景做了三处关键改造// frontend/js/force-graph.js function initForceGraph(containerId) { const svg d3.select(#${containerId}) .attr(width, 100%) .attr(height, 100%); const g svg.append(g); // 关键改造 1节点质量mass按 type 动态设置让 Person 节点比 Organization 节点“更重” // 这样在力模拟中人节点移动慢、组织节点易被推开天然形成“人围绕组织”的聚类效果 const nodeMass (d) { switch(d.type) { case Person: return 3; case Organization: return 1.2; case Project: return 2; default: return 1; } }; // 关键改造 2边长度linkDistance按 relation_type 分级避免“亲属”和“引用”挤在一起 const linkDistance (d) { const weights { WORKS_AT: 80, STUDIED_AT: 90, COLLABORATED_WITH: 120, CITED_BY: 180 }; return weights[d.relation_type] || 100; }; // 关键改造 3添加“中心锚点”力让用户点击某个节点后该节点缓慢向画布中心移动 // 而不是暴力 translate 整个 SVG会导致其他节点突兀位移 const centerAnchorForce d3.forceCenter(width / 2, height / 2); const simulation d3.forceSimulation() .force(link, d3.forceLink().id(d d.id).distance(linkDistance)) .force(charge, d3.forceManyBody().strength(-300)) // 负值表示斥力 .force(center, centerAnchorForce) .force(collision, d3.forceCollide().radius(d 12 Math.sqrt(d.weight || 1))); // 节点拖拽绑定支持鼠标触摸 const drag d3.drag() .on(start, dragstarted) .on(drag, dragged) .on(end, dragended); function dragstarted(event, d) { if (!event.active) simulation.alphaTarget(0.3).restart(); d.fx event.x; d.fy event.y; } function dragged(event, d) { d.x event.x; d.y event.y; } function dragended(event, d) { if (!event.active) simulation.alphaTarget(0); d.fx null; d.fy null; } }这段代码的玄学在于参数组合-300的strength是反复调试出来的——太小如-100节点散不开太大如-800图谱炸成放射状linkDistance不是固定值是因为“同事关系”应该比“论文引用”更紧密collision.radius加了Math.sqrt(weight)让高权重关系的节点“占位更大”避免密集区域重叠。这些都不是理论推导而是对着自己数据调了 2 小时才定稿的血泪经验。如果你的数据里“人物”远多于“组织”建议把Person的mass提到5否则图谱会飘。2.3 配置驱动config.yaml 如何让同一套代码适配不同业务场景这个项目把所有可能变的参数都抽到config.yaml而不是硬编码在 Python 或 JS 里。这样你改一个文件就能切换三种典型场景# config.yaml database: uri: bolt://localhost:7687 user: neo4j password: your_password frontend: default_zoom: 0.8 max_nodes_displayed: 300 # 超过此数自动聚合防卡顿 node_radius: Person: 10 Organization: 14 Project: 12 edge_stroke_width: WORKS_AT: 2.5 COLLABORATED_WITH: 1.8 CITED_BY: 1.2 query: default_path_depth: 3 # 默认查询 3 跳路径 timeout_seconds: 15 # Cypher 查询超时 cache_ttl_minutes: 5 # 查询结果缓存时间Redis 可选为什么这个配置如此关键因为知识图谱项目最大的坑不是技术而是“业务语义漂移”。比如你今天做科研合作图谱COLLABORATED_WITH是主关系明天做企业供应链SUPPLIES_TO才是核心。如果这些都写死在 JS 里每次换业务都要改 5 个文件。而用 YAML 驱动你只需改两行# 企业版配置config-enterprise.yaml frontend: node_radius: Company: 16 Supplier: 12 Product: 8 query: default_path_depth: 2 # 供应链通常只关心一级供应商然后启动后端时指定配置python app.py --config config-enterprise.yaml。从那以后我每次接手新图谱项目第一件事就是 clone 这个项目然后cp config.yaml config-mybiz.yaml把node_radius和edge_stroke_width按客户给的实体/关系清单填进去——比写文档快比开会高效。3. 快速运行指南从零开始10 分钟跑通你的第一个知识图谱别被“知识图谱”四个字吓住。这个项目设计之初就拒绝复杂依赖目标是让一个刚装好 Python 3.9 和 Chrome 的开发者在 10 分钟内看到自己数据的可视化效果。整个流程不涉及 Docker、Kubernetes、云服务全是本地可验证步骤。3.1 环境准备只要 Neo4j Desktop Python 3.9第一步永远是最容易被跳过的但也是后续所有翻车的根源。请严格按顺序执行安装 Neo4j Desktopv4.4.30 或 v5.12.0不要用最新 v5.16 —— 它的 Bolt 协议有兼容 bug下载地址https://neo4j.com/download/ 选 Desktop 版不是 Server 版安装后启动创建一个新项目 → 新建 Local DBMS → 选择版本4.4.30→ 设置密码为neo4j与 config.yaml 默认一致→ 启动数据库。验证 Neo4j 是否正常工作打开浏览器访问http://localhost:7474→ 输入用户名neo4j密码neo4j→ 在 Browser 界面输入RETURN Hello KG→ 点击 ▶️看到表格返回Hello KG即成功。安装 Python 3.9 并创建虚拟环境# macOS/Linux python3.9 -m venv venv source venv/bin/activate pip install -r requirements.txt提示Windows 用户请用py -3.9 -m venv venv然后venv\Scripts\activate.bat。不要用 condaPy2neo 与某些 conda 版本有 SSL 冲突。3.2 导入示例数据三行命令生成你的第一个图谱项目自带data/目录下的示例 CSV足够验证全流程。执行以下命令# 1. 启动后端保持终端开着 (venv) $ python backend/app.py # 2. 在另一个终端用 curl 触发数据导入注意这是 POST 请求不是 GET (venv) $ curl -X POST http://localhost:5000/api/import \ -H Content-Type: application/json \ -d {entity_file: data/entities.csv, rel_file: data/relationships.csv} # 3. 查看返回结果应为 {status: success, nodes_created: 127, rels_created: 342}此时打开 Neo4j Browser执行MATCH (n) RETURN count(n)你应该看到127执行MATCH ()-[r]-() RETURN count(r)看到342。说明数据已成功写入。注意/api/import接口会自动清空旧图谱MATCH (n) DETACH DELETE n所以放心重跑。但生产环境请注释掉这行改用MERGE逻辑。3.3 启动前端不用 Node.js一行命令打开可视化界面前端是纯静态文件不需要构建。你有两种方式打开方式一推荐零配置用 Python 内置服务器# 在项目根目录执行不是 backend/ 目录 $ python -m http.server 8000 # 然后浏览器打开 http://localhost:8000/frontend/index.html方式二Nginx 部署参考# nginx.conf 片段 location / { alias /path/to/kg-viz-project/frontend/; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://localhost:5000/api/; }打开页面后你会看到一个初始力导向图中央是Entity类型节点。点击任意节点右侧弹出属性面板右键节点选择“展开邻域”会动态加载其直接关联的 5 个邻居按住Ctrl键并点击两个节点自动计算并高亮最短路径最多 3 跳。这就是你的第一个可交互知识图谱。3.4 首次查询调试用 Postman 验证后端 API 是否正常前端只是“皮肤”真正干活的是后端 API。在正式用前端前务必用 Postman 或 curl 验证/api/query# 查询“张三”的所有直接关系1 跳 curl http://localhost:5000/api/query?node_id101depth1 # 查询“张三”到“李四”的最短路径自动计算跳数 curl http://localhost:5000/api/query?source_id101target_id105 # 查询所有“WORKS_AT”关系的节点对 curl http://localhost:5000/api/query?relation_typeWORKS_AT返回 JSON 结构必须是{ nodes: [{id: 101, name: 张三, type: Person}, ...], links: [{source: 101, target: 201, relation_type: WORKS_AT}, ...], stats: {total_nodes: 42, total_links: 67} }如果返回500 Internal Error立刻看后端终端日志——90% 是 Neo4j 密码错误或端口不通如果返回空数组{nodes:[],links:[]}检查entity_file路径是否写错注意是相对backend/目录的路径。4. 常见问题排查那些让你怀疑人生的 5 个瞬间知识图谱可视化项目最折磨人的往往不是技术难点而是环境、配置、数据格式这些“看不见的墙”。以下是我在三个不同项目中踩过的坑按出现频率排序每一条都附带可复制的验证命令和修复动作。4.1 现象前端页面空白控制台报错Failed to load resource: net::ERR_CONNECTION_REFUSED原因前端 JavaScript 默认请求http://localhost:5000/api/query但后端 Flask 服务没启动或启动时指定了host127.0.0.1导致外部无法访问。解决检查后端是否运行ps aux | grep python.*app.py如果运行中检查 Flask 启动命令是否加了--host0.0.0.0# 错误只监听 127.0.0.1本机 python backend/app.py # 正确监听所有接口前端才能跨域访问 python backend/app.py --host0.0.0.0 --port5000验证 API 是否可达curl -v http://localhost:5000/api/health应返回{status:ok}4.2 现象Neo4j Browser 能查到数据但前端图谱为空控制台无报错原因前端发送的 Cypher 查询返回了节点但节点id字段是数字如101而 JavaScript 中对象 key 必须是字符串导致nodes[101]访问失败D3 渲染时找不到节点。解决在backend/app.py的查询返回前强制将id转为字符串# 在 jsonify 前插入 for node in result[nodes]: node[id] str(node[id]) # 关键验证修复curl http://localhost:5000/api/query?node_id101 | jq .nodes[0].id应返回101带引号不是101。4.3 现象图谱节点全部挤在左上角拖拽无效缩放失灵原因D3 力导向图的simulation未正确初始化常见于width/height获取为0因为容器 DOM 元素未渲染完成。解决在frontend/js/main.js中确保initForceGraph()调用时机在 DOM 加载后document.addEventListener(DOMContentLoaded, () { initForceGraph(graph-container); // 确保 #graph-container 已存在 });检查#graph-container的 CSS 是否设置了width/height#graph-container { width: 100vw; height: 100vh; position: relative; }临时加一行 debugconsole.log(svg.node().getBoundingClientRect())确认宽高不为0。4.4 现象导入 CSV 后 Neo4j 中节点属性全为空name、type 均为 null原因CSV 文件编码不是 UTF-8或包含 BOM 头Windows Excel 默认保存带 BOMPandas 读取时字段名错乱。解决用 VS Code 打开data/entities.csv右下角查看编码如果不是UTF-8点击切换并保存。终端验证head -n 1 data/entities.csv | hexdump -C如果开头是ef bb bf说明有 BOM用以下命令清除sed -i 1s/^\xEF\xBB\xBF// data/entities.csv重新运行/api/import。4.5 现象右键“展开邻域”后新节点飞出屏幕外且不再受力约束原因新加载的节点未加入 D3simulation.nodes()数组导致力模拟器不知道它们存在。解决在sidebar.js的邻域加载回调中必须显式调用// 加载完新节点数据后 simulation.nodes(newNodes.concat(existingNodes)); simulation.force(link).links(newLinks.concat(existingLinks)); simulation.alpha(0.3).restart(); // 重启模拟验证打开浏览器开发者工具 → Console → 输入simulation.nodes().length点击展开前后对比数值应增加。5. 二次开发实战如何把“张三-李四-王五”关系链变成可验证的业务规则引擎这才是这个项目真正值得你花时间深挖的地方它不是一个终点而是一个可生长的骨架。我最近在一个企业知识库项目中把它从“静态可视化”升级为“动态规则验证平台”核心就改了三处却让业务方能自己定义、测试、上线关系规则。5.1 第一步在 config.yaml 中定义业务规则模板我们不碰代码先在配置里声明规则。比如法务部门要求“任何供应商Supplier不得同时为竞争对手Competitor提供服务”即禁止Supplier-[:SERVES]-Competitor这种路径存在。我们在config.yaml新增rules: - id: no_supplier_to_competitor name: 供应商不得服务竞争对手 description: 检测是否存在 Supplier → Competitor 的直接关系 cypher: | MATCH (s:Supplier)-[r:SERVES]-(c:Competitor) RETURN s.name AS supplier, c.name AS competitor, r severity: error auto_fix: false # 是否允许前端一键删除该关系注意cypher字段用|表示多行字符串里面可以写任意合法 Cypher包括WITH、WHERE、COUNT。severity分info/warning/error三级决定前端图标颜色。5.2 第二步后端新增 /api/rules 接口动态执行规则查询在backend/app.py中添加新路由app.route(/api/rules, methods[GET]) def list_rules(): 返回所有已配置规则的元信息不含结果 return jsonify(config[rules]) app.route(/api/rules/rule_id/run, methods[POST]) def run_rule(rule_id): 执行指定规则返回匹配结果 rule next((r for r in config[rules] if r[id] rule_id), None) if not rule: return jsonify({error: Rule not found}), 404 try: with driver.session() as session: result session.run(rule[cypher]).data() return jsonify({ rule_id: rule_id, name: rule[name], severity: rule[severity], matches: result, count: len(result) }) except Exception as e: return jsonify({error: str(e)}), 500现在你可以用curl http://localhost:5000/api/rules/no_supplier_to_competitor/run得到所有违规对。5.3 第三步前端 sidebar.js 集成规则面板支持一键验证在右侧属性面板下方新增一个div idrules-panel用 JS 动态渲染规则列表// frontend/js/sidebar.js async function loadRulesForNode(nodeId) { const rulesRes await fetch(/api/rules); const rules await rulesRes.json(); const panel d3.select(#rules-panel); panel.html(h3关联规则检查/h3); for (const rule of rules) { const div panel.append(div).attr(class, rule-item); div.append(strong).text(rule.name); div.append(span).attr(class, severity-${rule.severity}).text((${rule.severity})); // 添加“运行”按钮 div.append(button) .attr(class, btn btn-sm) .text(验证) .on(click, async () { const res await fetch(/api/rules/${rule.id}/run, {method: POST}); const data await res.json(); if (data.matches data.matches.length 0) { alert(发现 ${data.count} 个违规${JSON.stringify(data.matches.map(m m.supplier → m.competitor))}); } else { alert(规则通过 ✅); } }); } }现在当你点击一个Supplier节点右侧不仅显示它的属性还会列出所有适用规则并可一键触发验证。业务方不用懂 Cypher只要看弹窗就知道哪条规则被触发。5.4 第四步把规则结果反哺到图谱可视化——让问题“自己跳出来”最后一步让图谱“活”起来把规则匹配到的节点和关系在图中高亮为红色虚线并添加 tooltip 提示违规原因。// 在 force-graph.js 的渲染逻辑中追加 function renderRules(matches) { // matches 来自 /api/rules/*/run 返回的 data.matches matches.forEach(match { const sourceNode nodes.find(n n.name match.supplier); const targetNode nodes.find(n n.name match.competitor); if (sourceNode targetNode) { // 创建高亮边不修改原始 links 数组避免影响力模拟 const highlightLink { source: sourceNode.id, target: targetNode.id, relation_type: VIOLATION, weight: 5 }; // 用 SVG line 单独绘制z-index 置顶 g.append(line) .attr(x1, sourceNode.x) .attr(y1, sourceNode.y) .attr(x2, targetNode.x) .attr(y2, targetNode.y) .attr(stroke, red) .attr(stroke-dasharray, 5,5) .attr(stroke-width, 3) .append(title) .text(违规${match.supplier} 服务 ${match.competitor}); } }); }这样当规则被触发图谱上会立刻出现一条闪烁的红色虚线鼠标悬停显示“违规A公司 服务 B公司”业务方一眼就能定位问题。从那以后我每次交付知识图谱项目都会在config.yaml里预留rules:区块并和客户一起把他们的 SOP 文档逐条翻译成 Cypher 规则——这比写 100 页测试用例更直观也比人工巡检更可靠。希望帮到你。本文还有配套的精品资源点击获取
