简介：这份资源面向希望快速上手中文文本分类的深度学习开发者与NLP学习者，基于pytorch-transformers实现BERT中文新闻标题分类，覆盖从数据预处理、模型加载到训练与评估的完整流程，适合具备一定PyTorch基础、想掌握预训练模型微调的中级读者。压缩包共29个文件，约732.57MB，包含7个txt数据与标签文件、5个py训练与预处理脚本、5个xml工程配置、3个pyc缓存、2张结果图及预训练权重pytorch_model.bin、config.json、vocab.txt等，结构清晰便于按模块查阅。数据取自THUCNews随机抽取的20万条新闻标题，涵盖财经、房产、股票、教育、科技、社会、时政、体育、游戏、娱乐十类，每类2万条，按18万训练、1万验证、1万测试划分，类别均衡。已有3700人学习下载，读者可据此复现BERT中文分类基线，理解预训练模型接入、数据管道搭建与结果可视化，并参考训练日志与准确率曲线排查问题。
1. 一份能直接跑通的 BERT 中文分类工程，到底长什么样
很多做 NLP 的朋友都有过这种经历：网上找到一份 BERT 中文文本分类代码，clone 下来发现缺数据、缺权重、缺配置，改半天跑不起来。这份基于 pytorch-transformers 实现的 BERT 中文文本分类代码，解决的就是这个问题——它把数据加载、模型封装、训练循环、评估预测整条链路都串好了，拿到手改改数据路径就能跑。适合两类人：一是刚接触文本分类、想找个能跑通的基线工程练手的新手；二是需要快速搭一个中文分类服务、不想从零造轮子的开发者。项目用 pytorch-transformers 作为底层库，兼容 BERT-base-chinese 预训练权重，覆盖情感分析、新闻分类、意图识别这类常见场景。下面从目录结构开始，把这份代码拆开讲清楚。
2. 工程结构与技术选型：为什么用 pytorch-transformers 而不是裸写 PyTorch
2.1 目录结构一览
这份代码的目录组织比较清晰，常见做法是分成配置、数据、模型、训练、预测几个部分。我拿到手后一般会先看目录，判断作者有没有把关注点分离好。典型的目录结构如下：
bert-chinese-classification/ ├── configs/ │ └── bert_config.json # 模型超参配置 ├── data/ │ ├── train.csv # 训练集 │ ├── dev.csv # 验证集 │ └── test.csv # 测试集 ├── outputs/ │ ├── checkpoints/ # 模型保存目录 │ └── logs/ # 训练日志 ├── src/ │ ├── dataset.py # 数据加载与预处理 │ ├── model.py # 模型定义 │ ├── train.py # 训练入口 │ ├── evaluate.py # 评估脚本 │ └── predict.py # 单条/批量预测 ├── requirements.txt └── README.md这个结构的好处是职责分明：dataset.py只管把原始文本转成 BERT 需要的 input_ids、attention_mask、token_type_ids；model.py只管在 BERT 输出上加分类头；train.py负责训练循环和 checkpoint 保存。改数据格式只动 dataset，换模型只动 model，不会牵一发动全身。
2.2 技术选型：pytorch-transformers 的取舍
项目选 pytorch-transformers 而不是直接写 PyTorch，核心原因是它把 BERT 的 tokenizer、预训练权重加载、模型结构都封装好了。裸写 PyTorch 的话，光是把中文文本正确切成 BERT 需要的 WordPiece token 就要写不少代码，还容易在 padding、truncation 上翻车。pytorch-transformers 提供BertTokenizer和BertForSequenceClassification，几行就能把预训练模型接上分类头。
不过要注意，pytorch-transformers 这个库后来改名成了 transformers，API 有变化。这份代码用的是老版本接口，如果你装的是新版 transformers，from pytorch_transformers import ...会直接报 ModuleNotFoundError。常见做法是固定版本安装：
pip install pytorch-transformers==1.2.0 pip install torch==1.4.0或者把 import 改成新版写法：
# 老版本 from pytorch_transformers import BertTokenizer, BertForSequenceClassification # 新版本 transformers from transformers import BertTokenizer, BertForSequenceClassification参数上，BertForSequenceClassification.from_pretrained的num_labels要和你实际类别数一致，二分类填 2，多分类填实际类别数。这个参数填错不会报错，但训练时 loss 会异常，属于典型的玄学问题。
2.3 数据格式约定
代码默认数据是 CSV 格式，两列：text和label。label 从 0 开始编号。如果你的数据是 tsv 或者 json，改dataset.py里的读取逻辑就行。常见做法是用 pandas 读进来，然后转成 list：
import pandas as pd train_df = pd.read_csv('data/train.csv') texts = train_df['text'].tolist() labels = train_df['label'].tolist()这里有个坑：中文文本里如果有换行符或者制表符，CSV 读取会错位。我一般会在读之前先做一次清洗，把\n、\t替换成空格。另外 label 如果是字符串（比如 "positive"/"negative"），需要先映射成整数，否则后面 CrossEntropyLoss 会报类型错误。
3. 核心模块拆解：从 tokenizer 到分类头的完整链路
3.1 数据预处理：tokenizer 的正确用法
BERT 中文分类的第一步是把文本转成模型能吃的张量。dataset.py里通常会封装一个 Dataset 类，核心逻辑在__getitem__里：
from torch.utils.data import Dataset from pytorch_transformers import BertTokenizer class TextClassificationDataset(Dataset): def __init__(self, texts, labels, tokenizer, max_len=128): 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]) label = self.labels[idx] # encode_plus 返回 input_ids, token_type_ids, attention_mask encoding = self.tokenizer.encode_plus( text, add_special_tokens=True, # 加 [CLS] 和 [SEP] max_length=self.max_len, padding='max_length', # 统一 padding 到 max_len truncation=True, # 超长截断 return_attention_mask=True, return_tensors='pt' ) return { 'input_ids': encoding['input_ids'].flatten(), 'attention_mask': encoding['attention_mask'].flatten(), 'token_type_ids': encoding['token_type_ids'].flatten(), 'labels': torch.tensor(label, dtype=torch.long) }这里几个参数值得说清楚。max_length=128是中文短文本分类的常用值，长文本可以调到 256 或 512，但显存占用会明显上升。padding='max_length'保证一个 batch 里所有样本长度一致，不然 DataLoader 拼 batch 时会报错。truncation=True处理超长文本，不设的话遇到长文本会直接抛异常。add_special_tokens=True会自动在开头加[CLS]、结尾加[SEP]，分类任务取[CLS]位置的输出做分类，这个 token 不能省。
3.2 模型定义：在 BERT 上加分类头
model.py的核心是继承BertForSequenceClassification或者自己封装。如果只是标准分类，直接用官方封装最省事：
from pytorch_transformers import BertForSequenceClassification, BertConfig class BertClassifier(nn.Module): def __init__(self, num_labels, dropout=0.3): super(BertClassifier, self).__init__() # 加载预训练 BERT，指定分类类别数 self.bert = BertForSequenceClassification.from_pretrained( 'bert-base-chinese', num_labels=num_labels ) # 可选：替换 dropout 层，防止过拟合 self.bert.dropout = nn.Dropout(dropout) def forward(self, input_ids, attention_mask, token_type_ids): outputs = self.bert( input_ids=input_ids, attention_mask=attention_mask, token_type_ids=token_type_ids ) return outputs[0] # logitsnum_labels必须和数据集类别数一致。dropout=0.3是我一般会设的值，小数据集上比默认的 0.1 更稳。outputs[0]是 logits，形状是(batch_size, num_labels)，后面接 CrossEntropyLoss 就行。如果你要做多标签分类，把 loss 换成 BCEWithLogitsLoss，num_labels 不变但标签要做 multi-hot 编码。
3.3 训练循环：学习率与 warmup 的设置
train.py是整份代码里最值得细看的部分。BERT 微调的学习率不能太大，常见做法是 2e-5 到 5e-5，配合 warmup：
from pytorch_transformers import AdamW, WarmupLinearSchedule # 优化器：AdamW 对 BERT 微调更友好 optimizer = AdamW(model.parameters(), lr=2e-5, correct_bias=False) # 学习率调度：前 10% 步数 warmup，之后线性衰减 total_steps = len(train_loader) * epochs scheduler = WarmupLinearSchedule( optimizer, warmup_steps=int(0.1 * total_steps), t_total=total_steps ) # 训练循环 for epoch in range(epochs): model.train() total_loss = 0 for batch in train_loader: optimizer.zero_grad() input_ids = batch['input_ids'].to(device) attention_mask = batch['attention_mask'].to(device) token_type_ids = batch['token_type_ids'].to(device) labels = batch['labels'].to(device) logits = model(input_ids, attention_mask, token_type_ids) loss = nn.CrossEntropyLoss()(logits, labels) loss.backward() # 梯度裁剪，防止梯度爆炸 nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0) optimizer.step() scheduler.step() total_loss += loss.item()AdamW比普通 Adam 多了权重衰减的正确实现，BERT 微调基本都用它。correct_bias=False是老版本 pytorch-transformers 的写法，新版 transformers 里这个参数已经默认处理了。warmup_steps设总步数的 10% 是经验值，太小容易前期震荡，太大收敛慢。clip_grad_norm_的max_norm=1.0是防止梯度爆炸的后悔药，中文分类任务上一般不会炸，但加上更保险。
3.4 评估与预测：从 logits 到类别
评估脚本的核心是算准确率和 F1。evaluate.py里通常会这么写：
from sklearn.metrics import accuracy_score, f1_score model.eval() preds, true_labels = [], [] with torch.no_grad(): for batch in dev_loader: input_ids = batch['input_ids'].to(device) attention_mask = batch['attention_mask'].to(device) token_type_ids = batch['token_type_ids'].to(device) labels = batch['labels'].to(device) logits = model(input_ids, attention_mask, token_type_ids) pred = torch.argmax(logits, dim=1) preds.extend(pred.cpu().numpy()) true_labels.extend(labels.cpu().numpy()) print('Accuracy:', accuracy_score(true_labels, preds)) print('F1:', f1_score(true_labels, preds, average='weighted'))torch.no_grad()关掉梯度计算，省显存也提速。torch.argmax(logits, dim=1)取概率最大的类别。average='weighted'在多分类不平衡时比 macro 更合理。预测脚本predict.py逻辑类似，只是输入变成单条文本，输出是类别和置信度。
4. 避坑与排查：跑这份代码最容易翻车的几个地方
4.1 报错 ModuleNotFoundError: No module named 'pytorch_transformers'
现象：pip install 之后 import 还是报找不到模块。原因：装的是新版 transformers，包名已经改了，或者装到了别的 Python 环境。解决：先pip show pytorch-transformers确认装没装，没装就pip install pytorch-transformers==1.2.0；如果用的是 conda 环境，确认 pip 和 python 是同一个环境下的。实在不行就把 import 改成from transformers import ...，同时注意新版 API 里WarmupLinearSchedule已经换成get_linear_schedule_with_warmup。
4.2 训练 loss 不下降或者变成 nan
现象：loss 一直在 0.69 附近（二分类）或者 nan。原因：学习率太大、数据标签没对齐、或者输入里有空文本。解决：先把学习率降到 1e-5 试试；检查 label 是不是从 0 开始连续编号，有跳号会导致 CrossEntropyLoss 越界；检查数据里有没有空字符串，空文本经过 tokenizer 后只有[CLS]和[SEP]，模型学不到东西。我一般会在 dataset 里加一行过滤：if len(text.strip()) == 0: continue。
4.3 显存不够，batch_size 调到 1 还是 OOM
现象：CUDA out of memory。原因：max_length 设太大，或者模型没放到 CPU 上评估。解决：先把 max_length 从 512 降到 128；训练时用梯度累积模拟大 batch；评估和预测时确保model.eval()和torch.no_grad()都加了。如果还不行，试试torch.cuda.empty_cache()，或者换小一号的模型比如 bert-base-chinese 换成更小的中文预训练模型。
4.4 预测结果全是同一个类别
现象：不管输入什么文本，预测出来都是同一类。原因：训练数据类别极度不平衡，或者模型根本没训练（加载了未微调的权重）。解决：先看训练集各类别样本数，差太多的话做重采样或者加 class_weight；确认 checkpoint 加载的是微调后的权重，不是原始 BERT；检查 tokenizer 和模型是不是配套的，用错 tokenizer 会导致输入完全错位。
4.5 中文标点被切没了
现象：文本里的标点符号在 tokenize 后消失。原因：BERT 中文 tokenizer 是基于字的，标点会被单独切出来，但如果你的文本里有全角/半角混用，可能被当成未知字符。解决：预处理时统一全角半角，常见做法是用unicodedata.normalize('NFKC', text)。另外[UNK]token 太多说明词表覆盖不够，检查是不是用了英文 BERT 的 tokenizer。
5. 二次开发：换数据、换模型、上服务的改造思路
拿到这份代码后，最常见的改造是换自己的数据集。假设你有一个三分类的中文新闻数据集，格式是text,label，label 是 0/1/2。第一步改configs/bert_config.json里的num_labels为 3，第二步把data/train.csv和data/dev.csv换成你的数据，第三步确认dataset.py里的列名和你的 CSV 一致。跑之前先用小样本（比如 100 条）过一遍，确认没有形状错误再上全量。
换模型也很直接。如果你想试 RoBERTa 或者 ALBERT，把model.py里的BertForSequenceClassification换成对应的类，tokenizer 也换成配套的。注意不同模型的max_length和hidden_size不一样，ALBERT 的 hidden_size 是 768 但层数少，训练更快但效果可能略降。我一般会先用 BERT-base 跑一个基线，再换其他模型对比 F1，不要一上来就上大模型。
上服务的话，predict.py里的单条预测逻辑可以包成一个 Flask 或 FastAPI 接口：
from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() model = load_model('outputs/checkpoints/best_model.pt') tokenizer = BertTokenizer.from_pretrained('bert-base-chinese') class TextInput(BaseModel): text: str @app.post('/predict') def predict(input: TextInput): encoding = tokenizer.encode_plus( input.text, max_length=128, padding='max_length', truncation=True, return_tensors='pt' ) with torch.no_grad(): logits = model( encoding['input_ids'], encoding['attention_mask'], encoding['token_type_ids'] ) pred = torch.argmax(logits, dim=1).item() return {'label': pred}这里要注意，服务启动时加载模型一次就行，不要每次请求都重新加载，否则延迟会很高。另外model.eval()别忘了加，不然 dropout 会随机丢神经元，同一个输入两次预测结果可能不一样。
最后说一个我踩过的坑：有次换了一个新数据集，训练 loss 正常下降，但验证集准确率一直上不去。排查了半天发现是训练集和验证集的 label 映射不一致——训练集里 0 是正面、1 是负面，验证集里反过来了。从那以后我每次换数据都强制走一遍 label 分布检查，确认训练集和验证集的类别映射完全一致再开跑。希望这份代码和这些经验能帮你少走点弯路。
本文还有配套的精品资源，点击获取
