sense2vec：基于上下文的词向量

sense2vec（Trask 等人, 2015）是对 word2vec 的一种巧妙改进，能够学习到更加丰富和细致的词向量。本库是一个简单的 Python 实现，用于加载、查询和训练 sense2vec 模型。更多详情请参阅 我们的博客文章。若想探索 2015 年和 2019 年所有 Reddit 评论之间的语义相似性，请访问 交互式演示。

🦆 版本 2.0（适用于 spaCy v3）现已发布！ 请在此处阅读发行说明。

✨ 功能特性

• 基于词性标注和实体标签，查询多词短语的向量。
• spaCy 管道组件和扩展属性。
• 完全可序列化，因此您可以轻松地将 sense2vec 向量与您的 spaCy 模型包一起分发。
• 可选的最近邻缓存，以实现超快速的“最相似”查询。
• 使用预训练的 spaCy 模型、原始文本以及通过 fastText 提供的 GloVe 或 Word2Vec， 训练您自己的向量（详情）。
• Prodigy 注释配方，用于评估模型、创建相似的多词短语列表，并将其转换为匹配模式，例如用于基于规则的 NER 或启动 NER 注释工作（详情及示例）。

🚀 快速入门

独立使用

from sense2vec import Sense2Vec

s2v = Sense2Vec().from_disk("/path/to/s2v_reddit_2015_md")
query = "natural_language_processing|NOUN"
assert query in s2v
vector = s2v[query]
freq = s2v.get_freq(query)
most_similar = s2v.most_similar(query, n=3)
# [('machine_learning|NOUN', 0.8986967),
#  ('computer_vision|NOUN', 0.8636297),
#  ('deep_learning|NOUN', 0.8573361)]

作为 spaCy 管道组件使用

⚠️ 请注意，此示例描述的是与 spaCy v3 的用法。若要与 spaCy v2 配合使用，请下载 sense2vec==1.0.3 并查看此仓库的 v1.x 分支。

import spacy

nlp = spacy.load("en_core_web_sm")
s2v = nlp.add_pipe("sense2vec")
s2v.from_disk("/path/to/s2v_reddit_2015_md")

doc = nlp("A sentence about natural language processing.")
assert doc[3:6].text == "natural language processing"
freq = doc[3:6]._.s2v_freq
vector = doc[3:6]._.s2v_vec
most_similar = doc[3:6]._.s2v_most_similar(3)
# [(('machine learning', 'NOUN'), 0.8986967),
#  (('computer vision', 'NOUN'), 0.8636297),
#  (('deep learning', 'NOUN'), 0.8573361)]

交互式演示

要试用我们在 Reddit 评论上训练的预训练向量，请访问 交互式 sense2vec 演示。

该仓库还包含一个 Streamlit 演示脚本，用于探索向量和最相似的短语。安装 streamlit 后，您可以通过运行 streamlit run 命令，并在命令行中提供 一个或多个预训练向量的路径作为位置参数来运行该脚本。例如：

pip install streamlit
streamlit run https://raw.githubusercontent.com/explosion/sense2vec/master/scripts/streamlit_sense2vec.py /path/to/vectors

预训练向量

要使用这些向量，您需要下载归档文件，并将解压后的目录传递给 Sense2Vec.from_disk 或 Sense2VecComponent.from_disk。向量文件已附加到 GitHub 发布页面。较大的文件已被拆分为多部分下载。

向量	大小	描述	📥 下载（压缩包）
s2v_reddit_2019_lg	4 GB	Reddit 评论 2019（01–07）	第1部分, 第2部分, 第3部分
s2v_reddit_2015_md	573 MB	Reddit 评论 2015	第1部分

要合并多部分归档文件，您可以运行以下命令：

cat s2v_reddit_2019_lg.tar.gz.* > s2v_reddit_2019_lg.tar.gz

⏳ 安装与设置

sense2vec 的发布版本可在 PyPI 上获取：

pip install sense2vec

要使用预训练向量，您需要下载 其中一个向量包，解压 .tar.gz 归档文件，并将 from_disk 指向解压后的数据目录：

from sense2vec import Sense2Vec
s2v = Sense2Vec().from_disk("/path/to/s2v_reddit_2015_md")

👩‍💻 使用方法

与 spaCy v3 的使用

使用该库和向量的最简单方法是将其集成到你的 spaCy 管道中。sense2vec 包公开了一个 Sense2VecComponent，它可以使用共享词汇表进行初始化，并作为自定义管道组件添加到你的 spaCy 管道中。默认情况下，组件会被添加到管道的_末尾_，这也是推荐的位置，因为该组件需要访问依存句法分析结果，以及命名实体（如果有的话）。

