BERT+TextCNN文本分类源码实战：融合预训练语义与局部特征

简介：这套基于BERT的文本分类CNN模型设计源码，面向自然语言处理初学者、算法工程师及课设学生，主要解决如何将预训练语义表示与CNN结合，快速完成短文本/多标签文本分类任务的问题。资源包共25个文件，压缩后约323KB；类型包括16个py源文件、3个txt、2个md、2个license、1个ipynb及1个gitignore。py脚本覆盖text_cnn模型搭建、BERT调用、训练推理、分词与特征提取等关键环节，ipynb可交互式演示，md/txt与license分别承担使用说明和协议说明，目录结构便于按需检索。整体界面友好，代码注释清晰，可迁移到情感分析、新闻分类、意图识别等常见NLP场景。作者给出从tokenization、optimization、modeling到run_classifier的完整实现，读者既能按脚本复现流程，也可更换数据集、调整模型结构做二次开发。目前已有428人学习下载，是一款适合作为入门级BERT应用项目与课程设计参考的开源实现。

1. BERT 遇上 TextCNN：一套能直接跑的文本分类源码

被 BERT 的效果惊艳、又被上线成本劝退，是做文本分类的人普遍经历过的事。BERT 在情感分析、意图识别上确实很猛，但更大的模型也意味着更贵的 GPU 和更慢的响应。这份源码给出的是一条折中路线：用 BERT 把每条文本转成语义更丰富的 token embedding，后面接一个轻量的 TextCNN 做分类——保留 BERT 的语义能力，又把训练和推理成本拉回到可接受范围。项目本身是完整的 Python 工程，loader.py、text_model.py、text_run.py 这些核心文件都在，顺手带了 BERT 官方的 modeling、tokenization 等依赖模块，既能微调，也能做特征提取。适合想把文本分类从论文落到业务、又不愿意从零搭 BERT 环境的开发者，学生拿它快速跑通 BERT 分类流程也合适。

2. 源码包拆解：26 个文件里谁在干活，谁是 BERT 官方配件

看开源项目我有个习惯：先分清“主代码”和“依赖文件”，而不是从头到尾挨个啃。这个包里 26 个文件，真正属于本项目自己写的只有一小撮，其余是 BERT 官方源码的副本和示例文档。分清之后，改起来心里才有底，也不至于误删不该动的模块。

2.1 核心三件套：loader、text_model、text_run 怎么配合

项目主代码集中在三个文件：loader.py 管数据读取，text_model.py 管模型结构，text_run.py 管训练和预测入口。调用关系很直接：text_run 解析命令行参数，把路径和超参读进来；loader 负责把原始文本切成 BERT 需要的 input_ids 和 mask；text_model 拿到这批张量之后建计算图，输出 logits 给损失函数。整个过程没有复杂的中间层，适合当入门模板拆着看。

提示：text_run.py 是整包的调度中心，如果你只想跑通实验，先读它；如果你想改分类效果，先动 loader.py 和 text_model.py。

2.2 BERT 官方文件为什么建议原样保留

包里 modeling.py、tokenization.py、optimization.py 以及对应的 _test.py 文件，本质是 BERT 官方发布时自带的代码副本。它们负责的是 Transformer 编码器、WordPiece 分词器和 Adam 优化器，是计算图的底层。此前见过有人为了“优化性能”去改 modeling.py 里的 attention 实现，结果算出来的 embedding 和预训练权重对不上，整个模型精度下降还查不出原因。这类文件的作用是保持和预训练 checkpoint 的兼容性：权重文件里每一层张量的名字、形状，都要和 modeling.py 里创建的计算图一一对应。动了名字，init_checkpoint 就加载不进去。正确的打开方式是原样保留，只通过参数来使用它们。

2.3 为什么是 BERT + CNN 这个组合

文本分类模型设计上有两条常见路线：BERT 直接接全连接层做分类，或者把 BERT 当作特征提取器、后续接更轻量的分类网络。前者叫 fine-tune，效果好但训练和推理都重；后者把 BERT 冻结成 embedding 层，后面接 TextCNN，等于让大模型负责语义理解、小网络负责抓局部特征。TextCNN 的价值在于参数少、训练快，在情感分类、主题分类这类任务上，用卷积核去抓 n-gram 特征往往够用。两者的结合点在 sequence_output：BERT 吐出每个 token 的上下文向量，TextCNN 在这个向量序列上做卷积和池化。这份源码选的就是这条组合路线，所以它的文本分类能力比单独用 Word2Vec + CNN 明显强一截，又比单独跑 BERT 分类省资源。

