简介：面向自然语言处理初学者与文本分类任务开发者，这份源码基于BERT预训练模型与text_cnn卷积网络实现文本分类能力，适合情感分析、新闻分类等场景，界面友好，可直接开展实验，亦可作为课程设计与项目原型参考。压缩包共25个文件，核心为16个Python源码文件，覆盖数据处理、分词、建模、优化、训练、推理等环节；另有Markdown文档、依赖清单、许可证及ipynb示例，整体323KB，结构紧凑，readme与依赖列表便于研究参考和二次开发。已有428人学习下载。读者可获得可运行的BERT分类实现，包括建模、优化、分词与预训练相关脚本，以及基于TF Hub的Notebook文本分类示例，能够理解BERT微调与CNN分类结合的完整思路，方便在此基础上扩展自己的文本分类实验。对于需要快速落地文本分类任务的团队，也是一个轻量级参考实现。
1. BERT不是文本分类终点，接一层CNN在很多场景反而更稳
做文本分类的团队，现在默认流程已经变成“上来先把BERT跑通”，但真正落到线上服务时你会发现，BERT在短文本、观点句、领域小样本分类这类任务上，要么显存吃紧，要么过拟合翻车，要么推理延迟压不下来。于是很多人又把目光放回CNN卷积神经网络——不是拿它替代BERT，而是拿它兜住BERT的尾巴。所谓基于BERT的文本分类CNN模型设计源码，核心就一件事：让BERT负责把句子表示成向量序列，让CNN在序列上抓局部关键模式，再交给全连接层做分类。这个组合既保留BERT的语义理解能力，又借CNN的平移不变性把小样本任务稳住，是源码里常见且实操性很强的折中方案。下面从设计原理讲到可复现代码，再给你一版踩坑清单。
2. BERT+CNN文本分类的设计逻辑：为什么BERT输出的向量还要再过卷积
2.1 BERT输出什么形状的张量，CNN拿它当什么
BERT不是文本分类的终点，而是文本编码的起点。用transformers库加载模型后，你把一句话喂进去，得到的last_hidden_state形状是[batch_size, sequence_length, hidden_size]，对bert-base来说hidden_size=768。这层输出意味着：句子中每一个token都被表示成一个768维的向量，而且这个向量已经通过多层Transformer做过双向上下文融合。
但关键点在于，这768维向量是按“词”组织的，不是按“特征图”组织的。想在它上面做分类，常见做法有两种：第一种是只取[CLS]向量，拼一个全连接层就完事；第二种是把整条token序列当成一张“伪图像”，交给CNN在局部窗口内提取n-gram级别的组合模式。
第一种做法简单，但[CLS]向量是整句话的压缩表示，它对“哪个片段真正触发了类别判断”这件事不敏感。比如你要判一条工单是不是投诉，句子里“发货慢”出现三次，这种关键词密度信息在[CLS]里容易被稀释。而CNN就不一样，卷积核天然扫过连续窗口，3-gram、5-gram这类局部特征会被显式捕捉。所以B站新结构里，BERT的输出会先调整维度，从[batch, seq_len, hidden]转成[batch, hidden, seq_len]，让卷积核沿时间步方向滑动，这一步是源码里第一个容易写错的地方。
2.2 三种常见网络结构，项目里选哪一种
在源码设计里，基于BERT的CNN分类模型一般有三种接法，不是随便选的。
第一种是“单层CNN接最后一层输出”，也就是上面说的把last_hidden_state当成伪图像。结构是BertEncoder -> Transpose -> Conv1d -> ReLU -> GlobalMaxPooling -> FC。这个结构简单，显存占用小，适合句子长度300以内的短文本，也是本项目标题下最标准的实现。
第二种是“多尺度CNN并行”，你会看到源码里卷积核尺寸往往不只一个，常见是[2,3,4]、[3,4,5]或[3,5,7]。每个卷积核负责捕捉不同粒度的局部特征，核宽3看到的是三元词组，核宽5看到的是五元词组。多个通道的特征拼在一起再进全连接层，这种方式对小样本分类提升明显，因为它相当于把“词袋”升级成“词组袋”。
第三种是“BERT层输出拼上原始词向量”。意思是把BERT输出的last_hidden_state与word embedding拼接作为CNN输入。这种做法的出发点是BERT的向量在微调初期不稳定，拼上固定词向量相当于给了CNN一条稳定通路。但实测下来，训练速度会慢一截，而且在小数据集上收益不稳定，我一般只在样本量超过5万的时候才考虑它。
2.3 这个设计的适用边界：什么时候该用，什么时候别硬用
必须说清楚，BERT+CNN不是万能药，它有自己的适用边界。适合的是：短文本、类别数5以内的分类、训练样本五千到十万这个区间、推理时延要求不高但希望模型体积不至于太大的场景。最常见的落地场景是舆情分类、工单打标、电商评论正负向判断。
不适合的场景也别硬套。如果句子平均长度超过512，或者文本是长文档，CNN的局部窗口根本没有意义，这时候直接分段做向量平均或者用序列模型更靠谱。如果类别数超过20，CNN的判别面不够，还是要回到BERT全连接微调。如果你的业务方要求CPU上推理延迟低于5毫秒，CNN接在BERT后面反而拖慢整体速度——因为瓶颈在Transformer前向，不在CNN层。
选型时还要关注一个指标：样本量。BERT自己就是个黑匣子，参数太多，小样本上微调容易过拟合。CNN恰恰是个正则化器，它限制模型只能从局部窗口组合特征，变相压缩了假设空间。所以对1000～2000条样本的中小数据集，BERT+CNN经常比纯BERT微调高出三四个点，这个结论你可以在自己的数据上复现。
3. 用PyTorch实现BERT+CNN文本分类：最小可运行结构
3.1 预处理与数据加载
源码里最容易被忽略但不是最酷的部分是数据预处理。BERT+CNN对输入格式有硬性要求：必须有input_ids、attention_mask和token_type_ids三个张量。其中attention_mask的长度必须和input_ids严格一致，token_type_ids在单句任务里全置0即可。
我一般会单独写一个预处理函数，避免在训练循环里反复调tokenizer。下面的代码是一个可直接落地的版本，输入句子列表，输出模型需要的三件套。
import torch from transformers import BertTokenizer tokenizer = BertTokenizer.from_pretrained("bert-base-chinese") def encode_texts(texts, tokenizer, max_len=64): encoded = tokenizer( texts, padding=True, truncation=True, max_length=max_len, return_tensors="pt", return_token_type_ids=True, return_attention_mask=True, ) return encoded["input_ids"], encoded["attention_mask"], encoded["token_type_ids"] # 示例：两条中文评论 texts = ["发货速度快，包装严实", "质量不行，客服态度差"] input_ids, attention_mask, token_type_ids = encode_texts(texts, tokenizer, max_len=64) print(input_ids.shape) # torch.Size([2, 64]) print(attention_mask.shape) # torch.Size([2, 64])这里有两个容易被忽略的参数：truncation=True会硬截断，超过max_len的部分直接丢弃；return_token_type_ids=True保证输出里有第三张量。如果你在源码里看到只返回了前两个tensor然后模型报错说缺少token_type_ids，多半是这里漏了。
max_len的设置会直接影响CNN的感受野：设得太大，padding占比高，卷积核扫到大量无效位置；设得太小，长句子信息被截断。对中文短文本分类，64到128是安全区间。训练集里句子普遍60字以内时，max_len=64就够；如果包含200字的投诉工单，直接拉到128。
3.2 模型定义：BERT编码器加多尺寸CNN
核心模块定义在这里。整个模型分三段：BERT取特征，CNN提取局部模式，全连接输出分类结果。BCELoss还是CrossEntropy取决于你的标签格式。
import torch import torch.nn as nn from transformers import BertModel class BertTextCNN(nn.Module): def __init__(self, bert_model_name="bert-base-chinese", hidden_size=768, num_filters=64, filter_sizes=(2, 3, 4, 5), dropout=0.3, num_classes=2): super().__init__() # 1) BERT encoder，默认冻结参数 self.bert = BertModel.from_pretrained(bert_model_name) # 2) 多尺寸CNN卷积层 self.convs = nn.ModuleList([ nn.Conv1d(hidden_size, num_filters, kernel_size=size) for size in filter_sizes ]) # 3) 分类头 self.dropout = nn.Dropout(dropout) self.fc = nn.Linear(len(filter_sizes) * num_filters, num_classes) def forward(self, input_ids, attention_mask, token_type_ids=None): # shape: [batch, seq_len, hidden] bert_output = self.bert( input_ids=input_ids, attention_mask=attention_mask, token_type_ids=token_type_ids ).last_hidden_state # CNN要求通道维度在第二维，转成 [batch, hidden, seq_len] x = bert_output.transpose(1, 2) # 每个卷积核输出一个feature map，做masked max pooling pooled_outputs = [] for conv in self.convs: conv_out = conv(x) # [batch, num_filters, seq_len - kernel_size + 1] conv_out = torch.relu(conv_out) # 关键点：把padding位置的卷积结果置为极小值，防止max pooling取到无效位置 mask = attention_mask.unsqueeze(1) # [batch, 1, seq_len] mask = mask[:, :, : conv_out.size(2)] conv_out = conv_out.masked_fill(mask == 0, -1e9) pooled = conv_out.max(dim=2).values # [batch, num_filters] pooled_outputs.append(pooled) # 拼接所有桶的特征 cat_features = torch.cat(pooled_outputs, dim=1) # [batch, num_filters * len(filter_sizes)] # 分类 logits = self.fc(self.dropout(cat_features)) return logits这个类的设计有四个细节值得说。一是nn.ModuleList的写法，它保证每个卷积核都被注册成模型的子模块，参数会进优化器，不能用Python列表替代，否则训练时卷积核参数不更新，这是源码里非常隐蔽的翻车点。二是seq_len经过卷积后会缩短，所以对attention_mask做了切片对齐，避免mask长度不匹配报错。三是masked_fill把padding位置的卷积结果替换成-1e9，这样max(dim=2)不会选中无效位置。四是self.bert默认是未冻结的，但如果你在小数据集上做实验，可以选择把bert.requires_grad_(False)，只训练CNN和分类头，效果往往出乎意料地好。
3.3 训练循环与验证：一套能跑通的代码骨架
模型定义好之后，训练循环本身没什么玄学，但有一个点要特别注意：BERT的AdamW优化器跟普通Adam不一样，它解耦了权重衰减，同时需要warmup来稳定前几百步的梯度波动。下面给的是一个可以直接跑的骨架，注意看优化器和损失函数的匹配关系。
import torch from transformers import AdamW, get_linear_schedule_with_warmup model = BertTextCNN(num_classes=2) device = torch.device("cuda" if torch.cuda.is_available() else "cpu") model.to(device) optimizer = AdamW(model.parameters(), lr=2e-5, weight_decay=0.01) total_steps = len(train_loader) * num_epochs scheduler = get_linear_schedule_with_warmup( optimizer, num_warmup_steps=int(0.1 * total_steps), num_training_steps=total_steps ) criterion = nn.CrossEntropyLoss() for epoch in range(num_epochs): model.train() total_loss = 0.0 for batch in train_loader: input_ids, attention_mask, token_type_ids, labels = batch input_ids = input_ids.to(device) attention_mask = attention_mask.to(device) token_type_ids = token_type_ids.to(device) labels = labels.to(device) logits = model(input_ids, attention_mask, token_type_ids) loss = criterion(logits, labels) optimizer.zero_grad() loss.backward() torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0) optimizer.step() scheduler.step() total_loss += loss.item() # 每轮结束后做验证，注意切到eval模式 model.eval() correct = 0 total = 0 with torch.no_grad(): for batch in val_loader: input_ids, attention_mask, token_type_ids, labels = batch input_ids = input_ids.to(device) attention_mask = attention_mask.to(device) token_type_ids = token_type_ids.to(device) labels = labels.to(device) logits = model(input_ids, attention_mask, token_type_ids) preds = torch.argmax(logits, dim=1) correct += (preds == labels).sum().item() total += labels.size(0) acc = correct / total print(f"Epoch {epoch+1} | Loss: {total_loss:.4f} | Val Acc: {acc:.4f}")clip_grad_norm_这行值得重点说。BERT参数规模大，训练后期偶尔会出现某个batch的梯度爆炸，导致loss变成NaN。把梯度模长截断到1.0，相当于给优化过程上了一份保险，源码里如果没有这行，你复现时大概率会撞上loss突然飞掉的情况。weight_decay只在非bias和Norm层上生效的写法我这里没展开，AdamW内部已经处理了，直接设0.01是经验值，不用来回调。
dropout在模型里出现的位置也有名堂。我建议只在全连接层之前加一次self.dropout，不要在BERT输出后重复加多层dropout。BERT内部已经自带dropout了，叠加太多会让模型在小样本上学不到东西。
4. 关键参数怎么设：从一轮跑通到效果能打
4.1 参数速查表与默认值
把源码里的参数打散看，真正影响效果的变量不超过十个。下面这张表是实操验证过的起点值，不是从论文里抄的，可以直接当成第一版实验配置。
| 参数 | 推荐值 | 影响方向 |
|---|---|---|
max_len | 64或128 | 短文本64，长文本128，再长会稀释CNN感受野 |
filter_sizes | (2,3,4,5) | 小卷积核适合短文本，大核适合行为序列 |
num_filters | 64或128 | 越大特征越丰富，小数据集建议64 |
dropout | 0.3～0.5 | 0.3起步，过拟合明显再往上调 |
learning_rate | 2e-5 | BERT微调的通用区间，超过5e-5容易崩 |
weight_decay | 0.01 | AdamW默认推荐值 |
batch_size | 16或32 | 受显存限制，BERT-base常用16 |
epochs | 3～5 | BERT微调轮数不宜多，多了过拟合 |
grad_clip | 1.0 | 防止梯度爆炸导致loss变成NaN |
num_classes | 取决于标签数 | 类别多时建议增加num_filters |
这里要说一个反直觉的经验：BERT+CNN模型在中等数据集上，训练轮数很少超过5。原因在于BERT本身已经在大语料上收敛过，我们只需要微调，CNN层学到的是分类相关的局部模式，学得太久反而把BERT原有泛化能力覆盖掉。如果你看到loss持续下降但验证集精度止步不前，尽早早停，这不是模型没学好，是在过拟合。
4.2 卷积核尺寸与通道数：不同任务怎么调
filter_sizes的选择和文本粒度强相关。中文短文本分类任务，字级别的输入下，2-gram对应的就是双字词，3-gram对应三字短语。实测下来，情感分类用(2,3,4)效果不错，这符合情感词“开心/不满意/太差了”多为双字到四字的直觉；而主题分类或意图识别，因为类别间差异体现在句式层面，卷积核拉到(3,4,5)甚至(4,5,6)更合理。
num_filters决定了每个卷积核提取多少种特征。64起步，128是上限。在小样本任务上盲目升到256反而容易过拟合，因为每个卷积核都有独立的768×k_size×num_filters个参数，这些参数都需要足够样本来稳定更新。你可以在源码里做一个简单实验：把num_filters从64调到128，如果验证集精度没涨，那说明数据量不够撑起更多参数，调回去。
还有一个容易被忽略的尺寸参数：kernel_size相对max_len的比例。当max_len=64时，核宽5覆盖了约8%的序列长度，这是合理的；但如果max_len=512，核宽5的感受野占比只剩1%，几乎看不到长距离依赖。所以长文本场景下要么缩短max_len，要么增大核宽到7或9，两者必须配套调整。
4.3 冻结策略与学习率：BERT微调中的两难选择
BERT部分参数动还是不动，这是源码里最值得纠结的设计决策。常见做法之一是全部解冻，让BERT和CNN联合训练，效果上限高，但需要足够数据。常见做法之二是冻结BERT全部参数，只把last_hidden_state当作固定的特征提取器，训练CNN和分类头，优点是小样本也不容易过拟合，缺点是特征不是面向任务优化的，上限低。
我推荐一个折中策略：冻结BERT的前9层，只微调最后3层和CNN层。理由是BERT的前几层学习的是通用语法特征，后几层才与任务相关。实现上只需要在定义模型后加几行代码：
for name, param in model.bert.named_parameters(): if name.startswith("encoder.layer.9.") or name.startswith("encoder.layer.10.") or name.startswith("encoder.layer.11."): param.requires_grad = True else: param.requires_grad = False这个写法是给BERT的12层编号从0开始，所以layer.9到layer.11是最后三层。需要注意：bert.embeddings的position embedding也得跟着冻，因为位置信息是通用特征。另外pooler层默认也是冻结的，反正CNN不用它。
学习率同样要分阶梯。BERT部分的lr保持2e-5，CNN和分类头部分用1e-3，这需要给模型参数分组：
optimizer_grouped_parameters = [ {"params": [p for n, p in model.named_parameters() if "bert" in n], "lr": 2e-5}, {"params": [p for n, p in model.named_parameters() if "bert" not in n], "lr": 1e-3}, ] optimizer = AdamW(optimizer_grouped_parameters, weight_decay=0.01)这个分组背后的逻辑是：BERT参数已经预训练过，学习率太大一步就把内部表征洗掉；CNN是从零开始训练，需要相对快的学习率才能在有限轮次内收敛。如果你发现两个部分用同一个学习率效果很差，多半就是这个问题。
5. BERT+CNN的五个常见坑：现象、原因、解决
5.1 坑一：验证集准确率高，线上预测全乱套
现象：训练和验证阶段accuracy都能到90%以上，但模型部署到测试环境后，随便来几条新样本，预测结果明显不对。
原因：attention_mask没参与卷积池化运算。当句子长度小于max_len时，padding位置对应的卷积输出参与max运算后，如果padding位的向量恰好大于真实文本位的向量，池化出来的特征就是padding带来的噪声。训练集里如果每个batch的padding比例不同，模型就被带偏了。
解决：在池化前做masked_fill。具体代码就是第3.2节里的做法：把attention_mask对齐到卷积输出的长度，对mask为0的位置填充一个极小值（-1e9），再做max维度归约。如果这步已经做了，检查一下attention_mask是不是被重复使用了——比如同一个batch先用在BERT输入上，然后在CNN阶段直接用了原始mask，但没有考虑卷积后序列长度变短了对齐问题。
5.2 坑二：loss降不下去，甚至原地打转
现象：训练了500步，loss始终维持在2.4左右不动，精度也在随机水平附近徘徊。
原因：最常见的是tokenizer和模型不匹配。比如用bert-base-uncased的tokenizer配了bert-base-chinese的模型，词表id对应不上，输入的全是乱码向量。另一个常见原因是优化器分组错误，BERT部分的学习率设成了1e-3，直接冲坏了预训练权重。
解决：第一件事检查tokenizer.vocab_size和model.config.vocab_size是否一致。不一致就换tokenizer，别硬跑。第二件事检查优化器参数分组，确认BERT层用的是2e-5档位。第三件事把batch_size降到8，排除显存溢出导致的静默报错。
5.3 坑三：显存溢出，batch size只能调到1
现象：batch size设为16，模型刚加载完就报OOM，被迫只能跑batch size=2甚至1，训练慢到无法接受。
原因：BERT-base每层有110M参数，一条64词的中文句子会产生[1,64,768]的中间激活，加上CNN层的特征图，显存比纯BERT微调高约20%。如果同时开了梯度检查点，情况更糟。
解决：有两条路。第一条是缩短max_len，从128降到64，显存占用直接降一半，付出的代价是长文本尾部的信息被截断，但对于短文本分类影响很小。第二条是把CNN从Conv1d换成可分离卷积，或把num_filters从128降到64。另外别忘了开混合精度训练：
from accelerate import Accelerator accelerator = Accelerator(mixed_precision="fp16") model, optimizer, train_loader = accelerator.prepare(model, optimizer, train_loader)fp16模式下显存占用约为fp32的一半，训练速度还能提升30%左右。这也是现在给BERT做部署前训练的标准做法。
5.4 坑四：小样本数据集上反复过拟合，验证集波动剧烈
现象：训练集只有1500条，训练到第3个epoch时验证集精度先升后降，不同随机种子跑出来结果差10个百分点。
原因：BERT参数太多，CNN的卷积核也引入了大量可学习参数，整体模型容量远超数据量所能约束的范围。加上小样本下batch内噪声大，验证集本身也小，一个batch的好坏直接影响验证集分数。
解决：先把这些限制加上。冻结BERT前几层，只留最后2层微调；dropout提到0.5；num_filters降到32；然后加一个简单的early stopping，连续3个epoch验证集acc没提升就停。还有个偏方是给输入做文本增强，把句子里的同义词随机替换，构建一个augmented训练集。这个方向在你源码里可能没体现，但加一条增强分支通常能稳定住2～3个点。
5.5 坑五：训练和推理阶段结果不一致，部署时掉点
现象：离线测试时F1是86%，上线后同分布样本F1掉到81%，且掉点稳定复现。
原因：模型定义里没有区分训练态和推理态。因为nn.Dropout只在model.train()时生效，推理时自动关闭，但我们常常在验证脚本里只调用了model.eval()但没切换BERT模块状态。更隐蔽的是，如果你在源码里手动调用过model.bert.train()或model.bert.eval()，这个操作会覆盖掉整个模型的状态，导致推理时BERT部分仍处于训练模式，引入随机dropout噪声。
解决：所有前向推理前只调用一次顶层model.eval()，不要单独操作子模块。如果你有自定义的推理脚本，在加载模型后打印model.training确认是False。还有一个规范性做法：把推理部分封装成一个接口函数，函数内固定model.eval()且with torch.no_grad()，让推理态与训练态彻底隔离。
6. 进阶验证技巧：怎么确认CNN真的在干活，而不是拖后腿
6.1 用消融实验验证CNN的真实贡献
当你把BERT+CNN模型跑出结果后，不要急着上线，先做一次消融实验。做法很简单：把CNN层替换成一个mean pooling操作，直接对BERT的输出取平均后接全连接层，其他训练参数完全不变，跑一遍对比。如果两个版本精度差不多，说明你的任务里局部n-gram特征不重要，CNN纯属白加；如果CNN版本高了2个点以上，说明特征提取确实有效。
这个对照实验的成本只需要改几行模型代码，但它能帮你回答“CNN到底为何物”这个源码评审时必被问的问题。我踩过一次坑：做一个垃圾评论识别时，BERT+CNN跑出的F1比纯BERT高3.5个点，我以为是CNN的功劳，后来一消融才发现，原来是加了dropout和输出层参数量的差异带来的正则化效应，跟CNN没多大关系。这类血泪经验在复现任何源码时都值得复制一遍。
6.2 一个值得投入的改进方向：BERT冻结加小卷积核组合
如果你验证后确认CNN有效，下一步最划算的改进是：冻结BERT全部参数，同时把卷积核尺寸调小到(2,3)，只训练CNN和分类头。这个组合在你的max_len比较大时，推理速度能比完全微调快1.5倍，显存占用降一半，精度只损失1个点以内。
为什么冻结BERT反而在小样本上更好用？因为BERT在预训练阶段学到的通用语义特征是稳定的，微调整个模型时，反向传播会同时调整低层语法特征和高层语义特征，导致原本稳定的表示被扰动。冻结之后，BERT变成一个固定特征提取器，CNN只需要在这些特征上学习线性决策面，符合小样本下的bias-variance权衡。
动手时注意一个细节：冻结BERT后，CNN输入仍然是768维，但梯度只流向CNN层，所以loss下降速度会比之前慢，这时把CNN的num_filters从64升到128，相当于把复杂度从BERT转移到CNN上，效果通常更好。
验证模型是否真正学到位，我会用badcase分析代替只盯acc：把验证集里预测错误的样本捞出来，按预测置信度排序，看高置信度错误集中在哪些类别上。如果错误样本主要集中在某两个近义标签上（比如“投诉”和“咨询”），说明特征区分度不够，优先调整卷积核尺寸而不是加数据。这算是我做文本分类以来最顺手的一条经验，也是源码改成生产系统的最后一步。希望帮到你。
本文还有配套的精品资源，点击获取
