NCRF++：开源神经序列标注工具包

• 1. 简介
• 2. 需求
• 3. 优势
• 4. 使用方法
• 5. 数据格式
• 6. 性能
• 7. 添加手工特征
• 8. 速度
• 9. N-best 解码
• 10. 复现论文结果与超参数调优
• 11. 报告问题或错误
• 12. 引用
• 13. 未来计划
• 13. 更新

简介

序列标注模型在许多自然语言处理任务中非常流行，例如命名实体识别（NER）、词性标注（POS）和分词等。当前最先进的序列标注模型大多采用带有输入词特征的CRF结构。LSTM（或双向LSTM）是序列标注任务中一种流行的基于深度学习的特征提取器。此外，由于计算速度更快，CNN也可以被使用。除此之外，单词内部的特征对于表示单词也很有用，这些特征可以通过字符级LSTM、字符级CNN结构或者人工定义的神经网络特征来捕捉。

NCRF++是一个基于PyTorch的框架，提供了灵活的输入特征和输出结构选择。使用NCRF++设计神经序列标注模型时，所有配置都可以通过一个配置文件完成，无需编写任何代码。NCRF++可以被视为CRF++的神经网络版本，而CRF++是一个著名的统计CRF框架。

该框架已被ACL 2018接受为演示论文。同时，使用NCRF++进行的详细实验报告和分析也被COLING 2018接受为最佳论文。

NCRF++支持在三个层次上对不同结构进行组合：字符序列表示、词序列表示和推理层。

• 字符序列表示：字符LSTM、字符GRU、字符CNN以及手工制作的词特征。
• 词序列表示：词LSTM、词GRU、词CNN。
• 推理层：Softmax、CRF。

欢迎给本仓库点个赞！

需求

Python: 2 或 3  
PyTorch: 1.0 

兼容PyTorch 0.3的版本请见这里。

优势

• 完全可配置：所有神经网络结构均可通过配置文件设置。
• 最先进的系统性能：基于NCRF++构建的模型能够达到与当前最先进模型相当甚至更好的效果。
• 特征灵活：用户可以自定义特征及预训练的特征嵌入。
• 运行速度快：NCRF++采用完全批处理操作，在GPU的帮助下系统效率极高（训练速度超过1000句/秒，解码速度超过2000句/秒）。
• N-best 输出：NCRF++支持nbest解码（并附带相应的概率）。

使用方法

NCRF++支持通过配置文件设计神经网络结构。程序有两种运行模式：训练和解码。（本仓库已包含示例配置和数据）

在训练模式下： python main.py --config demo.train.config

在解码模式下： python main.py --config demo.decode.config

配置文件控制着网络结构、输入输出、训练设置以及超参数。

详细配置及说明请参阅此处。

NCRF++的设计分为三层（如下所示）：字符序列层、词序列层和推理层。借助配置文件，大多数最先进的模型都可以轻松复现，且无需编写代码。另一方面，用户也可以通过设计自己的模块来扩展每一层（例如，他们可能希望设计除CNN/LSTM/GRU之外的其他神经网络结构）。我们分层的设计使得模块扩展变得十分方便，模块扩展的说明请参阅此处。

数据格式

• 您可以参考sample_data中的数据格式。
• NCRF++支持BIO和BIOES(BMES)两种标签体系。
• 请注意，IOB格式（与BIO不同）目前不被支持，因为这种标签体系较为老旧，且表现不如其他体系好Reimers and Gurevych, 2017。
• 这三种标签体系之间的区别已在该论文中解释过。
• 我编写了一个脚本，用于在IOB/BIO/BIOES之间转换标签体系。欢迎大家试用。

性能

在CONLL 2003英语NER任务上的结果与具有相同结构的SOTA结果相比，要么更好，要么相当。

CharLSTM+WordLSTM+CRF：91.20 vs 90.94，出自Lample .etc, NAACL16；

CharCNN+WordLSTM+CRF：91.35 vs 91.21，出自Ma .etc, ACL16。

默认情况下，LSTM为双向LSTM。

编号	模型	无字符特征	CharLSTM	CharCNN
1	WordLSTM	88.57	90.84	90.73
2	WordLSTM+CRF	89.45	91.20	91.35
3	WordCNN	88.56	90.46	90.30
4	WordCNN+CRF	88.90	90.70	90.43

我们在统计实验条件下，对十二种神经序列标注模型（{charLSTM, charCNN, 无} x {wordLSTM, wordCNN} x {softmax, CRF}）在三个基准数据集（POS、Chunking、NER）上进行了比较。详细结果及对比分析请参阅我们的COLING 2018论文《神经序列标注中的设计挑战与误解》Design Challenges and Misconceptions in Neural Sequence Labeling。

添加手工特征

NCRF++ 集成了几种当前最先进的神经网络字符序列特征提取器：CNN（Ma 等，ACL16）、LSTM（Lample 等，NAACL16）和 GRU（Yang 等，ICLR17）。此外，手工特征在序列标注任务中也被证明非常重要。NCRF++ 允许用户设计自己的特征，例如大小写、词性标签或其他任何特征（上图中的灰色圆圈）。用户可以通过配置文件来设置这些自定义特征（特征嵌入维度、预训练的特征嵌入等）。示例输入数据格式见 train.cappos.bmes，其中包含两个人工定义的特征 [POS] 和 [Cap]。（[POS] 和 [Cap] 只是示例，您可以为特征命名任意名称，只需遵循 [xx] 的格式，并在配置文件中使用相同的名称进行配置。） 用户可以在配置文件中通过以下方式配置每个特征：

feature=[POS] emb_size=20 emb_dir=%your_pretrained_POS_embedding
feature=[Cap] emb_size=20 emb_dir=%your_pretrained_Cap_embedding

