huggingface/sentence-transformers

State-of-the-Art Embeddings, Retrieval, and Reranking

什么是 Sentence-Transformers？

Sentence-Transformers 是一个 Python 库，让您可以轻松使用建立在 Hugging Face Transformers 之上的 文本嵌入 (text embedding) 模型。它提供了一个轻量且易于使用的 API，用于：

  • 计算密集或稀疏句子嵌入（让每个句子变成一个您可以存储、比较或索引的固定大小向量）。
  • 使用 Cross-Encoders 进行重排序 – 直接对 查询-文档 配对进行评分的模型，适用于检索与重排序管线的第二阶段。
  • 后期交互 / 多向量编码器 (ColBERT 风格)，保留标记层级的向量以获得更精确的相似度。
  • 训练 / 微调 上述任何类型的模型，并使用您自己的数据。

所有这些功能都封装在一个包中，并在 Hugging Face Hub 上托管了超过 15,000 个预训练模型，涵盖多种语言和任务。

快速开始（可复制粘贴的代码）

# 安装库 (建议使用 Python 3.10+, PyTorch 2.2+, transformers 5.0+)
# pip install -U sentence-transformers

# 1️⃣ 加载现成的密集嵌入模型
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium."
]
emb = model.encode(sentences)          # 形状 → (3, 384)
print(emb.shape)

# 2️⃣ 计算配对相似度（类似余弦相似度的分数）
print(model.similarity(emb, emb))

重排序示例 (Cross-Encoder)：

from sentence_transformers import CrossEncoder
ranker = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")
query = "How many people live in Berlin?"
passages = [
    "Berlin had a population of 3,520,031 registered inhabitants…",
    "Berlin has a yearly total of about 135 million day visitors…",
    "In 2013 around 600,000 Berliners were registered in sport clubs."
]
# 对每个 (查询, 段落) 配对进行评分
scores = ranker.predict([(query, p) for p in passages])
print(scores)
# 或者让库为您进行排序
print(ranker.rank(query, passages, return_documents=True))

稀疏嵌入示例：

from sentence_transformers import SparseEncoder
sparse = SparseEncoder("naver/splade-cocondenser-ensembledistil")
emb = sparse.encode(["The weather is lovely today."])
print(emb.shape)          # 例如 (1, 30522) – 每个词汇标记一个维度
print(SparseEncoder.sparsity(emb))

后期交互 (多向量) 示例：

from sentence_transformers import MultiVectorEncoder
mv = MultiVectorEncoder("lightonai/GTE-ModernColBERT-v1")
q_emb = mv.encode_query(["What is the capital of France?"])
 d_emb = mv.encode_document(["Paris is the capital of France.", "Berlin is the capital of Germany."])
print(mv.similarity(q_emb, d_emb))

您何时会使用它？

场景 建议模型类型 为什么使用 Sentence-Transformers？
语义搜索 / 检索 密集或稀疏编码器 一行 model.encode → 您可以使用 FAISS, Annoy 等索引的向量
重排序 top-k 结果 Cross-Encoder (重排序器) 直接对查询-文档配对进行评分，以获得更高的精确度
混合搜索 (密集 + 稀疏) 结合密集编码器与稀疏编码器 同时利用词汇匹配和语义相似度
多语言相似度 多语言 Sentence-BERT 模型 开箱即用，支持超过 100 种语言
内存有限的大型语料库 稀疏或 Matryoshka 嵌入 稀疏向量非常小；Matryoshka 可以即时截断
在自定义数据集上微调 上述四种模型家族的任何一种 库内置超过 20 种损失函数和训练工具

它是如何工作的？

  1. 基础 Transformer – 来自 🤗 Transformers 的 BERT/RoBERTa 等模型。
  2. 池化层 (Pooling layer) – 对于密集模型，它将标记嵌入压缩成单个句子向量（平均、CLS、最大池化等）。
  3. Cross-Encoder 头 – 一个分类头，接收串接的配对 [CLS] query [SEP] passage 并输出相关性分数。
  4. 稀疏头 – 预测词汇表上的分布，产生高维稀疏向量（如 SPLADE）。
  5. 多向量头 – 保留标记层级的嵌入，实现后期交互评分，而无需压缩成单个向量。

所有这些组件都整合在 sentence_transformers 包中，因此您永远不需要自己编写样板代码。

获取库

# 建议的 Python 版本
pip install -U sentence-transformers

选用的额外功能（使用 pip install "sentence-transformers[train]" 等安装）增加了对以下内容的支持：

  • 图像 / 音频 / 视频 编码器 ([image], [audio], [video])
  • ONNX / OpenVINO 导出以实现更快的推理 ([onnx], [openvino])
  • 训练工具 ([train])
  • 开发工具 ([dev])

文档与社区

  • 完整文档：www.sbert.net – 包含安装指南、API 参考、教程和模型库。
  • 模型中心：🤗 Hub – library=sentence-transformers – 浏览超过 15,000 个预训练模型。
  • 博客文章：训练指南、多模态扩展、效率技巧（Matryoshka、静态嵌入、量化）。
  • 问题与贡献：请参阅 CONTRIBUTING.md；维护者是 Tom Aarsen (🤗 Hugging Face)。

引用此工作

如果您在研究中使用此库，请引用原始的 Sentence-BERT 论文 (Reimers & Gurevych 2019)，对于多语言模型，请引用 2020 年的蒸馏论文。书目条目提供在 README 中。

相关