Python构建多模态知识图谱的中医智能诊疗平台实战

简介：知识图谱通过实体与关系的网状结构，能够有效表达复杂领域的关联语义，而多模态技术则进一步融合文本、图像与结构化数据，赋予机器更全面的感知能力。在深度学习工程实践中，将两者结合，可以构建出既具备语义理解能力、又支持可解释推理的智能系统。Neo4j作为图数据库，为知识存储与路径检索提供了高效支撑；BERT等预训练模型擅长处理非结构化文本，卷积神经网络则可提取图像特征，多模态融合机制让不同维度的信息相互印证。这类技术组合在医疗辅助诊断、智能问答、个性化推荐等垂直场景中具有广阔的应用价值，尤其适合需要结合专家知识与数据驱动的领域。本文以中医诊疗平台为实例，详细介绍多模态知识图谱的本体设计、特征融合、图谱推理及系统实现，完整展示工程落地的关键路径与常见问题排查方法。 看到这个题目，我第一反应是：这选题把目前AI领域最热的两条线——“大模型/多模态”和“知识图谱”——跟一个极具行业壁垒的垂直场景“中医诊疗”结合起来了。而且是用Python做毕业设计，说明作者既想展示工程落地能力，又想体现技术深度。这种项目如果只是搭个Web页面调个接口，那跟普通管理系统没区别，答辩时老师问两句就露馅了。但如果真把多模态知识图谱的构建、融合、推理这条链路走通，哪怕精度不高，那也是一个完整且有说服力的系统。这篇文章我会完全按照一个做过类似项目的工程师视角，把整个平台从数据层到应用层的拆解思路、核心代码逻辑、还有我踩过的那些坑，全部讲透。

1. 项目整体设计与技术选型思路

1.1 为什么是“多模态知识图谱”而不是普通数据库

很多同学做中医相关系统，第一反应是建几张MySQL表，把方剂、药材、症状存进去，然后用关键词匹配去做检索。这种方案做出来顶多算一个“电子翻书工具”，在毕设层面毫无竞争力。为什么？因为中医诊疗的核心是“辨证”和“推理”，它不是一个简单的键值查询，而是复杂的关联网络：一个症状可能对应多个证型，一个证型可能涉及不同治法，一个方剂里每味药的君臣佐使地位各不相同。

知识图谱天然适合表达这种网状关系。把“风寒束表证”和“恶寒重、发热轻、无汗”这些症状连接起来，把“麻黄汤”和“风寒束表证”连接起来，机器就能沿着图路径从症状跑到方剂。而“多模态”则更进一步：中医诊断讲究望闻问切，望诊看舌象照片，闻诊听声音，问诊获取症状文本，切诊感受脉象数据。这些数据形态完全不同，有文本、有图像、有结构化数值，所以需要让模型能同时理解这些模态，并在统一的图结构上做推理。

1.2 技术栈选型的底层逻辑

主语言选Python这点没什么好纠结的，深度学习生态、图数据库驱动、爬虫清洗工具基本都在Python这边。具体到核心组件，我的建议搭配如下：

• 知识图谱存储：Neo4j社区版。这是目前Graph DB里文档最全、社区最活跃的选择，而且它有官方的Python驱动neo4j，配合Cypher查询语言，做路径检索和多跳查询非常顺手。
• 多模态模型底座：视觉端使用ResNet或Vision Transformer提取舌象图像特征，文本端使用BERT或TextCNN提取症状描述特征，结构化体征数据用MLP编码。融合层采用Concatenation或Cross-Attention机制。
• 推理与检索：先基于规则模板做初筛，再用图数据库Cypher做可解释路径检索，最后用融合后的向量做相似度排序。这套组合拳的鲁棒性远高于单用任何一种方法。
• 后端框架：FastAPI。相比Flask和Django，FastAPI原生支持异步、自带Pydantic数据校验、自动生成Swagger文档。做算法服务的API封装时，写起来非常顺手。
• 前端框架：Vue3 + ECharts + D3.js。ECharts用来画证型分布雷达图、药材频次统计图，D3.js用来做知识图谱的力导向图交互展示。

这套选型的逻辑是：不能让每个模块各自为战。Neo4j解决关联数据的存储与推理，多模态模型解决非结构化数据的语义理解，FastAPI负责把两者粘合成可调用的服务。整个架构非常清晰，答辩的时候画一张系统架构图，老师一眼就能看出你做了完整的设计。

