伯克利神经依存句法分析器

一款高精度的句法分析器，支持11种语言，使用Python实现。该工具基于2018年ACL会议论文《基于自注意力编码器的成分句法分析》（arXiv:1805.01052），并结合了多语言成分句法分析：自注意力与预训练中提出的改进方法。

2021年2月更新： 伯克利神经依存句法分析器现已发布0.2.0版本，所有语言的预训练模型质量均有所提升。推理阶段现采用PyTorch框架，而训练始终仅支持PyTorch。本版本不再支持Python 2.7和3.5。同时新增对自定义训练和使用解析器的支持，并可根据用户选择的预训练模型进行配置。

目录

1. 安装
2. 使用
3. 可用模型
4. 训练
5. 实验复现
6. 引用
7. 致谢

如果您主要关注如何训练自己的句法分析模型，请直接跳转至本README中的训练部分。

安装

要安装该句法分析器，运行以下命令：

$ pip install benepar

注意：benepar 0.2.0是上一版本的重大升级，配备了全新且质量更高的解析模型。如果您暂不准备升级，可以将benepar版本固定为之前的0.1.3版本。

需要Python 3.6及以上版本以及PyTorch 1.6及以上版本。请参阅PyTorch官网，了解如何选择GPU版或CPU版；benepar会在PyTorch可用时自动使用GPU。

推荐的使用方式是将其与spaCy集成。若使用spaCy，您应为您的语言安装相应的spaCy模型。例如，对于英语，安装命令如下：

$ python -m spacy download en_core_web_md

spaCy模型仅用于分词和句子切分。如果不需要超出句法分析的语言特定分析，也可以不使用特定语言的模型，而改用仅执行分词和句子切分的多语言模型。此类模型于spaCy 3.0中新增，适用于英语、德语、韩语、波兰语和瑞典语（但不适用于中文，因为它似乎不支持中文分词）。

句法分析模型需单独下载，使用以下命令：

>>> import benepar
>>> benepar.download('benepar_en3')

完整模型列表请参见下方的可用模型部分。

使用

与spaCy结合使用（推荐）

推荐的使用方式是通过与spaCy的集成：

>>> import benepar, spacy
>>> nlp = spacy.load('en_core_web_md')
>>> if spacy.__version__.startswith('2'):
        nlp.add_pipe(benepar.BeneparComponent("benepar_en3"))
    else:
        nlp.add_pipe("benepar", config={"model": "benepar_en3"})
>>> doc = nlp("The time for action is now. It's never too late to do something.")
>>> sent = list(doc.sents)[0]
>>> print(sent._.parse_string)
(S (NP (NP (DT The) (NN time)) (PP (IN for) (NP (NN action)))) (VP (VBZ is) (ADVP (RB now))) (. .))
>>> sent._.labels
('S',)
>>> list(sent._.children)[0]
The time for action

由于spaCy并未提供官方的成分句法分析API，所有方法均通过扩展命名空间Span._和Token._访问。

以下是可用的扩展属性：

• Span._.labels：给定span的标签元组。当解析树中存在一元链时，一个span可能具有多个标签。
• Span._.parse_string：给定span的解析树字符串表示。
• Span._.constituents：按解析树的前序遍历迭代子构成的Span对象。
• Span._.parent：解析树中的父span。
• Span._.children：解析树中子span的迭代器。
• Token._.labels、Token._.parse_string、Token._.parent：这些行为与调用包含该token的长度为1的Span上的相应方法相同。

在非解析树中的span上调用这些方法会引发异常。可通过从句子级别（遍历doc.sents）或从单个Token对象开始遍历解析树来避免此类错误。

与NLTK结合使用

此外，还提供了NLTK接口，专为处理预分词的数据集和语料库设计，或者在已具备分词和句子切分功能的NLP流水线中集成解析器时使用。对于从原始文本开始的解析任务，强烈建议使用spaCy和benepar.BeneparComponent。

NLTK的使用示例：

>>> import benepar
>>> parser = benepar.Parser("benepar_en3")
>>> input_sentence = benepar.InputSentence(
    words=['"', 'Fly', 'safely', '.', '"'],
    space_after=[False, True, False, False, False],
    tags=['``', 'VB', 'RB', '.', "''"],
    escaped_words=['``', 'Fly', 'safely', '.', "''"],
)
>>> tree = parser.parse(input_sentence)
>>> print(tree)
(TOP (S (`` ``) (VP (VB Fly) (ADVP (RB safely))) (. .) ('' '')))

