简介面向自然语言处理课程实验与作业场景内容围绕BERT模型在20NewsGroups数据集上的新闻文本分类任务展开。资源包含完整Python源码、预处理后的训练与测试数据、模型检查点及训练日志以及配套的README说明文档和一篇参考PDF共二十一个文件压缩包整体约十四点四二MB目录按数据、源码、日志划分复现思路一目了然。已有七十六人学习下载。通过学习可掌握BERT微调分类的完整实现路径包括数据清洗、词汇表构建、模型训练与指标评估等关键环节同时也能获得日志分析、检查点管理、实验排错等一系列实践技巧这些内容既能支撑课程作业的交付也适合想深入理解预训练模型在下游任务中应用的初学者逐步上手。1. 从20NewsGroups到BERT一个值得动手的分类任务新闻组数据集诞生快三十年了但提到文本多分类它依然是很多人第一次完整跑通BERT的首选试验场。20NewsGroups分类任务要做的是把两万篇新闻正文归进二十个主题类别里听起来门槛不高真正动手却发现subword切分、标签对齐、序列截断、显存预算这些环节每个都能把人卡上半天。这个方向适合两类人一是刚看完transformer理论想找个中等规模数据集把预训练模型微调链路亲手跑通的人二是做过图像分类、但没接触过文本模型实操的工程师。下面按环境准备、数据预处理、模型微调、踩坑排查的顺序推进代码段基本可以直接搬进自己的工程里。2. 先搭好能跑BERT的环境版本组合与数据集预检2.1 Python、PyTorch与transformers的版本组合怎么选做BERT分类任务最常见的技术栈是Python PyTorch Hugging Face Transformers。版本上我不建议直接用最新分支半年前我遇到过transformers API改名把脚本整段打断的情况通常选一个发布已有一段时日、且和PyTorch官方预编译包能对齐的稳定版本就行。比较省心的组合是Python 3.10、torch 2.1.0、transformers 4.34以上。这个任务用不到PyTorch后续版本的新特性稳定压倒一切。用conda建独立环境是必须的因为这个项目的依赖常和做图像分类的环境冲突conda create -n bert-news python3.10 conda activate bert-news pip install torch2.1.0 pip install transformers datasets scikit-learn matplotlib numpy这里把transformers、datasets、scikit-learn装在一起分别是模型加载、数据处理、评估指标计算的常用底座。如果电脑有NVIDIA显卡安装torch时注意选对应CUDA版本的下载源没有显卡也没关系20NewsGroups这个任务用CPU训练BERT-base一个epoch大约二十多分钟完全能跑只是试错成本高一些。有个点我吃过亏conda自动解析依赖时常把transformers拉回旧版本。所以装完环境我习惯用pip list | grep transformers确认实际版本不要轻信安装日志里的显示版本。版本不一致会导致tokenizer的读入格式和模型权重对不上这是预处理阶段最不想看到的事。2.2 拉取20NewsGroups并确认类别分布获取数据集最常见的做法是sklearn的fetch_20newsgroups接口它直接返回去掉邮件头之后的文本和整数标签省去自己解析原始数据格式的麻烦。这个接口有两种用法subsettrain和subsettest给固定切分subsetall返回全部数据方便自己控制训练验证比例。from sklearn.datasets import fetch_20newsgroups import numpy as np raw fetch_20newsgroups( subsetall, shuffleTrue, random_state42, remove(headers, footers, quotes) ) data np.array(raw.data, dtypeobject) labels np.array(raw.target) target_names raw.target_names print(f类别数量: {len(target_names)}) print(f样本总数: {len(data)}) for name, count in zip(target_names, np.bincount(labels)): print(f{name}: {count})remove(headers, footers, quotes)会删除邮件头、签名档和引用原文。这个参数不是摆设如果用原始完整文本训练模型会严重依赖邮件头部线索泛化能力虚高删掉之后模型被迫去学正文语义指标更接近真实水平。完整20NewsGroups大概有一万八千多篇新闻每个类别约900篇类别不完全均匀但失衡程度没到需要加权采样的地步。划分训练验证集时不用简单随机打乱用StratifiedShuffleSplit按类别比例分层采样更稳防止验证集某类只有几篇from sklearn.model_selection import StratifiedShuffleSplit splitter StratifiedShuffleSplit(n_splits1, test_size0.15, random_state42) for train_idx, val_idx in splitter.split(data, labels): train_texts, val_texts data[train_idx], data[val_idx] train_labels, val_labels labels[train_idx], labels[val_idx] print(训练集大小:, len(train_texts), 验证集大小:, len(val_texts))15%的验证集约2800篇足够观察训练过程是否过拟合。这里顺便统计一下训练集文本长度分布后面定max_len就不靠猜了。简单做法是统计每篇新闻的单词数分位数比如P50和P90这决定BERT序列截断策略到底按什么标准设。3. 把新闻文本喂进BERTTokenizer切片与Dataset封装3.1 为什么BERT不直接读整篇新闻subword切分的边界第一次跑这个任务的人常问为什么不直接用现成分词工具切成词再查词典映射成id原因是BERT的词表是subword级别的像“unbelievable”会被切成“un”、“believ”、“able”不需要词典覆盖所有词形变化。传统词向量碰到新词只能给UNK标记信息全丢BERT能把词拆成词根和词缀这对新闻标题里的生造词特别有效。另一个原因是BERT的position embedding在预训练时只学到512个位置。输入超过512个token时模型根本没在那个位置上学到有意义的表示喂进去基本是噪声。而20NewsGroups里很多长新闻超过几千词所以截断策略不是可选项是必选项。截断方向也值得说。truncationTrue默认从尾部截新闻正文通常把关键信息放开头这样没问题。但某些任务把结论写在末尾就得用truncationonly_second配合文本对输入或预处理时做头尾拼接再截。我做技术讨论分类时遇到过中心句落在中段的情况默认截断把关键信息直接切掉验证分数卡在75%上不去换头尾截组合才解决。3.2 用BertTokenizer完成truncation与padding的代码实现加载tokenizer时我直接写BertTokenizer而不是AutoTokenizer因为任务明确要BERT原始wordpiece词表不需要机制自动猜测模型类型。注意from_pretrained的名字要和后面加载分类模型的保持一致bert-base-uncased是全小写版本新闻里的专有名词大小写信息会被丢bert-base-cased保留大小写。对20NewsGroups这种主题分类任务两者准确率差别不大但uncased体积更小、推理更快。from transformers import BertTokenizer tokenizer BertTokenizer.from_pretrained( bert-base-uncased, do_lower_caseTrue ) encoded tokenizer( Intel launches a new CPU architecture, truncationTrue, # 超过max_length从尾部截掉 paddingmax_length, # 不足max_length补到固定长度 max_length128, return_tensorspt ) print(encoded[input_ids].shape) # torch.Size([1, 128]) print(tokenizer.decode(encoded[input_ids][0][:12]))这段代码把一句话编码成固定[1, 128]的输入attention_mask同步标记哪些位置是真实token、哪些是padding。为什么固定长度而不是按batch内最长序列动态padding固定长度让所有batch的tensor形状完全一致排查显存和维度问题更省心缺点是短句也被强行补到128浪费约三分之一显存。想省显存可以用paddinglongest再配transformers的DataCollatorWithPadding统一pad到当前batch最长长度。接下来是自定义Dataset。最容易犯的错是把它放在__init__里一次性处理所有文本把一万六千条全部转成tensor存在内存。这样跑得快但内存和显存双高改max_len很不灵活。我一般放在__getitem__里按需编码牺牲一点速度换来可调试性import torch from torch.utils.data import Dataset class NewsDataset(Dataset): def __init__(self, texts, labels, tokenizer, max_len256): self.texts texts self.labels labels self.tokenizer tokenizer self.max_len max_len def __len__(self): return len(self.texts) def __getitem__(self, idx): text str(self.texts[idx]) encoding self.tokenizer( text, truncationTrue, paddingmax_length, max_lengthself.max_len, return_tensorspt ) return { input_ids: encoding[input_ids].squeeze(), # 去掉batch维 attention_mask: encoding[attention_mask].squeeze(), labels: torch.tensor(self.labels[idx], dtypetorch.long) } train_dataset NewsDataset(train_texts, train_labels, tokenizer, max_len256) val_dataset NewsDataset(val_texts, val_labels, tokenizer, max_len256) print(train_dataset[0][input_ids].shape) # torch.Size([256])return_tensorspt返回带batch维的tensor所以需要squeeze()去掉第0维否则dataloader拼接batch时维度不一致。labels用torch.long是为了配合CrossEntropyLoss的int64要求。DataLoader部分要确认维度匹配如果__getitem__返回的每个字段都是[max_len]dataloader合出来就是[batch_size, max_len]。num_workers在Windows下设成2以上经常触发多进程tokenizer崩溃这是老问题建议Linux服务器训练或者设0接受稍慢的数据读取from torch.utils.data import DataLoader train_loader DataLoader( train_dataset, batch_size16, shuffleTrue, num_workers4, pin_memoryTrue )pin_memoryTrue在有GPU时能把CPU端tensor放进页锁定内存减少host到device拷贝耗时代价是占用更多系统内存。batch_size16对BERT-base是稳妥的起步值显存带不动就往8退能带就试着往32走。4. BERT模型实操微调训练循环与关键超参怎么定4.1 加载预训练分类模型并替换分类头Dataloader就绪后加载BERT预训练权重并接分类头。用现成的BertForSequenceClassification最省事它内部自动加载BertModel再包一层dropout和线性分类器把768维隐藏表示投影到20类。from transformers import BertForSequenceClassification model BertForSequenceClassification.from_pretrained( bert-base-uncased, num_labels20 ) print(model.config.hidden_size) # 768 print(model.classifier) # Linear(768 - 20)新手常在这里纠结要不要冻结BERT主干、只训分类头。对20NewsGroups这种规模的数据集我建议全参数微调。原因有二一是样本量约1.6万篇远没过拟合警戒线二是新闻领域里的词汇比如硬件术语、宗教政治相关表达在预训练模型里已有语义但针对性微调仍能提升类别区分度。冻结主干适合算力受限或数据只有几千条的场景数据量足够时全参数微调准确率普遍高出3到5个百分点。这是一个可以验证的结论如果条件允许两组对比实验值得跑一次。4.2 训练循环里优化器、warmup与loss的设置优化器上BERT微调的标准选法是AdamW。这个名字里的“W”指weight decay只作用于可训练权重不作用于bias和LayerNorm参数这是PyTorch自带Adam和transformers的AdamW最关键的区别。学习率默认2e-5千万不能照搬图像任务的1e-3预训练模型已经收敛好过大的学习率等于把学到的表示一步打碎。from transformers import AdamW, get_linear_schedule_with_warmup total_steps len(train_loader) * 4 warmup_steps int(total_steps * 0.1) optimizer AdamW( model.parameters(), lr2e-5, weight_decay0.01 ) scheduler get_linear_schedule_with_warmup( optimizer, num_warmup_stepswarmup_steps, num_training_stepstotal_steps )总步数按4个epoch计算前10%步数做warmup让学习率从0线性升到2e-5。为什么要warmupBERT权重经过长时间预训练一上来用满学习率会破坏self-attention里已经稳定的数值分布warmup相当于软启动。之后学习率线性衰减到0让模型在训练末尾趋于稳定。如果训练压缩到2个epochwarmup比例提高到20%会更稳这是我的经验值具体原理是学习率曲线在短训练里需要更平缓的上升段。训练循环里直接使用模型的loss返回值省得自己从logits和labels再算一遍交叉熵默认return_dictTrue时outputs.loss和outputs.logits直接可取import torch import torch.nn as nn from tqdm.auto import tqdm device torch.device(cuda if torch.cuda.is_available() else cpu) model.to(device) model.train() for epoch in range(4): total_loss 0.0 progress tqdm(train_loader, descfEpoch {epoch1}) for batch in progress: optimizer.zero_grad() input_ids batch[input_ids].to(device) attention_mask batch[attention_mask].to(device) labels batch[labels].to(device) outputs model( input_idsinput_ids, attention_maskattention_mask, labelslabels ) loss outputs.loss loss.backward() nn.utils.clip_grad_norm_(model.parameters(), max_norm1.0) optimizer.step() scheduler.step() total_loss loss.item() progress.set_postfix({loss: f{loss.item():.4f}}) avg_loss total_loss / len(train_loader) print(fEpoch {epoch1} / 4, avg_loss: {avg_loss:.4f})clip_grad_norm_(..., max_norm1.0)不是可选项。BERT微调最常见的翻车点之一是梯度范数爆炸第二三层的gradient norm一旦冲到两位数loss就再也回不到正常水平。限制梯度范数能稳定参数更新方向省掉后续大量无效调试。同时每step之后必须scheduler.step()warmup计划按step而非epoch下降忘写这步会导致warmup失效、收敛变慢。4.3 一套能直接上手的超参表到这里超参基本成形给出一份可复现的参数表超参推荐值影响max_len256覆盖20NewsGroups中大部分新闻的有效信息batch_size16显存8G以下降到8lr2e-5超过5e-5容易炸lossepochs44个epoch接近收敛6个以上容易过拟合warmup比例10%训练轮次少时提到20%weight_decay0.01只作用于权重矩阵而非bias这套参数在20NewsGroups上训练验证准确率能做到0.9以上。实际跑的时候先跑一个batch验证loss能下降再全量训练能省一半时间。5. 训练不收敛与数据错配四个高频踩坑排查5.1 显存OOMmax_len设得太长现象训练脚本在第二个batch直接报CUDA out of memory前面第一个batch跑得正常下一个突然崩。原因max_len设置过大。比如直接把512塞给一堆长文本而20NewsGroups平均文本长度远达不到512padding的零token照样占显存显存就被无效填充吃光了。解决统计文本长度分布取90%分位数作为max_len。在预处理阶段算过训练集约90%的样本在600词以内换算成BERT的subword token大约250到350所以max_len设256能覆盖大部分信息。显存仍然不足先把batch_size减半这比继续调max_len更直观。也可以配合gradient_accumulation_steps例如batch_size8配accumulation_steps2等效batch_size16但显存占用不变。5.2 标签错位子集过滤后忘了重映射现象训练阶段acc涨到0.9验证阶段却跌到0.2看起来完全对不上。原因很多演示为了省时间会先从20类里挑几个子类做四分类如果直接用cat过滤拿到的原始编号类别筛选后数字没变但语义已经错位。模型在训练时学到的是新的类别顺序验证时又按旧编号解读结果全乱。解决过滤后必须重映射标签编号selected [0, 1, 2, 3] # 自定义类别索引 mask np.isin(labels, selected) sub_texts data[mask] sub_labels labels[mask] remap {old: new for new, old in enumerate(selected)} sub_labels np.array([remap[old] for old in sub_labels]) print(np.unique(sub_labels)) # [0 1 2 3]这个坑的现象很典型训练和验证分开跑都正常合并评估就完全对不上。想起“过滤之后标签映射失效”这条血泪经验就能立刻定位。5.3 loss不降学习率过大与权重衰减的误区现象loss在第一个step冲到5.0以上十几个epoch没有下降或者loss在某个值附近来回震连续40步不降。原因一类是学习率设太高典型照搬图像分类的1e-3或1e-2。另一类是weight decay设错把bias和LayerNorm参数也一起衰减导致LayerNorm的scale参数被压扁模型无法恢复正确特征分布。解决学习率固定到1e-5到3e-5不要超过5e-5。想让weight decay只作用于权重矩阵就分组传参no_decay [bias, LayerNorm.weight] optimizer_grouped_parameters [ { params: [p for n, p in model.named_parameters() if not any(nd in n for nd in no_decay)], weight_decay: 0.01, }, { params: [p for n, p in model.named_parameters() if any(nd in n for nd in no_decay)], weight_decay: 0.0, }, ] optimizer AdamW(optimizer_grouped_parameters, lr2e-5)判断依据打印第一个epoch的loss如果每个batch都在1.0附近徘徊先查学习率再查分组这两个没问题才排查模型结构和数据泄露。5.4 加载卡死预训练权重文件拉不全现象第一次运行脚本长时间卡在Downloading model.safetensors甚至直接报连接错误。原因加载权重时transformers会先从远端拉取文件BERT-base的权重文件比较大网络波动或缓存目录写权限异常都可能导致读取卡死。解决先手工预下载权重到本地缓存再让transformers直接走缓存export HF_HOME/data/hf_cache huggingface-cli download bert-base-uncased设置好环境变量后Python里正常from_pretrained(bert-base-uncased)会直接读取本地缓存。检查缓存完整性时看/data/hf_cache/hub/models--bert-base-uncased/snapshots/路径下文件大小是否接近预期文件缺一半说明下载中断删掉重下。这里补充一点tokenizer文件小基本能同步完好真正的大头是模型权重。预先下载好再训练后续每轮实验都不会卡在这一步。6. 验证结果与进阶提速从准确率再往前走一步模型训练完成后最常见的收尾动作是打印准确率但我建议把classification_report和混淆矩阵一起跑出来。20个类别上单看准确率很容易掩盖问题比如soc.religion.christian和talk.religion.misc这两类经常互相串单独看准确率0.9根本发现不了看类别的F1才能定位。from sklearn.metrics import accuracy_score, f1_score, classification_report model.eval() preds, trues [], [] with torch.no_grad(): for batch in val_loader: input_ids batch[input_ids].to(device) attention_mask batch[attention_mask].to(device) labels batch[labels].to(device) outputs model(input_ids, attention_maskattention_mask) pred torch.argmax(outputs.logits, dim-1) preds.extend(pred.cpu().tolist()) trues.extend(labels.cpu().tolist()) print(accuracy_score(trues, preds)) print(f1_score(trues, preds, averagemacro)) print(classification_report(trues, preds, target_namestarget_names))BART-base在20NewsGroups上做到0.92左右是正常的这个数据集上的上限大约在0.93到0.95。想知道模型还有多少提升空间把混淆矩阵可视化看哪几类互相混淆比只看单一准确率信息量大得多。进阶提速我会优先提两个方案。第一是混合精度训练用torch.autocast包前向和反向配合GradScaler显存占用能降将近一半20NewsGroups训练时间能缩到原来的三分之二准确率几乎不损失。第二是蒸馏训练好的BERT做teacherDistilBERT做student复现一遍数据推理速度提升到三倍准确率掉1到1.5个百分点部署成本却低很多。做这类项目我的习惯是每次改动先跑一小批数据验证脚本正确性再全量训练。实验日志只留关键指标和超参不保留中间检查点检查点只留验证集loss最低的一个。这样不会把磁盘空间耗在“某个epoch可能有用”的临时文件上。希望这一套从环境、预处理到排查的经验能帮你把BERT分类任务更快跑通少走几段弯路。本文还有配套的精品资源点击获取