1.3 功能模块划分

一个完整的中医智能辅助诊疗平台需要拆成这几个模块：

• 用户管理模块：患者注册登录、病历档案管理、历史诊疗记录查询。
• 多模态数据采集模块：支持舌象图片上传、症状文本录入（也可以做成结构化表单或语音输入）、脉象等体征数据手动录入。
• 知识图谱构建与管理模块：提供节点/关系导入接口，支持查询和可视化展示。
• 辨证推理模块：核心模块。接收多模态输入，经过特征提取和融合，在图谱上进行推理，输出证型判断依据链和置信度。
• 方剂推荐模块：根据证型推荐候选方剂，并解释推荐理由（哪些症状与方剂中的药物关系紧密）。
• 知识问答模块（可选加分项）：结合图谱实现简单的“症状查方”、“方剂查药”、“药物禁忌”问答。

2. 中医知识图谱本体设计与数据准备

2.1 本体模型：实体类型与关系类型必须分开设计

知识图谱的核心是本体（Ontology），即定义实体和关系的类型体系。我最开始做的时候犯过一个错误：看到中医名词那么多，就把所有东西都揉成一类实体，结果图谱里的关系乱成一团，查询效率极低。后来重新设计了本体，才理顺。

实体类型我规划为六类：Disease（疾病）、Syndrome（证型）、Symptom（症状）、Herb（中药）、Formula（方剂）、Acupoint（穴位）。此外可以把Channel（经络）也作为一个实体类型，跟穴位关联起来。

关系类型设计时不要怕多，但要保证每条关系都有明确语义指向，我定义了这些核心关系：

• (Disease)-[:HAS_SYNDROME]->(Syndrome)：疾病对应的证型。
• (Syndrome)-[:HAS_SYMPTOM]->(Symptom)：证型表现出的症状。
• (Symptom)-[:INDICATES]->(Syndrome)：症状指向证型，这是反向推理用的。
• (Formula)-[:TREATS]->(Syndrome)：方剂主治某证型。
• (Formula)-[:CONTAINS]->(Herb)：方剂包含某味药。
• (Herb)-[:TREATS]->(Symptom)：单味药针对某个症状。
• (Herb)-[:BELONGS_TO]->(Channel)：药物归经。
• (Acupoint)-[:LOCATED_ON]->(Channel)：穴位位于经络。
• (Acupoint)-[:TREATS]->(Symptom)：穴位治疗症状。

这样设计的好处是，从患者输入的症状出发，可以沿(Symptom)-[:INDICATES]->(Syndrome)找到可能的证型，再沿(Formula)-[:TREATS]->(Syndrome)找到候选方剂，最后沿(Formula)-[:CONTAINS]->(Herb)输出方剂里的药物组成。整条推理链完全可解释，每一步都能追溯到图谱中的具体路径。

2.2 数据来源：不能直接爬，必须做双层清洗

中医知识图谱的数据源主要有三个方向：公开的中医诊疗数据集、中药大辞典和药典的内容、以及医学教材里整理好的辨证论治表。我在做这个项目的时候没有直接写一个通用爬虫去爬网站数据，因为中医网站数据质量参差不齐，很多是论坛帖子、民间验方，直接拿进来会让图谱变得很脏。

我建议的流程是：

1. 先把《中医诊断学》教材里的辨证论治部分手工整理成结构化表格，虽然耗时，但准确率高，而且可以作为图谱的“黄金种子数据”。大约整理300个常见症状、80个常见证型、50个基础方剂、200味常用中药，就足够支撑一个演示系统了。
2. 再从公开的TCMSP（中药系统药理学数据库）和中医药综合数据库里，按“已收录药物”的清单去筛选补充靶点、归经、性味归经这些属性数据。
3. 最后用Python写一个基于规则的对齐脚本，把同义词规范化。比如“发热”和“发烧”、“恶寒”和“怕冷”要统一到同一个症状节点。这一步不做，后面检索会大量漏匹配。

关于舌象图像数据，公开的舌象数据集不是很多。我找了一个开源舌象数据集，再加上自己标注的一小部分图片。图片数据不用多，做毕设的话，每类舌象（淡红舌、红舌、紫暗舌、胖大舌、齿痕舌、黄苔、白苔、腻苔等）收集80-100张就够训练一个预训练模型微调版本的分类器了。

2.3 把数据批量导入Neo4j的实操方法

