Sentence Transformers：嵌入、检索与重排序

该框架提供了一种简便的方法来计算嵌入，以便访问、使用和训练最先进的嵌入模型及重排序模型。它可以用于通过 Sentence Transformer 模型计算嵌入（快速入门），使用交叉编码器（即重排序器）模型计算相似度分数（快速入门），或使用稀疏编码器模型生成稀疏嵌入（快速入门）。这为广泛的应用打开了大门，包括语义搜索、语义文本相似性以及释义挖掘。

在 🤗 Hugging Face 上提供了超过15,000 个预训练的 Sentence Transformers 模型，可供立即使用，其中包括许多来自MTEB 大规模文本嵌入基准排行榜的最先进模型。此外，使用 Sentence Transformers 轻松训练或微调您自己的嵌入模型、重排序模型或稀疏编码器模型，使您能够为特定用例创建自定义模型。

有关完整文档，请参阅**www.SBERT.net**。

安装

我们建议使用Python 3.10+、PyTorch 1.11.0+ 和 transformers v4.34.0+。

使用 pip 安装

pip install -U sentence-transformers

使用 conda 安装

conda install -c conda-forge sentence-transformers

从源代码安装

或者，您也可以从仓库克隆最新版本，并直接从源代码进行安装：

pip install -e .

带有 CUDA 的 PyTorch

如果您希望使用 GPU / CUDA，则必须安装与之匹配的 CUDA 版本的 PyTorch。请按照PyTorch - 开始使用中的说明进一步了解如何安装 PyTorch。

入门

请参阅我们文档中的快速入门。

嵌入模型

首先下载一个预训练的嵌入模型，即 Sentence Transformer 模型。

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

然后将一些文本提供给模型。

sentences = [
    "今天的天气真好。",
    "外面阳光明媚！",
    "他开车去了体育场。",
]
embeddings = model.encode(sentences)
print(embeddings.shape)
# => (3, 384)

就这样完成了。我们现在有了包含嵌入的 NumPy 数组，每个文本对应一个。我们可以使用这些嵌入来计算相似度。

similarities = model.similarity(embeddings, embeddings)
print(similarities)
# tensor([[1.0000, 0.6660, 0.1046],
#         [0.6660, 1.0000, 0.1411],
#         [0.1046, 0.1411, 1.0000]])

重排序模型

首先下载一个预训练的重排序模型，即交叉编码器模型。

from sentence_transformers import CrossEncoder

# 1. 加载一个预训练的交叉编码器模型
model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")

然后将一些文本提供给模型。

# 用于预测相似度分数的文本
query = "柏林有多少人居住？"
passages = [
    "柏林在891.82平方公里的区域内有3,520,031名注册居民。",
    "柏林每年约有1.35亿游客到访，使其成为欧盟访问量最大的城市之一。",
    "2013年，约有60万名柏林人注册加入了2,300多个体育和健身俱乐部。",
]

# 2a. 预测文本对的得分
scores = model.predict([(query, passage) for passage in passages])
print(scores)
# => [8.607139 5.506266 6.352977]

现在就可以开始了。您还可以使用model.rank来避免手动进行重排序：

# 2b. 对查询的段落列表进行排名
ranks = model.rank(query, passages, return_documents=True)

print("查询：", query)
for rank in ranks:
    print(f"- #{rank['corpus_id']} ({rank['score']:.2f})：{rank['text']}")
"""
查询：柏林有多少人居住？
- #0 (8.61)：柏林在891.82平方公里的区域内有3,520,031名注册居民。
- #2 (6.35)：2013年，约有60万名柏林人注册加入了2,300多个体育和健身俱乐部。
- #1 (5.51)：柏林每年约有1.35亿游客到访，使其成为欧盟访问量最大的城市之一。
"""

稀疏编码器模型

首先下载一个预训练的稀疏嵌入模型，即稀疏编码器模型。

from sentence_transformers import SparseEncoder

# 1. 加载一个预训练的稀疏编码器模型
model = SparseEncoder("naver/splade-cocondenser-ensembledistil")