并非benepar.InputSentence的所有字段都是必需的，但至少需要指定words或escaped_words之一。解析器会尝试猜测缺失字段的值，例如：

>>> input_sentence = benepar.InputSentence(
    words=['"', 'Fly', 'safely', '.', '"'],
)
>>> parser.parse(input_sentence)

使用parse_sents可解析多条句子。

>>> input_sentence1 = benepar.InputSentence(
    words=['The', 'time', 'for', 'action', 'is', 'now', '.'],
)
>>> input_sentence2 = benepar.InputSentence(
    words=['It', "'s", 'never', 'too', 'late', 'to', 'do', 'something', '.'],
)
>>> parser.parse_sents([input_sentence1, input_sentence2])

部分解析模型也支持Unicode文本输入，用于调试或交互式使用，但在任何对解析准确性有要求的应用场景中，强烈不建议直接传入原始文本字符串。

>>> parser.parse('"Fly safely."')  # 仅用于调试/交互式使用。

从原始文本进行解析时，我们仍推荐使用spaCy和benepar.BeneparComponent。原因是解析模型本身并不自带分词器或句子切分器，某些模型甚至可能没有词性标注器。因此必须借助其他工具来补充这些环节，而spaCy在这些方面的表现普遍优于NLTK，有时甚至差距显著。

可用模型

以下是可用的已训练解析器模型。要使用 spaCy 集成，您还需要安装适用于相应语言的 spaCy 模型。

模型	语言	信息
benepar_en3	英语	在修订版 WSJ 测试集上取得 95.40 的 F1 分数。训练数据采用了基于与 English Web Treebank 和 OntoNotes 相同指南的修订版分词和句法标注，这更符合 spaCy 等库中的现代分词实践。基于 T5-small。
benepar_en3_large	英语	在修订版 WSJ 测试集上取得 96.29 的 F1 分数。训练数据采用了基于与 English Web Treebank 和 OntoNotes 相同指南的修订版分词和句法标注，这更符合 spaCy 等库中的现代分词实践。基于 T5-large。
benepar_zh2	中文	在 CTB 5.1 测试集上取得 92.56 的 F1 分数。与 spaCy 一起使用时，支持从原始文本进行解析，但 NLTK API 仅支持对已分词句子进行解析。基于 Chinese ELECTRA-180G-large。
benepar_ar2	阿拉伯语	在 SPMRL2013/2014 测试集上取得 90.52 的 F1 分数。仅支持使用 NLTK API 对已分词句子进行解析。不支持从原始文本解析或与 spaCy 集成。基于 XLM-R。
benepar_de2	德语	在 SPMRL2013/2014 测试集上取得 92.10 的 F1 分数。基于 XLM-R。
benepar_eu2	巴斯克语	在 SPMRL2013/2014 测试集上取得 93.36 的 F1 分数。与 spaCy 一起使用时，首先需要在 spaCy 中实现巴斯克语支持。基于 XLM-R。
benepar_fr2	法语	在 SPMRL2013/2014 测试集上取得 88.43 的 F1 分数。基于 XLM-R。
benepar_he2	希伯来语	在 SPMRL2013/2014 测试集上取得 93.98 的 F1 分数。仅支持使用 NLTK API 对已分词句子进行解析。不支持从原始文本解析或与 spaCy 集成。基于 XLM-R。
benepar_hu2	匈牙利语	在 SPMRL2013/2014 测试集上取得 96.19 的 F1 分数。与 spaCy 一起使用时，需要一个匈牙利语 spaCy 模型。NLTK API 仅支持对已分词句子进行解析。基于 XLM-R。
benepar_ko2	韩语	在 SPMRL2013/2014 测试集上取得 91.72 的 F1 分数。可与 spaCy 的多语言句子分割模型一起使用（需 spaCy v3.0）。NLTK API 仅支持对已分词句子进行解析。基于 XLM-R。
benepar_pl2	波兰语	在 SPMRL2013/2014 测试集上取得 97.15 的 F1 分数。基于 XLM-R。
benepar_sv2	瑞典语	在 SPMRL2013/2014 测试集上取得 92.21 的 F1 分数。可与 spaCy 的多语言句子分割模型一起使用（需 spaCy v3.0）。基于 XLM-R。
benepar_en3_wsj	英语	建议改用 benepar_en3 或 benepar_en3_large。在用于数十年英语短语结构解析研究的标准版 WSJ 测试集上取得 95.55 的 F1 分数。基于 BERT-large-uncased。我们认为，用于训练 benepar_en3/benepar_en3_large 的修订版标注指南更适合下游应用，因为它们更能处理网络文本中的语言使用，并且与现代依存句法分析及 spaCy 等库的做法更加一致。尽管如此，我们仍提供 benepar_en3_wsj 模型，以备在不适合采用修订版树库规范的情况下使用，例如在同一数据集上比较不同模型的表现。