推荐用Python的py2neo库或官方neo4j驱动批量导入，一次用UNWIND批量创建节点和关系，比逐条CREATE快非常多。我实测过，用UNWIND分批导入大约2万条记录，十几秒就能完成，而逐条插入可能要几分钟。

核心导入代码逻辑大概是：

from neo4j import GraphDatabase class Neo4jImporter: def __init__(self, uri, user, password): self.driver = GraphDatabase.driver(uri, auth=(user, password)) def create_symptom_nodes(self, symptom_list): with self.driver.session() as session: session.run( """ UNWIND $batch AS row MERGE (s:Symptom {name: row.name}) SET s.category = row.category """, batch=symptom_list ) def create_syndrome_relations(self, relation_list): with self.driver.session() as session: session.run( """ UNWIND $batch AS row MATCH (s:Symptom {name: row.symptom}) MATCH (sy:Syndrome {name: row.syndrome}) MERGE (s)-[:INDICATES]->(sy) """, batch=relation_list ) def close(self): self.driver.close()

注意一点：节点的name属性必须建唯一约束，例如：

CREATE CONSTRAINT ON (s:Symptom) ASSERT s.name IS UNIQUE;

这样每次执行MERGE的时候才能正确匹配已有节点，而不是重复创建。

3. 多模态特征提取与融合模型实现

3.1 舌象图像特征提取：从ResNet到Vision Transformer的取舍

舌象图像属于细粒度分类问题，不同舌象之间的差异有时非常细微，比如“淡红舌”和“淡白舌”在色相上只差一点点。我先尝试了ResNet50直接做分类，效果不太理想，主要问题是光线干扰大、边缘信息丢失多。后来改成两阶段方案：

先用一个目标检测模型（YOLOv5或更轻量级的SSD）从原始照片里把舌体区域抠出来，去除嘴唇、面颊、背景这些干扰信息，再送入分类网络。这一步非常有效，准确率能提升近10个百分点。如果你的毕设不想做得太重，也可以手动裁剪舌头区域做成数据集，效果一样，只是工作量前移了。

舌象特征提取网络我用的是迁移学习方案，具体来说：

import torchvision.models as models import torch.nn as nn class TongueEncoder(nn.Module): def __init__(self, embed_dim=256): super().__init__() resnet = models.resnet50(weights=models.ResNet50_Weights.IMAGENET1K_V2) self.features = nn.Sequential(*list(resnet.children())[:-1]) self.fc = nn.Linear(2048, embed_dim) def forward(self, x): feat = self.features(x).flatten(1) return self.fc(feat)

训练时冻结前几层，只微调后面的卷积块和全连接层，避免数据量不够导致过拟合。数据增强方面，随机旋转、随机亮度对比度调整、高斯模糊这三个是必须加的，能有效提升模型对真实拍摄环境的鲁棒性。

3.2 症状文本编码：BERT还是传统词向量

症状文本的处理也是关键。如果直接用TF-IDF或者Word2Vec做词袋，会丢失上下文信息，比如“恶寒重”和“重恶寒”在词袋模型里完全一样，但实际语义重心不同。所以这里一步到位用预训练语言模型更省心。

考虑到是中文医学领域，直接拿通用中文BERT效果一般，推荐用MedicalBERT或者在中医语料上继续预训练的模型。如果嫌模型太大部署麻烦，可以退而求其次用哈工大Chinese-Word2Vec向量做词级编码，配合TextCNN提取语义特征。我用BERT做的时候，把每个症状描述文本编码成768维向量，再通过一个全连接层降到256维，跟图像特征对齐。

from transformers import BertTokenizer, BertModel tokenizer = BertTokenizer.from_pretrained("bert-base-chinese") model = BertModel.from_pretrained("bert-base-chinese") def encode_symptom_text(text): inputs = tokenizer(text, return_tensors="pt", max_length=64, padding=True, truncation=True) outputs = model(**inputs) return outputs.last_hidden_state[:, 0, :] # [CLS] token

3.3 多模态融合：不是简单拼接，而是要对齐

多模态融合是整个项目里最容易被做浅的地方。很多毕设就是把图像特征和文本特征拼在一起，然后接一个全连接层，这当然有作用，但只属于早期融合，没有建模模态间的关联。更合理的做法是加一层Cross-Attention，让文本特征去“关注”图像中最相关的区域，同时让图像特征去“查询”文本中的关键症状描述。

