Tina 小姐姐如果把“中药抗病毒”和“知识图谱”放在一起，大部分人第一反应是“检索一下文献，把所有药名和病毒名存进数据库，画个关系网”——实际上这活儿真没这么简单。我毕业后接手过一个类似的毕设项目，就是用 Java 和 SpringBoot 搭一个中医药抗病毒知识库，后端集成 Neo4j 做图存储与查询，前端用 Vue 做可视化。系统本身不复杂，但中间踩过的坑、绕过的弯路，能写出一整篇干货。这篇文章就完整复盘整个构建过程，从本体设计、数据清洗、知识抽取到后端接口和前端可视化，逐层拆解，做毕设或者想自己搭一个垂直领域知识图谱的朋友，可以直接照着做。
1. 项目定位与技术选型：为什么是SpringBoot + Neo4j + Vue
1.1 这个系统到底解决什么问题
传统的关系型数据库处理中医药数据时，最大的瓶颈是“多跳查询”。举个例子，想查“哪味中药的哪个成分作用于哪个靶点，从而对哪种病毒有抑制作用”，在 MySQL 里至少需要 JOIN 五张以上的表，SQL 写出来又长又难维护。知识图谱的思维方式不一样，它把“中药-成分-靶点-病毒-功效”建模成节点和边的网络，查询“路径”和“关联”是图数据库的原生能力。
我当时把项目定位成一个面向学术研究场景和中医药科普场景的知识管理平台，核心功能有三个：一是知识检索，输入中药名或病毒名，返回关联的子图；二是路径查询，找“药-成分-靶点-病毒”之间的最短关联路径；三是简单问答，用规则的思路做“XX能抗什么病毒”这类问句解析。整个系统不涉及诊疗建议，只做数据可视化和关联展示，所以不存在医学伦理层面的包袱，毕设答辩时也容易说清楚。
1.2 为什么选这套技术组合
选型时我其实纠结过 Python + Flask + Neo4j，毕竟 Python 生态有很多现成的 NLP 工具，做知识抽取更方便。但考虑到毕设的题目要求是 Java 方向，而且最终交付要体现 SpringBoot 的工程化能力，最终还是定了 Java 系。Neo4j 是图数据库里文档最全、社区最活跃的，它的 Cypher 查询语言上手成本极低，还提供 Browser 可视化界面，调试数据的时候非常直观。
SpringBoot 的优势不用多讲，自动配置、内嵌 Tomcat、Spring Data Neo4j 等 Starter 让集成成本降得很低。前端我选了 Vue 2 + ECharts，ECharts 的 graph 系列做关系图可视化很成熟，支持力导向布局、节点拖拽、点击高亮。整个架构可以概括成四层：
- 数据层：Python 爬虫抓取公开数据库，清洗后落入 MySQL 过渡表
- 知识层：用 HanLP 做分词与实体识别，结合规则模板完成知识抽取，写入 Neo4j
- 服务层：SpringBoot 提供 RESTful API，封装图谱查询、节点检索、路径分析
- 展示层：Vue 前端调用 API，渲染图谱和表格
1.3 模块划分与工作量评估
系统拆成五个模块：数据采集与预处理、本体设计与入库、知识抽取、后端 API、前端可视化。如果是一个人做，最耗时间的不是写代码，而是“数据清洗”。我当时从 TCMSP、DrugBank 和几篇综述文献里整理了将近 2000 条数据，光去重和别名归一化就花了两周。所以建议做同类项目的同学，先确定数据规模，再决定抽取方式——数据量小于 1000 条，完全可以手工整理加半自动脚本，别一上来就搞太重的 NLP 流程。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 本体设计与图数据建模：先把“图谱长什么样”定下来
2.1 实体和关系的定义
知识图谱的“schema”决定了系统能回答什么问题。我最终定义了六类实体和七类关系：
六类实体分别是：中药（Herb）、方剂（Formula）、活性成分（Compound）、靶点（Target）、病毒（Virus）、文献（Reference）。其中方剂这一层是为了后续扩展经典名方准备的，首版数据里可以先不填或少量填；关系则包括：
- 中药 → 成分：(herb)-[:HAS_COMPOUND]->(compound)
- 成分 → 靶点：(compound)-[:BINDS_TO]->(target)
- 靶点 → 病毒：(target)-[:RELATES_TO]->(virus)，含义是靶点参与病毒感染或复制过程
- 中药 → 病毒：(herb)-[:ACTIVITY_AGAINST]->(virus)，直接表达“抗病毒活性”，这是从文献里抽取出的最常用关系
- 中药 → 方剂：(formula)-[:CONTAINS]->(herb)
- 中药 → 文献：(herb)-[:REPORTED_IN]->(reference)
这里有个很关键的设计决策：为什么不直接建“中药→病毒”关系，还要中间插一个靶点？因为直接建两层关系虽然查询简单，但丢失了“作用机制”这个信息。用户问“黄连为什么能抗流感病毒”，只有通过“成分-靶点-病毒”的链路才能把机制讲清楚。所以 ACTIITY_AGAINST 属于“冗余加速边”，用于快速检索和默认展示，而核心的机制分析走多跳路径。
2.2 节点属性怎么设计
属性设计要遵循“够用就好”的原则，别把所有字段都堆上去。我的节点属性如下：
- 中药：name、pinyin、nature、flavor、meridian（性味归经）、indications（主治）、aliases（别名数组）
- 成分：name、cas、molecular_formula、pubchem_id
- 靶点：name、gene_name、uniprot_id、organism
- 病毒：name、family、genome_type、disease（所致疾病）
- 文献：title、authors、journal、year、doi
属性类型要注意一个坑：Neo4j 的节点属性没有数组索引，aliases 这种数组字段适合在 Cypher 里做“包含匹配”，但别指望它性能有多好。如果数据量大于十万节点，建议把别名单独拆成节点或者用全文索引。我这个项目是万级数据量，直接用数组没问题。
2.3 建约束与索引
数据入库之前先建好唯一性约束，这是我一开始忽略的，后面吃了大亏。没建约束的情况下重复导入数据会产生大量重复节点，图谱里出现十个“连翘”以后，什么查询都乱套了。Neo4j 的约束写法如下：
cypher复制CREATE CONSTRAINT unique_herb IF NOT EXISTS
ON (h:Herb) ASSERT h.name IS UNIQUE;
CREATE CONSTRAINT unique_virus IF NOT EXISTS
ON (v:Virus) ASSERT v.name IS UNIQUE;
CREATE CONSTRAINT unique_compound IF NOT EXISTS
ON (c:Compound) ASSERT c.name IS UNIQUE;
导入数据之前建好约束，再用 MERGE 语句代替 CREATE，这样可以天然去重。索引要根据查询模式来，比如经常按“name”搜节点，就建一个 BTREE 索引；经常做全文检索，就用 db.index.fulltext.createNodeIndex。名称为中文时注意全文索引需要配置 analyzer，默认的 standard analyzer 对中文分词不友好，后面在中文检索部分细说。
3. 数据采集与知识抽取：把非结构化文本变成三元组
3.1 数据来源与采集策略
中医药领域靠谱的公开数据源并不太多，我整理过几个还算稳定的：
- TCMSP（中药系统药理学数据库）：有中药成分、靶点信息，可下载 CSV
- SymMap：症状-中药-成分映射，适合补 relations
- DrugBank：西药和靶点信息，用来对齐成分和靶点的标准名
- PubMed 摘要：用于抽取“某中药提取物对某病毒有抑制作用”这类关系
- 中国药典：中药的性味归经和主治，适合人工整理
采集方案上，我没有直接用 Java 写爬虫，而是用 Python 的 requests + BeautifulSoup 抓取，因为 Python 写爬虫确实快，而且数据处理脚本改起来方便。抓回来的数据先放进 MySQL 过渡表，统一用 source 字段标记来源，等清洗完再通过 Java 程序批量导入 Neo4j。这样做的原因是避免在写爬虫阶段就纠结图模型，先把数据理顺，再设计导入逻辑。
3.2 数据清洗的三个关键动作
清洗步骤不多，但有三个动作直接影响后续抽取效果：
第一是去重。同一味中药在不同来源里名字可能不同，比如“金银花”也叫“忍冬花”，“牛膝”有“怀牛膝”和“川牛膝”之分。我建了一个别名表，canonical_name 是标准名，alias 是别名，清洗时统一映射到标准名。
第二是补属性。TCMSP 导出的数据经常缺分子式，PubChem ID 也有大量空值，我通过 CAS 号去 PubChem 批量补了一遍。这步是体力活，但补完之后图谱的完整性明显不一样，前端展示详情页时有东西可看。
第三是过滤。有些成分在所有来源里都查询不到靶点信息，保留下去会产生大量“孤立成分”，拉低图谱质量。我写了个筛选逻辑：至少有一条边关联到“靶点”或“病毒”的成分才保留，其余存档备用，等后续有数据了再补。
3.3 HanLP 在 SpringBoot 里的集成方式
实体识别和关系抽取我用了 HanLP，主要原因是它支持中文分词、词性标注、命名实体识别和依存句法分析，并且有 Java 版本，能直接打进 SpringBoot 工程。集成方式很简单，Maven 引入 hanlp 包，将配置文件和词典放到 resources 目录就行。
xml复制<dependency>
<groupId>com.hankcs</groupId>
<artifactId>hanlp</artifactId>
<version>portable-1.8.4</version>
</dependency>
HanLP 的 portable 版自带基础模型和词典，开箱即用。但我建议额外维护一个自定义词典，因为中医药领域专有名词太多，“板蓝根”“金银花”“穿心莲内酯”这些词默认词典可能拆得七零八落。自定义词典是纯文本文件，一行一个词，格式大概是：
code复制板蓝根 100 nz
金银花 100 nz
穿心莲内酯 100 nz
连花清瘟 100 nz
分词示例代码如下：
java复制import com.hankcs.hanlp.HanLP;
import com.hankcs.hanlp.seg.common.Term;
List<Term> termList = HanLP.segment(sentence);
for (Term term : termList) {
System.out.println(term.word + "/" + term.nature);
}
做完分词后，还需要结合规则完成关系抽取。比如句子“金银花提取物对甲型流感病毒有抑制作用”，先做实体识别，发现“金银花”是一个中药实体，“甲型流感病毒”是病毒实体，中间有“抑制作用”这个触发词，就抽出一条 (金银花)-[:ACTIVITY_AGAINST]->(甲型流感病毒)。这类模式在综述文献里反复出现，规则覆盖度能到 70% 左右，剩下的靠人工补。
3.4 实体对齐：图谱质量的胜负手
实体对齐是我在整个项目里最想提醒后来人的环节。不同来源的“靶点”名称写千奇百怪，比如“TNF-α”“TNF-alpha”“Tumor Necrosis Factor Alpha”其实是同一个东西。不对齐就入库，图谱里会出现大量“同义不同名”的节点，查询结果支离破碎。
我当时的对齐流程分四步：
第一步，标准化大小写和符号，全角转半角，“-”和“_”统一处理。第二步，用正则把希腊字母转成常见写法，比如“α”转成“alpha”，方便和英文资料匹配。第三步，优先用权威 ID 对齐，比如 Uniprot ID、CAS 号、PubChem ID 精确匹配，这类 ID 在数据源里出现时一定优先使用。第四步，文本相似度兜底，对长名称用编辑距离和包含关系打分，超过阈值再人工确认。
这套流程做完，我的数据里靶点节点从初版的 1600 多个降到 900 多个，图谱一下子干净很多。强烈建议在图数据库大量导数据之前，先写一套实体对齐脚本，否则后面删重复节点会删到怀疑人生。
4. SpringBoot 服务端实现：把图谱能力封装成 API
4.1 工程结构与核心依赖
后端工程我拆成 controller、service、repository、entity 四层，和大部分 SpringBoot 项目一样。核心依赖除了 spring-boot-starter-web 之外，重点有以下几个：
xml复制<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-neo4j</artifactId>
</dependency>
<dependency>
<groupId>org.neo4j.driver</groupId>
<artifactId>neo4j-java-driver</artifactId>
</dependency>
这里要提醒一个版本匹配的坑：Spring Data Neo4j 6.x 对应 SpringBoot 2.7.x，Spring Data Neo4j 7.x 对应 SpringBoot 3.x，Neo4j 数据库版本也有对应关系。我第一次用的是 SpringBoot 2.7.5 + Neo4j 5.x，结果驱动协议不兼容，启动后连不上数据库，日志里报了一堆 Protocol error。后来查了官方文档才发现，Neo4j Java Driver 4.4 才匹配 Neo4j 4.4 版本，如果数据库是 5.x，Java Driver 至少得用 5.x，Spring Data Neo4j 也要对得上。这个兼容性问题特别容易在毕设阶段让人卡住，先查版本矩阵再动手写代码。
4.2 Spring Data Neo4j 的实体映射
Spring Data Neo4j 的实体映射和 JPA 有点类似，用注解标注节点和关系。节点实体大致这么写：
java复制@Node("Herb")
public class Herb {
@Id
@GeneratedValue
private Long id;
@Property("name")
private String name;
@Property("nature")
private String nature;
@Property("flavor")
private String flavor;
}
关系映射写在实体类里，比如 Herb 里想带出它关联的成分：
java复制@Relationship(type = "HAS_COMPOUND", direction = Relationship.Direction.OUTGOING)
private List<Compound> compounds;
但如果关系上还要存额外属性，比如“实验浓度”“IC50 值”这类信息，就不能用这种简单写法，需要把关系建模成单独的实体。做法是新建一个 ActivityRelation 类，用 @RelationshipProperties 注解标注，里面持有起始节点和结束节点。
4.3 核心查询：用 Cypher 表达复杂的关联分析
服务层最核心的场景有三个：搜索、路径、子图。
第一个场景是关键词搜索，输入“金银花”，返回所有匹配节点和它一跳以内的全部关系。这个场景我用 Cypher：
cypher复制MATCH (n)
WHERE n.name CONTAINS $keyword
OPTIONAL MATCH (n)-[r]-(neighbor)
RETURN n, r, neighbor
LIMIT 100
第二个场景是路径查询，找“中药到病毒”的最短关联路径，用于展示作用机制。路径查询是图数据库最能体现优势的地方，Cypher 写出来很短：
cypher复制MATCH p = shortestPath((h:Herb)-[*..6]-(v:Virus))
WHERE h.name = $herbName AND v.name = $virusName
RETURN p
这里 [*..6] 表示关系深度最多六跳，太深了路径会非常长，而且大部分没有实际意义。实际跑下来发现，中药到靶点再到病毒的路径深度一般是 2 到 4，很少有超过 5 的。
第三个场景是子图查询，选一个中药节点，返回以它为中心的多跳子图，用来在前端做可视化展示。我封装了一个比较通用的接口：输入实体类型和名称，返回两跳以内的所有节点和关系。这个接口对应前端的主视图。
4.4 简单问答模块的实现思路
“简单问答”听起来高大上，但在数据量不大的情况下，用规则模板完全够用。我把问题分成几类模板：
- “XX 能抗什么病毒？” → 查
(h:Herb {name: xx})-[:ACTIVITY_AGAINST]->(v:Virus) - “什么药能抗 XX 病毒？” → 反向查病毒
- “XX 的成分有哪些？” → 查
(h:Herb)-[:HAS_COMPOUND]->(c:Compound) - “XX 和 XX 有什么关系？” → 匹配两个节点之间的路径
实现思路是：先对句子做 HanLP 分词，识别出里面的中药实体和病毒实体，命中实体后根据问句中的触发词判断模板类型，最后拼 Cypher 查 Neo4j。这套规则引擎的代码量不大，大概 200 行左右，但效果很直观，演示时体验非常加分。不要一上来就把问题引入大模型，毕设重点应该是把这个流程走通，加模型反而是另外一个层次的事。
5. 前端可视化：把图谱画出来并支持交互
5.1 Vue 工程与 API 对接
前端我用的是 Vue 2 + Element UI + ECharts，工程结构就是标准的 Vue CLI 项目。API 层用 axios 封装，和后端约定统一的返回格式 { code, message, data }。整个页面分成三块：左侧是检索栏和筛选器，中间是图谱可视化画布，右侧是选中节点的详情面板。
接口列表大致如下：
GET /api/herb/search?name=xx：搜中药节点GET /api/graph/subgraph?type=Herb&name=xx：获取两跳子图GET /api/path/herb-virus?herb=xx&virus=xx：最短路径查询GET /api/question/ask?question=xx：问答接口
这里要特别注意接口返回的数据结构要和 ECharts 需要的数据结构对齐。ECharts graph 系列要求的数据格式是：
json复制{
"nodes": [
{ "id": "Herb_1", "name": "金银花", "category": 0, "symbolSize": 40 },
{ "id": "Virus_5", "name": "甲型流感病毒", "category": 1, "symbolSize": 50 }
],
"links": [
{ "source": "Herb_1", "target": "Virus_5", "label": { "show": true, "formatter": "抑制作用" } }
]
}
所以后端返回子图数据时，我会在 service 层把 Neo4j 的查询结果直接转换成这个结构，而不是让前端去遍历节点和关系做二次组装，省掉不少麻烦。
5.2 ECharts 图谱配置的关键参数
ECharts 关系图的配置有几个参数值得单独提出来。力导向布局用 force 字段控制，repulsion 设置节点之间的斥力，数值太小时节点会堆挤在一起，太大时图会散成一团。中药、成分、靶点、病毒四类节点的数量差别很大，我会根据 category 设置不同的 symbolSize，同时用 categories 字段给每个类别配一个颜色，视觉上一眼能区分实体类型。
edgeSymbol 可以在边的两端加箭头，表示关系方向。因为 Neo4j 里关系是有方向的，前端展示时建议加上，这样能明显看出“谁指向谁”。另外，emphasis.focus 设置为 'adjacency' 后，鼠标悬浮某个节点时，只有和它直接相连的邻居和边会高亮，其他都变暗，这是关系图可视化里体验提升最大的一个配置。
5.3 从查询结果到可视化数据的组装逻辑
组装逻辑看起来简单，里面有个细节：Neo4j 返回的节点 ID 是数字，但 ECharts 要求图中所有节点的 id 全局唯一。如果数字 ID 跨类型不冲突还好，但保险起见，我会在前端拼一个“类型_数字ID”的复合 ID，例如 Herb_12、Virus_8，避免两种不同类型的节点因为数字 ID 相同导致渲染错乱。
还有个点，两跳子图返回的节点数量通常有几十个，如果不控制深度和数量，前端渲染会卡。我的做法是：分页或限流，接口默认最多返回 200 个节点和 500 条边，超出的部分提示用户“图太大，建议缩小检索范围”。真正做演示的时候没人会真的一次看几千个节点，限制数量反而是提升使用体验的正确做法。
6. 部署、避坑与常见问题实录
6.1 Neo4j 部署时的资源参数
Neo4j 的默认内存配置对开发机不太友好，动不动就占好几个 GB。毕设项目用的数据量一般不大，可以手动把配置调低，在 neo4j.conf 里设置：
properties复制server.memory.heap.initial_size=512m
server.memory.heap.max_size=1g
server.memory.pagecache.size=512m
数据量在万级左右时，这个配置完全够跑。如果是在本地 Windows 上做开发，记得关掉系统休眠和自动更新，否则跑着跑着内存被吃满，Neo4j 进程会直接挂掉。Linux 服务器部署时要注意，默认的 vm.max_map_count 如果太低，Neo4j 启动会报错，执行 sysctl -w vm.max_map_count=262144 就能解决。
6.2 中文检索与全文索引配置
Neo4j 的 CONTAINS 查询是简单子串匹配，数据量大了之后性能不好，而且遇到分词边界问题会漏数据。更优的方案是用全文索引，Neo4j 内置的全文索引可以直接用：
cypher复制CREATE FULLTEXT INDEX fulltext_herb_name IF NOT EXISTS
FOR (h:Herb) ON EACH [h.name, h.aliases];
查询时用 db.index.fulltext.queryNodes：
cypher复制CALL db.index.fulltext.queryNodes('fulltext_herb_name', '金银花')
YIELD node, score
RETURN node, score ORDER BY score DESC;
需要提醒的是，Neo4j 全文索引默认的分词器对中文支持一般，中文分词粒度偏粗，搜索“板蓝根颗粒”可能匹配不到“板蓝根”。这个限制在数据量小的时候影响不大，但如果你做的是中文文本密集的属性检索，建议在 Neo4j 里挂中文分词插件，或者在搜索入口用 HanLP 先分词，再拼出多个关键词去匹配。
6.3 必坑清单：我踩过且不希望你再踩的坑
版本不匹配是第一大坑，具体前面提过，SpringBoot、Spring Data Neo4j、Neo4j 数据库、Java Driver 四者的版本要对应。第二大坑是数据导入时忘记清空旧数据，重复执行导入脚本后出现大量重复节点。我后来在导入脚本开头加了 MATCH (n) DETACH DELETE n，每次重新导入前清空图数据库，避免脏数据累积。虽然粗暴，但在开发阶段效率最高。
第三大坑是 Cypher 查询里使用中文参数时编码问题。确保 Neo4j 数据库连接串里配置了字符集，Java 侧统一用 UTF-8 编码，前端传到后端的参数也要做 URL 解码，否则中文搜索会莫名失败。第四大坑是分页问题，Neo4j 的 SKIP 和 LIMIT 在深层遍历时性能很差，替代方案是尽量在查询里先用条件过滤范围，再分页。
6.4 常见问题速查表
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 应用启动时 Neo4j 连接失败 | 数据库版本与驱动不匹配 | 查版本矩阵，统一升级或降级 |
| 中文搜索匹配不到数据 | 全文索引 analyzer 不支持中文 | 建索引时指定中文 analyzer，或提前分词 |
| 图谱中出现大量重复同名节点 | 导入用 CREATE 而非 MERGE | 先建唯一约束，导入时用 MERGE |
| 查询速度慢，点击卡顿 | Cypher 未走到索引 | 用 EXPLAIN 分析查询计划，补 BTREE 索引 |
| 前端渲染时节点丢失或连线错乱 | ID 冲突或数据结构不匹配 | 用“类型_数字ID”复合 ID，统一返回结构 |
| 重启服务后数据丢失 | Neo4j 数据库路径配置错误 | 检查 server.directories.data 配置 |
我还想单独说一个容易忽略的点：图数据库导入数据后，最好先做一遍统计校验，比如节点总数、各类节点数量、孤立节点数。写一个简单的计数接口，或者在 Neo4j Browser 里跑 MATCH (n) RETURN count(n)，确认数据规模符合预期再开始做查询层。否则数据缺失或重复的问题会一直潜伏到演示阶段才暴露，到那时候再回头修数据，相当折腾。
写在最后：一点个人体会
整套系统从零到一做完，我最深的体会是，知识图谱项目的难点从来不在“图数据库”本身，而在“怎么把杂乱的数据整理成结构化的三元组”。Neo4j 和 SpringBoot 都只是工具，真正考验人的是数据清洗、实体对齐和规则设计这些“看不见”的功夫。如果你也准备做同类项目，我建议先把数据源摸清楚，再动手搭框架，别急着写代码，数据理顺了，后面每一步都会顺很多。
最后再分享一个小技巧：每次修改本体模型或关系类型后，记得用一批固定的“回归用例”验证，比如“查金银花的子图”“查连翘到流感病毒的路径”，确保老功能没被改坏。这比什么自动化测试都管用，演示前跑一遍心里有底。希望这篇文章能让你少走一些弯路。