简介：这套基于BERT、BiLSTM与CRF混合模型的医生推荐系统知识图谱项目，是一套面向计算机专业毕业设计的完整解决方案，也适用于课程设计、期末大作业或项目实战练习。它通过深度学习从医学文本中抽取实体与关系，构建包含疾病、症状、科室和医生的推荐图谱，并为患者智能匹配合适医生，能够解决毕业设计选题难、缺少可运行的完整项目的问题。资源包共114个文件，压缩后约40.42MB，核心为37个Python源码文件，覆盖数据处理、模型训练与推荐模块；另有XML/JSON配置、HTML/CSS/JS前端、CSV数据集、pkl模型文件及日志图片等，结构清晰，方便直接运行与二次开发。目前已有246人学习/下载，参考价值明确。除经过严格调试的完整工程外，资源还附带项目说明文档，详细展示知识图谱构建流程、实体识别与关系抽取的实现思路，以及推荐算法设计逻辑，可直接作为毕业设计整体框架使用，帮助快速掌握BERT、BiLSTM与CRF在实际项目中的配合方式。
1. 把医生推荐做成知识图谱问答：这套代码到底解决什么问题
先别急着看模型，这个标题里最值钱的东西其实是「知识图谱」三个字。医生推荐系统如果只靠 BERT 或者 BiLSTM 做文本匹配，本质上就是个相似度计算器，病人问「头痛耳鸣挂什么科」，它顶多给你返回几个包含这些词的科室名，至于「神经内科和耳鼻喉科到底哪个更对症」这种跨实体推理，纯文本模型根本答不上来。加上知识图谱之后，症状、疾病、科室、医生之间的关联关系变成了一张可查询的图，推荐动作就从「找相似文本」升级成「沿着图结构做多跳推理」，这才是这个项目能写出落地价值的根本原因。
这套基于 BERT + CRF + BiLSTM 知识图谱实现的医生推荐系统，适合谁用？三类人：第一类是正在做垂直领域问答系统、需要一套从数据标注到模型部署完整链路的 NLP 工程师；第二类是做医疗信息化、想把导诊功能塞进现有 HIS 系统的后端开发者；第三类是研究生，拿它当论文的 baseline 或者工程验证。它能解决的问题很具体：从病人的自由文本主诉中抽取症状和疾病实体（BERT+BiLSTM+CRF 负责），把抽出来的实体映射到知识图谱上（实体链接），然后在图谱里查询推荐路径（科室、医生、擅长领域匹配），最后返回推荐结果排序。本文接下来会按数据怎么准备、模型怎么串、图谱怎么查、坑在哪里这条线讲透，新手能照着跑通，熟手能直接拿去改业务。
2. 先搞清楚数据流：从病人主诉到推荐结果的四层管线
2.1 为什么是 BERT + BiLSTM + CRF 三层叠，而不是只用预训练模型
很多第一次接触这个标题的读者会问：BERT 自己就能做序列标注，为什么还要叠 BiLSTM 和 CRF？答案在于标签之间的依赖关系和解码效率。BERT 输出的每个 token 表示是上下文相关的，但它对每个位置独立做分类，不考虑「B-症状后面不能直接跟 I-症状」这类标签转移约束。BiLSTM 在 BERT 之上再做一次序列建模，能把整句话的前后文信息融合进每个位置的隐状态，但它依然不做标签层面的约束。CRF 层的价值就在最后这道工序，它把「标签序列的整体概率」作为优化目标，转移矩阵会学到类似「I-症状 必须跟在 B-症状 后面」「O 标签后面接 I-症状 的概率极低」这种规则。
从训练效率上看，这个三层结构也比端到端换一个更大的预训练模型划算。医疗文本里专业术语多，BERT 底子好但微调成本高，BiLSTM+CRF 结构简单训练快，组合起来既能吃到预训练模型的语义先验，又能用 CRF 保证输出序列合法。如果只有 BERT，长句子里的实体边界经常被切得乱七八糟；如果只上 BiLSTM+CRF，没有预训练模型的底子，小数据集上的泛化能力又不够。这个项目的做法在工业界非常普遍，不是炫技，是被业务数据量逼出来的务实选择。
2.2 数据集长什么样：主诉文本、实体标注、医生画像三张表
做这个项目之前，先要把数据脑补清楚。数据集至少包含三个部分，缺一个推荐逻辑就断了。第一张表是病人主诉文本，格式是一行一句，比如「患者近两周头痛伴恶心，夜间视力模糊」，每一句要有对应的实体标注，标注类别一般是症状、疾病、身体部位、检查项目、药物五类。第二张表是医生画像，字段包括科室、职称、擅长领域、从业年限、评分、接诊量，这是推荐结果的候选池。第三张表是知识图谱的三元组文件，格式是 CSV 或者 JSON，存的是「头痛-属于-神经内科疾病」「偏头痛-可用药-布洛芬」「神经内科医生张医生-擅长-偏头痛」这样的关系。
如果你没有现成医疗数据，可以用公开的 CCKS 竞赛数据或者自己爬公开医院网站做标注。注意标注一致性是个大坑，后面避坑章节我会专门讲。这里先给出一个典型的主诉标注文件格式，tab 分隔，每行一句：
患者近两周头痛伴恶心，夜间视力模糊 B-症状 I-症状 O O O O O B-症状 O O O B-症状这行数据的含义是：每个字/词对应一个标签，标签是 BIO 格式，B 开头是实体首字，I 是实体内部，O 是非实体。实际项目中一般用 word-level 而不是 char-level，中文场景建议按字标注，因为医疗术语分词器经常把「偏头痛」切成「偏/头痛」，但按字标注就不会丢边界信息。把这三张表放进项目目录，数据流就跑通了。
2.3 主诉文本的预处理：分字、词典构建、BERT tokenizer 三件套
文本预处理是整个管线里最容易被低估的一步。常见做法是用 BERT 自带的 tokenizer 做切分，然后额外维护一个字符到 id 的映射，因为 BiLSTM 层的输入不一定完全等价于 BERT 的 subword 切分。以中文为例，BERT 的 tokenizer 会把句子切成字级别，但有些特殊符号如「%」「＋」会被拆成多个 subword，此时要给每个 subword 分配实体标签，规则是：如果原始字是实体开头，则第一个 subword 标 B，其余标 I。
from transformers import BertTokenizer tokenizer = BertTokenizer.from_pretrained("bert-base-chinese") def align_label(text, labels, tokenizer): # 将 char-level 的 BIO 标签对齐到 BERT subword 级别 tokens = tokenizer.tokenize(text) aligned_labels = [] idx = 0 for token in tokens: if token.startswith("##"): # BERT 中文一般没有 ## 后缀，但保险起见处理英文 aligned_labels.append("I" + labels[idx][1:] if labels[idx] != "O" else "O") else: aligned_labels.append(labels[idx]) idx += 1 return tokens, aligned_labels这段代码的逻辑是逐 token 对齐标签。中文场景下 tokenizer 基本是字级别，所以 idx 每次加 1 即可；如果是英文，遇到连续 subword 时要特殊处理。跑不通的情况多半是带标签的字符数和 tokenizer 切出的 token 数不一致，解决办法是在预处理时忽略空字符和特殊符号，不要硬对齐。
预处理完还要统计所有标签类别数量，构建 label2id 映射，这个映射在训练和推理时都要保持一致。如果你在训练完成后又往数据里加了新实体类型，那就要重训模型，否则 CRF 层的转移矩阵维度对不上，这是新手极容易踩的坑，后面会展开。
3. 模型怎么串：BERT 编码、BiLSTM 增强、CRF 解码的完整训练流程
3.1 网络结构图拆解：输入层、编码层、解码层的维度怎么对
先画一遍维度流转，这个搞懂了代码不会写歪。输入是一个句子，长度为seq_len，每个 token 转成 id 后过 embedding 层，得到维度[batch_size, seq_len, hidden_size]。BERT base 的 hidden_size 是 768。接着把 BERT 的最后一层输出拉出来，维度还是[batch_size, seq_len, 768]，这一步不做池化，因为序列标注需要保留每个位置的表示。
然后过 BiLSTM，LSTM 的隐藏层维度设为 256，双向拼接后变成 512。此时输出维度是[batch_size, seq_len, 512]，再经过一个线性层映射到标签数量。假设实体类型有 5 类，B/I/O 后总共是 11 个标签（5 类乘以2再加O），线性层输出就是[batch_size, seq_len, 11]。最后进入 CRF 层，CRF 不改变维度，它计算的是最优标签序列的概率，输出仍然是[batch_size, seq_len]的 label ids。
关键参数就三个：LSTM hidden size、dropout、CRF 的学习率缩放。hidden size 一般取 128 或 256，太大会让训练变慢且容易过拟合；dropout 在 BERT 输出和 BiLSTM 输出之间各加一层，概率取 0.5 强度适中；CRF 层的学习率建议比主模型小一个数量级，否则转移矩阵振荡太剧烈，loss 下不去。待会儿我会给出具体代码。
3.2 训练代码：PyTorch 实现 BERT+BiLSTM+CRF 的标准写法
先定义一个实体识别模型类，把所有层串起来。
import torch import torch.nn as nn from torchcrf import CRF from transformers import BertModel class BertBilstmCrf(nn.Module): def __init__(self, bert_model_name, num_tags, lstm_hidden=256, dropout=0.5): super().__init__() self.bert = BertModel.from_pretrained(bert_model_name) self.bilstm = nn.LSTM( input_size=768, hidden_size=lstm_hidden, num_layers=1, bidirectional=True, batch_first=True, ) self.dropout = nn.Dropout(dropout) self.dense = nn.Linear(lstm_hidden * 2, num_tags) self.crf = CRF(num_tags) def forward(self, input_ids, attention_mask, labels=None): bert_outputs = self.bert(input_ids=input_ids, attention_mask=attention_mask) sequence_output = bert_outputs.last_hidden_state sequence_output = self.dropout(sequence_output) lstm_output, _ = self.bilstm(sequence_output) lstm_output = self.dropout(lstm_output) emissions = self.dense(lstm_output) if labels is not None: loss = -self.crf(emissions, labels, mask=attention_mask.bool()) return loss else: return self.crf.decode(emissions, mask=attention_mask.bool())逻辑说明：前向计算分两段，训练时返回 CRF 的负对数似然损失，推理时返回解码出的标签序列。torchcrf的decode方法内部用了 Viterbi 解码，不需要自己写动态规划。这里有个细节，mask参数传的是attention_mask.bool()，它的作用是把 padding 位置排除在 CRF 转移计算之外，如果你的数据里有长句子，padding 后不传 mask，CRF 会把 padding 位置的标签也纳入转移计算，结果一塌糊涂。
参数说明：lstm_hidden=256是双向后的单方向维度，所以线性层输入是 512；num_tags是标签总数，按前面 11 类算就是 11。bert_model_name建议用bert-base-chinese，显存不够就换hfl/chinese-bert-wwm-ext，效果差不多但词表覆盖更好，下载失败时可以用本地路径加载。
3.3 训练循环里的三个决定性细节：学习率、梯度裁剪、类别不均衡
模型定义好了，训练循环里还有三个细节直接决定模型能不能收敛。
optimizer = torch.optim.AdamW(model.parameters(), lr=5e-5) # 单独给 CRF 层一个更小的学习率 optimizer_crf = torch.optim.AdamW(model.crf.parameters(), lr=1e-5) for epoch in range(num_epochs): for batch in dataloader: input_ids = batch["input_ids"].to(device) attention_mask = batch["attention_mask"].to(device) labels = batch["labels"].to(device) loss = model(input_ids=input_ids, attention_mask=attention_mask, labels=labels) total_loss = loss + sum(p.norm(2) for p in model.parameters() if p.requires_grad) * 0.01 optimizer.zero_grad() optimizer_crf.zero_grad() total_loss.backward() # 梯度裁剪防止 LSTM 梯度爆炸 nn.utils.clip_grad_norm_(model.parameters(), max_norm=5.0) optimizer.step() optimizer_crf.step()说明：LSTM 层和 CRF 层容易梯度爆炸，clip_grad_norm_是必须的，max_norm=5.0是经验值，如果你的 loss 在训练前几个 step 变成 NaN，先看是不是这个问题。CRF 转移矩阵对学习率很敏感，单独给 1e-5 会比较稳。L2 正则加的 0.01 权重不是必须的，如果训练集很小，可以加上防止过拟合；数据集够大直接去掉节省时间。
类别不均衡问题在实体识别里很突出，O 标签（非实体）占了绝大多数。如果你不做任何处理，模型很容易把所有 token 都预测成 O，精确率看着还行但召回率极低。常见做法是给 CRF 的 loss 按标签类别加权，torchcrf库里拿 loss 不方便直接加权重，我一般会在数据预处理阶段对 O 标签做欠采样，或者用 Focal Loss 的思路把难例权重调大。考虑到 Crf 解码的特殊性，更省事的方案是在训练时把 batch 按句子的实体数量做排序，保证每个 batch 里都有一半带实体的句子，这个方法比调损失函数更直观。
4. 知识图谱构建：三元组怎么设计、Neo4j 怎么存、推荐查询怎么写
4.1 本体设计：症状、疾病、科室、医生四类实体和六种关系
知识图谱不是把三元组随便堆进 Neo4j 就行，先设计本体（Ontology），也就是实体类型和关系类型的约束。这个医疗推荐系统里，实体类型最少四类：症状、疾病、科室、医生。关系类型我建议定义六种：症状-属于-疾病、疾病-属于-科室、医生-擅长-疾病、医生-属于-科室、医生-接诊-症状、科室-包含-症状。前三种是硬关系，来自数据集里的标注；后三种是推导关系，在写入 Neo4j 前要用脚本自动生成，不然推荐路径太短，全是一跳查询，没法叫知识图谱。
举个例子，如果数据里有「偏头痛-属于-神经内科疾病」和「神经内科疾病-属于-神经内科」，还有「张医生-擅长-偏头痛」，那推理路径就是：病人说「头痛」→ 图谱里找到「头痛」节点 → 沿「属于」关系找到「偏头痛」或「紧张性头痛」类疾病 → 沿「擅长」关系找到医生。这段路径如果只靠 BERT 做文本匹配是找不出来的，文本匹配只能算出「头痛」和哪个科室描述更像，做不到多跳推理。
设计本体时还有个常见误用：把「医生」的属性全部塞进关系里，比如「张医生-评分80-推荐」这种三元组，这其实应该存在医生节点的属性上，而不是关系类型。图谱的查询性能跟关系种类的数量强相关，关系种类堆得越多，多跳查询的路径组合越复杂，性能越差，设计原则是关系宁少勿多，能用属性表达的，不要建关系。
4.2 构建脚本：从 CSV 三元组到 Neo4j 的 import 命令
Neo4j 是最常用的图数据库，社区版够用。导入方式有两种：小数据量用 Cypher 的LOAD CSV，大数据量用neo4j-admin import。这个项目的数据规模一般不大，LOAD CSV够用，而且方便做转换。先准备 CSV 文件：entities.csv里每行是一个节点，字段是id, label, name, properties；relations.csv里每行是一个关系，字段是start_id, end_id, type。
# entities.csv id:ID,label,name E001,疾病,偏头痛 E002,症状,头痛 E003,科室,神经内科 E004,医生,张医生# relations.csv :START_ID,:END_ID,:TYPE E002,E001,属于 E001,E003,属于 E004,E001,擅长导入命令如下，在 Neo4j 的 bin 目录下执行：
neo4j-admin import \ --database=medical_kg.db \ --nodes=entities.csv \ --relationships=relations.csv \ --delimiter="," \ --id-type=STRING逻辑说明：neo4j-admin import是批量导入工具，要求所有节点和关系分别放在一个文件里，且节点文件里必须有一个:ID列，关系文件里必须有:START_ID和:END_ID。--id-type=STRING表示 ID 是字符串而不是整数，这样 E001 这种带前缀的 ID 才能被识别。导入完成后需要重启 Neo4j 并切换数据库，注意这个命令只能初始化新数据库，对已有数据的库执行会覆盖，操作前备份是必须的。
如果你是第一次搭环境，建议直接用 Neo4j Desktop，图形界面里创建数据库后把 CSV 放在 import 目录里，然后打开 Browser 执行：
LOAD CSV WITH HEADERS FROM "file:///entities.csv" AS row CREATE (n:Entity {id: row.id, label: row.label, name: row.name});这段 Cypher 的作用是逐行读取 CSV 并创建节点，语法直观，适合验证数据格式。区别是LOAD CSV慢，几万条数据还能接受，几十万条建议走admin import，先本地跑通再决定。
4.3 推荐查询：基于 Cypher 的多跳匹配和排序
图谱建好后，推荐逻辑本质是一条带条件的多跳查询。假设前端传来一个实体链接的结果「头痛」，推荐系统要完成两步：先用 Cypher 查出所有关联医生，再按医生画像属性排序。一个标准查询长这样：
MATCH (s:Symptom {name: "头痛"})-[:属于]->(d:Disease)<-[:擅长]-(doc:Doctor) RETURN doc.name AS doctor_name, doc.department AS department, doc.score AS score, d.name AS disease, s.name AS symptom ORDER BY doc.score DESC LIMIT 10;这段查询的路径是「症状 → 疾病 → 医生」，两跳。如果你想让推荐结果更有可解释性，可以在返回里加上疾病名称和症状名称，这样界面上可以展示「你可能是XX，推荐你看YY医生」。参数说明：ORDER BY doc.score DESC用的是医生评分属性，按业务需要可以换成职称权重乘以接诊量的加权分；LIMIT 10是返回条数上限，一般 5 到 10 条就够了，过多反而让用户选择困难。
实际生产里，实体链接的结果可能有多个候选（比如「头痛」可能同时匹配症状节点「头痛」和疾病节点「偏头痛」），这时推荐系统要先把所有候选实体取出来，再做一次图谱查询合并结果。这个逻辑不要写在 Cypher 里，写在 Python 服务层更清晰，后面章节会给出服务代码。
5. 避坑/常见问题：从数据标注到模型推理的十个血泪经验
5.1 标注不一致导致 CRF 学到错误转移规则
现象：模型训练完成后，验证集 F1 值在 70% 左右就上不去了，打印预测结果发现所有「B-疾病」后面的词都被预测成 O，而不是「I-疾病」。
原因：数据标注时有人把「偏头痛」整体标为 B-疾病，有人标成 B-疾病 + I-疾病 + I-疾病，还有人只标了「偏」字。CRF 的转移矩阵学到的是「I 很少出现在 B 后面」这种统计规律，但真实标注规则是「I 必须出现在 B 后面」，统计规律压过了规则，解码时就把正确的内部连续实体拆断了。
解决：训练前写一个校验脚本，扫描所有标注序列，检查每个 I 标签是否紧跟合法的 B 标签，不合法的直接报错并输出文件名和行号。数据量小就手动修正，数据量大就写规则自动把「B-疾病 + O + 疾病」这种错误序列里 O 改成 I。这个预处理校验比模型调参重要得多，强烈建议放进入口流程。
5.2 BERT 模型下载失败或加载缓慢
现象：在服务器上运行时，BertModel.from_pretrained("bert-base-chinese")卡住不动，或者直接报连接超时。
原因：国内网络环境下 HuggingFace 下载不稳定，尤其是首次运行要下载约 400MB 的模型文件，公司内网经常屏蔽外部域名。
解决：先用本机浏览器或下载工具手动下载三个文件config.json、pytorch_model.bin、vocab.txt，放到项目目录./bert-base-chinese/下，然后代码里改成加载本地路径：
self.bert = BertModel.from_pretrained("./bert-base-chinese/")注意文件目录结构要严格匹配，pytorch_model.bin不能改名，vocab.txt缺失会导致 tokenizer 初始化失败。如果你用的是hfl/chinese-bert-wwm-ext，加载方式一样。另外下载时校验一下文件大小，如果下载到一半中断，加载时会报 unexpected EOF，删掉重下即可。
5.3 BiLSTM 在长文本上丢失实体边界信息
现象：短句测试效果还行，但病人主诉超过 50 个字时，症状实体经常只预测出一半。
原因：BiLSTM 是顺序模型，处理长序列时前面的信息经过多层传递后会衰减，尤其当 BERT 对这种长句的注意力分布已经分散时，LSTM 的隐状态里症状边界信息会被稀释。
解决：第一个办法是限制输入长度，截断到 128 个 token，主诉文本本身不需要全文引入；第二个办法是在 BERT 输出后加一层LayerNorm再进 LSTM，让特征分布稳定些；第三个办法是数据层面，训练时把长句子按标点符号切分成短句，比如按句号、分号切分，保证每段是独立完整的主诉描述。实际业务里第二种和第三种配合用，效果提升比换模型明显。
5.4 CRF 解码结果全是 O 标签
现象：模型训练了好几个 epoch，loss 也降了，但预测任何句子都返回全 O。
原因：训练数据里 O 标签占比过高，模型收敛到「全预测 O」这个局部最优解，因为这样 loss 也不会太大，尤其在 CRF 的转移矩阵初始化不当的时候，CRF 学到的转移概率全偏向 O 标签。
解决：检查训练数据中正样本（含实体的句子）和负样本（没有实体）的比例，控制在 8:2 以上，不要拿大量无实体句子做训练；另外把 CRF 初始转移矩阵里「从 O 转移到 O」的值调低一些，比如在torchcrf里对转移矩阵加一个很小的负偏置。再不行就把dropout从 0.5 降到 0.2，让模型更有拟合能力，这个坑我遇到四次，基本都是数据问题而不是结构问题。
5.5 PyTorch 版本兼容性导致 CRF 层不可用
现象：使用torchcrf库时报错AttributeError: module 'torch' has no attribute 'bool'或者 forward 时维度对不上。
原因：torchcrf是老库，对最新 PyTorch 2.x 的某些 API 兼容不好，尤其mask参数要求torch.bool类型，而某些版本默认返回torch.uint8。
解决：在传入 mask 之前显式转换：
mask = attention_mask.bool()如果还报错，改用pytorch-crf这个维护更积极的库，接口基本一样，导入语句改成from pytorch_crf import CRF。还是不行就锁版本：pip install torch==1.13.1 torchcrf==0.1.0，这个组合在大多数环境里稳定。这类兼容性坑很难靠看报错迅速定位，建议在项目 README 里注明依赖版本，环境重建时能少花半天时间。
6. 进阶技巧：用 FastAPI 把推荐模型包成一个可调试的本地服务
到这里，模型训练完了，图谱也建好了，最后一步是让它能够被业务系统调用。我一般用 FastAPI 起一个轻量服务，把实体识别和推荐查询串成一个接口，这样前端传一段主诉文本进来，后端返回推荐医生列表和推荐理由。这个服务本身还能当调试工具用，接口设计得好不好，直接决定你后续调参和测试效率。
from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class Query(BaseModel): text: str top_k: int = 5 @app.post("/recommend") def recommend(query: Query): # 1. 实体识别：拿到所有症状和疾病实体 tokens, labels = ner_model.predict(query.text) entities = extract_entities(tokens, labels) # 2. 实体链接：把文本实体映射到知识图谱节点 graph_entities = link_entities_to_graph(entities) # 3. 图谱查询：多跳匹配推荐医生 results = query_recommendations(graph_entities, top_k=query.top_k) return {"entities": entities, "recommendations": results}这段服务的核心价值是把三个步骤拆成独立函数，哪个环节出问题可以单独调试。实体识别模型在内存里加载一次，不要在接口内部反复from_pretrained，否则每次请求都要重新加载 BERT，响应时间直接飙到秒级。link_entities_to_graph是实体链接函数，要做模糊匹配，比如模型输出「头疼」而图谱里是「头痛」，需要加一个同义词表或编辑距离匹配。query_recommendations就是上一章的 Cypher 查询封装，注意 Neo4j 连接要用连接池驱动，neo4j官方 Python 驱动自带连接池，每次请求不要新建连接。
关于服务层参数调优，top_k默认返回 5 条，实际推荐系统里我建议返回 10 条然后前端做一个「相关理由」展示下拉框，把每条推荐的路径显示出来，比如「头痛→偏头痛→张医生（擅长偏头痛）」，这样用户认可度高很多。实体识别模型如果预测出多个科室相关的实体，推荐结果要把多个查询结果先合并再排序，合并时要给不同路径的得分加权重，比如症状实体匹配得分 0.6、疾病实体匹配得分 0.4，权重参数也建议暴露在接口里，方便调试。
最后说一个我的个人习惯：对所有接口做回归测试，更要在每次改模型或图谱结构后，拿固定的 20 条典型主诉文本跑一遍输出，对比新旧结果是否有异常变化。这套系统的黑匣子不只 BERT 和 CRF，知识图谱的本体变更也会悄悄改变推荐路径。护住这套回归用例能让你少踩一半以上的坑，希望帮到你。
本文还有配套的精品资源，点击获取