训练

训练需要从 GitHub 克隆本仓库。虽然 src/benepar 中的模型代码已发布在 PyPI 上的 benepar 包中，但直接位于 src/ 下的训练和评估脚本并未包含在内。

训练所需的软件

• Python 3.7 或更高版本。
• PyTorch 1.6.0 或任何兼容版本。
• benepar 包所需的所有依赖项，包括：NLTK 3.2、torch-struct 0.4、transformers 4.3.0 或兼容版本。
• pytokenizations 0.7.2 或兼容版本。
• EVALB。开始前，请在 EVALB/ 目录下运行 make 编译出 evalb 可执行文件。该文件将在 Python 中调用以进行评估。若在 SPMRL 数据集上训练，则需在 EVALB_SPMRL/ 目录下运行 make。

训练说明

可以使用命令 python src/main.py train ... 来训练新模型。可用的参数包括：

参数	描述	默认值
--model-path-base	用于保存模型的基础路径	无
--evalb-dir	EVALB 目录的路径	EVALB/
--train-path	训练树文件的路径	data/wsj/train_02-21.LDC99T42
--train-path-text	训练数据的可选非破坏性分词	根据原始文本猜测；参见 --text-processing
--dev-path	开发集树文件的路径	data/wsj/dev_22.LDC99T42
--dev-path-text	开发集数据的可选非破坏性分词	根据原始文本猜测；参见 --text-processing
--text-processing	从非破坏性分词的树文件中推断原始文本的启发式方法。参见 src/treebanks.py 中的 load_trees()	非阿拉伯语、汉语和希伯来语语言的默认规则
--subbatch-max-tokens	训练时并行处理的最大词数（完整批次可能无法放入 GPU 内存）	2000
--parallelize	将预训练模型（如 T5）的层分布到多个 GPU 上。	最多使用一个 GPU
--batch-size	每次训练更新的样本数量	32
--checks-per-epoch	每个 epoch 的开发集评估次数	4
--numpy-seed	NumPy 随机种子	随机
--use-pretrained	使用预训练编码器	不使用预训练编码器
--pretrained-model	如果指定了 --use-pretrained，则使用的模型。可以是路径或 HuggingFace Model Hub 中的模型 ID	bert-base-uncased
--predict-tags	向解析器添加词性标注组件及辅助损失	不预测词性标签
--use-chars-lstm	使用学习到的 CharLSTM 词表示	不使用 CharLSTM
--use-encoder	在预训练模型或 CharLSTM 之上使用学习到的 Transformer 层	不使用额外的 Transformer 层
--num-layers	如果指定了 --use-encoder，则使用的 Transformer 层数量	8
--encoder-max-len	允许额外 Transformer 层处理的最大句子长度（以词为单位）	512

其他超参数也有相应的参数可供使用，详见 src/main.py 中的 make_hparams()。这些参数可以在命令行中指定，例如 --num-layers 2（数值型参数）、--predict-tags（默认为 False 的布尔型参数），或 --no-XXX（默认为 True 的布尔型参数）。

每次开发集评估时，都会计算开发集上的 F 分数，并与之前的最佳结果进行比较。如果当前模型更好，则会删除之前的模型并保存当前模型。新文件名将基于提供的模型路径基础和开发集 F 分数生成。

在训练解析器之前，您需要先获取合适的训练数据。我们提供了关于如何处理 PTB、CTB 以及 SMPRL 2013/2014 共享任务数据等标准数据集的说明。按照英语 WSJ 数据的说明操作后，您可以使用以下命令，以默认超参数训练一个英语解析器：

python src/main.py train --use-pretrained --model-path-base models/en_bert_base

更多良好的超参数选择示例，请参阅 EXPERIMENTS.md。

评估说明

可以使用命令 python src/main.py test ... 对已保存的模型进行测试集评估，参数如下：