import spacy
from sense2vec import Sense2VecComponent

nlp = spacy.load("en_core_web_sm")
s2v = nlp.add_pipe("sense2vec")
s2v.from_disk("/path/to/s2v_reddit_2015_md")

该组件会为 spaCy 的 Token 和 Span 对象添加若干 扩展属性和方法，使你可以检索向量和频率，以及找到最相似的术语。

doc = nlp("A sentence about natural language processing.")
assert doc[3:6].text == "natural language processing"
freq = doc[3:6]._.s2v_freq
vector = doc[3:6]._.s2v_vec
most_similar = doc[3:6]._.s2v_most_similar(3)

对于实体，实体标签会被用作“语义”（而不是词性的标签）：

doc = nlp("A sentence about Facebook and Google.")
for ent in doc.ents:
    assert ent._.in_s2v
    most_similar = ent._.s2v_most_similar(3)

可用属性

以下扩展属性通过 ._ 属性在 Doc 对象上暴露：

名称	属性类型	类型	描述
s2v_phrases	属性	列表	给定 Doc 中所有与 sense2vec 兼容的短语（名词短语、命名实体）。

以下属性可通过 Token 和 Span 对象的 ._ 属性访问——例如 token._.in_s2v：

名称	属性类型	返回类型	描述
in_s2v	属性	布尔值	键是否存在于向量映射中。
s2v_key	属性	Unicode	给定对象的 sense2vec 键，例如 "duck NOUN"。
s2v_vec	属性	ndarray[float32]	给定键的向量。
s2v_freq	属性	整数	给定键的频率。
s2v_other_senses	属性	列表	可用的其他语义，例如对于 "duck|NOUN" 的 "duck|VERB"。
s2v_most_similar	方法	列表	获取最相似的 n 个术语。返回一个 ((word, sense), score) 元组列表。
s2v_similarity	方法	浮点数	计算与另一个 Token 或 Span 的相似度。

⚠️ 关于 span 属性的说明： 在底层，doc.ents 中的实体实际上是 Span 对象。这就是为什么管道组件也会为 spans 而不是仅 tokens 添加属性和方法的原因。然而，不建议对文档的任意切片使用 sense2vec 属性，因为模型很可能没有对应文本的键。此外，Span 对象也没有词性标签，因此如果没有实体标签，则“语义”会默认为根节点的词性标签。

将 sense2vec 添加到训练好的管道

如果你正在训练并打包一个 spaCy 管道，并希望在其中包含 sense2vec 组件，可以通过训练配置中的 [initialize] 块加载数据：

[initialize.components]

[initialize.components.sense2vec]
data_path = "/path/to/s2v_reddit_2015_md"

独立使用

你也可以直接使用底层的 Sense2Vec 类，并使用 from_disk 方法加载向量。可用的 API 方法见下文。

from sense2vec import Sense2Vec
s2v = Sense2Vec().from_disk("/path/to/reddit_vectors-1.1.0")
most_similar = s2v.most_similar("natural_language_processing|NOUN", n=10)

⚠️ 重要提示： 要在向量表中查找条目，键必须遵循 phrase_text|SENSE 的格式（注意使用 _ 而不是空格，以及在标签或类别前使用 |），例如 machine_learning|NOUN。另外请注意，底层向量表是区分大小写的。

🎛 API

类 Sense2Vec

独立的 Sense2Vec 对象，用于存储向量、字符串和频率。

方法 Sense2Vec.__init__

初始化 Sense2Vec 对象。

参数	类型	描述
shape	元组	向量形状。默认值为 (1000, 128)。
strings	spacy.strings.StringStore	可选的字符串存储。如果不存在，则会自动创建。
senses	列表	可选的全部可用语义列表。用于生成最佳语义或其他语义的方法中。
vectors_name	Unicode	可选的向量表名称，用于避免冲突。默认值为 "sense2vec"。
overrides	字典	可选的自定义函数，映射到注册表中已注册的名称，例如 {"make_key": "custom_make_key"}。
返回值	Sense2Vec	新构造的对象。

s2v = Sense2Vec(shape=(300, 128), senses=["VERB", "NOUN"])

方法 Sense2Vec.__len__

向量表中的行数。

参数	类型	描述
返回值	整数	向量表中的行数。

s2v = Sense2Vec(shape=(300, 128))
assert len(s2v) == 300

方法 Sense2Vec.__contains__

检查键是否存在于向量表中。