未提供预训练嵌入的特征将被随机初始化。

速度

NCRF++ 使用完全批处理计算实现，因此在模型训练和解码方面都非常高效。借助 GPU（Nvidia GTX 1080）和较大的批量大小，使用 NCRF++ 构建的 LSTMCRF 模型在训练和解码时分别可以达到 1000 句子/秒和 2000 句子/秒的速度。

N 最优解码

传统的 CRF 结构只解码概率最大的一条标签序列（即 1-best 输出）。而 NCRF++ 则可以提供多种选择，解码出前 n 个概率最高的标签序列（即 n-best 输出）。这种 n-best 解码功能已经被一些流行的 统计 CRF 框架所支持。然而，据我们所知，NCRF++ 是首个也是唯一一个支持 神经 CRF 模型 n-best 解码的工具包。

在我们的实现中，当 nbest=10 时，基于 NCRF++ 构建的 CharCNN+WordLSTM+CRF 模型在 CoNLL 2003 NER 任务上可以获得 97.47% 的 oracle F1 值（nbest=1 时 F1=91.35%）。

复现论文结果与超参数调优

要复现我们 COLING 2018 论文中的结果，您只需将配置文件 demo.train.config 中的 iteration=1 改为 iteration=100，并在该配置文件中配置好您的文件目录即可。默认配置文件描述的是 Char CNN + Word LSTM + CRF 模型，您可以通过相应地修改配置来构建自己的模型。此演示配置文件中的参数与我们论文中的参数一致。（请注意，与 Word CNN 相关的模型需要略微不同的参数，详细信息请参阅我们的 COLING 论文。）

如果您想在新的任务或数据集上使用该框架，这里有一些由 @Victor0118 提供的 调优技巧。

报告问题或故障

如果您想报告问题或提出疑问，请在必要时附上以下材料。有了这些信息，我可以更快更准确地为您提供讨论和建议。

• 日志文件
• 配置文件
• 样本数据

引用

如果您在论文中使用了 NCRF++，请引用我们的 ACL 演示论文：

@inproceedings{yang2018ncrf,  
 title={NCRF++: 一个开源的神经序列标注工具包},  
 author={Yang, Jie and Zhang, Yue},  
 booktitle={第56届计算语言学协会年会论文集},
 Url = {http://aclweb.org/anthology/P18-4013},
 year={2018}  
}

如果您使用了 NCRF++ 的实验结果和分析，请引用我们的 COLING 论文：

@inproceedings{yang2018design,  
 title={神经序列标注中的设计挑战与误解},  
 author={Yang, Jie and Liang, Shuailong and Zhang, Yue},  
 booktitle={第27届国际计算语言学会议 (COLING) 论文集},
 Url = {http://aclweb.org/anthology/C18-1327},
 year={2018}  
}

未来计划

• 文档分类（正在进行中）
• 支持 API 使用
• 将训练好的模型上传至分词/词性标注/命名实体识别平台
• 启用加载预训练的 ELMo 参数功能
• 添加 BERT 特征提取层

更新

• 2018年12月17日，NCRF++ v0.2，支持 PyTorch 1.0
• 2018年3月30日，NCRF++ v0.1，初始版本
• 2018年1月6日，添加结果对比。
• 2018年1月2日，支持字符特征选择。
• 2017年12月6日，初始版本

NCRF++ 快速上手指南

NCRF++ 是一个基于 PyTorch 的开源神经序列标注工具包，支持命名实体识别（NER）、词性标注（POS）和分词等任务。它通过配置文件灵活定义模型结构（如 LSTM、CNN、CRF 等），无需修改代码即可复现主流模型。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux / macOS / Windows
• Python 版本：Python 2 或 Python 3
• 核心依赖：PyTorch 1.0 或更高版本
  • 注：如需使用旧版 PyTorch 0.3，请参考项目仓库中的 PyTorch0.3 分支。

建议先安装好 CUDA 驱动以利用 GPU 加速训练和解码过程。

安装步骤

1. 克隆项目仓库 将 NCRF++ 源码下载到本地：

   git clone https://github.com/jiesutd/NCRFpp.git
   cd NCRFpp
   

2. 安装 Python 依赖 确保已安装 PyTorch。如果尚未安装，推荐访问 PyTorch 官网 获取适合您环境的安装命令。若需国内加速，可使用清华源：

   pip install torch -i https://pypi.tuna.tsinghua.edu.cn/simple
   

   NCRF++ 本身主要依赖 PyTorch 和标准库，通常无需额外安装复杂的第三方包。如有其他依赖缺失，请根据报错提示安装。

基本使用

NCRF++ 的核心优势在于通过配置文件控制模型结构、超参数及数据路径。项目内置了示例数据和配置文件，可直接运行。

1. 训练模型 (Training)

使用默认的演示配置文件启动训练：

python main.py --config demo.train.config

• demo.train.config：定义了网络结构（默认为 CharCNN + WordLSTM + CRF）、学习率、迭代次数等参数。
• 训练过程中会生成模型文件并输出日志。

2. 模型解码/预测 (Decoding)

训练完成后，使用解码配置文件对测试数据进行预测：

python main.py --config demo.decode.config

• demo.decode.config：需指定训练好的模型路径和待预测的数据文件路径。

3. 自定义配置

您可以复制 demo.train.config 创建自己的配置文件，修改以下关键项以适应新任务：

• 网络结构：切换 Character/Word 层的提取器（LSTM, GRU, CNN）及推理层（Softmax, CRF）。
• 特征工程：添加人工特征（如大小写、词性标签等）。
• 数据路径：指向您的训练集、开发集和测试集。

详细的配置项说明请参阅项目目录下的 readme/Configuration.md。