参数	描述	默认值
--model-path	已保存模型的路径	无
--evalb-dir	EVALB 目录的路径	EVALB/
--test-path	测试树文件的路径	data/23.auto.clean
--test-path-text	测试数据的可选非破坏性分词	根据原始文本猜测；参见 --text-processing
--text-processing	从非破坏性分词的树文件中推断原始文本的启发式方法。参见 src/treebanks.py 中的 load_trees()	非阿拉伯语、汉语和希伯来语语言的默认规则
--test-path-raw	仅用于 EVALB 的测试树文件替代路径（用于双重检查对预处理树的评估是否包含任何错误）	与 --test-path 中的树进行对比
--subbatch-max-tokens	并行处理的最大词数（GPU 内存不足以一次性处理整个数据集）	500
--parallelize	将预训练模型（如 T5）的层分布到多个 GPU 上。	最多使用一个 GPU
--output-path	用于写入预测树的路径（使用 "-" 表示输出到标准输出）。	不保存预测树
--no-predict-tags	运行 EVALB 时使用金标准词性标签。这是发表论文的标准做法，省略此标志可能会导致 F1 分数虚高。	如果有可用的预测词性标签，则在 EVALB 中使用预测标签

例如，您可以使用以下命令评估已训练好的模型：

python src/main.py test --model-path models/en_bert_base_dev=*.pt

导出模型用于推理

benepar 包可以直接使用保存的检查点文件，只需将模型名称（如 benepar_en3）替换为路径（如 models/en_bert_base_dev_dev=95.67.pt）。然而，发布单文件检查点存在一些不足：

• 单文件检查点不包含分词器或预训练模型配置。这些通常可以从 HuggingFace 模型库自动下载，但需要互联网连接，并且可能会（无意中且不必要的）从 HuggingFace 模型库下载预训练权重。
• 单文件检查点比实际需要大三倍，因为它们还保存了优化器状态。

可以使用 src/export.py 脚本将检查点文件转换为一个包含训练好的模型所有信息的目录。例如：

python src/export.py export \
  --model-path models/en_bert_base_dev=*.pt \
  --output-dir=models/en_bert_base

在导出时，还有一个 --compress 选项，它会轻微调整模型权重，以便将输出目录压缩成一个体积小得多的 ZIP 压缩包。我们在官方模型发布中会使用此选项，因为分发大小超过 2GB 的模型权重非常麻烦。使用 --compress 选项时，建议指定一个测试集，以验证压缩对解析准确率的影响确实很小。不建议使用开发数据进行验证，因为在训练过程中，开发数据已经被用作模型选择的标准。

python src/export.py export \
  --model-path models/en_bert_base_dev=*.pt \
  --output-dir=models/en_bert_base \
  --test-path=data/wsj/test_23.LDC99T42

src/export.py 脚本还有一个 test 子命令，与 python src/main.py test 大致相同，只是它支持已导出的模型，并且标志略有不同。我们可以运行以下命令来验证我们使用的 BERT-large-uncased 英语句法分析器确实在标准 WSJ 测试集上达到了 95.55 的 F1 分数：

python src/export.py test --model-path benepar_en3_wsj --test-path data/wsj/test_23.LDC99T42

重现实验

请参阅 EXPERIMENTS.md，了解如何重现我们发表在 ACL 2018 和 2019 年论文中的实验。

引用

如果您将本软件用于研究，请按如下方式引用我们的论文：

@inproceedings{kitaev-etal-2019-multilingual,
    title = "多语言句法分析：基于自注意力机制与预训练的方法",
    author = "Kitaev, Nikita  and
      Cao, Steven  and
      Klein, Dan",
    booktitle = "第57届计算语言学协会年会论文集",
    month = jul,
    year = "2019",
    address = "意大利佛罗伦萨",
    publisher = "计算语言学协会",
    url = "https://www.aclweb.org/anthology/P19-1340",
    doi = "10.18653/v1/P19-1340",
    pages = "3499--3505",
}

@inproceedings{kitaev-klein-2018-constituency,
    title = "基于自注意力编码器的句法分析",
    author = "Kitaev, Nikita  and
      Klein, Dan",
    booktitle = "第56届计算语言学协会年会论文集（第一卷：长文）",
    month = jul,
    year = "2018",
    address = "澳大利亚墨尔本",
    publisher = "计算语言学协会",
    url = "https://www.aclweb.org/anthology/P18-1249",
    doi = "10.18653/v1/P18-1249",
    pages = "2676--2686",
}