我用的是一个简化版的跨模态注意力模块，核心逻辑如下：

import torch import torch.nn as nn import torch.nn.functional as F class CrossAttentionFusion(nn.Module): def __init__(self, embed_dim=256): super().__init__() self.img_proj = nn.Linear(embed_dim, embed_dim) self.txt_proj = nn.Linear(embed_dim, embed_dim) self.fusion_gate = nn.Linear(embed_dim * 2, embed_dim) def forward(self, img_feat, txt_feat): q = self.txt_proj(txt_feat).unsqueeze(1) # 文本作为查询 k = self.img_proj(img_feat).unsqueeze(1) # 图像作为键 v = img_feat.unsqueeze(1) attn_weights = F.softmax(torch.matmul(q, k.transpose(-2, -1)) / (k.size(-1) ** 0.5), dim=-1) attended = torch.matmul(attn_weights, v).squeeze(1) gate = torch.sigmoid(self.fusion_gate(torch.cat([img_feat, txt_feat], dim=-1))) fused = gate * attended + (1 - gate) * txt_feat return fused

这里用了门控机制，让最终的融合向量能动态权衡图像特征和文本特征的贡献。你可以把它理解为：模型在判断“气虚证”的时候，会同时看舌象上有没有齿痕（图像线索），以及主诉里有没有“神疲乏力”（文本线索），而且这两个线索不一定是等权重的。

至于结构化体征数据（体温、心率、血压、脉率等），我会单独用一个MLP编码成64维向量，再通过注意力池化拼接进融合层。这样“多模态”就不是噱头了，而是覆盖了图像、文本、结构化数值三类模态。

3.4 从融合向量到图谱节点的链接预测

拿到了多模态融合向量之后，怎么用它判断证型？这里有个很关键的设计思路：不能直接让融合向量去做一个Softmax多分类，因为那样只会输出一个证型标签，无法解释推理过程。更好的做法是：

1. 把融合向量映射到“症状增强向量”，即预测每个标准症状在患者身上的存在概率。
2. 然后根据图谱中(Symptom)-[:INDICATES]->(Syndrome)的关系，把症状概率沿边传播到证型节点。
3. 累加得到每个证型的得分，再按阈值筛选和排序。

这个流程既利用了多模态模型对非结构化输入的理解，又保留了知识图谱的结构化推理能力。用图论术语讲，这就是在图上做label propagation。这样做的好处非常明显：你能告诉用户“因为你存在舌质红、口干、发热这三个症状，所以判断为卫分证”，而不是只扔一个“风热犯卫证”的结论。

4. 辨证推理与方剂推荐的核心逻辑

4.1 基于图谱路径的证型得分传播设计

这个模块是系统的大脑。完整推理流程分成四步：

第一步：归一化多模态输出。模型对每个标准症状输出一个0到1之间的存在概率，低于0.5的一律置0，避免噪声症状干扰后续传播。

第二步：在知识图谱里找到所有与输入症状相关的证型节点，并计算传播得分。每个证型的初始得分为其覆盖的匹配症状的加权和，权重则来自症状对该证型的区分度系数。我在本体里给每个INDICATES关系设置了weight属性，这个权重预先通过频率统计归一化得到。某个症状在越多证型中出现，它的区分度就越低，权重就相应越小。

第三步：对证型得分做衰减修正。如果一个证型命中的症状数量很少，但得分很高，也要适当打折。这里采用了一个简单的非对称衰减公式：

score_final = score_raw * (1 - exp(-n / K))

其中n是匹配到的症状数量，K是一个超参数，我取2.5。这个公式的含义是：症状匹配个数越少，可信度越低。

第四步：按得分排序，取前3个证型作为候选结果，并格式化输出推理链。

4.2 Cypher查询语句怎么组织

我把核心的证型推理查询写成了一段Cypher，在Neo4j里执行效率还不错：

MATCH (s:Symptom)-[r:INDICATES]->(sy:Syndrome) WHERE s.name IN $symptom_names WITH sy, sum(r.weight) AS syndrome_score, collect(s.name) AS matched_symptoms WHERE syndrome_score >= $threshold RETURN sy.name AS syndrome, syndrome_score, matched_symptoms ORDER BY syndrome_score DESC LIMIT 5

方剂推荐的查询则是在确定证型之后，沿着(Formula)-[:TREATS]->(Syndrome)关系查找：