3. 从下载到跑通：环境准备、数据格式与训练参数

这章解决的是“怎么把它跑起来”。BERT 官方源码的历史包袱比较重，它按 TensorFlow 1.x 时代的标准写法写的，所以环境版本是第一个坎；数据格式直接决定 loader 能不能读进去，也影响最终分类效果。

3.1 Python 版本与依赖安装

建议用 Python 3.6 或 3.7 建虚拟环境。不是新版 Python 不行，而是这份代码里 tf.contrib 这类模块在 TF 2.x 里被移除了，Python 3.8+ 搭配旧版 TensorFlow 又容易踩编译兼容问题。常见做法是给项目单独建环境，不污染系统 Python：

python -m venv bertcnn_env source bertcnn_env/bin/activate # Windows 用 bertcnn_env\Scripts\activate pip install -r requirements.txt

requirements.txt 里通常锁的是 tensorflow、numpy、six、tqdm 这一组，其中 tensorflow 版本是核心。如果锁定的是 1.15，直接安装即可；如果下载慢，可以在 pip 命令里临时换成国内镜像源，但注意不要顺带把 tensorflow 版本也换了，版本一变，后面加载 checkpoint 很容易出幺蛾子。装完可以用pip list | grep tensorflow确认实际安装版本。

注意：如果你只有 TensorFlow 2.x 环境，建议先单独装一个 Python 3.6 的虚拟环境跑这套源码，而不是在 2.x 里硬试，后面的避坑章节会解释原因。

3.2 数据怎么喂给 loader

loader.py 的数据读取格式决定了你要怎么准备自己的文件。比较典型的是每行一条样本，格式类似“标签 + 分隔符 + 文本”，分隔符可能是制表符\t也可能是空格。如果文本里本身含空格，用空格做分隔符会给分词环节添乱，更稳妥的是 TSV 格式，一列标签一列文本。包里的 sample_text.txt 是示例明文，更适合用来做预测演示，而不是训练。

拿自己的数据集来跑时，我会先打印 loader 读出来的前五行，确认标签和文本没黏在一起。常见翻车点是 CSV 转码问题：Windows 下存的 CSV 可能是 GBK 编码，而 loader 通常按 UTF-8 读取，一串乱码进去，模型当然学不到东西。解决方案是统一转成 UTF-8 with BOM 或者无 BOM 的 UTF-8，再检查有没有多余的双引号和换行符。

3.3 训练命令与参数说明

环境准备好后，训练入口一般是这样的（具体参数名以包内代码为准）：

python text_run.py \ --mode train \ --train_file ./data/train.tsv \ --eval_file ./data/dev.tsv \ --vocab_file ./bert/vocab.txt \ --bert_config_file ./bert/bert_config.json \ --init_checkpoint ./bert/bert_model.ckpt \ --output_dir ./output \ --max_seq_length 128 \ --batch_size 16 \ --num_epochs 3 \ --learning_rate 5e-5

几个关键参数的实际影响：max_seq_length 控制输入截断长度，128 对短文本足够，文本平均长度超过 200 字就提到 256；batch_size 直接决定显存占用，12G 显存下 16 是比较保险的起跑值；learning_rate 用的是 BERT 微调惯用的 5e-5，比新训 CNN 常用的 1e-3 低一个量级，原因在于预训练权重已经收敛得不错，步子迈太大会把学好的语义冲乱。output_dir 是训练产物目录，跑完里面会有 checkpoint 和 eval 结果，不要和--init_checkpoint指向同一位置，否则会把预训练权重覆盖掉。

预训练权重需要从 BERT 官方发布页下载三件套：bert_config.json、vocab.txt、bert_model.ckpt 系列文件，三个必须来自同一个发布版本。选 uncased 还是 cased，按你的业务场景定：中文和英文学术文本推荐 uncased，专有名词敏感的用 cased。下载后放进一个固定目录，路径不要带中文和空格，避免读文件时踩编码坑。

4. 模型设计拆解：sequence_output 接卷积的四个关键点

跑通之后就该看模型内部了。这章把 text_model.py 的设计思路拆开讲：为什么取 sequence_output 而不是 pooled_output，多尺度卷积的参数怎么定，以及冻结 BERT 和全量微调各自适合什么情况。

4.1 为什么取 sequence_output 而不是 pooled_output

