简介：这是一份面向自然语言处理学习者的Bert预训练模型微调实战资源，聚焦文本相似度计算任务。资源以蚂蚁金服文本匹配数据为基础，提供完整的fine-tune训练与测试脚本，适合希望掌握Bert下游任务改造、句对匹配模型训练流程的开发者。压缩包共50个文件，其中包含30个Python脚本、13个编译后的pyc文件、2个txt说明、2个csv数据及json、index、meta等辅助文件，整体大小2.77MB，目录结构清晰，便于按模块调用。目前已有480人学习下载。资源内建有sentence_similarity_Bert项目，可直接执行run_classifier_modify2进行微调，并通过run_classifier_class完成测试，chinese_data文件夹内置训练数据，同时提供requirements依赖与环境配置说明，可帮助读者快速复现实验、理解Bert在语义匹配场景中的实际应用与调参细节。
1. 用Bert预训练模型fine-tune计算文本相似度：一条从数据标注到模型部署的完整链路
做FAQ问答系统的重复问题合并时，我最先尝试的是TF-IDF加余弦相似度，直到碰上“手机进水了怎么办”和“iPhone掉水里了有没有救”这种表达差异极大的句子，词面几乎不重叠，传统方案彻底歇菜。后来换成Bert预训练模型fine-tune计算文本相似度这条路，用预训练语言模型的语义表示取代词面统计，在几千条标注文本对上做完fine-tune，模型就能直接输出两段文本语义是否一致。这个zip标题对应的正是这么一套项目实践：预训练模型下载、数据处理、微调训练、相似度推理与评估全链路，适合有Python基础、刚切入NLP并需要把文本匹配业务落地的工程师照着跑通。
2. 预训练模型选型与参数下载：开箱即用的bert是怎么接入项目的
2.1 中文预训练模型怎么选：bert-base-chinese与RoBERTa中文版的取舍
做中文文本相似度，第一步是选预训练模型，这一选基本决定了整个项目效果的天花板。大多数项目会把bert-base-chinese当作默认起点：12层Transformer编码器、768维隐藏层、约1.1亿参数，在大规模中文语料上做过掩码语言模型预训练。它的优点是生态足够成熟，网上跑通的中文Bert示例几乎都基于它，遇到报错也好搜解决方案。如果你的数据是新闻、百科、通用问答这类相对规范的文本，直接用它没有毛病。
如果文本偏向口语和噪声，比如客服对话、电商评论、闲聊式短句，那RoBERTa中文预训练模型通常更稳。RoBERTa去掉了下一句预测任务，改用动态掩码以及更大的batch size训练，对短文本语义的建模比原版Bert更抗口语变体；hfl发布的RoBERTa-wwm-ext就是很多人实际会用到的版本。但换成时要特别注意，RoBERTa的分词器配置和Bert不完全一致，如果拿BertTokenizer去加载RoBERTa权重，会直接报词表大小不匹配。
我的建议是项目起步阶段别花太多时间在选型上，先用bert-base-chinese把全流程跑通拿到baseline，验证集分数不理想再换RoBERTa做对照。切换成本只落在模型路径和tokenizer实例上，训练脚本完全不用动，这算是预训练语言模型生态对下游任务最友好的地方。
为什么Bert能迁移到文本相似度任务？简单一句话：预训练阶段它在海量无标注文本上学到的不是某个具体任务，而是词法、句法、指代、语义关系这些通用语言能力。下游只要在预训练权重上加一个分类头，用几千条标注数据做fine-tune，就能把这套能力引导到“判断两段文本语义是否一致”上，标注需求比从零训练少了两个数量级。
2.2 bert 参数下载与模型文件：transformers缓存目录里装了什么
from_pretrained是接入预训练模型最常见的入口，但bert 参数下载这个环节也是新手最容易卡住的一道坎。直接在代码里写“bert-base-chinese”会让transformers在首次运行时自动联网下载，网络不稳就反复失败，而且自动下载不带断点续传。下表是下载完成后模型目录里出现的三个关键文件：
| 文件 | 作用 | 大致体量 |
|---|---|---|
| config.json | 模型层数、维度、注意力头数等结构配置 | 几KB |
| pytorch_model.bin | 预训练权重，后续fine-tune基于它继续训练 | 400MB级别 |
| vocab.txt | 中文词表，tokenizer分词与编码依赖它 | 1MB左右 |
我一般会先把预训练模型下载好放进项目目录，再用本地相对路径加载，这样训练环境不再依赖外网。加载本地模型的最小代码长这样，后面顺便验证分词是否正常：
from transformers import BertTokenizer, BertForSequenceClassification model_path = "./models/bert-base-chinese" # 从本地目录加载，不会触发联网下载 tokenizer = BertTokenizer.from_pretrained(model_path) model = BertForSequenceClassification.from_pretrained( model_path, num_labels=2 # 输出层替换为2分类：相似/不相似 ) print(tokenizer.tokenize("怎么申请退货退款"))from_pretrained的第一个参数传本地路径后，transformers会直接读取磁盘上的config和权重文件，不再联网。num_labels=2会构造一个全新的线性分类头替换掉预训练时的MLM预测头，这是fine-tune的标准姿势。执行后打印的分词结果是按字切开的，比如['怎', '么', '申', '请', '退', '货', '退', '款']，因为bert-base-chinese用的是字级词表，看到这个输出就能确认模型和词表都加载成功了。
如果想确认模型真的换成了分类版本，可以在加载后打印参数量：sum(p.numel() for p in model.parameters())，结果通常也在1亿出头，和原版BertModel量级一致，因为替换的分类头只占很小一部分参数。这类小检查在项目里常用来快速确认预训练模型加载完整，也能在后续做模型裁剪时提供一个基线。
2.3 第一次前向推理：未微调的模型输出为什么不能当相似度用
模型加载完，新手最想干的事肯定是拿几个文本对直接算相似度。这里我不拦你，因为跑一次前向输出能直观看到预训练与微调之间的差距。下面这段代码用未微调的模型处理两对文本，打印softmax概率：
import torch sent_pairs = [ ("苹果手机怎么退货", "刚买的iphone还能退吗"), ("如何查看快递单号", "今天中午吃什么"), ] inputs = tokenizer( sent_pairs, padding=True, truncation=True, max_length=64, return_tensors="pt", ) model.eval() with torch.no_grad(): logits = model(**inputs).logits probs = torch.softmax(logits, dim=-1).numpy() for pair, prob in zip(sent_pairs, probs): print(pair, "-->", prob)关键在tokenizer的调用方式。传入list of tuples时，tokenizer会自动把每个文本对拼成[CLS]加文本A加[SEP]加文本B加[SEP]的结构，同时生成attention_mask和token_type_ids。padding=True会把batch内的短样本补齐到和最长样本一致，truncation=True截断超长输入，max_length=64限制了序列最长长度，token_type_ids则让模型知道当前token属于前半句还是后半句。
此时模型的分类头还是随机初始化的，输出的概率分布基本没有判别意义。你要记住的是这个结论：Bert预训练模型本身只学到了通用的语言表示，还不会“比较两段文本相似与否”，这个能力只能靠后续的fine-tune喂给它。所以这步跑通的意义是验证加载与数据管路正常，真正的重头戏从数据构造开始。
3. 构建文本相似度数据集：样本组织形式决定模型成绩上限
3.1 标注范式设计：二分类还是多分类相似度
文本相似度的建模本质，是把“语义相近程度”这个模糊概念转化成模型能学的监督信号。最常见的是二分类标注：给每个文本对打0或1，0表示不相似，1表示相似。二分类的优点是标注成本低、边界清楚，对FAQ问题合并、搜索召回这类场景足够用。另一种做法是连续分数，比如0到5打分，理论上更精细，但不同标注者对“相似程度”的理解很难对齐，结果往往是标注一致性崩掉，模型学得也很别扭。
如果你的业务除了“是否相似”还想再分一层“部分相似”，可以上三分类：0表示无关，1表示部分相关，2表示完全同义。三分类输出保留了一定梯度，业务方拿到分数后可以根据自己的场景调整阈值线。但不管分几类，都要在项目启动时把类别定义写进标注规范，并配上正反例。二分类的定义我会写成“核心语义一致、去修饰后可互相替换不改变答案”，这句话能帮标注者在模糊case上做出相对一致的判断。
3.2 正负样本构造：随机负样本与难负例的配比
样本来源决定了模型上限，这一块值得多花心思。正样本可以从业务日志里挖：用户搜索同一个答案时前后点击的同义query、客服合并过的工单标题、电商后台的相似商品问题，都是中文本相似度正样本的好来源。没有业务数据时也可以用同义词替换、句式变换自动生成，效果会打折扣，但至少能把链路跑通，后面再迭代。
负样本的构造是很多项目翻车的重灾区。如果只拿完全不相关的句子当负例，模型很快会发现一个捷径：只要词面重叠度低就判不相似，根本不用理解语义。要逼它学语义，就得加入难负例：词面看着像、语义其实不同的文本对。常见做法是先用BM25或向量召回一批候选，人工挑出“看起来像但答案不同”的负样本补进训练集，我把随机负样本和难负例按7比3混合，效果比只用随机负样本稳定。整体正负样本比例控制在1:1到1:2之间，负样本过多模型会倾向输出“不相似”，线上阈值怎么调都别扭。
3.3 用tokenizer把文本对转成特征：padding、截断与attention_mask
数据准备好后，关键一步是把原始文本编码成Bert的输入特征。下面这个Dataset类把编码逻辑收口到一处，训练时每条样本进来都会产出标准化的tensor：
import torch from torch.utils.data import Dataset class PairDataset(Dataset): def __init__(self, pairs, labels, tokenizer, max_len=64): self.pairs = pairs self.labels = labels self.tokenizer = tokenizer self.max_len = max_len def __len__(self): return len(self.pairs) def __getitem__(self, idx): text_a, text_b = self.pairs[idx] encoded = self.tokenizer( text=text_a, text_pair=text_b, padding="max_length", # 统一补到max_len truncation=True, # 超出则截断 max_length=self.max_len, return_tensors="pt", ) return { "input_ids": encoded["input_ids"].squeeze(0), "attention_mask": encoded["attention_mask"].squeeze(0), "token_type_ids": encoded["token_type_ids"].squeeze(0), "label": torch.tensor(self.labels[idx], dtype=torch.long), }这里text与text_pair必须分开传，tokenizer会在内部拼成[CLS]加text加[SEP]加text_pair加[SEP]，并生成token_type_ids区分前后两段。padding="max_length"让每条样本统一补齐到一样长，DataLoader堆batch时shape完全对齐，不会在collate环节报错；truncation=True负责截断，max_length=64对中文短文本对是个性价比很高的值，FAQ里的句子很少超过64个字。注意return_tensors="pt"返回的tensor带了batch维度，shape是[1, seq_len]，所以要用squeeze(0)把它去掉，否则样本送进DataLoader后多套一层batch，模型前向会直接报维度错误。
3.4 训练集与验证集划分：按行切分还是按源文本切分
相似度任务里有个很容易被忽略的泄漏风险：如果两个文本对共享了同一条源文本，又恰好被分进train和valid两个集合，验证集就会混入训练时见过的句子，评估分数虚高。更干净的方式是按源文本去重后再划分，确保验证集里的query和reply都不在训练集中出现过。我在项目里会先给每条样本加一个source_id，再基于source_id做分层抽样，而不是直接对行做随机shuffle。
数据集构造完成后，别急着开训。先打印一个batch检查input_ids的shape是否一致、label分布是否合理，再统计训练集正负样本比例。虽然这些检查看起来繁琐，但一旦数据本身有问题，后面所有训练结论都不可信，返工成本远高于这几分钟检查。
4. fine-tune训练核心流程：损失函数与超参数怎么配
4.1 输出与损失函数：CrossEntropyLoss为什么适合相似度分类
BertForSequenceClassification在预训练模型之上加了一层线性分类层，输出维度等于num_labels。对二分类相似度任务，这层输出直接接CrossEntropyLoss就行。它计算的是预测概率分布与真实标签之间的交叉熵，等价于最大化正确类别的对数概率，梯度大小合适，不会出现MSE损失在softmax饱和区梯度消失的问题。
还有一部分人会把相似度任务建模成回归，用MSE去拟合0到1的相似度分。如果标注本身就是连续分数，这样做没问题；但多数项目的标注是离散标签，强行回归不如分类稳定。另一个常见变体是双塔模型输出余弦相似度作为logit，适合大数据量召回场景，性能比单塔好一个量级，但准确率通常不如单塔交叉编码器，这一点放在第6章细说。对新手项目，单塔分类头加交叉熵是最省心也最不会出错的组合。
4.2 训练脚本拆解：一个可以直接跑的fine-tune入口
下面这段脚本把前面封装的PairDataset接进DataLoader，完成一次完整的fine-tune训练循环：
from transformers import AdamW from torch.utils.data import DataLoader from tqdm import tqdm train_loader = DataLoader( train_dataset, batch_size=32, shuffle=True, # 打乱样本顺序，避免同类样本扎堆 ) optimizer = AdamW(model.parameters(), lr=2e-5) loss_fn = torch.nn.CrossEntropyLoss() epochs = 3 model.train() for epoch in range(epochs): total_loss = 0.0 for batch in tqdm(train_loader, desc=f"epoch {epoch+1}"): # 把三个输入张量按字段名传给模型 outputs = model( input_ids=batch["input_ids"], attention_mask=batch["attention_mask"], token_type_ids=batch["token_type_ids"], ) loss = loss_fn(outputs.logits, batch["label"]) optimizer.zero_grad() loss.backward() optimizer.step() total_loss += loss.item() print(f"epoch {epoch+1}, avg loss: {total_loss / len(train_loader):.4f}")代码里的learning rate设的是2e-5，这是Bert类模型fine-tune最通用的起点，原因在于预训练权重已经接近收敛，微调时刻度必须远小于从零训练。batch_size=32对64长度的文本对分类任务压力适中，显存如果吃紧就降到16或8，但要记得batch减半时learning rate同步减半，保证梯度更新规模大致不变。epochs设3，几千到几万条样本的训练集在这个量级下通常2到4轮就能收敛，超过5轮非常容易过拟合。
如果你在GPU上跑，还需要把tensor搬到GPU：在for循环开头加一行batch = {k: v.cuda() for k, v in batch.items()}。CPU训练也不是不行，但上万条样本要跑到天荒地老，不建议。观察loss时盯着每个epoch的平均loss比看单步loss更有参考价值，所以我这里用total_loss除以batch数量。
4.3 learning rate、batch size与epoch：三组必须自己调一遍的参数
learning rate是这三组参数里最敏感的。2e-5到5e-5是绝大多数中文文本分类场景的安全区间，一旦超过1e-4，预训练权重会被大幅度破坏，损失函数直接跳到很大的值而且回不来。如果你发现第一个epoch的loss没怎么下降，先不要急着加轮次，把learning rate往上调到5e-5试试；如果loss一开始就是inf或nan，那大概率是learning rate过高，要么就是数据里有异常值。
batch size影响训练的稳定性和显卡显存。Bert的显存大头在Transformer层，文本对拼接后序列长度是两段文本长度之和加3个特殊token，batch size=32配上max_length=64对常见的10G级别显卡能扛住，但max_length翻到128或256时显存消耗会急剧上涨。batch size的调整通常要联动learning rate：batch减半梯度估计噪声变大，learning rate也应减半保持更新尺度一致。
epoch数相对好判断。几千到几万样本的相似度任务，3个epoch是常见落点；少于2个epoch分类头可能还没充分学习，多于5个epoch验证集分数大概率先升后降，呈现典型的过拟合曲线。每训完一个epoch都跑一次验证集，如果第2轮之后F1连续下跌，就固定epoch为2，并把注意力转移到数据质量和模型结构优化上。
4.4 验证策略：准确率、F1与阈值的关系
训练完成不能只看loss，验证集评估决定模型能不能上线。正负样本均衡时准确率是一个直观指标，但负样本偏多时准确率会被“全部预测为负样本”这种偷懒策略刷得很高，失去参考意义。此时F1更可靠，它同时衡量精确率和召回率，尤其在FAQ合并场景里，你既不想放过真正的同义问题，也不想把无关问题并到一起。
评估代码可以直接贴一个分类报告，假设valid_loader已经按同样的方式构造：
from sklearn.metrics import classification_report preds = [] labels_all = [] model.eval() with torch.no_grad(): for batch in valid_loader: outputs = model( input_ids=batch["input_ids"], attention_mask=batch["attention_mask"], token_type_ids=batch["token_type_ids"], ) preds.extend(outputs.logits.argmax(dim=-1).tolist()) labels_all.extend(batch["label"].tolist()) print(classification_report(labels_all, preds, digits=4))报告会给出每个类别的精确率、召回率、F1。看结果时把重点放在少数类的那一行，多数类分数再高也说明不了问题。如果你打算调低线上阈值换召回，可以先在验证集上画出正负样本的概率分布，找到两者重叠最少的区间再选阈值，这一步比闭眼用0.5有效得多。
5. fine-tune常见问题排查：loss不降与相似度全打高分的五个坑
5.1 训练loss稳定在0.69附近不下降——正负样本配比与随机种子
现象：第一个epoch开始时loss就是0.69左右，后续几个epoch纹丝不动，打印预测结果发现模型把所有样本都判成同一个类。这种情况通常出现在项目第一轮训练里，看到loss曲线像一条水平直线，很多人会先去换优化器，其实问题往往不在优化器。
原因：0.69这个数值是二分类交叉熵在模型输出均匀概率时的理论值，也就是ln2。它表示模型完全没学到有效信息。最常见的原因是正负样本严重失衡，模型偷懒输出均匀分布就能维持稳定loss；其次可能是learning rate太低，第一个step的梯度变化极小，loss自然停在初始位置。
解决：先检查DataLoader的标签分布，负样本超过80%就先做下采样或改用加权采样，让正负比例回到1:1附近。然后手动打印第一个batch回传后的梯度范数；梯度小于1e-3就把learning rate调到5e-5再试。另外确认DataLoader的shuffle=True，否则模型每个batch看到的正负样本比例差异很大，训练过程也会抖动。
5.2 验证F1第二个epoch后开始下跌——过拟合与学习率衰减缺失
现象：训练loss持续下降，验证F1先升后跌，第二个epoch开始明显回落。这种曲线在几万条样本以内的数据集上非常典型，属于过拟合的标准信号。
原因：小数据集上微调Bert很容易过拟合，分类头记住训练样本的细节后，泛化开始变差。另一种常见情况是learning rate全程不变，模型在loss曲面底部附近反复震荡，找不到更平滑的极小点，验证集表现自然上不去。
解决：给optimizer加warmup和线性衰减调度。transformers里有现成的get_linear_schedule_with_warmup，把warmup步数设为总步数的6%到10%，后阶段线性衰减到0，两行代码就能接上。同时把epoch限制在3轮以内。加上调度器后，模型前期不会因为学习率过大跑偏，后期还能慢慢落到一个更稳的极值，验证F1通常会明显变稳。
5.3 线上相似度分数全挤在0.99附近——softmax的置信度虚高
现象：验证集F1没问题，线上拿新样本算相似度，概率几乎全部在0.99以上，人工看一眼都觉得离谱，业务方的阈值完全失去区分能力。这个坑最容易在项目交付前突然冒出来，让之前报告里的指标显得不可信。
原因：交叉熵训练的模型天然倾向输出高置信度概率，二分类任务里正样本输出0.99、负样本输出0.01，从分类角度看是正确的，但“概率差值”被压得非常小，直接拿来当相似度分数看区分度很差。真正有效的判别信息其实在logits的差值里，softmax只是把它压扁了。
解决：不要直接用softmax概率当相似度，改用正类对应的原始logit；或者对logits除以一个温度系数再做softmax，temperature取2到3可以把概率分布拉平，保留排序信息。更进一步的做法是把验证集所有样本的logits保存下来，画出正负样本的分布重叠区间，在这个区间内选阈值。二分类相似度项目里“模型收敛但分数不可用”的坑基本都出在这里，踩一次下次就记住了。
5.4 padding带来相似度假象——attention_mask没被正确使用
现象：文本长度差异悬殊时，模型给“苹果手机”和“苹果手机怎么退货”打出非常高的相似度，人工判断完全不相似，但模型就是给了高分。这类假象在短query和长文章做匹配时尤其常见。
原因：问题出在padding策略与attention_mask的配合上。padding="max_length"把短文本补到和长文本一样长，但如果你在自定义分类头或池化层里没有把padding位置mask掉，这些[PAD] token也会参与平均池化或者注意力计算，模型实际上在拿一堆无意义的填充符“找相似”，自然会出现假高分。
解决：在forward调用里确认attention_mask被显式传入模型。如果自定义了Bert输出之上的池化层，不要对最后一层hidden states直接做不加权平均，先乘attention_mask再除以有效token数。可以做个自检：给模型分别输入一个短句和这个短句后接大量padding的版本，如果输出向量差异很小，说明attention_mask生效了；如果几乎一样，就回去查mask链路。
5.5 微调后领域词判断失常——灾难性遗忘
现象：fine-tune完成后，训练集外的新领域术语测试效果明显变差，预训练阶段原本认识的一些低频词、成语也开始出现奇怪的分词或语义偏差。如果你拿新的专业词汇去测，甚至会发现模型对它们的理解还不如未微调之前。
原因：这是小样本微调里典型的灾难性遗忘。训练集中领域语料太少、领域词太少，反向传播为了拟合少量标注样本，把预训练学到的一部分通用语言先验覆盖掉，模型的泛化能力跟着受损。
解决：最扎实的做法是用领域语料先做一轮继续预训练，用MLM loss在未标注的领域文本上继续训练，然后再接着fine-tune相似度任务，两个阶段叠加效果最明显。工程时间不够时，可以冻结Bert主体、只训练顶部两层加分类头，让预训练权重被改动的幅度变小；或者直接把learning rate降到1e-5甚至5e-6、epoch改成2，让fine-tune更像在原有权重基础上的微调而不是重训。这个坑和5.1的区别在于，5.1是不收敛，这里是收敛但泛化差，排查时先确认验证集来自同一分布还是真正的新领域数据。
6. 进阶：把fine-tune模型变成向量编码器，相似度从逐对计算改成批量检索
直接计算相似度时，Bert是单塔结构：两段文本拼成一个序列过模型，输出匹配分数。小规模评估没问题，但如果你有几十万条FAQ，要给每个新query和库内全部候选算分数，单塔的计算量是完整的N次前向，线上根本扛不住。这时更常用的做法是把fine-tune过的模型改造成双塔结构：两段文本分别过编码器，把[CLS]向量或者全部token的均值池化结果当作句向量，用余弦相似度来近似语义相似度。Sentence-BERT就是这个思路的典型实现，它用孪生网络训练模型，让输出的句向量在语义空间里更紧凑。
实际操作里可以复用这次fine-tune的成果：把训练好的分类模型重新加载为BertModel，只保留bert部分的权重，丢掉分类头，然后对最后一层hidden states做mean pooling得到句向量。核心代码就几行：
from transformers import BertModel encoder = BertModel.from_pretrained("./models/bert-base-chinese") # 只迁移bert主体权重，丢弃分类头 state_dict = {k: v for k, v in model.state_dict().items() if k.startswith("bert.")} encoder.load_state_dict(state_dict, strict=False) encoder.save_pretrained("./models/fine_tuned_encoder")迁移完成后，encoder输出的向量就是经过fine-tune任务拉齐后的语义表示。我个人测试里，这种迁移出来的句向量在“语义相近但表述差异大”的句对上，余弦相似度比未微调的bert-base-chinese平均提升十几个点，原因是分类任务已经把语义空间的分布向目标方向拉近。但也要知道双塔的代价：它失去了单塔模型让两个句子充分交互的能力，如果业务里有大量“退货”和“换货”这种细粒度语义差异的判断，还是得保留单塔做精排。
这几年做文本相似度项目，我最大的教训是不要在起步阶段追求完美模型，先把单塔fine-tune全链路跑通，拿到一个可用baseline；等性能瓶颈真的出现了，再考虑迁移到双塔做向量召回，用单塔交叉编码器做精排。文本相似度项目的成败大头其实在数据定义、阈值口径和评估方法上，这些比调参更值得投入时间。希望帮到你。
本文还有配套的精品资源，点击获取
