简介：面向中文NER任务中词汇信息融合效果的验证需求，资源包提供了完整可复现的LEBERT与BERT基线实现，适合NLP初学者、课程设计学生以及需要做模型对比的算法工程师，重点解决中文命名实体识别中词汇特征如何有效注入预训练模型的问题。压缩包共44个文件，整体约12.97MB，源码以Python为主，另含Word版设计报告、shell训练脚本、说明文档、结果对比图和数据压缩包，目录按bert-softmax、bert-crf、lebert-softmax、lebert-crf四个变体组织，并匹配resume、msra、weibo、ontonote四个数据集输出，结构清晰，便于按模型和数据快速定位实验结果。引入词汇信息后，LEBERT与原始BERT在多个中文数据集上的F1差异可直接观察，帮助理解词汇增强机制的有效性和局限性；同时附带trie树、vocab、dataset等预处理模块、label smoothing与focal loss等训练技巧，以及数据格式转换等实用脚本，方便基于该工程切换不同配置继续扩展实验。目前已有492人学习下载，适合在课程设计或论文复现中作为基础框架使用。
1. 词汇信息融合：为什么中文NER需要LEBERT
中文NER（命名实体识别）有个顽固问题：词边界。字粒度模型对分词错误不敏感，但丢掉了词义；词粒度模型又受限于分词质量。LEBERT（Lexicon Enhanced BERT）的答案是——把外部词汇表里匹配到的词，以软对齐的方式注入BERT的每一层注意力计算，让字向量在编码过程中感知到它所处的候选词。这个思路不重新预训练，只在微调阶段加载词汇表，就能在Resume、OntoNotes、MSRA、Weibo这些中文数据集上稳定超过纯字粒度的BERT-Softmax和BERT-CRF基线。对于要做课程设计、论文基线复现、或者给线上NER模型找低成本改进的人来说，这批源码的价值不只是训练脚本，而是把“词汇信息融合”从论文公式变成了可以直接改、直接跑的Python项目。
2. LEBERT模型结构与词汇映射机制
2.1 从BERT到LEBERT：词在哪一层注入
标准BERT对中文的处理是分词符级别的，每个汉字对应一个token，词边界信息只能通过下游CRF或者注意力头被动学习。LEBERT的核心修改点有两个：一是用Trie树对句子做最长/最大匹配，得到每个字可能参与组成的词表；二是设计一个词汇注意力层，在BERT的Transformer层之间插入，让每个字的表示去聚合它所在候选词的信息。
项目源码中的lebert.py就是模型主文件。它继承BERT的实现方式，但不再是简单的“BERT编码 + 分类器”。下面这一段是简化后的前向逻辑，对应源码中词汇融合的骨架：
# lebert.py 简化示意 class LEBERT(nn.Module): def __init__(self, bert_path, vocab_path, num_labels): super().__init__() self.bert = BertModel.from_pretrained(bert_path) self.trie = TrieTree(vocab_path) # 加载外部词典 self.word_proj = nn.Linear(bert_hidden, bert_hidden) # 词向量投影 self.attn = nn.MultiheadAttention(bert_hidden, 8) def forward(self, input_ids, attention_mask, token_type_ids): # 1. 字向量经过最初两层BERT hidden = self.bert.embeddings(input_ids) hidden = self.bert.encoder.layer[:2](hidden)[0] # 2. 用Trie在input_ids对应的token序列上做匹配 matched_words = self.trie.match_span(input_ids) # 3. 将匹配到的词向量投影后与原字向量做注意力融合 word_vecs = self.word_proj(self.lookup_words(matched_words)) hidden = self.attn(hidden, word_vecs, word_vecs)[0] # 4. 继续走完剩余的BERT层 hidden = self.bert.encoder.layer[2:](hidden)[0] return hidden这段代码对应论文里的“词汇融合层插入到第2层之后”。实际源码里不会这么简略，但结构是一致：trie_tree.py负责匹配，lebert.py里把词向量和字向量做attention。注意bert.encoder.layer[:2]和[2:]这种方式并不是PyTorch官方API的写法，而是为说明“前置两层参与词汇注入、后续层继续编码”这个设计。复现时你需要保留BERT的position embedding，因为词向量序列和字向量序列长度不一致，attention计算前要做位置对齐。
2.2 Trie树匹配：候选词从哪里来
trie_tree.py是另一个关键文件。中文词典通常有几十万词条，逐字扫描句子时如果不做前缀剪枝，复杂度会非常高。Trie树把共享前缀的词折叠存储，匹配时沿着树往下走，一次遍历就能拿到从当前字开始的全部词汇。项目里TrieTree的用法是：给定一个字序列[B, E, G, I, N]，输出所有命中的词以及它们在句子中的跨度。
# trie_tree.py 核心方法片段 class TrieNode: __slots__ = ("children", "word", "end") def __init__(self): self.children = {} self.word = None self.end = False def match(self, tokens): """返回 [(start_idx, end_idx, word)] 列表""" results = [] for i in range(len(tokens)): node = self.root j = i while j < len(tokens) and tokens[j] in node.children: node = node.children[tokens[j]] j += 1 if node.end: results.append((i, j, node.word)) return results这段代码是最简单的“遍历所有起点，沿Trie往下吃到最大深度”的匹配方式。参数上要关注两点：一是end标记决定词条是否合法，不要只标记前缀；二是返回的j是词尾的右开区间，后续取词向量时用word_embeddings[start:end]切片要注意长度。源码里还提供了convert_format.py，作用是把原始标注数据转换成(token, label)序列，这个转换会直接影响Trie匹配的“字序列”一致性。
2.3 Softmax输出与CRF输出：两种解码方式的取舍
资源里对比了bert-softmax和bert-crf两种序列标注解码。Softmax就是在每个token上独立预测标签，速度快但忽略标签之间的转移约束，比如“B-PER后面不能直接跟O”这种规则它学不干净。CRF在Softmax输出上额外建模一个转移矩阵，解码时通过Viterbi搜索整体概率最高的标签序列。
crf.py中你可以看到可学习的转移矩阵self.transitions，形状是(num_labels + 2, num_labels + 2)，多出来的两维是START和STOP。训练时计算负对数似然损失，测试时用维特比解码。在平衡且长实体多的数据集上，CRF相对Softmax的提升更明显；但CRF对标签编号顺序敏感，如果processor.py里把标签映射成数字时顺序混乱，转移矩阵的收敛速度会变慢。建议启动训练前先打印一遍id2label，确认O标签的id不是0（因为CRF默认把id为0的标签当作合法标签，不会单独惩罚从O跳到B这类情况）。
下面用一个表汇总项目里主要的模块职责，方便复现时快速锁定文件：
| 文件路径 | 职责 | 对应实验阶段 |
|---|---|---|
models/lebert.py | LEBERT模型定义 | 搭建网络结构 |
models/crf.py | CRF层实现 | 解码与损失计算 |
models/ner_model.py | 模型选型入口 | 切换softmax/crf |
processors/dataset.py | 数据读取与缓存 | 预处理 |
processors/processor.py | 特征构造与标签映射 | 预处理 |
processors/trie_tree.py | 词典匹配 | 词汇融合 |
processors/vocab.py | 词表与id映射 | 特征层 |
metrics/ner_metrics.py | F1计算 | 评估 |
train.py | 训练主程序 | 训练 |
losses/focal_loss.py | Focal损失 | 文本不平衡时 |
3. 训练流程复现：从数据处理器到CRF解码
3.1 数据预处理链路
拿到资源后，先不要急着跑train.py。项目的数据存放在datasets/ner_data.zip里，解压后是四个数据集的原始标注文件。processor.py会做以下事情：读取原始文本、按空格或标点切分为句子、给每个字符打上BIO标签、构建(input_ids, attention_mask, token_type_ids, label_ids)四元组。值得注意的是，这个项目不是把所有数据一次性加载到内存，而是用dataset.py里的load_and_cache_examples做成缓存文件，所以第一次运行会较慢，后面再训练就直接读缓存。
下面是我在实际复现时常用的数据检查命令，用来确认标签分布是否合理：
python -c " from processors.processor import load_dataset train = load_dataset('data/msra', split='train') from collections import Counter c = Counter() for _, labels in train: c.update(labels) print(c.most_common(10)) "这段命令会输出MSRA训练集中出现最多的10个标签。正常结果应该是O压倒性多，实体类标签中B-PER、I-PER这类出现次数随数据集风格变化。如果B-PER和I-PER数量相差过大，说明数据截断或者标注不一致；如果O占比超过90%，就要注意Focal Loss和类别权重设置，否则模型会倾向把所有词都预测成O。
3.2 训练启动与参数说明
train.py接收命令行参数，script/train.sh里已经写好了四组实验的启动方式。以LEBERT-CRF在MSRA上的训练为例，我习惯这样组织命令：
python train.py \ --model_name lebert_crf \ --dataset msra \ --bert_model pretrained/bert-base-chinese \ --dict_path data/lexicon/msra_words.txt \ --max_seq_len 128 \ --batch_size 32 \ --learning_rate 3e-5 \ --num_epochs 8 \ --crf \ --use_lexicon参数含义拆开看：--model_name决定模型入口走ner_model.py里的哪个分支；--crf开启CRF层，不加就是用Softmax；--use_lexicon是LEBERT与BERT实验的唯一差异，如果关掉，就退化成普通BERT-CRF；--dict_path指向外部词典文件，每行一个词，编码格式要求UTF-8，注意词典里不要带词性标注。--max_seq_len对中文数据集比较关键，Resume短句多，128足够；MSRA有些长实体跨句子，调到256会提升一点，但显存占用会翻倍。
训练过程中日志会打印当前的loss和验证集F1。这里有个容易踩的坑：metrics/ner_metrics.py里的F1计算用了字符级的BIO匹配，如果你的预测结果里出现了“B-PER后面直接跟B-PER”这种不合法骨架，CRF层会强制纠正，但Softmax不会。所以对比实验中，BERT-Softmax通常会观察到更高的标签级错误率。我一般会在训练脚本里同时输出错误样本的前十个，用output/{dataset}/bad_cases.txt保存。
3.3 损失函数与类别不均衡
losses/目录下有三个文件：__init__.py、label_smoothing.py、focal_loss.py。默认的训练损失是CrossEntropyLoss，但项目提供这两个备选，说明作者考虑到了NER数据的长尾问题。Focal Loss主要解决实体类别样本数远少于O类时模型变成“全O党”的问题。它的参数gamma和alpha可以调整，我复现时常用gamma=2.0、alpha=0.75。
# focal_loss.py 关键逻辑 class FocalLoss(nn.Module): def __init__(self, gamma=2.0, alpha=0.75): super().__init__() self.gamma = gamma self.alpha = alpha def forward(self, logits, targets): ce_loss = F.cross_entropy(logits, targets, reduction='none') pt = torch.exp(-ce_loss) focal_loss = self.alpha * ((1 - pt) ** self.gamma) * ce_loss return focal_loss.mean()这里的pt是模型对正确标签的置信度。难样本的pt小，(1 - pt)^gamma就大，相当于给难样本加权。alpha用于调整正负样本比例，如果实体占比低于10%，建议alpha设到0.7以上。要注意的是，Focal Loss和CRF并不冲突——CRF是解码层，损失函数是预测分布之上的度量。在源码里，crf.py已经自己实现了负对数似然损失，所以你没法简单把Focal Loss用到CRF输出上。我通常的做法是：LEBERT-Softmax配Focal Loss来做难例分析，LEBERT-CRF仍然用CRF自带损失，两者结果分开报告，这样实验逻辑更清晰。
4. Resume/OntoNotes/MSRA/Weibo实测对比与F1曲线解读
4.1 四个数据集的差异与实验配置
资源里的output目录按数据集分子目录，每个数据集下都有四个实验子目录：lebert-crf、bert-softmax、bert-crf、lebert-softmax。这说明作者对四个数据集分别跑了四组配置。从文件命名可以还原出实验设计：统一用BERT-base做底座，外部词典来自各数据集自带词典或人工构造。Resume是简历实体，人物/学校/公司等类别边界清晰；OntoNotes有比较严格的嵌套实体标注规则；MSRA是新闻语料，机构名和地名经常交错；Weibo是短文本，口语化严重且实体密度低。
在复现时，我建议不要直接把这四个数据集的结果放在一起比F1绝对值大小，因为它们实体标签体系不同。对比时只看同一数据集内部lebert相对bert的提升幅度。下表是我整理的实验组划分思路，对应output目录结构：
| 数据集 | 词汇表来源 | 基线组 | 词汇融合组 |
|---|---|---|---|
| Resume | 官方附带词典 | bert-softmax, bert-crf | lebert-softmax, lebert-crf |
| OntoNotes | 词表文件lexicon/ontonote.txt | bert-softmax, bert-crf | lebert-softmax, lebert-crf |
| MSRA | 词表文件lexicon/msra.txt | bert-softmax, bert-crf | lebert-softmax, lebert-crf |
| 词表文件lexicon/weibo.txt | bert-softmax, bert-crf | lebert-softmax, lebert-crf |
4.2 曲线图与实际数字的对应关系
资源根目录下的ontonote-f1.jpg、weibo-f1.jpg、f1.jpg、msra-f1.jpg、resume-f1.jpg是训练过程中的验证集F1曲线。这些图里面通常有四条线：BERT-Softmax、BERT-CRF、LEBERT-Softmax、LEBERT-CRF。看图时不要只看终值，要看曲线收敛速度。词汇融合带来的直观变化是前几个epoch里F1爬升更快，尤其是在MSRA这种长实体多的数据集上，LEBERT在第二个epoch就能超过BERT-CRF在第七个epoch的水平。
要精确量化提升，最好把train.py日志里的F1重新计算一遍。我的做法是写一个汇总脚本，把output目录下的test_result.txt或eval_results.txt解析出来：
# 解析输出目录下的F1结果 import json, os, glob for path in glob.glob('output/*/*/eval_results.json'): dataset, _ = path.split('/')[1], path.split('/')[2] with open(path) as f: data = json.load(f) model_name = data['model_name'] f1 = data['f1'] print(f"{dataset:12s} {model_name:15s} F1={f1:.4f}")这段脚本假设每个实验目录下有eval_results.json。如果资源里没有这个文件，你可以从train.py的日志里抓取，使用正则表达式匹配"F1 = 0.xxxx"。注意模型在训练过程中的验证集F1和测试集F1不是一回事，train.py默认每epoch做一次验证，最终报告的是在测试集上的一次前向结果。所以你要在日志中区分是哪个阶段的值。
4.3 一个反直觉结论：CRF不一定总赢
很多初学者以为“CRF一定比Softmax好”，但这批对比实验里可以观察到：在Weibo数据集上，LEBERT-Softmax甚至可能接近LEBERT-CRF。原因是Weibo短文本、实体碎片化，转移约束带来的收益被数据稀疏性抵消。真正稳定的提升来自词汇融合，而不是CRF层。如果你只对比BERT-CRF和LEBERT-CRF，会误以为CRF是主要功臣。所以分析时要把“模型架构差异”和“是否使用词汇融合”拆成两个维度。复现时建议跑一个2×2矩阵：Softmax/CRF × BERT/LEBERT，这样能从四个实验点分离出各自的净贡献。
5. 词汇表构建与Trie树优化：复现之外的工程技巧
5.1 词典质量比模型结构更影响F1
LEBERT的上限由外部词汇表决定。项目自带的词典能支撑现有实验，但换到自己业务数据时，词汇表构建就是新的坑。常见做法是收集业务语料中的实体词典、热词榜单、领域术语表，合并成一列一行一个词的文件。需要注意，词典里不要包含单字词（比如“人”），否则Trie树会把大量无意义的单字词注入注意力，增加噪声。我用一个过滤脚本处理：
# 过滤掉单字词和纯数字词 awk 'length($0) >= 2 && $0 !~ /^[0-9]+$/' raw_lexicon.txt > filtered_lexicon.txt词表总数量建议控制在2万到10万之间。太少，词汇融合层学不到东西；太多，Trie树匹配时间暴涨，且许多低频词会导致注意力权重稀疏。如果词表很大，可以在trie_tree.py里加一个最小词频阈值，或者限定最长词长度（比如不超过8个汉字），加速构建。
5.2 用前缀词典加速匹配
项目原始Trie树是逐字匹配，每个句子都要从头遍历，长文档上速度较慢。一个工程优化点是在Trie树的每个节点上标记is_word和max_child_len，匹配时提前剪枝。另一个更简单的做法是先把句子按字符转成id，用固定窗口滑动查词典：
# 窗口滑动匹配词典，返回 (start, end, word) 三重词 def match_window(tokens, word2ids, max_len): n = len(tokens) for start in range(n): for end in range(start + 1, min(start + max_len + 1, n + 1)): word = ''.join(tokens[start:end]) if word in word2ids: yield start, end, word这个方法的复杂度是O(n * max_len)，适合max_len取4～6的场景。但需要把词典预计算成word2ids字典，内存占用比Trie树高。你可以在小数据集上对比一下两种匹配方式的速度和内存，再决定部署方案。
5.3 最后验证：检查融合层是否真的生效
训练结束后，有一个技巧可以验证词汇融合是否真的起到了作用：关掉--use_lexicon参数，重新加载训练好的LEBERT模型进行推理，观察F1下降幅度。如果下降很小，说明训练过程没有学到词汇敏感信息，多半是Trie匹配的word embedding没有梯度流入——检查lebert.py里word_proj是否别detach了。另一个验证方法是打印某一条样本的注意力权重，查看含有实体词的位置是否有更高的权重。用model.attn的输出做PCA降维画图，也可以直观看到字向量在词汇融合后的分布变化。
如果你只是想快速复现结论，建议严格按照script/train.sh里的顺序：先跑BERT-Softmax作为下限，再跑LEBERT-CRF作为上限，中间两个模型确认词汇融合和CRF各自的作用。跑完一组后手动修改随机种子再跑一遍，因为小数据集上F1波动有可能达到1个点以上。
本文还有配套的精品资源，点击获取