BERT 的接口里有两个常用输出：get_pooled_output() 返回的是 [CLS] 位置的聚合向量，适合直接接全连接层；get_sequence_output() 返回的是每个 token 的向量序列，形状是 (batch_size, seq_len, hidden_size)。TextCNN 需要的是后者，因为卷积操作要在序列维度上滑动窗口，抓取相邻 token 之间的局部关系。用 pooled_output 就相当于把整句话压缩成一个点，卷积核没有东西可扫，TextCNN 直接变成两层全连接，失去了多尺度 n-gram 特征提取的能力。这是模型设计里很容易被忽略但直接影响效果的一处选择。

4.2 多尺度卷积怎么搭

包里的 text_model.py 大体按下面这个结构组织（示意代码，具体实现以包内为准）：

import tensorflow as tf from bert import modeling def build_text_cnn(input_ids, input_mask, segment_ids, bert_config, num_labels, is_training): # 1. BERT 编码得到 token 向量序列 bert_model = modeling.BertModel( config=bert_config, is_training=is_training, input_ids=input_ids, input_mask=input_mask, token_type_ids=segment_ids, use_one_hot_embeddings=True) seq_out = bert_model.get_sequence_output() # (batch, seq_len, 768) # 2. 用不同尺寸卷积核扫 n-gram pooled_outputs = [] for kernel_size in [2, 3, 4]: conv = tf.layers.conv1d( inputs=seq_out, filters=128, kernel_size=kernel_size, padding='same', activation=tf.nn.relu) pooled = tf.reduce_max(conv, axis=1) # 全局最大池化 pooled_outputs.append(pooled) # 3. 拼接多尺度特征，过 dropout 后分类 fused = tf.concat(pooled_outputs, axis=-1) fused = tf.layers.dropout(fused, rate=0.2, training=is_training) logits = tf.layers.dense(fused, num_labels) return logits

代码逻辑按三步走：BERT 先给每个 token 算出上下文相关的向量；三个尺度的卷积核在序列上滑动，分别抓 2-gram、3-gram、4-gram 的局部特征；全局最大池化把不同长度的序列压成固定长度向量，拼接后送进 softmax。padding='same' 保证卷积前后序列长度一致，不加它，长度短的句子到池化时维度会不稳定。

参数上，filters 设 128 是个平衡点，数据量大可以提到 256，小数据集用 64 就能防过拟合；kernel_size 组合 [2,3,4] 是最常用搭配，如果任务以短文本为主，比如短信分类，去掉 4 只留 [2,3] 往往更稳定。dropout 的 rate=0.2 对应的是 BERT 微调常见的正则力度，过拟合严重时再提到 0.3 或 0.5。

4.3 冻结 BERT 还是全参数微调

这是个效果和成本的权衡。冻结 BERT 意味着只更新 TextCNN 和最后的全连接层，训练快、显存省，小数据集上不容易过拟合，缺点是 BERT 没有针对你的领域做适配。全参数微调则让 BERT 也参与反向传播，效果上限高，但对数据量和显存都有要求。数据只有几千条时微调 BERT，几乎必过拟合；十万条以上再考虑全量微调才划算。冻结的做法在代码层面通常是在 optimizer 的 var_list 上动手，只把 TextCNN 的变量传进去，或者更简单地：

# 常见做法：先把 BERT 整体冻结，只训练下游网络 # 具体写法取决于包内是否暴露了 trainable 控制接口 # 通常是在 text_run.py 中过滤 var_list： train_vars = [v for v in tf.trainable_variables() if 'text_cnn' in v.name or 'dense' in v.name]

我第一次跑这类模型时贪效果直接全量微调，三千条训练样本跑了五个 epoch，验证 F1 反而比冻结版本低八个点，典型的过拟合。后来改成折中方案：先冻结 BERT 训练几个 epoch，再把 BERT 后几层解冻做小学习率微调，效果和稳定性都兼顾了。建议从冻结版本起步，跑通后再逐步放开层数。

5. 避坑手册：BERT+CNN 场景下 4 个高频翻车点

这套组合的坑主要集中在资源、数据、权重版本、框架版本四个方向，每条都是我见过的真实事故，按“现象 → 原因 → 解决”写出来，能少走不少弯路。

5.1 OOM 几乎人人遇到

现象：训练刚开始或者跑到第二个 epoch，终端直接报Resource exhausted: OOM when allocating tensor，进程退出。

原因：max_seq_length 和 batch_size 的乘积决定了显存里的中间张量规模。BERT-Base 是 12 层 Transformer，每个 token 的中间激活都很占显存，512 的长度乘以 32 的 batch，12G 显存根本扛不住。

解决：先降 batch_size 到 8 或 16，max_seq_length 从 128 起步，确认能跑通再逐步往上加。还不行就看是不是同时开了 eval 流程，evaluation 也要占一份前向显存，可以把 eval 频率调低或者先注释掉。单卡跑不动又必须大 batch 的，考虑梯度累积——攒几个小 batch 的梯度再更新一次，效果接近大 batch。