致谢

本仓库中的代码以及本 README 的部分内容基于 https://github.com/mitchellstern/minimal-span-parser。

self-attentive-parser (Berkeley Neural Parser) 快速上手指南

self-attentive-parser (包名：benepar) 是一个基于自注意力机制的高精度成分句法分析器，支持包括中文在内的 11 种语言。本指南将帮助你快速在 Python 环境中部署并使用该工具。

1. 环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.6 或更高（训练建议 3.7+）
• 核心依赖：
  • PyTorch 1.6 或更高版本
  • spaCy (推荐用于分词和句子分割)
• 硬件加速：如果系统可用 GPU，benepar 会自动利用 PyTorch 进行加速。

提示：国内用户安装 PyTorch 时，建议访问 PyTorch 官网 获取针对国内网络优化的安装命令，或使用清华/中科大镜像源。

2. 安装步骤

2.1 安装主程序包

使用 pip 安装 benepar：

pip install benepar

2.2 安装 spaCy 及语言模型

推荐使用 spaCy 进行预处理（分词和断句）。以英语为例，安装命令如下：

python -m spacy download en_core_web_md

中文用户注意： 若需处理中文文本，请安装对应的 spaCy 中文模型（例如 zh_core_web_sm 或 zh_core_web_md）：

python -m spacy download zh_core_web_md

注：部分语言（如阿拉伯语、希伯来语）的模型暂不支持直接从原始文本解析，仅支持通过 NLTK 接口处理已分词数据。

2.3 下载预训练解析模型

解析模型需要单独下载。根据目标语言选择对应的模型名称（见下文“可用模型”），并在 Python 中执行下载：

import benepar
# 示例：下载英语模型 benepar_en3
benepar.download('benepar_en3')

# 示例：下载中文模型 benepar_zh2
# benepar.download('benepar_zh2')

3. 基本使用

最推荐的方式是通过 spaCy 集成 使用，它可以自动处理分词和句子边界检测。

3.1 基于 spaCy 的使用示例

import benepar
import spacy

# 1. 加载 spaCy 语言模型 (此处以英语为例，中文请替换为 'zh_core_web_md')
nlp = spacy.load('en_core_web_md')

# 2. 添加 benepar 组件
# spaCy v3.x+ 写法
nlp.add_pipe("benepar", config={"model": "benepar_en3"})
# 如果是 spaCy v2.x，请使用: nlp.add_pipe(benepar.BeneparComponent("benepar_en3"))

# 3. 处理文本
doc = nlp("The time for action is now. It's never too late to do something.")

# 4. 获取第一句话的分析结果
sent = list(doc.sents)[0]

# 打印成分句法树字符串
print(sent._.parse_string)
# 输出示例: (S (NP (NP (DT The) (NN time)) ...) ...)

# 获取当前 Span 的标签
print(sent._.labels)
# 输出: ('S',)

# 遍历子成分
for child in sent._.children:
    print(child.text, "->", child._.labels)

3.2 基于 NLTK 的使用示例（仅限已分词数据）

如果你已有分好词的数据集，或需要更底层的控制，可以使用 NLTK 接口：

import benepar

# 初始化解析器
parser = benepar.Parser("benepar_en3")

# 构建输入句子对象 (至少提供 words 列表)
input_sentence = benepar.InputSentence(
    words=['"', 'Fly', 'safely', '.', '"'],
    tags=['``', 'VB', 'RB', '.', "''"], # 可选：提供词性标注以提高准确率
)

# 执行解析
tree = parser.parse(input_sentence)
print(tree)
# 输出: (TOP (S (`` ``) (VP (VB Fly) (ADVP (RB safely))) (. .) ('' '')))

附：常用预训练模型列表

模型名称	语言	说明
benepar_en3	英语	推荐默认模型，基于 T5-small，F1 95.40
benepar_en3_large	英语	高精度模型，基于 T5-large，F1 96.29
benepar_zh2	中文	基于 Chinese ELECTRA，F1 92.56，支持 spaCy 原始文本解析
benepar_de2	德语	基于 XLM-R
benepar_fr2	法语	基于 XLM-R
benepar_ko2	韩语	基于 XLM-R
benepar_pl2	波兰语	基于 XLM-R，F1 97.15

完整模型列表请参考官方文档。对于中文开发者优先推荐使用 benepar_zh2。