参数	类型	描述
key	unicode / int	要查找的键。
返回值	bool	键是否在表中。

s2v = Sense2Vec(shape=(10, 4))
s2v.add("avocado|NOUN", numpy.asarray([4, 2, 2, 2], dtype=numpy.float32))
assert "avocado|NOUN" in s2v
assert "avocado|VERB" not in s2v

方法 Sense2Vec.__getitem__

根据给定的键检索向量。如果键不在表中，则返回 None。

参数	类型	描述
key	unicode / int	要查找的键。
返回值	numpy.ndarray	向量或 None。

vec = s2v["avocado|NOUN"]

方法 Sense2Vec.__setitem__

为给定的键设置向量。如果键不存在，则会引发错误。要添加新条目，请使用 Sense2Vec.add。

参数	类型	描述
key	unicode / int	键。
vector	numpy.ndarray	要设置的向量。

vec = s2v["avocado|NOUN"]
s2v["avacado|NOUN"] = vec

方法 Sense2Vec.add

向表中添加一个新的向量。

参数	类型	描述
key	unicode / int	要添加的键。
vector	numpy.ndarray	要添加的向量。
freq	int	可选的频率计数。用于找到最佳匹配的词义。

vec = s2v["avocado|NOUN"]
s2v.add("🥑|NOUN", vec, 1234)

方法 Sense2Vec.get_freq

获取给定键的频率计数。

参数	类型	描述
key	unicode / int	要查找的键。
default	-	如果未找到频率，则返回的默认值。
返回值	int	频率计数。

vec = s2v["avocado|NOUN"]
s2v.add("🥑|NOUN", vec, 1234)
assert s2v.get_freq("🥑|NOUN") == 1234

方法 Sense2Vec.set_freq

为给定的键设置频率计数。

参数	类型	描述
key	unicode / int	要设置频率的键。
freq	int	频率计数。

s2v.set_freq("avocado|NOUN", 104294)

方法 Sense2Vec.__iter__, Sense2Vec.items

遍历向量表中的条目。

参数	类型	描述
产出	tuple	表中的字符串键和向量对。

for key, vec in s2v:
    print(key, vec)

for key, vec in s2v.items():
    print(key, vec)

方法 Sense2Vec.keys

遍历表中的键。

参数	类型	描述
产出	unicode	表中的字符串键。

all_keys = list(s2v.keys())

方法 Sense2Vec.values

遍历表中的向量。

参数	类型	描述
产出	numpy.ndarray	表中的向量。

all_vecs = list(s2v.values())

属性 Sense2Vec.senses

表中可用的词义，例如 "NOUN" 或 "VERB"（在初始化时添加）。

参数	类型	描述
返回值	list	可用的词义。

s2v = Sense2Vec(senses=["VERB", "NOUN"])
assert "VERB" in s2v.senses

属性 Sense2vec.frequencies

表中键的频率，按降序排列。

参数	类型	描述
返回值	list	按频率降序排列的 (key, freq) 元组。

most_frequent = s2v.frequencies[:10]
key, score = s2v.frequencies[0]

方法 Sense2vec.similarity

对两个键或两组键进行语义相似度估计。默认估计是使用向量平均值的余弦相似度。

参数	类型	描述
keys_a	unicode / int / iterable	字符串或整数键。
keys_b	unicode / int / iterable	另一组字符串或整数键。
返回值	float	相似度分数。

keys_a = ["machine_learning|NOUN", "natural_language_processing|NOUN"]
keys_b = ["computer_vision|NOUN", "object_detection|NOUN"]
print(s2v.similarity(keys_a, keys_b))
assert s2v.similarity("machine_learning|NOUN", "machine_learning|NOUN") == 1.0

方法 Sense2Vec.most_similar

获取表中最相似的条目。如果提供了多个键，则使用向量的平均值。为了加快此方法的速度，可以参考 预计算缓存的脚本，以预先计算最近邻节点。

参数	类型	描述
keys	unicode / int / iterable	要比较的字符串或整数键。
n	int	返回的相似键数量。默认为 10。
batch_size	int	使用的批量大小。默认为 16。
返回值	list	最相似向量的 (key, score) 元组。

most_similar = s2v.most_similar("natural_language_processing|NOUN", n=3)


# [('machine_learning|NOUN', 0.8986967),
#  ('computer_vision|NOUN', 0.8636297),

#  ('深度学习|名词', 0.8573361)]

方法 Sense2Vec.get_other_senses

查找同一单词但具有不同语义的其他条目，例如针对 "duck|NOUN" 的 "duck|VERB"。