5.2 分词不一致导致“训练很准、预测很烂”

现象：dev 集上 F1 挺好看，拿新句子预测时结果完全不对，翻车概率极高。

原因：训练数据走了 tokenization.py 的 WordPiece 分词，而预测脚本里用了 jieba 或者直接按空格切。BERT 的词汇表是 subword 级别，和中文词语切分不是一回事，两边 token 对不上，模型看到的输入分布完全变了。

解决：训练和预测强制走同一套分词流程，直接用包里 tokenization.py 的tokenize方法。排查方法是打印同一句话在训练和预测两个路径下的 input_ids，逐位对比是否一致。

5.3 checkpoint 与 config 不匹配

现象：加载预训练权重时报维度不匹配，或者干脆静态检查都过不了，报Shape mismatch。

原因：下载 checkpoint 时没注意版本。BERT 有 uncased 和 cased 之分，还有 Base 和 Large 的区别，以及中文版和英文版的 vocab.txt 完全不同。混搭就会出现 hidden_size、num_hidden_layers 对不上的问题。

解决：下载时把同一个 release 下的三个文件放一个目录，记住版本名。我的习惯是在目录里写个 README 记录版本和来源，避免过两个月自己都忘。加载报错时，先核对 bert_config.json 里的 hidden_size 和 checkpoint 是否一致，再检查 vocab.txt 最后一行是不是常见不一致来源。

5.4 TensorFlow 2 环境跑 TensorFlow 1 时代代码

现象：import 就报AttributeError: module 'tensorflow' has no attribute 'contrib'，或者get_shape这类旧 API 直接不可用。

原因：模型和依赖代码是 TF 1.15 时代写的，tf.contrib 在 TF 2.x 里被整体移除，contrib 模块本来承载了部分 attention 实现。

解决：最省事的方案是按 3.1 节建 Python 3.6 + TensorFlow 1.15 的环境。非要留在 TF 2.x 的话，需要做大量兼容改造，工作量不在看代码之下。bert 目录下的官方测试文件会帮你在装完环境后自检：跑一遍 modeling_test.py 和 tokenization_test.py，确认依赖没问题再开始训练。这个动作是我拿到任何 BERT 项目都会先做的“环境体检”。

6. 验证与进阶：从官方 notebook 到自己的业务数据

到手先别急着灌自己的数据。这个包里附带了一个预测影评的 notebook 文件，它是 Google 官方在 TensorFlow Hub 上放出的经典示例，跑通它相当于给环境做了一次端到端体检：预训练权重能不能加载、分词链路通不通、前向预测顺不顺。我通常先全跑一遍，确认没有任何红色报错，才会进到自己的任务。

跑通之后，用 sample_text.txt 做一次推理是最快的验证手段：

python text_run.py \ --mode predict \ --text_file ./sample_text.txt \ --vocab_file ./bert/vocab.txt \ --bert_config_file ./bert/bert_config.json \ --init_checkpoint ./output/model.ckpt \ --output_dir ./output

注意这里 init_checkpoint 指向的是你自己训练产出的 checkpoint，而不是预训练权重。输出文件里每条样本对应一行预测标签和置信度，先人工过一遍，重点看置信度分布是否合理——所有样本都六七个点信心，说明模型没学会，别急着上线。

迁移到自己的业务数据，核心是保住格式和标签映射。把数据整理成 TSV，标签从 0 开始编号，并记录一份 label 和中文含义的映射表。分类任务评估时不要只看 accuracy：类别不平衡时用 macro-F1 更客观，负面样本只占 10% 的业务场景，accuracy 高也是虚的。部署阶段，我的做法是把训练好的模型导出成 SavedModel，只保留前向推理图，去掉优化器相关节点，BERT 在这里的角色从“训练主体”变成“特征提取器”，这样单条推理时间能控制在可接受范围内。

回顾这套流程，我最想叮嘱的还是顺序问题。刚拿到这类 BERT 项目时，我犯过的最蠢的错是跳过验证直接跑自己的数据，结果权重没下载成功，排查了半天才意识到是环境问题而不是代码问题。从那以后，我每次拿到新的 BERT 源码包，都强制自己先把官方示例和样例文件完整跑一遍，确认基座没问题再碰业务逻辑，把环境问题和模型问题彻底分开。这个习惯帮我省下的无效排查时间，远比多跑一遍示例花掉的多。希望帮到你。

本文还有配套的精品资源，点击获取