✨NeuralCoref 4.0：使用神经网络在spaCy中进行共指消解。

NeuralCoref 是一个适用于 spaCy 2.1 及以上版本的管道扩展，它利用神经网络标注并解析共指聚类。NeuralCoref 已经可以用于生产环境，集成到 spaCy 的 NLP 管道中，并且可以扩展到新的训练数据集。

如需简要了解共指消解和 NeuralCoref，请参阅我们的 博客文章。

NeuralCoref 使用 Python/Cython 编写，附带一个针对 英语 的预训练统计模型。

NeuralCoref 配有一个可视化客户端 NeuralCoref-Viz，这是一个由 REST 服务器驱动的 Web 界面，您可以在 在线试用。NeuralCoref 采用 MIT 许可证发布。

✨ 版本 4.0 现已推出！可通过 pip 安装，并兼容 SpaCy 2.1 及以上版本。

• 操作系统: macOS / OS X · Linux · Windows (Cygwin, MinGW, Visual Studio)
• Python 版本: Python 3.6+（仅 64 位）
• 包管理器: [pip]

安装 NeuralCoref

使用 pip 安装 NeuralCoref

这是安装 NeuralCoref 最简单的方式。

pip install neuralcoref

spacy.strings.StringStore size changed 错误

如果您在使用 import neuralcoref 加载 NeuralCoref 时遇到 spacy.strings.StringStore size changed, may indicate binary incompatibility 的错误，这意味着您需要从源代码而非二进制包安装 NeuralCoref，以便使其与您系统上最新版本的 SpaCy 进行编译。

在这种情况下，只需按以下步骤重新安装：

pip uninstall neuralcoref
pip install neuralcoref --no-binary neuralcoref

安装 SpaCy 模型

要使用 NeuralCoref，您还需要一个 SpaCy 的英语模型。

您可以根据应用需求选择任何合适的英语模型，但请注意，NeuralCoref 的性能高度依赖于 SpaCy 模型的表现，尤其是其词性标注、句法分析和命名实体识别组件的性能。因此，使用更大的 SpaCy 英语模型将有助于提升共指消解的质量（详情请参阅下方的“内部机制与模型”部分）。

以下是如何安装 SpaCy 和一个小型英语模型的示例，更多信息请访问 SpaCy 官网：

pip install -U spacy
python -m spacy download en

从源码安装 NeuralCoref

您也可以从源码安装 NeuralCoref。首先需要安装依赖项，包括 Cython 和 SpaCy。

具体步骤如下：

venv .env
source .env/bin/activate
git clone https://github.com/huggingface/neuralcoref.git
cd neuralcoref
pip install -r requirements.txt
pip install -e .

内部机制与模型

NeuralCoref 由两个子模块组成：

• 基于规则的提及检测模块，它利用 SpaCy 的词性标注、句法分析和命名实体识别结果来识别潜在的共指提及；
• 一个前馈神经网络，用于为每对潜在提及计算共指得分。

首次在 Python 中导入 NeuralCoref 时，它会将神经网络模型的权重下载到缓存文件夹中。

默认情况下，缓存文件夹设置为 ~/.neuralcoref_cache（参见 file_utils.py），但您可以通过设置环境变量 NEURALCOREF_CACHE 来指定其他位置以覆盖此行为。

缓存文件夹可以随时安全删除，下次加载模块时会重新下载模型。

您可以通过在加载 NeuralCoref 之前激活 Python 的 logging 模块来获取有关内部模型位置、下载和缓存过程的更多信息，方法如下：

import logging;
logging.basicConfig(level=logging.INFO)
import neuralcoref
>>> INFO:neuralcoref:Getting model from https://s3.amazonaws.com/models.huggingface.co/neuralcoref/neuralcoref.tar.gz or cache
>>> INFO:neuralcoref.file_utils:https://s3.amazonaws.com/models.huggingface.co/neuralcoref/neuralcoref.tar.gz not found in cache, downloading to /var/folders/yx/cw8n_njx3js5jksyw_qlp8p00000gn/T/tmp_8y5_52m
100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 40155833/40155833 [00:06<00:00, 6679263.76B/s]
>>> INFO:neuralcoref.file_utils:copying /var/folders/yx/cw8n_njx3js5jksyw_qlp8p00000gn/T/tmp_8y5_52m to cache at /Users/thomaswolf/.neuralcoref_cache/f46bc05a4bfba2ae0d11ffd41c4777683fa78ed357dc04a23c67137abf675e14.7d6f9a6fecf5cf09e74b65f85c7d6896b21decadb2554d486474f63b95ec4633
>>> INFO:neuralcoref.file_utils:creating metadata file for /Users/thomaswolf/.neuralcoref_cache/f46bc05a4bfba2ae0d11ffd41c4777683fa78ed357dc04a23c67137abf675e14.7d6f9a6fecf5cf09e74b65f85c7d6896b21decadb2554d486474f63b95ec4633
>>> INFO:neuralcoref.file_utils:removing temp file /var/folders/yx/cw8n_njx3js5jksyw_qlp8p00000gn/T/tmp_8y5_52m
>>> INFO:neuralcoref:extracting archive file /Users/thomaswolf/.neuralcoref_cache/f46bc05a4bfba2ae0d11ffd41c4777683fa78ed357dc04a23c67137abf675e14.7d6f9a6fecf5cf09e74b65f85c7d6896b21decadb2554d486474f63b95ec4633 to dir /Users/thomaswolf/.neuralcoref_cache/neuralcoref