MATCH (f:Formula)-[:TREATS]->(sy:Syndrome {name: $syndrome_name}) OPTIONAL MATCH (f)-[:CONTAINS]->(h:Herb) RETURN f.name AS formula, collect(h.name) AS herbs, f.usage AS usage

4.3 推荐结果的解释生成策略

辅助诊疗平台跟一般的问答系统有个很核心的区别：用户要的不仅是结果，更是“为什么”。所以我实现了一个generate_explanation函数，把推理链拼接成可读文本。

比如最终输出是这样一段：

“根据您输入的‘咳嗽、咽痒、恶寒重、无汗’等症状，结合舌象特征（舌淡红、苔薄白），系统通过知识图谱关联分析，匹配到3条指向‘风寒束表证’的症状关系，置信度为0.86。在此基础上检索到经典方剂‘麻黄汤’，该方包含麻黄、桂枝、杏仁、炙甘草四味药，其中麻黄、桂枝针对恶寒无汗，杏仁协助止咳。建议咨询专业中医师后参考使用。”

这段解释里每一个环节都能在代码里定位：症状匹配来自文本模型预测，舌象分析来自图像模型预测，证型置信度来自图谱传播得分，方剂的“君臣佐使”解释则来自图谱路径中(Herb)-[:TREATS]->(Symptom)的关联。这就是多模态知识图谱跟黑盒深度模型最大的不同——它的每一步推理都是可以审计的。

5. 系统后端API与知识图谱可视化交互实战

5.1 FastAPI接口定义与内部调度逻辑

后端不是简单地调一下模型就行，而是要编排一整套流水线。我用FastAPI定义了四个核心接口：

• POST /api/diagnosis：接收患者上传的舌象图片和症状文本，返回辨证结果、推荐方剂及解释。
• GET /api/graph/syndrome/{name}：查询某个证型的关联子图，用于前端可视化展示。
• GET /api/herb/{name}：查询中药的性味归经、禁忌信息。
• GET /api/history/{patient_id}：查询历史诊疗记录。

/api/diagnosis的处理逻辑是线性编排的，大致如下：

@app.post("/api/diagnosis") async def diagnosis(patient: DiagnosisRequest): # 1. 处理文本症状 text_feat = encode_symptom_text(patient.symptoms_desc) # 2. 处理舌象图像 image_feat = encode_tongue_image(patient.tongue_image) # 3. 处理结构化体征 struct_feat = encode_signals(patient.signs) # 4. 多模态融合 fused = fusion_module(text_feat, image_feat, struct_feat) # 5. 转换症状概率 symptom_probs = symptom_predictor(fused) active_symptoms = symptom_probs[symptom_probs >= 0.5] # 6. 图谱推理 syndrome_scores = graph_reasoning(active_symptoms) top_syndromes = select_top(syndrome_scores, k=3) # 7. 方剂推荐 formulas = recommend_formulas(top_syndromes[0]) # 8. 组装解释 explanation = generate_explanation(active_symptoms, top_syndromes, formulas) return { "syndromes": top_syndromes, "formulas": formulas, "explanation": explanation }

路由函数里不直接写业务逻辑，而是拆到独立的service层。这样后面如果要加缓存、加异步任务、换模型版本，都不需要改接口层代码。

5.2 前端图谱可视化：D3.js力导向图的布局与交互

前端知识图谱可视化我选择了D3.js的力导向图。原因比较简单：Neo4j自带的Bloom和Neo4j Browser虽然炫酷，但一个是商业授权限制，一个不适合直接嵌入Web页面。D3.js自由度最高，可以自定义节点颜色、连边样式、悬浮信息卡片、点击展开折叠。

我实现的交互逻辑是这样的：

• 节点颜色按实体类型区分：证型用红色、症状用蓝色、方剂用绿色、中药用橙色。
• 节点大小按度中心性（degree centrality）映射，关联越多的节点显示越大。
• 点击一个证型节点，右侧抽屉展示该证型的详细信息，包括对应的方剂列表、典型症状、舌象特征。
• 支持拖拽画布、缩放、搜索定位节点。

D3的力导向图在数据量超过500个节点时会有性能问题，所以我在前端加了一个简单的策略：默认只渲染当前选中节点的一跳邻居，点击展开时才逐步加载更多二级节点。这个体验比一次全量渲染要好太多，而且代码逻辑也更清晰。

