简介：面向具备Java Web基础、想尝试知识图谱与自然语言处理项目的开发者，这份源码完整实现了基于知识图谱的古诗词智能问答。后端采用Java、SSM、SpringBoot、Maven，前端使用React，数据放在MySQL与图数据库Neo4j中；交互过程包含问句分词、词性标注、问题模板匹配与还原、图谱查询和结果回显，适合课程设计、毕业设计或AI入门参考。压缩包共57个文件，大小543KB。12个Java文件对应控制层、服务层与数据库连接逻辑，7个SQL脚本负责建库建表及初始化诗词数据，7个JS文件和2个CSS文件构成前端交互，另带Maven/XML/properties配置、Markdown说明与若干图片，目录按后端、前端、SQL分开，便于定位阅读。目前已有2146人学习下载。借助词汇表、用户字典与问题模板设计，读者可沿“提问—解析—查图—作答”全链路理解问答系统的实现思路，并在此基础上扩展实体关系与模板。
1. 古诗词智能问答的落地关键在于问句拆解层
基于知识图谱的古诗词智能问答，本质上不是玄学，而是一条从用户问句到图查询、再到答案组装的完整链路。我拆完这个项目后最大的感受是：Java 代码层面其实不复杂，真正花时间的是问答解析层——怎么把“李白写过哪些关于送别的诗”拆成“李白”这个实体和“作品查询”这个意图，再映射成 Neo4j 的 Cypher 语句。这个项目适合两类人：准备 Java 毕业设计、需要演示完整链路的人，以及刚接触知识图谱、想用最小成本跑通问答系统的开发新人。下面从数据建模开始，按搭建顺序完整复盘一遍。
2. 图谱数据层：五类实体、四种关系与一次导入
动手写 Spring Boot 之前，先把知识图谱的数据结构定下来。这个项目选用的图数据库是 Neo4j，所有实体和关系最终都以标签和边的方式存储。这里容易犯的错误是一上来就写代码，等查询接口开发时发现实体属性命名混乱，不得不返工。我先从数据侧把基础打牢。
2.1 实体与关系设计：节点标签、属性与关系方向的确定
我按常见古诗词问答的语义范围做了一版设计，没有追求实体类型的完整，而是保证覆盖高频问句。第一版只需要五类实体：诗人（Poet）、作品（Work）、主题（Theme）、意象（Image）和朝代（Dynasty）。
各实体类型需要带的属性，直接决定后面 Java 查询层写什么字段：
| 实体标签 | 含义 | 关键属性 |
|---|---|---|
| Poet | 诗人 | id、name、dynasty |
| Work | 单首诗词 | id、title、content |
| Theme | 内容主题 | name |
| Image | 核心意象 | name |
| Dynasty | 朝代 | name |
关系设计遵循一个原则：关系名和自然语言里的动词方向保持一致。这样后面拼 Cypher 时思维负担最小。
| 关系 | 起点 | 终点 | 对应问句 |
|---|---|---|---|
| AUTHOR_OF | Poet | Work | 李白写过什么诗 |
| THEME_OF | Work | Theme | 哪些诗属于送别主题 |
| MENTION_OF | Work | Image | 描写月亮的诗 |
| BELONG_TO | Poet | Dynasty | 李白是哪个朝代的诗人 |
这里有一个可以省掉的建模：作品要不要直接挂朝代？我建议不挂。同一诗人的作品朝代一致，从 Poet 出发经过 BELONG_TO 就可以得到，多一条边对问答没有实质帮助，反而增加数据清洗的工作量。关系方向定了之后，几类高频问题都能在这个模型上覆盖：查作品、查作者、查主题、查意象、查朝代。
2.2 数据清洗与批量导入：Python 预处理 + LOAD CSV 命令
手头拿到的是常见古诗词 JSON 数据集时，先做一步清洗转换，把目标结构整理成三个 CSV 文件：poets.csv、works.csv、rels.csv。这一步我用 Python 脚本完成，因为它处理中文和文件编码最顺手。
import csv import json import hashlib poets = set() works = [] rels = [] with open("poetry.json", "r", encoding="utf-8") as f: data = json.load(f) for item in data: author = item["author"].strip() title = item["title"].strip() content = item.get("content", "").strip() dynasty = item.get("dynasty", "").strip() pid = "poet_" + hashlib.md5(author.encode("utf-8")).hexdigest()[:8] wid = "work_" + str(item["id"]) poets.add((pid, author, dynasty)) works.append((wid, title, content)) rels.append((pid, "AUTHOR_OF", wid)) with open("poets.csv", "w", encoding="utf-8", newline="") as f: writer = csv.writer(f) writer.writerow(["id", "name", "dynasty"]) writer.writerows(sorted(poets)) with open("works.csv", "w", encoding="utf-8", newline="") as f: writer = csv.writer(f) writer.writerow(["id", "title", "content"]) writer.writerows(works) with open("rels.csv", "w", encoding="utf-8", newline="") as f: writer = csv.writer(f) writer.writerow(["from", "rel", "to"]) writer.writerows(rels)这段脚本里最关键的是pid用 md5 生成稳定 ID。第 5 章会讲到，如果不做稳定 ID，LOAD CSV 重复执行时节点会翻倍。注意写入 CSV 时统一使用encoding="utf-8"且不带 BOM，Neo4j 的 LOAD CSV 对 BOM 头处理得很差。
接下来执行 Cypher 导入。先导入诗人节点：
LOAD CSV WITH HEADERS FROM 'file:///poets.csv' AS row MERGE (p:Poet {id: row.id}) SET p.name = row.name, p.dynasty = row.dynasty;再导入作品节点：
LOAD CSV WITH HEADERS FROM 'file:///works.csv' AS row MERGE (w:Work {id: row.id}) SET w.title = row.title, w.content = row.content;最后建立关系：
LOAD CSV WITH HEADERS FROM 'file:///rels.csv' AS row MATCH (p:Poet {id: row.from}) MATCH (w:Work {id: row.to}) MERGE (p)-[:AUTHOR_OF]->(w);这里统一用MERGE而不是CREATE，原因是 MERGE 以指定属性为唯一键，重复执行不会产生重复节点。关系导入里去掉SET是因为关系本身不需要额外属性。数据导入完成后，强烈建议按查询高频字段建索引：
CREATE INDEX FOR (p:Poet) ON (p.name); CREATE INDEX FOR (w:Work) ON (w.title); CREATE INDEX FOR (t:Theme) ON (t.name); CREATE INDEX FOR (i:Image) ON (i.name);索引不建，后面问答层只要遇到按名字定位实体，全图扫描会把查询拖到秒级。LOAD CSV 默认读取 Neo4j 安装目录下的 import 文件夹，把三个 CSV 放进去再执行即可。
3. Spring Boot 服务层：原生 Neo4j 驱动的查询接口封装
图谱数据准备好以后，进入 Java 侧开发。我的做法是工程结构按 config、nlu、service、controller 四层拆，让后面加问答模板时不至于在 Controller 里堆逻辑。
3.1 依赖选型与驱动配置：为什么选择原生 Driver 而不是 Spring Data Neo4j
第一次做这个项目的开发者很容易想引入 Spring Data Neo4j，因为它提供了@Node实体映射。但我实际跑下来发现，问答场景下 Cypher 是随意图动态变化的，实体映射的价值不大，反而每加一种查询就要维护实体类、Repository 接口，非常重。我这里选择的是 Neo4j 官方 Java Driver 原生客户端，自己管理查询会话。
pom.xml 里的核心依赖如下：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.neo4j.driver</groupId> <artifactId>neo4j-java-driver</artifactId> <version>4.4.12</version> </dependency>如果你用的是 Spring Boot 2.x 配 JDK 8，就选 4.4.x 驱动；如果是 Spring Boot 3.x 配 JDK 17，驱动版本必须上 5.x 系列，否则会因为字节码版本不兼容直接启动失败。驱动版本和 Neo4j 服务端版本之间也存在兼容矩阵，通常 4.4 驱动配 Neo4j 4.4 服务端是稳定组合。
驱动配置类：
@Configuration public class Neo4jConfig { @Bean(destroyMethod = "close") public Driver neo4jDriver() { return GraphDatabase.driver( "bolt://localhost:7687", AuthTokens.basic("neo4j", "your_password"), Config.builder() .withConnectionTimeout(Duration.ofSeconds(5)) .withMaxConnectionPoolSize(50) .build() ); } }这里两个参数需要说明：withConnectionTimeout控制建立连接的超时时间，默认值偏长，问答接口对响应时间敏感，我一般压到 5 秒；withMaxConnectionPoolSize控制连接池上限，单机部署 50 足够，调太大只会浪费 Neo4j 服务端的线程资源。destroyMethod = "close"保证 Spring 容器关闭时驱动连接被释放。
3.2 查询服务与统一返回：QaService 与 Controller 的分层结构
查询逻辑集中放在 QaService 里，避免每个查询方法都写一遍 Session 打开和关闭的样板代码。先定义一个统一的返回结构：
public class Answer { private String question; private String intent; private String entity; private List<String> results; private String fallback; // getter / setter 省略 public static Answer ok(String question, String intent, String entity, List<String> results) { Answer a = new Answer(); a.question = question; a.intent = intent; a.entity = entity; a.results = results; return a; } public static Answer fallback(String question, String message) { Answer a = new Answer(); a.question = question; a.fallback = message; return a; } }实体直接存在 entity 字段里，方便前端排查“系统到底识别到了什么”。QaService 里的查询方法，以“查某位诗人写过哪些作品”为例：
@Service public class QaService { private final Driver driver; private final IntentParser intentParser; private final EntityExtractor entityExtractor; private final QueryBuilder queryBuilder; public QaService(Driver driver, IntentParser intentParser, EntityExtractor entityExtractor, QueryBuilder queryBuilder) { this.driver = driver; this.intentParser = intentParser; this.entityExtractor = entityExtractor; this.queryBuilder = queryBuilder; } public Answer answer(String question) { String intent = intentParser.parse(question); Entity entity = entityExtractor.extract(question); String cypher = queryBuilder.build(intent, entity); if (cypher == null || entity == null) { return Answer.fallback(question, "暂时没理解你的意思，试试问“李白写过什么诗”"); } List<String> rows = executeQuery(cypher, entity.getName()); if (rows.isEmpty()) { return Answer.fallback(question, "图谱里没找到相关内容，换个说法试试"); } return Answer.ok(question, intent, entity.getName(), rows); } private List<String> executeQuery(String cypher, String param) { try (Session session = driver.session(SessionConfig.forDatabase("neo4j"))) { return session.executeRead(tx -> { List<String> list = new ArrayList<>(); Result result = tx.run(cypher, Map.of("name", param)); while (result.hasNext()) { list.add(result.next().get("title").asString()); } return list; }); } } }注意try (Session session ...)写法，Session 不是线程安全的，用完即关闭。executeRead表示这是一个只读事务，Neo4j 会把它路由到集群中的只读副本，单机部署时没有区别，但代码语义更清晰。查询参数一律通过Map.of("name", param)传入，禁止用字符串拼接，既防注入，又能让 Neo4j 缓存同一模板的执行计划。
Controller 层只做参数接收和异常兜底：
@RestController @RequestMapping("/api/qa") public class QaController { private final QaService qaService; public QaController(QaService qaService) { this.qaService = qaService; } @PostMapping("/ask") public Answer ask(@RequestBody QuestionRequest request) { if (request.getQuestion() == null || request.getQuestion().trim().isEmpty()) { return Answer.fallback("", "问题不能为空"); } return qaService.answer(request.getQuestion().trim()); } }接口设计为 POST/api/qa/ask，请求体是{"question": "李白写过什么诗"}，响应统一走 Answer 结构。把参数校验放在 Controller 入口，避免空字符串进入解析层。
4. 问答解析器：从问句到 Cypher 的四步拆解
问答解析层是整个系统的核心，我把拆解过程固定成四步：先识别意图，再抽取实体，然后根据意图和实体拼 Cypher，最后执行查询并组装答案。这一步的代码量不大，但每一步都要考虑边界情况。
4.1 意图识别：先把问句归类到四种查询模板
意图识别没有用模型，用的是规则字典 + 正则匹配。对固定领域来说，规则方案足够稳定，而且不用准备训练数据。我按高频问句定义了四类意图：
| 意图标识 | 含义 | 典型问句 |
|---|---|---|
| QUERY_POET_WORK | 查诗人作品 | 李白写过什么诗 |
| QUERY_WORK_AUTHOR | 查作品作者 | 《静夜思》是谁写的 |
| QUERY_FULL_TEXT | 查作品全文 | 静夜思的全文 |
| QUERY_THEME_WORK | 查主题作品 | 关于思乡的诗 |
| QUERY_IMAGE_WORK | 查意象作品 | 描写月亮的诗 |
IntentParser 的实现思路是维护一组有序规则，先匹配精确的意图，再匹配宽泛的意图：
public class IntentParser { private static final List<Rule> RULES = new ArrayList<>(); static { RULES.add(new Rule(".*是谁写的|.*作者是谁", "QUERY_WORK_AUTHOR")); RULES.add(new Rule(".*全文.*|.*完整内容.*", "QUERY_FULL_TEXT")); RULES.add(new Rule(".*写过.*|.*写了.*|.*有哪些.*", "QUERY_POET_WORK")); RULES.add(new Rule(".*关于.*|.*为题材.*", "QUERY_THEME_WORK")); RULES.add(new Rule(".*写[月酒剑].*|.*月亮.*诗.*", "QUERY_IMAGE_WORK")); } public String parse(String question) { for (Rule rule : RULES) { if (question.matches(rule.pattern)) { return rule.intent; } } return "UNKNOWN"; } private static class Rule { String pattern; String intent; Rule(String pattern, String intent) { this.pattern = pattern; this.intent = intent; } } }规则顺序不是随便排的。.*是谁写的必须排在.*写过.*前面，否则“《静夜思》是谁写的”会被误判成查李白作品。同样的，.*全文.*也要提前，因为“静夜思的全文是什么”同时包含“什么”和“全文”，宽泛规则会先命中。这条顺序问题我在第 5 章还会展开。
4.2 实体抽取与模板组装：词典匹配与 Cypher 拼接
实体抽取同样采用词典匹配，但我做了一件事：作品标题的匹配优先级高于诗人名字。原因是“《静夜思》是谁写的”这句话里，“静夜思”是一个完整作品名，如果诗人字典里有“思”相关字段会误命中。作品标题通常更长、更具辨识度，优先匹配能显著降低错杀概率。
public class EntityExtractor { private final Set<String> poetDict; private final Set<String> workDict; private final Set<String> themeDict; private final Set<String> imageDict; public EntityExtractor(Set<String> poetDict, Set<String> workDict, Set<String> themeDict, Set<String> imageDict) { this.poetDict = poetDict; this.workDict = workDict; this.themeDict = themeDict; this.imageDict = imageDict; } public Entity extract(String question) { for (String name : workDict) { if (question.contains(name)) { return new Entity("WORK", name); } } for (String name : poetDict) { if (question.contains(name)) { return new Entity("POET", name); } } for (String name : themeDict) { if (question.contains(name)) { return new Entity("THEME", name); } } for (String name : imageDict) { if (question.contains(name)) { return new Entity("IMAGE", name); } } return null; } }Entity 是一个最小模型，只包含类型和名称两个字段。字典初始化时从数据库或配置文件加载，我这里用了一个简单习惯：把诗人、作品、主题、意象四个 Set 在应用启动时查一次 Neo4j 全量加载进内存，避免每次问答都访问数据库查字典。古诗词领域的实体总量通常在几千到几万级别，内存完全放得下。
QueryBuilder 负责把意图和实体转换成 Cypher 模板：
public class QueryBuilder { public String build(String intent, Entity entity) { if (entity == null) { return null; } switch (intent) { case "QUERY_POET_WORK": return "MATCH (p:Poet {name:$name})-[:AUTHOR_OF]->(w:Work) RETURN w.title AS title"; case "QUERY_WORK_AUTHOR": return "MATCH (p:Poet)-[:AUTHOR_OF]->(w:Work {title:$name}) RETURN p.name AS title"; case "QUERY_FULL_TEXT": return "MATCH (w:Work {title:$name}) RETURN w.content AS title"; case "QUERY_THEME_WORK": return "MATCH (w:Work)-[:THEME_OF]->(t:Theme {name:$name}) RETURN w.title AS title"; case "QUERY_IMAGE_WORK": return "MATCH (w:Work)-[:MENTION_OF]->(i:Image {name:$name}) RETURN w.title AS title"; default: return null; } } }这里的$name占位符和第 3 章的Map.of("name", param)对应，注意所有 RETURN 字段统一取别名 title，这样 QaService 的 executeQuery 方法只需要读result.get("title")一个字段，代码高度复用。如果后面想返回多字段，比如同时返回标题和内容，就需要改 executeQuery 和 Answer 结构，所以第一版统一成标题字符串是最省事的做法。
执行完 Cypher 之后，QaService 把结果交给 Controller 返回。到这里，一条完整的问答链路已经可以跑通：用户发问句，系统解析意图和实体，拼 Cypher 查 Neo4j，返回 JSON。
5. 常见问题排查：乱码、重复实体与连接超时的高频现场
整个项目复现过程中，我收集到最多的问题集中在数据导入和问答运行两个环节。每一个都是实际发生过的问题，按“现象、原因、解决”整理如下。
5.1 数据导入环节的三个现场
第一个现象：执行 LOAD CSV 后，第一列字段或值前面出现\ufeff字符，按名字查诗人一直查不到。原因是 CSV 文件保存成了 UTF-8 with BOM 格式，Neo4j 的 LOAD CSV 不会自动剥离 BOM，导致第一列属性值里混入了不可见字符。解决方式是在 Python 侧写入时统一用encoding="utf-8"，不要用记事本等编辑器另存为带 BOM 的 UTF-8。我给团队定的规矩是：所有进入 import 目录的文件，必须由脚本产出，不手工编辑。
第二个现象：同一份 CSV 执行第二次导入后，诗人节点数量翻倍。原因是第一次用CREATE (p:Poet {id:row.id})插入，第二次执行时没有考虑幂等性。解决方式是把导入语句全部换成MERGE，并且保证 MERGE 用的属性（比如 id）在业务上唯一。这个项目的 id 用 md5 哈希生成，天然唯一，配合 MERGE 可以随意重复执行导入脚本。
第三个现象：几千首作品导入耗时较长，单条 Cypher 执行都要几十毫秒。原因是使用脚本逐条调 Neo4j 事务接口，每条记录一次网络往返和事务提交。解决方式是优先用 LOAD CSV 原生批量导入，或者使用UNWIND $batch AS row把一批数据放进同一个事务执行。配合在 Poet.id、Work.id 上建索引，MATCH 定位实体的速度会明显提升。我的经验是三千条数据用 LOAD CSV 导入基本是秒级完成，逐条执行则要几分钟。
5.2 问答运行环节的三个现场
第四个现象：问“《静夜思》是谁写的”，接口返回了一堆李白的诗，而不是作者名。原因有两个，一个是规则顺序问题，.*写过.*比.*是谁写的.*更早匹配了问句；另一个是实体抽取虽然命中“静夜思”，但意图已经被错误归类。解决方式是把“作者、谁写的”类规则提到所有作品列表类规则之前，并在 IntentParser 里加一条约定：一旦出现书名号，优先检查是否属于作品相关意图。这个排查花了我半天时间，所以我后来把所有规则顺序写成了单元测试用例，避免改动时再次踩坑。
第五个现象：问一个知识图谱里不存在的问题，接口返回空数组，前端页面显示“暂无数据”，用户不清楚是系统没听懂还是没有这个内容。原因是接口层没有做空结果与未识别之间的区分。解决方式是统一走 Answer 结构，fallback字段专门承载提示文案，同时把results为空和意图为 UNKNOWN 两种情况区分成不同提示。项目里我默认两条兜底文案：“暂时没理解你的意思”和“图谱里没找到相关内容”，分别对应未识别和无结果。
第六个现象：应用启动后第一次请求特别慢，偶尔直接报连接超时。原因是 Driver 的GraphDatabase.driver()不会立即建立连接，第一次真正执行 Cypher 时才初始化连接池，再加上默认连接超时时间较长。解决方式是在@PostConstruct初始化阶段调用一次driver.verifyConnectivity()，把连接建立提前到应用启动时；同时在Config.builder()中显式设置withConnectionTimeout(Duration.ofSeconds(5))。这样首次请求就不会背负连接初始化的开销。
6. 从能回答到答得准：同义词扩展与候选排序落地
6.1 别名表与同义词扩展
古诗词领域有一个很典型的痛点：同一个诗人存在大量别号，“李白”也叫“太白”“青莲居士”，“杜甫”也叫“子美”“少陵野老”。如果实体提取字典只收录标准名，用户问“青莲居士写过什么诗”会直接落进兜底文案，体验很差。解决方式是在实体提取层加一张别名映射表：
public class AliasMap { private static final Map<String, String> ALIAS = new HashMap<>(); static { ALIAS.put("太白", "李白"); ALIAS.put("青莲居士", "李白"); ALIAS.put("子美", "杜甫"); ALIAS.put("少陵野老", "杜甫"); ALIAS.put("夜思", "静夜思"); } public static String normalize(String raw) { return ALIAS.getOrDefault(raw, raw); } }使用方式是在 EntityExtractor 匹配到候选实体后，再调用一次normalize转成标准名，后续 QueryBuilder 和 Cypher 执行都不需要感知别名存在。这个表还可以扩展作品别名，比如常见古籍里的“静夜思”有时被简写成“夜思”，加一行映射就解决了。运行时从配置文件加载到内存，比写死在类里更好维护。
6.2 候选排序与兜底策略
当图谱里有多个候选时，比如“写月的诗”可能命中几十首作品，直接按图遍历返回的顺序给用户，不稳定。我加了一个轻量评分排序：
private int scoreHit(Map<String, Object> row) { int score = 0; Object title = row.get("title"); if (title != null && String.valueOf(title).length() < 10) { score += 2; } return score; }这里的逻辑是：短作品名通常记忆度更高，比如《月》、《静夜思》这类，优先展示。这个排序不追求语义相关性，而是要一个确定性的展示顺序，保证同一问题每次返回的结果排序一致，避免演示时“这次和上次结果不同”的尴尬。候选结果超过 20 条时，我会截断只返回前 20 条，防止响应体过大。
兜底策略同样重要：当查询结果为空，除了返回 fallback 文案，还可以做一次“宽泛化”重试。比如“王维写过关于喝酒的诗吗”没有直接命中，就把意象“酒”去掉，退化成查王维全部作品，再在结果中做一次关键词过滤。这一步可以让问答系统在数据覆盖不足时仍然给出有参考价值的结果。
做这个项目最大的收获是让我认清楚了问答系统的黑匣子不在模型，而在数据与规则之间的衔接。从那以后，我每次搭完问答原型，都会把“词典优先级”和“兜底文案”作为两个强制验收点走一遍：先列二十条高频问句，逐个跑接口，确认意图没有错位、空结果有明确提示，再考虑扩展功能。这套土办法看起来简单，但确实能挡住绝大多数演示时的翻车。希望帮到你。
本文还有配套的精品资源，点击获取