加载 NeuralCoref

将 NeuralCoref 添加到英语 SpaCy 语言模型的管道中

以下是实例化 NeuralCoref 并将其添加到 SpaCy 注释管道中的推荐方法：

# 加载您常用的 SpaCy 模型（任一 SpaCy 英语模型）
import spacy
nlp = spacy.load('en')

# 将 Neural Coref 添加到 SpaCy 的管道中
import neuralcoref
neuralcoref.add_to_pipe(nlp)

# 完成。现在您可以像操作 SpaCy 文档注释一样使用 Neural Coref。
doc = nlp(u'我姐姐有一只狗。她很喜欢它。')

doc._.has_coref
doc._.coref_clusters

手动加载 Neural Coref 并将其添加到英语 SpaCy 语言模型的管道中

另一种将 Neural Coref 添加到 SpaCy 模型管道的方法是先实例化 Neural Coref 类，然后手动将其添加到 SpaCy 语言模型的管道中。

# 加载您常用的 SpaCy 模型（任一 SpaCy 英语模型）
import spacy
nlp = spacy.load('en')

# 加载 NeuralCoref 并将其添加到 SpaCy 模型的管道中
import neuralcoref
coref = neuralcoref.NeuralCoref(nlp.vocab)
nlp.add_pipe(coref, name='neuralcoref')

# 完成！现在你可以像平常操作 SpaCy 文档及其标注一样使用 NeuralCoref。
doc = nlp(u'我姐姐有一只狗。她很喜欢它。')

doc._.has_coref
doc._.coref_clusters

使用 NeuralCoref

NeuralCoref 会解析共指关系，并将这些信息作为 扩展属性 注入到 SpaCy 的 Doc、Span 和 Token 对象中，存储在 ._. 字典下。

以下是所有标注的列表：

属性	类型	描述
doc._.has_coref	布尔值	文档中是否已解析出任何共指关系
doc._.coref_clusters	Cluster 列表	文档中所有共指提及的聚类
doc._.coref_resolved	Unicode	文档的 Unicode 表示，其中每个共指提及都被其所属聚类中的主要提及替换。
doc._.coref_scores	字典的字典	提及之间共指解析的得分。
span._.is_coref	布尔值	该 span 是否至少包含一个共指提及
span._.coref_cluster	Cluster	与该 span 共指的提及聚类
span._.coref_scores	字典	该 span 与其他提及（如果适用）之间的共指解析得分。
token._.in_coref	布尔值	该 token 是否位于至少一个共指提及内
token._.coref_clusters	Cluster 列表	包含该 token 的所有共指提及聚类

Cluster 是一组共指提及的聚类，具有 3 个属性和一些方法，用于简化对聚类内部的导航：

属性或方法	类型 / 返回类型	描述
i	整数	聚类在文档中的索引
main	Span	聚类中最具代表性的提及范围
mentions	Span 列表	聚类中所有提及的列表
__getitem__	返回 Span	访问聚类中的某个提及
__iter__	生成 Span	遍历聚类中的提及
__len__	返回整数	聚类中提及的数量

导航共指聚类链

你还可以轻松地导航共指聚类链，并展示聚类和提及。

以下是一些示例，请亲自尝试以测试效果。

import spacy
import neuralcoref
nlp = spacy.load('en')
neuralcoref.add_to_pipe(nlp)

doc = nlp(u'我姐姐有一只狗。她很喜欢它')

doc._.coref_clusters
doc._.coref_clusters[1].mentions
doc._.coref_clusters[1].mentions[-1]
doc._.coref_clusters[1].mentions[-1]._.coref_cluster.main

token = doc[-1]
token._.in_coref
token._.coref_clusters