参数	类型	描述
key	unicode / int	要检查的键。
ignore_case	bool	检查大写、小写和首字母大写形式。默认值为 True。
返回值	list	具有不同语义的其他条目的字符串键。

other_senses = s2v.get_other_senses("duck|NOUN")
# ['duck|VERB', 'Duck|ORG', 'Duck|VERB', 'Duck|PERSON', 'Duck|ADJ']

方法 Sense2Vec.get_best_sense

根据可用的语义和频率计数，为给定单词找到最佳匹配的语义。如果没有找到匹配项，则返回 None。

参数	类型	描述
word	unicode	需要检查的单词。
senses	list	可选的语义列表，用于限制搜索范围。如果未设置或为空，则使用向量中的所有语义。
ignore_case	bool	检查大写、小写和首字母大写形式。默认值为 True。
返回值	unicode	最佳匹配的键，或 None。

assert s2v.get_best_sense("duck") == "duck|NOUN"
assert s2v.get_best_sense("duck", ["VERB", "ADJ"]) == "duck|VERB"

方法 Sense2Vec.to_bytes

将 Sense2Vec 对象序列化为字节串。

参数	类型	描述
exclude	list	要排除的序列化字段名称。
返回值	bytes	序列化的 Sense2Vec 对象。

s2v_bytes = s2v.to_bytes()

方法 Sense2Vec.from_bytes

从字节串中加载 Sense2Vec 对象。

参数	类型	描述
bytes_data	bytes	要加载的数据。
exclude	list	要排除的序列化字段名称。
返回值	Sense2Vec	加载后的对象。

s2v_bytes = s2v.to_bytes()
new_s2v = Sense2Vec().from_bytes(s2v_bytes)

方法 Sense2Vec.to_disk

将 Sense2Vec 对象序列化到一个目录中。

参数	类型	描述
path	unicode / Path	目标路径。
exclude	list	要排除的序列化字段名称。

s2v.to_disk("/path/to/sense2vec")

方法 Sense2Vec.from_disk

从目录中加载 Sense2Vec 对象。

参数	类型	描述
path	unicode / Path	要从中加载的路径
exclude	list	要排除的序列化字段名称。
返回值	Sense2Vec	加载后的对象。

s2v.to_disk("/path/to/sense2vec")
new_s2v = Sense2Vec().from_disk("/path/to/sense2vec")

---

类 Sense2VecComponent

用于将 sense2vec 添加到 spaCy 管道中的管道组件。

方法 Sense2VecComponent.__init__

初始化管道组件。

参数	类型	描述
vocab	Vocab	共享的 Vocab。主要用于共享的 StringStore。
shape	元组	向量形状。
merge_phrases	布尔值	是否将 sense2vec 短语合并为一个标记。默认为 False。
lemmatize	布尔值	如果向量中存在词元，则始终查找词元，否则使用原始词。默认为 False。
overrides	可选的自定义函数，映射到通过注册表注册的名称，例如 {"make_key": "custom_make_key"}。
返回值	Sense2VecComponent	新创建的对象。

s2v = Sense2VecComponent(nlp.vocab)

类方法 Sense2VecComponent.from_nlp

从 nlp 对象初始化组件。主要用于入口点的组件工厂（参见 setup.cfg），以及通过 @spacy.component 装饰器自动注册。

参数	类型	描述
nlp	Language	nlp 对象。
**cfg	-	可选配置参数。
返回值	Sense2VecComponent	新创建的对象。

s2v = Sense2VecComponent.from_nlp(nlp)

方法 Sense2VecComponent.__call__

使用该组件处理 Doc 对象。通常仅作为 spaCy 管道的一部分被调用，而不直接调用。

参数	类型	描述
doc	Doc	要处理的文档。
返回值	Doc	处理后的文档。

方法 Sense2Vec.init_component

在此处注册组件特定的扩展属性，且仅在组件被添加到管道并使用时才会注册；否则，即使组件仅被创建而未添加到管道，标记仍会获得这些属性。

方法 Sense2VecComponent.to_bytes

将组件序列化为字节串。当组件被添加到管道并运行 nlp.to_bytes 时也会调用此方法。

参数	类型	描述
返回值	字节	序列化的组件。

方法 Sense2VecComponent.from_bytes

从字节串加载组件。当运行 nlp.from_bytes 时也会调用此方法。

参数	类型	描述
bytes_data	字节	要加载的数据。
返回值	Sense2VecComponent	加载后的对象。

方法 Sense2VecComponent.to_disk