# 要编码的句子
sentences = [
    "今天的天气真好。",
    "外面阳光明媚！",
    "他开车去了体育场。",
]

# 2. 通过调用 model.encode() 计算稀疏嵌入
embeddings = model.encode(sentences)
print(embeddings.shape)
# [3, 30522] - 具有词汇表大小维度的稀疏表示

# 3. 计算嵌入之间的相似度
similarities = model.similarity(embeddings, embeddings)
print(similarities)
# tensor([[   35.629,     9.154,     0.098],

#         [    9.154,    27.478,     0.019],
#         [    0.098,     0.019,    29.553]])

# 4. 检查稀疏性统计信息
stats = SparseEncoder.sparsity(embeddings)
print(f"稀疏度: {stats['sparsity_ratio']:.2%}")
# 稀疏度: 99.84%

预训练模型

我们提供了涵盖100多种语言的大量预训练模型。其中一些是通用模型，而另一些则针对特定应用场景生成嵌入。

• 预训练的 Sentence Transformer（嵌入）模型
• 预训练的 Cross Encoder（重排序器）模型
• 预训练的 Sparse Encoder（稀疏嵌入）模型

训练

该框架允许您微调自己的句子嵌入方法，从而获得特定任务的句子嵌入。为了满足您的具体需求，您可以选择多种不同的选项来构建理想的句子嵌入。

• 嵌入模型
  • Sentence Transformer > 训练概述
  • Sentence Transformer > 训练示例，或访问GitHub上的训练示例。
• 重排序器模型
  • Cross Encoder > 训练概述
  • Cross Encoder > 训练示例，或访问GitHub上的训练示例。
• 稀疏嵌入模型
  • Sparse Encoder > 训练概述
  • Sparse Encoder > 训练示例，或访问GitHub上的训练示例。

不同类型的训练中的一些亮点包括：

• 支持多种Transformer网络，包括BERT、RoBERTa、XLM-R、DistilBERT、Electra、BART等。
• 多语言和多任务学习。
• 在训练过程中进行评估以找到最优模型。
• 嵌入模型提供20多种损失函数，重排序器模型提供10多种损失函数，稀疏嵌入模型也提供10多种损失函数，使您可以针对语义搜索、释义挖掘、语义相似度比较、聚类、三元组损失、对比损失等任务对模型进行优化。

应用示例

您可以使用此框架实现以下功能：

• 计算句子嵌入

  • 密集嵌入
  • 稀疏嵌入

• 语义文本相似度

  • 密集STS
  • 稀疏STS

• 语义搜索

  • 密集搜索
  • 稀疏搜索

• 检索与重排序

  • 仅密集检索
  • 稀疏/密集/混合检索

• 聚类

• 释义挖掘

• 翻译句子挖掘

• 多语言图像搜索、聚类及重复检测

以及更多其他应用场景。

有关所有示例，请参阅examples/sentence_transformer/applications。

开发环境搭建

将仓库（或其分支）克隆到您的机器后，在虚拟环境中运行以下命令：

python -m pip install -e ".[dev]"
pre-commit install

要测试您的更改，请运行：

pytest

引用与作者

如果您觉得本仓库对您有所帮助，请随时引用我们的论文《Sentence-BERT：基于孪生BERT网络的句子嵌入》：

@inproceedings{reimers-2019-sentence-bert,
    title = "Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks",
    author = "Reimers, Nils and Gurevych, Iryna",
    booktitle = "Proceedings of the 2019 Conference on Empirical Methods in Natural Language Processing",
    month = "11",
    year = "2019",
    publisher = "Association for Computational Linguistics",
    url = "https://arxiv.org/abs/1908.10084",
}

如果您使用的是多语言模型，请随时引用我们的论文《利用知识蒸馏将单语句嵌入转化为多语言句嵌入》：

@inproceedings{reimers-2020-multilingual-sentence-bert,
    title = "Making Monolingual Sentence Embeddings Multilingual using Knowledge Distillation",
    author = "Reimers, Nils and Gurevych, Iryna",
    booktitle = "Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing",
    month = "11",
    year = "2020",
    publisher = "Association for Computational Linguistics",
    url = "https://arxiv.org/abs/2004.09813",
}