span = doc[-1:]
span._.is_coref
span._.coref_cluster.main
span._.coref_cluster.main._.coref_cluster

重要提示：NeuralCoref 中的提及是 SpaCy 的 Span 对象，这意味着你可以访问所有常规的 Span 属性，例如 span.start（该 span 在文档中第一个 token 的索引）、span.end（该 span 后第一个 token 的索引）等。

示例：doc._.coref_clusters[1].mentions[-1].start 将给出文档中第二个共指聚类中最后一个提及的第一个 token 的索引。

参数

你可以向 neuralcoref.add_to_pipe 或 NeuralCoref() 传递多个额外参数来控制 NeuralCoref 的行为。

以下是这些参数及其说明的完整列表：

参数	类型	描述
greedyness	浮点数	一个介于 0 和 1 之间的数值，决定模型在做出共指决策时的“贪婪”程度（越贪婪，共指链接越多）。默认值为 0.5。
max_dist	整数	在考虑当前提及的可能先行词时，系统会回溯多少个提及。降低此值会使系统运行更快，但准确性会降低。默认值为 50。
max_dist_match	整数	如果当前提及与其前方超过 max_dist 距离的提及共享名词或专有名词，则系统会考虑将两者连接起来。此时，系统将搜索距离为 max_dist_match 的提及。默认值为 500。
blacklist	布尔值	系统是否应解析以下代词的共指关系：["i", "me", "my", "you", "your"]。默认值为 True（解析共指）。
store_scores	布尔值	系统是否应将共指得分存储在标注中。默认值为 True。
conv_dict	字典(str, list(str))	一个转换字典，可用于将 稀有词（键）的嵌入替换成一组 常见词（值）嵌入的平均值。例如：conv_dict={"Angela": ["woman", "girl"]} 将帮助通过使用更常见的 woman 和 girl 的嵌入来解析 Angela 的共指关系，而不是直接使用 Angela 的嵌入。目前此功能仅适用于单个单词，不适用于词组。

如何更改参数

import spacy
import neuralcoref

# 加载 SpaCy 模型
nlp = spacy.load('en')

# 控制参数的第一种方式
neuralcoref.add_to_pipe(nlp, greedyness=0.75)

# 控制参数的另一种方式
nlp.remove_pipe("neuralcoref")  # 移除当前的 NeuralCoref 实例
coref = neuralcoref.NeuralCoref(nlp.vocab, greedyness=0.75)
nlp.add_pipe(coref, name='neuralcoref')

使用转换字典参数帮助解析稀有词

以下是一个如何使用 conv_dict 参数来帮助解析像人名这样的稀有词共指关系的示例：

import spacy
import neuralcoref

nlp = spacy.load('en')

# 尝试在未使用转换字典之前：
neuralcoref.add_to_pipe(nlp)
doc = nlp(u'迪皮卡有一只狗。她很喜欢它。这位电影明星一直喜爱动物')
doc._.coref_clusters
doc._.coref_resolved
# >>> [迪皮卡: [迪皮卡、她、它、这位电影明星]]
# >>> '迪皮卡有一只狗。迪皮卡很喜欢迪皮卡。迪皮卡一直喜爱动物'
# >>> 效果并不理想...

# 以下是三种添加转换字典的方法
nlp.remove_pipe("neuralcoref")
neuralcoref.add_to_pipe(nlp, conv_dict={'迪皮卡': ['woman', 'actress']})

# 或者
nlp.remove_pipe("neuralcoref")
coref = neuralcoref.NeuralCoref(nlp.vocab, conv_dict={'Deepika': ['woman', 'actress']})
nlp.add_pipe(coref, name='neuralcoref')
# 或者在 NeuralCoref 已经加入 SpaCy 管道后，通过修改管道中的 NeuralCoref 组件来实现
nlp.get_pipe('neuralcoref').set_conv_dict({'Deepika': ['woman', 'actress']})

# 让我们再次尝试使用转换字典：
doc = nlp(u'迪皮卡有一只狗。她爱它。这位电影明星一直很喜欢动物')
doc._.coref_clusters
# >>> [迪皮卡: [迪皮卡, 她, 迪皮卡], 一只狗: [一只狗, 它]]
# >>> '迪皮卡有一只狗。迪皮卡爱那只狗。迪皮卡一直很喜欢动物'
# >>> 好多了！

将 NeuralCoref 用作服务器

一个将 NeuralCoref 集成到 REST API 中的简单服务器脚本示例，已作为示例提供在 examples/server.py 文件中。

要使用它，您需要先安装 falcon：