将组件序列化到目录中。当组件被添加到管道并运行 nlp.to_disk 时也会调用此方法。

参数	类型	描述
path	unicode / Path	路径。

方法 Sense2VecComponent.from_disk

从目录中加载 Sense2Vec 对象。当运行 nlp.from_disk 时也会调用此方法。

参数	类型	描述
path	unicode / Path	要加载的路径
返回值	Sense2VecComponent	加载后的对象。

---

class registry

函数注册表（由 catalogue 提供支持）用于轻松自定义生成键和短语的函数。它允许你为自定义函数添加装饰器并命名，替换这些函数，并在保存模型时序列化自定义名称。以下是可用的注册表选项：

名称	描述
registry.make_key	给定一个 word 和 sense，返回键的字符串形式，例如 "word|sense"。
registry.split_key	给定一个字符串键，返回一个 (word, sense) 元组。
registry.make_spacy_key	给定一个 spaCy 对象（Token 或 Span）以及一个布尔类型的 prefer_ents 关键字参数（是否优先使用单个标记的实体标签），返回一个 (word, sense) 元组。该函数用于扩展属性中，为标记和跨度生成键。
registry.get_phrases	给定一个 spaCy Doc，返回用于 sense2vec 短语的 Span 对象列表（通常为名词短语和命名实体）。
registry.merge_phrases	给定一个 spaCy Doc, 获取所有 sense2vec 短语并将它们合并为单个标记。

每个注册表都提供一个 register 方法，可以用作函数装饰器，并接受一个参数，即自定义函数的名称。

from sense2vec import registry

@registry.make_key.register("custom")
def custom_make_key(word, sense):
    return f"{word}###{sense}"

@registry.split_key.register("custom")
def custom_split_key(key):
    word, sense = key.split("###")
    return word, sense

在初始化 Sense2Vec 对象时，现在可以传入一个包含自定义注册函数名称的覆盖字典。

overrides = {"make_key": "custom", "split_key": "custom"}
s2v = Sense2Vec(overrides=overrides)

这使得尝试不同的策略变得容易，并且可以将这些策略序列化为普通字符串（而无需传递或 pickle 函数本身）。

🚂 训练你自己的 sense2vec 向量

/scripts 目录包含用于文本预处理和训练你自己的向量的命令行工具。

要求

要训练你自己的 sense2vec 向量，你需要以下内容：

• 一个 非常大 的原始文本源（理想情况下比用于 word2vec 的数据量还要多，因为语义会使词汇表更加稀疏）。我们建议至少 10 亿词。
• 一个 预训练的 spaCy 模型，能够分配词性标签、依存关系和命名实体，并填充 doc.noun_chunks。如果你需要的语言没有内置的 名词短语语法迭代器，则需要自己编写。（doc.noun_chunks 和 doc.ents 是 sense2vec 用来确定什么是短语的关键部分。）
• 已安装并构建好的 GloVe 或 fastText。你应该能够克隆仓库并在相应目录中运行 make 命令。

分步流程

训练过程被拆分为多个步骤，以便您可以在任何时刻从中断处继续。处理脚本设计为对单个文件进行操作，从而便于并行化工作。此仓库中的脚本需要使用 Glove 或 fastText，您需要先克隆这些仓库并执行 make 命令来编译。

对于 FastText，脚本需要指定生成的二进制文件路径。如果您在 Windows 上工作，可以使用 cmake 进行编译，或者直接使用这个提供 Windows 版 FastText 二进制构建的非官方仓库中的 .exe 文件：https://github.com/xiamx/fastText/releases。

	脚本	描述
1.	01_parse.py	使用 spaCy 解析原始文本，并输出 Doc 对象的二进制集合（参见 DocBin）。
2.	02_preprocess.py	加载上一步生成的已解析 Doc 对象集合，输出 sense2vec 格式的文本文件（每行为一个句子，合并带有语义的短语）。
3.	03_glove_build_counts.py	使用 GloVe 构建词汇表和词频统计。如果您使用的是通过 FastText 实现的 Word2Vec，则可跳过此步骤。
4.	04_glove_train_vectors.py 04_fasttext_train_vectors.py	使用 GloVe 或 FastText 训练词向量。
5.	05_export.py	加载词向量和词频，并输出一个 sense2vec 组件，可通过 Sense2Vec.from_disk 加载。
6.	06_precompute_cache.py	可选： 预计算词汇表中每个条目的近邻查询，以加快 Sense2Vec.most_similar 的速度。

如需更详细的脚本说明，请查看源代码或运行脚本时添加 --help 参数。例如，python scripts/01_parse.py --help。