为了把Neo4j查询结果转成D3需要的{nodes: [], links: []}格式，我写了一个小的转换函数：

def format_graph_data(records): nodes, links = {}, [] for record in records: for node in [record["a"], record["b"]]: if node.identity not in nodes: nodes[node.identity] = { "id": node.identity, "label": node["name"], "category": list(node.labels)[0] } links.append({ "source": record["a"].identity, "target": record["b"].identity, "relation": record["r"].type }) return {"nodes": list(nodes.values()), "links": links}

6. 实操中遇到的典型问题与排查方法

6.1 图谱查询性能慢的排查与优化

我在开发过程中发现，当图谱节点数量到了三万多个以后，某些不带索引的MATCH查询会明显变慢。一次MATCH (s:Symptom {name:"发热"})竟然要200毫秒以上，这在交互式应用里是不可接受的。

排查步骤如下：

1. 首先用EXPLAIN或PROFILE查看执行计划，确认是否走了NodeIndexScan而非NodeByLabelScan。
2. 检查是否给Symptom、Syndrome、Formula、Herb这些高频查询的实体添加了name唯一约束或普通索引。
3. 如果某个查询经常需要遍历所有关系，考虑把关系方向写死，或者用MATCH (a)-[r]->(b)之间先加WHERE过滤，减少候选集。

优化后，同样的查询从200毫秒降到了10毫秒以内。这个优化过程本身就是毕设的一个亮点，建议在论文里单独写一节“系统性能优化”。

6.2 多模态特征向量“模态坍缩”问题

训练多模态融合模型时，我遇到过一个很典型的坑：图像特征和文本特征拼接后，模型在训练集上loss降得很快，但验证集上图像部分几乎不起作用。原因是文本特征本身已经能比较好地完成分类任务，模型学不到图像特征的增益，最后所有样本的融合向量在图像那一维退化成了近似固定值，这就是“模态坍缩”。

解决办法有两个方向：

一是用跨模态对比学习做预训练，强制模型拉近“同一个病人”的舌象特征和症状特征，拉远“不同病人”的特征，这样图像分支就不会偷懒。二是在融合前对每个模态做独立的dropout，训练时随机丢弃其中一种模态，迫使模型即使只看到一个模态也能做预测。我用第二种方法加上了0.3的dropout，效果立竿见影，图像模态开始真正起作用了。

6.3 数据对齐错漏：同义症状名称无法匹配

中医术语的同义现象极其严重。“口渴”和“口干”在临床上可能含义相近，但如果不做规范化，它们在图谱里就是两个独立节点，导致用户输入“口干”时匹配不到任何证型。部分实体入库的时候同一个症状被爬虫从不同来源写成了不同名字，图谱就乱了。

我的解决方案是维护一个“术语别名表”，在数据入库时做一遍统一映射。比如：

这个别名表一开始手工整理，后面可以用Word2Vec找相似词来辅助扩充，但最终需要人工审核一遍，避免把相反语义的词合并在一起。

7. 测试与部署环境的完整搭建

7.1 模型评估指标要选对

中医辅助诊疗的评估不能只看“准确率”。因为证型类别多且分布极不均衡，常见的“气虚证”“血虚证”样本数量远多于“湿热证”，如果模型全预测为热门证型，准确率可能虚高。

我建议采用三个指标：

• Macro-F1：每个类的F1取算术平均，对少数类更公平。
• Top-3命中率：只要真实证型出现在前三个预测结果里就算命中。因为辅助诊疗系统目标不是替代医生做唯一判断，而是提供候选范围，这个指标更贴近实际应用场景。
• 推理路径覆盖率：输出的解释中，有多少比例可以被知识图谱中的路径完整回溯。这个指标是我自己定义的，用来检验系统“可解释性”不是靠编故事。

7.2 Docker Compose一键部署与踩坑记录

为了答辩演示方便，我把整个系统打包成了Docker Compose部署方案，把Neo4j、FastAPI后端、前端Vue构建后的静态资源服务、以及训练好的模型权重都封装成了镜像。

version: '3.8' services: neo4j: image: neo4j:5.16.0-community ports: - "7474:7474" - "7687:7687" environment: - NEO4J_AUTH=neo4j/password123 - NEO4J_server_memory_heap_max__size=1G volumes: - neo4j_data:/data backend: build: ./backend ports: - "8000:8000" depends_on: - neo4j environment: - NEO4J_URI=bolt://neo4j:7687 - NEO4J_USER=neo4j - NEO4J_PASSWORD=password123 volumes: - ./backend/models:/app/models frontend: build: ./frontend ports: - "80:80" depends_on: - backend volumes: neo4j_data:

这里有一个非常容易踩的坑：Neo4j在Docker容器里分配内存需要显式配置，否则默认堆内存可能只有几百MB，导入大批量数据时会直接OOM。我给NEO4J_server_memory_heap_max__size设置了1G，如果你机器内存充足，建议给到2G。

另外，后端容器连接Neo4j时，host必须写neo4j而不是localhost，因为容器间是通过Docker内部网络通信的。第一次部署时我在这里卡了大半天，日志里一直报连接超时，最后才发现是地址配置问题。

7.3 模型文件管理与版本控制

模型训练好之后会有好几个文件：舌象分类器的.pth权重、文本编码器的pytorch_model.bin、融合模块的权重。这些文件加起来可能有500MB以上，不适合提交到Git仓库。我的做法是：

• 用git-lfs管理核心模型文件。
• 训练脚本里每次保存模型时，同时导出一份包含超参数和评估指标的config.json。
• 做一个模型注册表机制，后端启动时可以通过环境变量指定加载哪个版本的模型，方便切换对比实验。

MODEL_REGISTRY = { "v1.0": { "tongue_encoder": "models/tongue_encoder_1018.pth", "fusion": "models/fusion_1018.pth", "symptom_predictor": "models/symptom_pred_1018.pth", "metrics": {"accuracy": 0.82, "macro_f1": 0.71} }, "v1.1": { "tongue_encoder": "models/tongue_encoder_1025.pth", "fusion": "models/fusion_1025.pth", "symptom_predictor": "models/symptom_pred_1025.pth", "metrics": {"accuracy": 0.84, "macro_f1": 0.75} } }

8. 常见问题排查速查表与经验总结

我把调试过程中遇到的典型问题整理成了一个速查表，后续做这类系统的同学可以直接参考：

还有一个我特别想强调的经验：在写毕业设计或者说写任何源码项目时，功能可以删减，但解释链路不能丢。哪怕你的模型F1分数不那么亮眼，只要你输出的每一个结论都有图谱路径作为证据，答辩时的说服力就会强非常多。老师追问“这个证型为什么是它”的时候，你能够在台上直接打开Neo4j可视化，指出患者症状指向证型的路径，这比你说一百句“准确率有多高”都有用。

最后聊一下代码结构。别把所有逻辑都堆在main.py里，我记得自己第一次写的时候main文件直接干到1500行，改任何一个小功能都要滚动半天。后来重构成了下面的结构，整个人都舒服了：

tcm_platform/ ├── backend/ │ ├── api/ # FastAPI路由层 │ ├── core/ # 配置、数据库连接 │ ├── graph/ # Neo4j查询封装 │ ├── models/ # 深度学习模型定义 │ ├── services/ # 业务逻辑层（诊断流水线） │ └── utils/ # 文本清洗、数据转换工具 ├── frontend/ │ ├── src/ │ │ ├── components/ # 图谱可视化、表单组件 │ │ ├── views/ # 诊断页面、知识图谱页面 │ │ └── api/ # 前端接口封装 ├── data/ │ ├── raw/ # 原始数据 │ ├── processed/ # 清洗后的结构化数据 │ └── ontology/ # 本体定义json/csv ├── scripts/ │ ├── import_neo4j.py │ ├── train_tongue.py │ └── eval_model.py └── docker-compose.yml

这次做这个中医智能辅助诊疗平台，让我对“知识图谱+深度学习”这套组合的实战边界有了更清晰的认识。深度学习强在感知，知识图谱强在认知和推理，两者不是替代关系，而是互补关系。尤其像中医这种强调“整体观念”和“辨证论治”的领域，单靠任何一种方法都无法构建出真正有用的辅助系统。现在这个项目做完之后，我也在规划后续扩展方向：一个是把脉象传感器采集的波形数据接入进来，做成四模态融合；另一个是把大语言模型接入到解释生成模块，让系统的反馈语言更像一个真人中医师在跟患者对话。如果你们也正在做类似方向，建议从一个小而美的闭环切入，先跑通“症状输入—图谱推理—方剂输出—可解释展示”这条路，再逐步加复杂功能。祝顺利。

本文还有配套的精品资源，点击获取