pip install falcon

然后您可以按如下方式启动服务器：

cd examples
python ./server.py

并以以下方式查询服务器：

curl --data-urlencode "text=我姐姐有一只狗。她爱它。" -G localhost:8000

管理与部署 NeuralCoref 的方式还有很多。一些示例可以在 spaCy Universe 中找到。

重新训练模型 / 扩展到其他语言

如果您想重新训练模型或将其训练于另一种语言，请参阅我们的训练说明，以及我们的博客文章。

NeuralCoref 快速上手指南

NeuralCoref 是一个基于神经网络的共指消解（Coreference Resolution）工具，作为 spaCy 的管道扩展组件运行。它能够识别文本中指代同一实体的不同提及（例如："My sister" 和 "She"），并将其聚类。该工具目前仅支持英语。

环境准备

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

• 操作系统：macOS / Linux / Windows (需安装 Cygwin, MinGW 或 Visual Studio)
• Python 版本：Python 3.6+ (仅支持 64 位)
• 前置依赖：
  • spaCy (版本 2.1+)
  • spaCy 英语模型 (如 en_core_web_sm 或更大模型，模型性能直接影响共指消解效果)

注意：共指消解的质量高度依赖于 spaCy 模型的词性标注器 (tagger)、句法分析器 (parser) 和命名实体识别 (NER) 组件的性能。建议至少使用中等规模的英语模型以获得更好效果。

安装步骤

1. 安装 spaCy 及英语模型

首先安装 spaCy 并下载英语模型。国内用户若遇网络问题，可配置国内镜像源（如清华源）。

# 使用 pip 安装 spacy (可选：指定国内镜像加速)
pip install -U spacy -i https://pypi.tuna.tsinghua.edu.cn/simple

# 下载 spaCy 英语模型 (推荐 en_core_web_md 或 en_core_web_lg)
python -m spacy download en_core_web_sm

2. 安装 NeuralCoref

方式 A：通过 pip 安装（推荐）

这是最简便的安装方式。

pip install neuralcoref

如果遇到二进制兼容性错误： 若在导入时出现 spacy.strings.StringStore size changed 错误，说明预编译包与当前 spaCy 版本不兼容。请卸载后从源码重新构建安装：

pip uninstall neuralcoref
pip install neuralcoref --no-binary neuralcoref

方式 B：从源码安装

如果您需要最新代码或进行开发调试：

# 创建虚拟环境
python -m venv .env
source .env/bin/activate  # Windows 用户使用: .env\Scripts\activate

# 克隆仓库
git clone https://github.com/huggingface/neuralcoref.git
cd neuralcoref

# 安装依赖并启用编辑模式
pip install -r requirements.txt
pip install -e .

基本使用

NeuralCoref 集成在 spaCy 的处理管道中，使用后会在 Doc、Span 和 Token 对象中增加自定义属性（通过 ._. 访问）。

最简单示例

以下代码演示了如何加载模型、添加 NeuralCoref 管道，并提取共指簇。

import spacy
import neuralcoref

# 1. 加载 spaCy 英语模型
nlp = spacy.load('en_core_web_sm')

# 2. 将 NeuralCoref 添加到 spaCy 管道中
neuralcoref.add_to_pipe(nlp)

# 3. 处理文本
doc = nlp(u'My sister has a dog. She loves him.')

# 4. 访问共指消解结果
# 检查文档中是否存在共指关系
print(f"Has coref: {doc._.has_coref}")

# 获取所有共指簇列表
clusters = doc._.coref_clusters
print(f"Number of clusters: {len(clusters)}")

# 遍历并打印每个簇的主提及 (main) 和所有提及 (mentions)
for cluster in clusters:
    print(f"Cluster main: {cluster.main}")
    print(f"Cluster mentions: {[mention.text for mention in cluster.mentions]}")

# 5. 获取替换后的文本（将所有指代词替换为主提及）
resolved_text = doc._.coref_resolved
print(f"Resolved text: {resolved_text}")

核心属性说明

处理后的 doc 对象包含以下关键扩展属性：

属性	类型	描述
doc._.has_coref	boolean	文档中是否解析出任何共指关系
doc._.coref_clusters	List[Cluster]	文档中所有的共指簇列表
doc._.coref_resolved	str	将共指提及替换为主提及后的完整文本
span._.is_coref	boolean	该片段是否属于某个共指簇
span._.coref_cluster	Cluster	包含该片段的共指簇对象

Cluster 对象常用属性：

• main: 簇中最具代表性的提及（Span 对象）。
• mentions: 簇中所有提及的列表（List of Span）。