🍳 Prodigy 配方

本包还与标注工具 Prodigy 无缝集成，并提供了利用 sense2vec 向量快速生成多词短语列表以及启动 NER 标注的配方。要使用这些配方，sense2vec 需安装在与 Prodigy 相同的环境中。有关实际应用场景的示例，请参阅此 NER 项目，其中包含可下载的数据集。

以下是可用的配方——更多详细文档请见下文。

配方	描述
sense2vec.teach	使用 sense2vec 启动术语列表。
sense2vec.to-patterns	将短语数据集转换为基于标记的匹配模式。
sense2vec.eval	通过询问短语三元组来评估 sense2vec 模型。
sense2vec.eval-most-similar	通过纠正最相似的条目来评估 sense2vec 模型。
sense2vec.eval-ab	对两个预训练的 sense2vec 向量模型进行 A/B 评估。

配方 sense2vec.teach

使用 sense2vec 启动术语列表。Prodigy 会根据 sense2vec 中最相似的短语建议相关术语，随着您标注并接受相似短语，建议也会相应调整。对于每个种子术语，将采用 sense2vec 向量所确定的最佳匹配语义。

prodigy sense2vec.teach [数据集] [向量路径] [--seeds] [--threshold]
[--n-similar] [--batch-size] [--resume]

参数	类型	描述
数据集	必填位置参数	用于保存标注结果的数据集。
向量路径	必填位置参数	预训练 sense2vec 向量的路径。
--seeds, -s	可选参数	一个或多个用逗号分隔的种子短语。
--threshold, -t	可选参数	相似度阈值，默认为 0.85。
--n-similar, -n	可选参数	每次获取的相似项数量。
--batch-size, -b	可选参数	提交标注的批次大小。
--resume, -R	标志	从现有短语数据集中续接。

示例

prodigy sense2vec.teach tech_phrases /path/to/s2v_reddit_2015_md
--seeds "自然语言处理, 机器学习, 人工智能"

recipe sense2vec.to-patterns

将使用 sense2vec.teach 收集的短语数据集转换为基于标记的匹配模式，这些模式可以与 spaCy 的 EntityRuler 或类似 ner.match 的配方一起使用。如果未指定输出文件，则模式会写入标准输出。示例会被分词，以便多标记术语能够正确表示，例如： {"label": "SHOE_BRAND", "pattern": [{ "LOWER": "new" }, { "LOWER": "balance" }]}。

prodigy sense2vec.to-patterns [dataset] [spacy_model] [label] [--output-file]
[--case-sensitive] [--dry]

参数	类型	描述
dataset	必需位置参数	要转换的短语数据集。
spacy_model	必需位置参数	用于分词的 spaCy 模型。
label	必需位置参数	应用于所有模式的标签。
--output-file, -o	可选参数	可选的输出文件。默认为标准输出。
--case-sensitive, -CS	标志	使模式区分大小写。
--dry, -D	标志	执行试运行，不输出任何内容。

示例

prodigy sense2vec.to-patterns tech_phrases en_core_web_sm TECHNOLOGY
--output-file /path/to/patterns.jsonl

recipe sense2vec.eval

通过询问短语三元组来评估 sense2vec 模型：单词 A 更类似于单词 B，还是更类似于单词 C？如果人类的判断大多与模型一致，则该向量模型表现良好。该配方只会询问具有相同语义的向量，并支持不同的示例选择策略。

prodigy sense2vec.eval [dataset] [vectors_path] [--strategy] [--senses]
[--exclude-senses] [--n-freq] [--threshold] [--batch-size] [--eval-whole]
[--eval-only] [--show-scores]

参数	类型	描述
dataset	必需位置参数	用于保存标注的数据集。
vectors_path	必需位置参数	预训练 sense2vec 向量的路径。
--strategy, -st	可选参数	示例选择策略。most similar（默认）或 random。
--senses, -s	可选参数	以逗号分隔的语义列表，用于限制选择范围。若未设置，则会使用向量中的所有语义。
--exclude-senses, -es	可选参数	以逗号分隔的要排除的语义列表。默认值请参阅 prodigy_recipes.EVAL_EXCLUDE_SENSES。
--n-freq, -f	可选参数	限制为出现频率最高的若干条目。
--threshold, -t	可选参数	考虑示例时使用的最小相似度阈值。
--batch-size, -b	可选参数	使用的批次大小。
--eval-whole, -E	标志	评估整个数据集，而不是当前会话。
--eval-only, -O	标志	不进行标注，仅评估当前数据集。
--show-scores, -S	标志	显示所有分数以供调试。

