简介基于Python与BERT模型的文本相似度检测系统是一套面向计算机相关专业毕业设计、课程设计及NLP入门者的完整工程。项目采用Python 3.6.8与MySQL 5.7实现通过BERT双向Transformer预训练模型提取词、句子、篇章的深层语义信息有效解决传统文本表示方法无法捕捉上下文语义的痛点可应用于论文查重、问答匹配、语义检索等场景。压缩包共389个文件大小约52.27MB包含72个Python源码文件、82个pyc编译文件以及数据库SQL脚本同时提供前端展示所需的HTML、CSS、JavaScript、图片与字体资源还含75张GIF演示图并附有部署说明文档和LW相关材料目录结构清晰方便按模块查阅。工具链涵盖PyCharm开发环境与Navicat11数据库管理完整呈现从后端算法到前端交互的开发流程。目前已有69人学习适合希望通过完整项目掌握BERT微调、文本向量化和系统设计的开发者既能直接运行验证也可作为二次开发、毕业论文及课程报告的参考素材。1. 从“BERT做相似度”到“能跑的检测系统”之间隔着什么把 BERT 模型加载进 Python跑一遍余弦相似度整个过程用不了二十行代码。但在实际交付里这个动作只是入口BERT 输出是接分类头还是做成双塔向量训练数据怎么标注阈值切在哪里检索阶段怎么走 GPU这些环节直接决定系统是 demo 还是可用。文本相似度检测在重复内容过滤、问答匹配、语义搜索和毕业设计演示里都是高频需求很多人拿到别人的完整源码后能跑通但一换数据就不出效果。下文按“原理选型 → 最小实现 → 微调训练 → 分数校准”的顺序把基于 python 的 bert 深度学习文本相似度检测系统从头拆开命令和代码都能直接本地运行。2. BERT 文本相似度检测的两种路线与选型边界2.1 句对分类让两个文本在注意力层里直接交互在文本相似度检测里最直观的 BERT 用法是句对分类。输入格式是[CLS] 句子A [SEP] 句子B [SEP][CLS]位置汇聚了整个序列的信息后面接一个线性层和 softmax输出就是相似概率。这种结构被称为 Cross-Encoder两个句子在整个编码过程中互相可见词与词之间的对齐关系可以被自注意力直接看到。相比 TextCNN 这类只做局部窗口交互的基线BERT 在长距离依赖上更有优势这也是它在匹配和意图识别任务上表现更稳的原因。tokenizer 的输出常被新手忽略但恰恰是句对模型最容易错的地方from transformers import AutoTokenizer tok AutoTokenizer.from_pretrained(bert-base-chinese) enc tok(为什么还不发货, 订单为什么显示已取消) print(enc[input_ids][:10]) print(enc[attention_mask][:10])input_ids里[101]是[CLS]起始符[102]是[SEP]分隔符attention_mask用 0/1 表示哪些位置是真实 token、哪些是 padding。padding 位置的 attention mask 为 0告诉模型不要对这些位点投入注意力。我见过不少照着教程改文本、却忘了把 mask 一起喂进去的情况最终分数全部漂移看起来像模型训坏了其实是输入侧有问题。2.2 向量化路线双塔结构把相似度变成向量距离另一种常见做法是把句子编码成语义向量再用余弦相似度衡量距离即 Bi-Encoder。两个句子分别经过同一个 BERT 编码器各自得到句向量相似度用余弦或者内积计算。这种结构没有句子间的交互但换来一个巨大的工程优势候选集可以提前全部向量化查询时只要算查询向量和候选矩阵的乘积。我一般会把双塔作为默认方案。语义检索、文本去重、大规模候选召回底层全都可以落到向量相似性这一个操作上。十万条候选文本预先编码成矩阵新查询到来时一次矩阵乘法就能完成排序线上响应时间稳定在几毫秒到几十毫秒。这也是它成为相似度检测系统主流形态的原因。2.3 预训练 BERT 向量不能直接拿来算相似度一个常见的错误是用bert-base-chinese的最后一层 CLS 向量直接算余弦相似度效果往往不理想。原因是 BERT 预训练产生的表示空间存在各向异性向量被压缩在一个狭窄锥形区域内高频词和低频词的差异很容易被整体方向淹没导致“语义相近但余弦分数不高”。同时预训练阶段的 CLS 头服务于掩码语言模型和下一句预测并没有针对相似任务做对齐。微调的本质就是用人类标注的相似/不相似文本对把 BERT 的向量空间重新排布一遍。相似文本的向量被拉近不相似文本被推开。所以才需要真正的“检测系统”部分数据准备、损失函数、训练与阈值标定缺哪个都会让模型的语义能力落不到业务分数上。2.4 选型边界与量化指标维度句对分类Cross-Encoder向量相似度Bi-Encoder输入形式两个文本拼成一句两个文本分别编码词间交互有注意力可见整段无编码相互独立候选集大慢每对一次前向快候选可预计算典型场景小批量精排、判重检索、聚类、去重精度上限高较低但工程上更强选型边界可以这么判断候选集只有几十条、每对文本都需要严格判重直接用句对分类候选集成百上千则用双塔先召回再句对精排两个模型各管一段。评估指标上检索场景报 RecallK判重场景报 F1。指标先立住后面所有调参才有比对基准。3. 用 Python 在本地跑通 BERT 相似度检测的最小实现3.1 环境与依赖torch、transformers、sentence-transformers先搭一个干净环境。Python 版本建议 3.9 到 3.11过高的 Python 版本容易碰上某个算子没有预编译 wheel 的问题。python -m venv venv source venv/bin/activate pip install torch transformers sentence-transformers第一行创建虚拟环境第二行激活第三行安装三个库。transformers提供模型结构torch是深度学习计算后端sentence-transformers在两者之上封装了句向量和训练接口。安装完先跑一句python -c import torch;print(torch.__version__)确认 CUDA 可用如果输出 CPU 版本后面编码会一边抬高 CPU 占用一边拖慢速度。下载权重时会自动访问 Hugging Face 的模型仓库。如果网络环境不稳定可以设置镜像环境变量或者先在网页端把模型文件下下来解压放进模型缓存目录。模型加载报错大多不是代码问题而是权重没放对位置。3.2 最小实现加载中文 BERT 并计算两句话的相似度from sentence_transformers import SentenceTransformer, util model SentenceTransformer(BAAI/bge-small-zh-v1.5) texts [商品什么时候发货, 订单多久能送到] vecs model.encode(texts, normalize_embeddingsTrue) score float(util.cos_sim(vecs[0], vecs[1])) print(f相似度: {score:.4f})三个要点对应三处参数。模型名决定下载哪一套预训练权重BAAI/bge-small-zh-v1.5是国内常用的中文向量模型体积小、效果好normalize_embeddingsTrue把句向量归一化到单位长度归一化后余弦相似度退化为内积后续接数据库或矩阵运算都更方便util.cos_sim本质是一次矩阵乘法如果传入一批向量它会返回一个完整的相似度矩阵。如果你在本地机器上跑这段代码第一次会看到模型下载第二次开始就直接从磁盘加载。显存不足时把模型名换成shibing624/text2vec-base-chinese显存正常但追求更强效果可以换参数规模更大的嵌入模型代价是推理延迟明显上升。做系统原型先从小模型跑通链路。3.3 封装成检测器从“算分数”到“能判定”工程上不能每来一对文本都临时写一遍 encode需要把模型固定下来。下面的类把模型加载、阈值判定和批量 Top-K 都收进去class BertSimilarityDetector: def __init__(self, model_nameBAAI/bge-small-zh-v1.5, threshold0.8): self.model SentenceTransformer(model_name) self.threshold threshold def is_similar(self, text1, text2): vecs self.model.encode([text1, text2], normalize_embeddingsTrue) score float(vecs[0] vecs[1]) return score self.threshold, round(score, 4) def top_k(self, query, candidates, k5): q_vec self.model.encode([query], normalize_embeddingsTrue)[0] c_vecs self.model.encode(candidates, normalize_embeddingsTrue) scores c_vecs q_vec idx scores.argsort()[::-1][:k] return [(candidates[i], float(scores[i])) for i in idx]is_similar用一次encode同时编码两个文本内部是同一个 batch比两次分别 encode 省一次前向。top_k把候选文本整体编码成二维矩阵再和查询向量做矩阵乘法一次性得到全部相似度argsort()[::-1]从大到小排序后取前 k 个。批量接口和循环逐个调is_similar的时间差距会随候选数量放大候选过万时循环方案基本不可用。提示normalize_embeddingsTrue务必一致。训练、验证、上线推理三个阶段只要有一处没归一化分数尺度就不一致阈值也就失去意义。3.4 参数拆解与常见误区参数建议初始值说明max_length128超长文本截断避免无效计算batch_size32大批量编码时生效normalize_embeddingsTrue统一分数尺度devicecuda:0CPU 也能跑但慢 20 倍threshold0.8用验证集 F1 重新标定一个高频误用是坚持加载bert-base-chinese后自己写mean_pooling。自己写没问题但要注意 BERT 输出的last_hidden_state形状是(batch, seq_len, hidden_size)mean_pooling 要沿着 seq_len 维度做平均而很多人直接对整个张量做 mean得到的是(batch, hidden_size)却损失了注意力掩码。更稳妥的做法是需要考虑attention_mask的 masked mean pooling。用sentence-transformers可以把这个细节封装掉把精力留给数据。4. 训练自己的相似度模型数据、损失与参数调整4.1 数据准备标注格式与难负样本微调 BERT 相似度模型不需要海量数据但需要高质量文本对。一种通用的标注格式TRAIN_PAIRS [ (手机屏幕碎了怎么办, 手机屏摔碎了怎么修, 1), (手机屏幕碎了怎么办, 衣服上的油渍怎么洗, 0), (会员过期什么时候扣费, 会员自动续费怎么关闭, 0), ]第三条是典型的难负样本都围绕“会员”字面也有重复但语义完全不同。这类样本对模型学会“抽象语义比字面重叠更重要”帮助最大。公开中文数据里 LCQMC 是现成的文本匹配语料包含大量来自搜索的疑问句对直接拿来微调就够跑通流程。负样本建议按 1:1 到 1:3 的比例加入。正样本过多模型会把大多数 pair 都先验判成相似负样本过多阈值会往高分数方向偏。数据量小时宁缺毋滥要是负样本全是“苹果-香蕉”这种一眼假的 pair模型在真实场景里推高相似分误判率反而上升。要刻意从候选库里找那种“字面上像、语义上不像”的难例喂进去。4.2 损失函数选型余弦、对比与 CoSENT相似度训练里有三个常用损失选型依据主要是标注粒度。CosineSimilarityLoss把两个句向量的余弦相似度直接和 label 做均方误差label 可以取 0 到 1 之间的连续值适合标注含中间相似度的任务。ContrastiveLoss基于欧氏距离相似样本对拉近、不相似样本对的距离需要大于 margin适合二值标注。CoSENTLoss则把 pair 的分数差映射成概率用于“文本 A 比文本 B 更相似于查询”这类排序信号适合训练数据来自点击日志的检索系统。实际工程里我一般先用 CosineSimilarityLoss 跑基线它实现最简单、收敛稳定排序目标明确时再换 CoSENT。数据规模小的时候不要迷恋复杂损失先看基线分数是不是被数据质量问题拖住了。4.3 用 SentenceTransformer 跑一遍微调from sentence_transformers import SentenceTransformer, InputExample, losses from torch.utils.data import DataLoader model SentenceTransformer(BAAI/bge-small-zh-v1.5) examples [ InputExample(texts[手机屏幕碎了怎么办, 手机屏摔碎了怎么修], label1.0), InputExample(texts[手机屏幕碎了怎么办, 衣服上的油渍怎么洗], label0.0), ] loader DataLoader(examples, batch_size16) loss losses.CosineSimilarityLoss(model) model.fit( train_objectives[(loader, loss)], epochs3, warmup_steps100, output_path./output/sim_model, )InputExample.texts里放一对文本label是相似度目标值。CosineSimilarityLoss前向计算出这对文本的余弦相似度再和 label 计算均方误差误差反传更新模型。epochs3对 BERT 微调已经够用数据量超过十万时再考虑 5。warmup_steps100让学习率先小后大避免训练初期模型参数被大梯度冲乱。训练完的模型保存在output_path后续加载方式和预训练模型完全一致。超参数经验值参数推荐区间说明batch_size16~32显存不足降到 8epochs3~5小数据不超过 5learning_rate1e-5~3e-5过大会灾难性遗忘max_seq_length128长文本任务设 256warmup_steps总步数 10%稳定训练learning_rate是这里最值得手动调的参数。BERT 预训练权重已经收敛得不错微调只是“小幅修正”学习率超过 3e-5 非常容易把向量空间原有的语义结构破坏掉表现为训练 loss 降得很低、验证分数反而变差。4.4 训练时的三个坑冻结、过拟合与显存显存不够时常见操作是冻结部分层。sentence-transformers 的模型结构里model[0]是底层的 transformer 模块可以只冻结 embeddingtransformer model[0].auto_model for param in transformer.embeddings.parameters(): param.requires_grad False冻结 embedding 层后训练参数量变小显存占用大约降低三到四成。代价是模型不能更新词向量如果领域内有大量专业词效果会受影响。小数据场景里这是稳定性优先的做法数据量上万后建议全量微调。过拟合的表现是训练 loss 持续下降但验证 F1 不再增长解决方式是降低 epochs、加难负样本而不是再叠早停和 dropout。模型在相似度任务上更依赖数据分布而不是正则化强度数据越偏规则越容易背住模板。5. 相似度检测系统的分数校准与批量推理优化5.1 用验证集把阈值变成有依据的参数部署时最常用到的技巧是阈值标定。上一节训练完的模型输出的是 0 到 1 的相似分数但业务上要的是“是否判重”的布尔结果。阈值定太低会放过重复项定太高又会误杀正常文本。用验证集遍历一遍候选阈值取 F1 最高的那个就能得到有依据的 thresholdimport numpy as np val_scores np.array([0.83, 0.76, 0.92, 0.61, 0.55]) # 模型输出 val_labels np.array([1, 1, 1, 0, 0]) # 真实标签 best_f1, best_thr 0.0, 0.5 for thr in np.arange(0.5, 1.0, 0.01): pred (val_scores thr).astype(int) tp ((pred 1) (val_labels 1)).sum() fp ((pred 1) (val_labels 0)).sum() fn ((pred 0) (val_labels 1)).sum() f1 2 * tp / (2 * tp fp fn) if f1 best_f1: best_f1, best_thr f1, thr print(fbest f1{best_f1:.4f}, threshold{best_thr:.2f})这里的val_scores是模型在验证集上的输出分数val_labels是人工标注。遍历区间 0.5 到 1.0步长 0.01。F1 能同时惩罚漏掉和误报在相似文本占比低的场景下比准确率更可靠。选好的阈值直接替换检测器构造函数里的threshold。注意验证集必须是模型没见过的数据不能用训练集来选定阈值否则会虚高。5.2 大候选集推理一次批量 encode 加一次矩阵乘如果相似度检测要面向“一段查询打全库”的场景优化重点就是少跑 encode。候选文本可以提前全部编码为矩阵并缓存下来线上只有查询是动态的cache_vecs model.encode(all_texts, batch_size64, normalize_embeddingsTrue) def search(query, top_k10): q_vec model.encode([query], normalize_embeddingsTrue)[0] scores cache_vecs q_vec idx scores.argsort()[-top_k:][::-1] return [(all_texts[i], float(scores[i])) for i in idx]cache_vecs的形状是(N, hidden_size)查询编码成(hidden_size,)后运算符得到 N 个分数。argsort()[-top_k:][::-1]先升序排序再取最后 top_k 个最后反转成降序。这一步内存矩阵乘在十万条候选上通常几十毫秒内完成瓶颈回到model.encode。查询本身也做一层缓存完全相同的查询直接查哈希表不动模型。5.3 观察分数分布判断模型是否该重训上线后的维护动作是持续监控分数分布。取最近一周所有查询产生的相似度分数计算均值和 p90 分位如果均值从 0.6 掉到 0.4往往是业务侧文本风格变了或者新增了一批模型没见过的高频话术。另一个观察点是被判为相似的比例占比持续走高说明阈值偏松或负样本没跟上走低说明模型在数据分布上开始失效。这时候的做法不是改阈值而是采样一批“分数接近阈值”的难例人工标注追加进训练集重新微调。阈值只在分布不变时有效分布一变必须回数据中心。最终交付的系统里应该有四样东西可复现的训练脚本、固定的验证集与阈值、缓存了向量的候选库、分数分布监控任务。监控任务跑在定时调度里每天早上生成前一天的分数分布报表分数均值、相似率、top-k 命中率三项指标出现明显偏移时就触发告警。本文还有配套的精品资源点击获取