请参阅出版物，了解我们整合到SentenceTransformers中的各类研究成果。

维护者

维护者：Tom Aarsen，🤗 Hugging Face

如果遇到任何问题（尽管不应该出现），或者您有其他疑问，请随时提交 Issue。

---

本项目最初由达姆施塔特工业大学的 无处不在的知识处理（UKP）实验室 开发。我们感谢他们在该领域所做的基础性工作以及持续的贡献。

本仓库包含实验性软件，仅用于提供相关论文的更多背景信息。

sentence-transformers 快速上手指南

sentence-transformers 是一个用于计算文本嵌入（Embeddings）、语义搜索及重排序（Reranking）的 Python 框架。它提供了简单易用的接口来调用和训练最先进的模型，支持稠密向量、稀疏向量及交叉编码器模型。

环境准备

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

• Python: 推荐版本 3.10 或更高。
• PyTorch: 推荐版本 1.11.0 或更高。
  • 若需使用 GPU 加速，请安装匹配 CUDA 版本的 PyTorch。
• Transformers: 推荐版本 4.34.0 或更高。

国内加速建议：由于模型默认从 Hugging Face 下载，国内用户建议设置镜像环境变量以加速下载：

export HF_ENDPOINT=https://hf-mirror.com

安装步骤

你可以选择通过 pip 或 conda 进行安装。

方式一：使用 pip 安装（推荐）

pip install -U sentence-transformers

方式二：使用 conda 安装

conda install -c conda-forge sentence-transformers

方式三：从源码安装

git clone https://github.com/huggingface/sentence-transformers.git
cd sentence-transformers
pip install -e .

基本使用

以下是三种核心功能的最简使用示例。

1. 生成文本嵌入 (Embedding Models)

这是最常用的功能，将句子转换为固定长度的向量，可用于计算相似度或构建搜索引擎。

from sentence_transformers import SentenceTransformer

# 1. 加载预训练模型
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

# 2. 定义待处理的文本
sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium.",
]

# 3. 生成嵌入向量
embeddings = model.encode(sentences)
print(embeddings.shape)
# 输出: (3, 384)

# 4. 计算相似度矩阵
similarities = model.similarity(embeddings, embeddings)
print(similarities)

2. 文本重排序 (Reranker Models)

使用 Cross-Encoder 模型对检索结果进行精细排序，适用于提高搜索准确率。

from sentence_transformers import CrossEncoder

# 1. 加载预训练重排序模型
model = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")

# 2. 定义查询和候选文档
query = "How many people live in Berlin?"
passages = [
    "Berlin had a population of 3,520,031 registered inhabitants in an area of 891.82 square kilometers.",
    "Berlin has a yearly total of about 135 million day visitors, making it one of the most-visited cities in the European Union.",
    "In 2013 around 600,000 Berliners were registered in one of the more than 2,300 sport and fitness clubs.",
]

# 3. 直接对候选文档进行排序
ranks = model.rank(query, passages, return_documents=True)

print("Query:", query)
for rank in ranks:
    print(f"- #{rank['corpus_id']} ({rank['score']:.2f}): {rank['text']}")

3. 稀疏嵌入 (Sparse Encoder Models)

生成基于词汇表的稀疏向量，适用于特定场景下的检索任务。

from sentence_transformers import SparseEncoder

# 1. 加载预训练稀疏编码模型
model = SparseEncoder("naver/splade-cocondenser-ensembledistil")

sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium.",
]

# 2. 生成稀疏嵌入
embeddings = model.encode(sentences)
print(embeddings.shape)
# 输出: [3, 30522] (维度等于词表大小)

# 3. 查看稀疏度统计
stats = SparseEncoder.sparsity(embeddings)
print(f"Sparsity: {stats['sparsity_ratio']:.2%}")

---

更多预训练模型列表及高级训练教程，请访问官方文档：www.SBERT.net 或 Hugging Face Model Hub。