策略

名称	描述
most_similar	从随机语义中随机选取一个单词，获取其属于同一语义的最相似条目。然后询问该选择中最后一条和中间一条之间的相似性。
most_least_similar	从随机语义中随机选取一个单词，获取其最相似条目中最不相似的一条，然后再获取其中最相似的最后一条。
random	从同一个随机语义中随机选取 3 个单词作为样本。

示例

prodigy sense2vec.eval vectors_eval /path/to/s2v_reddit_2015_md
--senses NOUN,ORG,PRODUCT --threshold 0.5

recipe sense2vec.eval-most-similar

通过查看模型为随机短语返回的最相似条目，并剔除其中的错误项，来评估向量模型。

prodigy sense2vec.eval [数据集] [向量路径] [--senses] [--exclude-senses]
[--n-freq] [--n-similar] [--batch-size] [--eval-whole] [--eval-only]
[--show-scores]

参数	类型	描述
dataset	位置参数	用于保存标注的数据集。
vectors_path	位置参数	预训练 sense2vec 向量的路径。
--senses, -s	选项	以逗号分隔的词义列表，用于限制选择范围。若未设置，则会使用向量中的所有词义。
--exclude-senses, -es	选项	以逗号分隔的要排除的词义列表。默认值请参阅 prodigy_recipes.EVAL_EXCLUDE_SENSES。
--n-freq, -f	选项	限制为出现频率最高的若干条目。
--n-similar, -n	选项	要检查的相似项数量。默认值为 10。
--batch-size, -b	选项	使用的批次大小。
--eval-whole, -E	标志	对整个数据集进行评估，而不是仅对当前会话。
--eval-only, -O	标志	不进行标注，仅对当前数据集进行评估。
--show-scores, -S	标志	显示所有得分以供调试。

prodigy sense2vec.eval-most-similar vectors_eval_sim /path/to/s2v_reddit_2015_md
--senses NOUN,ORG,PRODUCT

recipe sense2vec.eval-ab

通过对两个预训练 sense2vec 向量模型为随机短语返回的最相似条目进行比较，执行 A/B 评估。界面会显示两个随机排列的选项，分别展示每个模型的最相似条目，并高亮显示不同的短语。在标注会话结束时，将显示总体统计信息和更优的模型。

prodigy sense2vec.eval [数据集] [向量路径_a] [向量路径_b] [--senses]
[--exclude-senses] [--n-freq] [--n-similar] [--batch-size] [--eval-whole]
[--eval-only] [--show-mapping]

参数	类型	描述
dataset	位置参数	用于保存标注的数据集。
vectors_path_a	位置参数	预训练 sense2vec 向量的路径。
vectors_path_b	位置参数	预训练 sense2vec 向量的路径。
--senses, -s	选项	以逗号分隔的词义列表，用于限制选择范围。若未设置，则会使用向量中的所有词义。
--exclude-senses, -es	选项	以逗号分隔的要排除的词义列表。默认值请参阅 prodigy_recipes.EVAL_EXCLUDE_SENSES。
--n-freq, -f	选项	限制为出现频率最高的若干条目。
--n-similar, -n	选项	要检查的相似项数量。默认值为 10。
--batch-size, -b	选项	使用的批次大小。
--eval-whole, -E	标志	对整个数据集进行评估，而不是仅对当前会话。
--eval-only, -O	标志	不进行标注，仅对当前数据集进行评估。
--show-mapping, -S	标志	在界面上显示哪个模型是选项 1，哪个是选项 2（用于调试）。

prodigy sense2vec.eval-ab vectors_eval_sim /path/to/s2v_reddit_2015_md /path/to/s2v_reddit_2019_md --senses NOUN,ORG,PRODUCT

预训练向量

预训练的 Reddit 向量支持以下“语义”，即词性标注或实体标签。更多详情请参阅 spaCy 的 标注方案概述。

标签	描述	示例
ADJ	形容词	大的、旧的、绿色的
ADP	介词	在、向、在……期间
ADV	副词	非常、明天、向下、哪里
AUX	助动词	是、已经（完成）、将会（做）
CONJ	连词	和、或、但
DET	冠词	一个、一只、那
INTJ	感叹词	嘘、哎哟、好极了、你好
NOUN	名词	女孩、猫、树、空气、美丽
NUM	数词	1、2017年、一、七十七、MMXIV
PART	助词	‘s、不
PRON	代词	我、你、他、她、我自己、某人
PROPN	专有名词	玛丽、约翰、伦敦、北约、HBO
PUNCT	标点符号	，？（）
SCONJ	从属连词	如果、当……时、那
SYM	符号	$、%、=、:)、😝
VERB	动词	跑、跑步、吃、吃了、正在吃

