简介这是一套面向Python初学者与知识图谱入门者的实战项目资源基于Flask框架构建三国演义人物关系可视化及智能问答系统解决古典文学数据结构化分析与交互式探索的实际问题。资源包共364个文件含12个核心Python脚本实现后端逻辑、图谱构建与问答接口、4个HTML前端页面、11个CSS与8个JS文件支撑BootstrapDatatables的响应式可视化界面、306张人物关系图谱截图及3个JSON格式结构化数据集整体压缩包仅8.45MB轻量易部署。已有217人学习下载配套提供完整部署文档、清晰目录结构说明及开箱即用的数据替换方案。读者可直接运行服务查看动态力导向图谱、检索人物关系链路并通过自然语言提问获取答案同时掌握Flask Web开发、Neo4j或NetworkX图谱建模、前端可视化集成等关键技术环节。1. 项目概述当三国演义遇上知识图谱最近在整理个人项目库时翻出了一个几年前做过的“老伙计”——一个基于Flask和知识图谱的三国演义人物关系可视化及问答系统。这个项目虽然技术栈不算最新潮但它的设计思路和实现路径对于想入门知识图谱应用、或者想结合经典文本做点有趣可视化的小伙伴来说依然有很强的参考价值。它本质上是一个将非结构化的文本《三国演义》小说转化为结构化的知识网络并提供一个交互界面让用户既能“看图说话”也能“有问必答”的系统。简单来说这个项目干了三件事第一它把《三国演义》里上百号人物、他们之间的亲属、隶属、敌对、合作等复杂关系从文字描述里“抽”出来变成一张巨大的、可追溯的关系网。第二它用可视化的方式把这张网清晰地呈现出来你可以像查看地图一样直观地看到“曹操”周围围绕着哪些文臣武将他和“刘备”之间隔着多少层恩怨。第三它内置了一个简单的问答引擎你不再需要去翻书查“关羽的结拜兄弟是谁”直接输入问题系统就能从构建好的知识图谱里找到答案并返回。对于历史爱好者、文学研究者或者单纯对数据可视化感兴趣的程序员这个项目都是一个很好的练手素材它能让你亲身体验从数据获取、知识建模、存储到应用开发的全流程。2. 核心架构与工具选型解析2.1 为什么是Flask Neo4j这个组合当初选择这个技术栈是经过一番权衡的。核心需求很明确需要一个轻量级的Web框架来快速搭建前后端以及一个专门为图数据设计的数据库来高效存储和查询人物关系。后端框架FlaskFlask是一个Python的微型Web框架它的“微”体现在核心简洁但扩展性极强。对于这个项目来说它有几个无法拒绝的优点快速上手相比于Django那种“全家桶”式框架Flask的学习曲线平缓几行代码就能跑起一个Web服务非常适合快速原型开发。灵活自由没有强制的项目结构你可以按自己喜欢的方式组织代码。这对于一个融合了数据处理、图谱构建、API服务和前端渲染的综合性项目来说非常友好。丰富的扩展通过Flask-SQLAlchemy、Flask-Login、Flask-RESTful等扩展可以轻松实现ORM、用户认证、构建REST API等功能。在这个项目中我们主要用其搭建路由提供数据API接口。图数据库Neo4j存储人物关系传统的关系型数据库如MySQL会非常吃力。想象一下要查询“所有与曹操直接相关的人物”你需要频繁地进行多表JOIN效率低下且查询语句复杂。而Neo4j是原生图数据库它的数据模型就是“节点-关系”。节点代表实体比如“刘备”、“关羽”、“赤壁之战”。关系代表节点间的连接有类型和方向比如“刘备”-[结义]-“关羽”[参与]-“赤壁之战”。 这种结构对于关系查询是天生的优势例如查找“孙权的两度联姻对象”用Neo4j的查询语言Cypher写出来非常直观MATCH (a:人物 {name:孙权})-[r:联姻]-(b:人物) RETURN b.name。其查询性能在深度关系遍历上远超关系型数据库。可视化库ECharts / D3.js / Vis.js前端可视化是项目的门面。当时可选的有ECharts百度开源文档丰富图表类型多配置化程度高。对于快速实现一个关系力导向图来说它的graph组件非常合适通过简单的JSON配置就能实现交互式图谱适合大多数场景。D3.js功能无比强大自由度极高你可以控制每一个像素的渲染。但学习成本也高需要深入理解SVG和数据绑定。如果你追求极致的定制化效果比如为不同关系类型设计独特的动画D3是终极选择。Vis.js一个轻量级的动态可视化库它的网络模块vis-network专门用于显示网络拓扑图操作简单内置拖拽、缩放、物理引擎等交互开箱即用。 在这个项目中我最终选择了ECharts原因在于其与Flask结合简单后端传JSON前端用JS初始化且能满足基本的力导向图布局、高亮关联、点击查看详情等需求平衡了效果和开发效率。2.2 数据从哪里来——数据集构建的两种路径项目源码包里附带的data文件夹通常包含了处理好的结构化数据。但这些数据最初是如何从小说文本变成图谱数据的呢这里有两种主流方法路径一基于规则与词典的信息抽取本项目采用这是比较传统但可控的方法适合领域固定、结构相对规范的文本。人物清单构建首先你需要一个“三国人物白名单”。可以从权威资料如《三国志》人物列表或公开的数据集中获取形成一个基础人物库。这能避免把“店小二”、“老农”这类非重要角色抽取进来。关系规则定义人工定义关系类型和触发词。例如关系类型结义触发词“结为兄弟”、“桃园结义”。关系类型隶属触发词“麾下”、“部将”、“拜为”。关系类型敌对触发词“讨伐”、“大战”、“击败”。文本扫描与匹配用Python编写脚本逐章扫描《三国演义》文本。当句子中同时出现两个白名单中的人物并且包含了某个关系触发词时就认为这两人之间存在该关系并将其记录到结构化数据中如CSV文件包含人物A、关系、人物B、出处章节。注意这种方法精度较高但召回率依赖规则完备性且无法发现隐含关系。例如“曹操赠予关羽赤兔马”规则可能需要额外定义“赠予”来表示一种赏识或拉拢的“关系”。路径二基于NLP模型的信息抽取进阶方向随着自然语言处理技术的发展现在更流行使用预训练模型进行自动抽取。命名实体识别使用NER模型如HanLP、LTP、或基于BERT的微调模型自动识别文本中的所有人物实体即使是不在初始白名单中的人物也能被识别。关系抽取使用关系抽取模型判断句子中两个实体间的关系。这需要标注好的训练数据或者利用远程监督的方法自动构造数据。对于三国领域可以寻找开源的RE模型或进行微调。 这种方法自动化程度高能发现更复杂的关系但对计算资源和数据标注有要求。对于初学者建议从路径一开始理解整个流程后再尝试用NLP模型替换其中的某些环节。3. 从零到一系统搭建详细步骤3.1 环境准备与依赖安装假设你已经在本地机器上准备好了Python环境建议3.7以上版本接下来是具体的环境搭建步骤。第一步安装并启动Neo4j数据库前往Neo4j官网下载Neo4j Desktop社区版。这是一个集成了数据库实例和图形化管理工具Neo4j Browser的桌面应用非常适合开发和测试。安装后创建一个新的数据库实例例如命名为ThreeKingdoms设置密码记住它后面连接要用然后点击“Start”启动数据库。打开Neo4j Browser通常随Desktop一起启动在浏览器中输入http://localhost:7474使用默认用户名neo4j和你设置的密码登录。能看到一个命令行界面说明数据库服务已经正常运行。第二步创建Python虚拟环境与安装包为了避免包冲突强烈建议使用虚拟环境。# 在项目根目录下 python -m venv venv # 创建虚拟环境 # 激活虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate # 安装核心依赖假设你有requirements.txt文件 pip install -r requirements.txt如果项目没有提供requirements.txt你需要手动安装核心包pip install flask neo4j py2neo pandas jieba # 基础必备 # 如果涉及更复杂的NLP处理可能还需要 # pip install hanlp transformers这里解释一下几个关键包flask: Web框架核心。neo4j: Neo4j官方的Python驱动用于执行Cypher查询。py2neo: 另一个流行的Neo4j Python工具包它提供了更高级的OGM对象图映射功能使用起来有时比官方驱动更便捷。本项目示例中可能用的是它。pandas: 数据处理和分析用于清洗和准备CSV数据。jieba: 中文分词库在基于规则的信息抽取中用于对句子进行分词辅助实体匹配。3.2 知识图谱的构建与数据导入这是项目的核心“数据工程”部分。我们假设你已经通过规则或NLP方法得到了一个relationships.csv文件格式如下person_arelationperson_bchapter刘备结义关羽第一回曹操隶属郭嘉第十回周瑜敌对诸葛亮第四十四回编写数据导入脚本import_data.py这个脚本的任务是读取CSV文件并将数据转化为节点和关系批量插入Neo4j。from py2neo import Graph, Node, Relationship import pandas as pd # 1. 连接Neo4j数据库 # 注意将 your_password 替换为你启动Neo4j时设置的密码 graph Graph(bolt://localhost:7687, auth(neo4j, your_password)) # 2. 清空现有图谱谨慎操作仅用于初始化 graph.delete_all() # 3. 定义唯一性约束确保人物节点不重复 graph.run(CREATE CONSTRAINT ON (p:Person) ASSERT p.name IS UNIQUE) # 4. 读取数据 df pd.read_csv(data/relationships.csv) # 5. 创建节点和关系的缓存字典避免重复创建节点 node_cache {} for index, row in df.iterrows(): p_a_name, rel_type, p_b_name, chapter row[person_a], row[relation], row[person_b], row[chapter] # 获取或创建人物A节点 if p_a_name not in node_cache: node_a Node(Person, namep_a_name) graph.create(node_a) node_cache[p_a_name] node_a else: node_a node_cache[p_a_name] # 获取或创建人物B节点 if p_b_name not in node_cache: node_b Node(Person, namep_b_name) graph.create(node_b) node_cache[p_b_name] node_b else: node_b node_cache[p_b_name] # 创建关系。关系可以带有属性例如出处章节。 rel Relationship(node_a, rel_type, node_b, chapterchapter) graph.create(rel) print(数据导入完成)实操心得在导入大量数据前先创建唯一性约束CREATE CONSTRAINT至关重要。这能保证刘备这个人物在数据库中只存在一个节点后续所有关于刘备的关系都会挂接到这个唯一的节点上避免数据冗余和查询混乱。另外使用node_cache字典缓存已创建的节点对象能大幅提升导入效率否则每处理一行数据都要去数据库查询一次节点是否存在速度会非常慢。运行这个脚本后打开Neo4j Browser输入查询MATCH (n) RETURN n LIMIT 25你应该能看到可视化的人物节点和连接线。3.3 Flask后端API开发后端的主要任务是提供数据接口供前端调用。我们会在Flask中创建几个核心路由。项目结构建议ThreeKingdoms-KG/ ├── app.py # Flask应用主入口 ├── config.py # 配置文件数据库连接等 ├── kg/ # 知识图谱操作模块 │ ├── __init__.py │ └── neo4j_connector.py # 封装所有Neo4j查询 ├── static/ # 静态文件CSS, JS, 图片 │ └── js/ │ └── main.js ├── templates/ # Jinja2模板 │ └── index.html └── data/ # 原始数据 └── relationships.csv核心API接口实现app.py部分代码from flask import Flask, render_template, jsonify, request from kg.neo4j_connector import Neo4jConnector app Flask(__name__) kg_connector Neo4jConnector() # 实例化图谱连接器 app.route(/) def index(): 渲染主页面 return render_template(index.html) app.route(/api/graph, methods[GET]) def get_full_graph(): 获取全局图谱数据用于初始化 # 限制返回节点和关系的数量防止前端卡死 limit request.args.get(limit, default100, typeint) data kg_connector.get_graph_data(limitlimit) return jsonify(data) app.route(/api/search/person, methods[GET]) def search_person(): 根据人物名搜索其关联子图 name request.args.get(name, ) if not name: return jsonify({nodes: [], links: []}) data kg_connector.get_person_subgraph(name) return jsonify(data) app.route(/api/qa, methods[POST]) def answer_question(): 简单问答接口 question request.json.get(question, ) if not question: return jsonify({answer: 请输入问题。}) # 这里是一个极其简单的规则匹配问答示例 answer kg_connector.simple_qa(question) return jsonify({answer: answer})Neo4j查询封装kg/neo4j_connector.pyfrom py2neo import Graph import re class Neo4jConnector: def __init__(self): self.graph Graph(bolt://localhost:7687, auth(neo4j, your_password)) def get_graph_data(self, limit100): 获取图谱数据格式化为ECharts Graph所需格式 query f MATCH (p1:Person)-[r]-(p2:Person) RETURN p1.name as source, p2.name as target, type(r) as relation LIMIT {limit} result self.graph.run(query).data() nodes_set set() links [] for record in result: source, target, relation record[source], record[target], record[relation] nodes_set.add(source) nodes_set.add(target) links.append({ source: source, target: target, name: relation # 关系类型作为连线名称 }) nodes [{name: node_name, category: 0} for node_name in nodes_set] # category可用于分类 return {nodes: nodes, links: links} def get_person_subgraph(self, person_name, depth2): 查询某个人物在指定深度内的关系网络 query MATCH path (p:Person {name: $name})-[*1..%s]-(related:Person) UNWIND relationships(path) as r RETURN startNode(r).name as source, endNode(r).name as target, type(r) as relation % depth result self.graph.run(query, nameperson_name).data() # ... 类似地格式化为nodes和links return formatted_data def simple_qa(self, question): 基于规则的简单问答 # 示例处理“关羽的结义兄弟是谁” if 结义 in question and 谁 in question: # 使用jieba或正则提取人物名这里简化处理 match re.search(r(\w)的结义, question) if match: person match.group(1) query MATCH (p:Person {name: $person})-[:结义]-(brother:Person) RETURN brother.name as name result self.graph.run(query, personperson).data() names [r[name] for r in result] return f{person}的结义兄弟是{, .join(names)}。 return 抱歉我暂时无法回答这个问题。注意事项在生产环境中绝对不要像上面simple_qa函数那样将用户输入直接拼接到Cypher查询字符串中f-string或%格式化这会导致严重的Cypher注入安全风险。正确的做法是始终使用参数化查询即$param语法如self.graph.run(query, nameperson_name)所示。上面的get_graph_data函数中的limit参数拼接仅用于演示在实际接受用户输入时也应参数化。3.4 前端可视化与交互实现前端页面templates/index.html主要负责布局而交互逻辑在static/js/main.js中。这里的关键是如何使用ECharts绘制力导向图。ECharts力导向图核心配置// main.js function initChart(graphData) { var chartDom document.getElementById(graph-container); var myChart echarts.init(chartDom); var option { tooltip: {}, legend: { data: [人物] // 可以根据节点类别显示图例 }, series: [{ type: graph, layout: force, // 力引导布局 data: graphData.nodes.map(function (node) { return { id: node.name, name: node.name, category: node.category, symbolSize: 20, // 节点大小可根据度数动态计算 draggable: true }; }), links: graphData.links.map(function (link) { return { source: link.source, target: link.target, name: link.name, lineStyle: { color: getRelationColor(link.name) // 根据关系类型设置颜色 } }; }), force: { repulsion: 200, // 节点之间的斥力 gravity: 0.1, // 向中心的引力 edgeLength: [50, 150] // 边的长度范围 }, roam: true, // 允许拖拽缩放 label: { show: true, position: right }, emphasis: { // 高亮样式 focus: adjacency, lineStyle: { width: 3 } } }] }; myChart.setOption(option); // 添加点击事件点击节点时查询并更新为该节点的子图 myChart.on(click, function (params) { if (params.dataType node) { var personName params.data.name; fetch(/api/search/person?name encodeURIComponent(personName)) .then(response response.json()) .then(data { myChart.setOption({ series: [{ data: data.nodes, links: data.links }] }); }); } }); } // 初始化加载全局图谱 fetch(/api/graph?limit150) .then(response response.json()) .then(data initChart(data));这段代码实现了基本的力导向图渲染和交互。节点可拖拽布局力参数repulsion,gravity需要根据节点数量多次调整以达到最佳视觉效果。点击节点时会向后台请求该人物的局部关系网络并更新图表实现了“下钻”查看的交互。4. 问答系统的进阶思考与优化项目自带的问答系统通常比较简单基于规则匹配。要让问答变得更智能我们可以从以下几个方向进行优化这也是当前知识图谱与NLP结合的热点。4.1 从规则匹配到语义解析简单的关键词匹配如判断问题里是否有“结义”、“谁”脆弱且局限。进阶的方法是进行语义解析将自然语言问题转化为结构化的查询条件即Cypher查询模板的参数。意图识别判断用户问题属于哪种查询意图。例如“关羽的结义兄弟是谁”意图是查询关系_结义对象“曹操参与了哪些战役”意图是查询人物_参与事件。可以用一个分类器如基于BERT的文本分类模型来实现。实体链接识别问题中提到的实体如“关羽”、“曹操”并将其链接到知识图谱中对应的节点ID。这需要解决别名问题如“关云长”、“曹孟德”。查询模板填充为每种意图预定义Cypher查询模板。例如对于意图查询关系_结义对象模板是MATCH (p:Person {name: $entity})-[:结义]-(o:Person) RETURN o.name。系统识别出意图和实体后将实体名$entity关羽填入模板执行查询得到答案。4.2 结合RAG增强复杂问答能力对于更复杂、需要综合多段信息才能回答的问题或者图谱中不存在直接关系的问题可以引入检索增强生成技术。知识库构建除了结构化图谱将《三国演义》原著每一回的内容或者人物生平介绍等非结构化文本进行切片并向量化存入向量数据库如ChromaDB、Milvus。混合检索当用户提问时图谱检索先尝试用上述语义解析的方法从知识图谱中查找精确的结构化答案。向量检索如果图谱检索失败或答案不完整则将用户问题也向量化去向量数据库中检索语义最相关的文本片段。答案生成将检索到的图谱查询结果结构化三元组和相关文本片段一起作为上下文输入到大语言模型如ChatGLM、Qwen等经过指令微调的模型中让模型生成一个连贯、完整的自然语言答案。 例如问题“诸葛亮和司马懿在军事上有过哪些经典对决”。图谱可能只记录了两人[敌对]关系。向量检索则可以找到“六出祁山”、“空城计”、“上方谷之战”等详细描述文本。LLM综合这些信息就能生成一段精彩的总结。4.3 性能优化与部署考量当数据量变大人物上千关系上万时前端一次性加载全图会导致浏览器卡死后端查询也可能变慢。后端分页与懒加载修改/api/graph接口不再返回全量数据。首次只返回中心度最高的前N个核心人物及其直接关系。当用户拖动视图或搜索时再按需加载新区域的人物数据。数据库索引优化确保在Person节点的name属性上建立了唯一约束它同时也是索引。对于频繁按关系类型查询的场景可以考虑对关系类型建立索引Neo4j 4.x 支持关系属性索引。查询优化避免使用[*]这种无界深度的查询它会导致性能爆炸。始终指定深度范围如[*1..3]。对于复杂的多跳查询使用APOC库中的路径扩展过程性能更好。部署开发完成后可以使用Gunicorn或uWSGI作为Flask应用的WSGI服务器配合Nginx进行反向代理部署到云服务器上。Neo4j也可以部署在服务器或使用云服务如Neo4j Aura。5. 常见问题与调试实录在实际开发和运行过程中你几乎一定会遇到下面这些问题。5.1 数据导入与连接问题问题1运行导入脚本时报错“Unable to connect to Neo4j using...”排查这是最常见的连接问题。检查Neo4j服务是否启动确认Neo4j Desktop里的数据库实例是“Running”状态。检查连接协议和端口默认的Bolt协议端口是7687HTTP端口是7474。在代码中确保使用的是bolt://localhost:7687。检查认证信息用户名默认是neo4j密码是你第一次启动时设置的。如果你修改过密码代码中的密码也必须更新。防火墙确保本地防火墙没有阻止7687端口。问题2导入数据后在Neo4j Browser中查询不到节点。排查事务提交确保你的创建操作被提交了。在使用py2neo的graph.create()时它是自动提交的。但如果你使用了graph.begin()开启事务必须最后执行graph.commit(tx)。标签匹配在Neo4j Browser中查询时你创建的节点标签是Person那么查询语句应为MATCH (p:Person) RETURN p。如果查询MATCH (n) RETURN n会返回所有标签的节点也能看到。清空缓存Neo4j Browser有缓存尝试在查询输入框旁点击“清除”按钮或者运行:clear命令。5.2 前端图表显示异常问题3ECharts图一片空白控制台无报错。排查检查容器确保div idgraph-container有明确的宽度和高度例如stylewidth: 100%; height: 600px;没有高度图表无法渲染。检查数据格式在浏览器开发者工具的“网络”标签页中查看/api/graph接口返回的JSON数据是否符合ECharts Graph要求。核心格式是{ nodes: [{name: ..., category: 0}, ...], links: [{source: A, target: B}, ...] }。确保source和target的值在nodes的name中存在。检查JS控制台虽然可能没报错但可能有警告信息比如“Invalid data”。问题4节点和连线重叠严重布局混乱。调整力导向参数这是力导向布局的常见问题需要耐心调整series[0].force下的参数repulsion节点间的斥力。值越大节点越分散。节点多时需调大如300-500。gravity向中心的引力。值越大图越向中心收缩。通常设一个较小的值0.1防止图飞散。edgeLength连线的理想长度。可以是一个范围如[30, 100]布局器会尝试让边长接近这个范围。多次尝试没有标准值需要根据你的数据量和视觉效果反复调整。可以提供一个滑块控件让用户实时调整这也是很多专业可视化工具的做法。5.3 问答功能不准确问题5问答系统只能回答预设的几种问题模式泛化能力差。这是规则系统的固有局限。解决方案就是向4.1和4.2节提到的语义解析和RAG方向升级。短期改进可以大幅扩充规则库。使用更灵活的正则表达式并加入同义词。例如对于“父亲”规则可以匹配“爸爸”、“爹”、“父皇”等。建立一个更全面的意图-模板映射表。问题6问答接口响应慢。排查Cypher查询优化使用PROFILE或EXPLAIN命令在Neo4j Browser中分析你的问答查询语句看是否有全节点扫描。确保查询利用了索引。减少查询深度检查你的问答查询是否使用了过深的路径查询如[*1..10]尝试降低深度。后端缓存对于常见、答案不变的问题如“刘备的结义兄弟是谁”可以在Flask后端使用内存缓存如functools.lru_cache或Redis缓存查询结果避免重复查询数据库。这个项目就像一座桥梁连接了古老的文本与现代的数据技术。从最基础的规则抽取到接入大语言模型其扩展路径非常清晰。动手实现一遍你会对知识图谱的应用逻辑有深刻的理解。本文还有配套的精品资源点击获取