实体标签	描述
PERSON	人物，包括虚构人物。
NORP	国籍、宗教或政治团体。
FACILITY	建筑物、机场、高速公路、桥梁等。
ORG	公司、机构、组织等。
GPE	国家、城市、州。
LOC	非 GPE 地点，如山脉、水域等。
PRODUCT	物品、车辆、食品等（不包括服务）。
EVENT	有名称的飓风、战役、战争、体育赛事等。
WORK_OF_ART	书籍、歌曲等作品的标题。
LANGUAGE	任何有名称的语言。

sense2vec 快速上手指南

sense2vec 是 word2vec 的增强版，能够基于词性标签和实体标签学习更精细的多词短语向量。它与 spaCy 深度集成，适用于语义相似度查询、规则构建及 NER 标注引导。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.6+
• 核心依赖：
  • spacy (推荐 v3.0+)
  • numpy
  • srsly
• 前置模型：若作为 spaCy 组件使用，需预先下载 spaCy 语言模型（如 en_core_web_sm）。

安装步骤

1. 安装 sense2vec

使用 pip 直接安装最新版：

pip install sense2vec

提示：国内用户如遇下载缓慢，可使用清华或阿里镜像源：

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

2. 下载预训练向量

sense2vec 本身不包含向量数据，需从 GitHub Release 页面下载预训练好的向量包（基于 Reddit 评论训练）。

• 轻量版 (2015 数据，约 573MB): s2v_reddit_2015_md
• 大型版 (2019 数据，约 4GB，分卷压缩): s2v_reddit_2019_lg

下载后解压，记下文件夹路径（例如 /path/to/s2v_reddit_2015_md）。

(注：大型版分卷文件需在 Linux/macOS 下合并：cat s2v_reddit_2019_lg.tar.gz.* > s2v_reddit_2019_lg.tar.gz)

基本使用

方式一：独立模式 (Standalone)

直接加载向量库进行查询，无需 spaCy 管道。

from sense2vec import Sense2Vec

# 加载本地向量目录
s2v = Sense2Vec().from_disk("/path/to/s2v_reddit_2015_md")

# 构造查询键：短语_下划线连接 | 词性/标签
query = "natural_language_processing|NOUN"

# 检查是否存在
if query in s2v:
    # 获取向量
    vector = s2v[query]
    
    # 获取频率
    freq = s2v.get_freq(query)
    
    # 获取最相似的 3 个短语
    most_similar = s2v.most_similar(query, n=3)
    print(most_similar)
    # 输出示例：[('machine_learning|NOUN', 0.898...), ('computer_vision|NOUN', 0.863...), ...]

方式二：作为 spaCy v3 管道组件

集成到 spaCy 流程中，自动处理分词、词性标注和实体识别，支持通过 ._ 属性直接访问。

import spacy
from sense2vec import Sense2VecComponent

# 加载 spaCy 模型
nlp = spacy.load("en_core_web_sm")

# 添加 sense2vec 组件到管道末尾
s2v = nlp.add_pipe("sense2vec")
s2v.from_disk("/path/to/s2v_reddit_2015_md")

# 处理文本
doc = nlp("A sentence about natural language processing.")

# 获取短语片段 (Span)
phrase_span = doc[3:6] # "natural language processing"

# 访问扩展属性
if phrase_span._.in_s2v:
    freq = phrase_span._.s2v_freq
    vector = phrase_span._.s2v_vec
    similar = phrase_span._.s2v_most_similar(3)
    
    print(similar)
    # 输出示例：[(('machine learning', 'NOUN'), 0.898...), ...]

# 实体查询示例 (自动使用实体标签作为 Sense)
doc_ent = nlp("Facebook and Google are tech giants.")
for ent in doc_ent.ents:
    if ent._.in_s2v:
        print(f"{ent.text}: {ent._.s2v_most_similar(2)}")

关键注意事项

1. Key 格式：独立模式下查询键必须严格遵循 短语文本 (空格转下划线)|标签 格式（如 machine_learning|NOUN），且区分大小写。
2. Span 限制：在 spaCy 模式中，不建议对任意文本切片使用 sense2vec 属性，除非该切片是模型识别出的名词短语或命名实体，否则可能找不到对应的 Key。
3. 默认 Sense：若非实体且未指定词性，系统默认使用根节点的词性标签作为 Sense。