Haystack 中的 Sentence Transformers 集成:稠密/稀疏/多模态嵌入与语义排序完整指南
Haystack 中的 Sentence Transformers 集成:稠密/稀疏/多模态嵌入与语义排序完整指南
导读:本文以 Haystack 官方 API 参考文档(docs-website/reference/integrations-api/sentence_transformers.md)为核心骨架,系统讲解 sentence-transformers-haystack 集成包提供的全部组件:用于索引与查询的稠密文本/文档嵌入器、SPLADE 稀疏嵌入器、CLIP 多模态图像嵌入器,以及基于交叉编码器的相似度排序器和多样性排序器。读完本文,你将掌握每个组件的全部初始化参数、run/warm_up/to_dict/from_dict 生命周期用法,并能在 Haystack Pipeline 中独立搭建从嵌入、检索到重排的完整语义搜索与 RAG 链路。
集成总览:sentence-transformers-haystack 组件全家桶
Sentence Transformers 集成是 Haystack 生态中最常用的本地嵌入方案之一,它允许你完全在本地(或通过 Hugging Face Hub 拉取权重)运行嵌入模型与重排模型,无需调用远程 API。该集成统一打包在 sentence-transformers-haystack 这一个 Python 包中,涵盖以下 7 个组件:
| 类别 | 组件 | 默认模型 | 典型用途 |
|---|---|---|---|
| 稠密嵌入 | SentenceTransformersTextEmbedder |
sentence-transformers/all-mpnet-base-v2 |
查询侧:把单条字符串编码为向量 |
| 稠密嵌入 | SentenceTransformersDocumentEmbedder |
sentence-transformers/all-mpnet-base-v2 |
索引侧:把文档列表编码并写入 embedding 字段 |
| 稀疏嵌入 | SentenceTransformersSparseTextEmbedder |
prithivida/Splade_PP_en_v2 |
查询侧:生成 SPLADE 稀疏向量 |
| 稀疏嵌入 | SentenceTransformersSparseDocumentEmbedder |
prithivida/Splade_PP_en_v2 |
索引侧:为文档生成 sparse_embedding 字段 |
| 多模态嵌入 | SentenceTransformersDocumentImageEmbedder |
sentence-transformers/clip-ViT-B-32 |
索引侧:读取图片/PDF 生成图像向量 |
| 相似度排序 | SentenceTransformersSimilarityRanker |
cross-encoder/ms-marco-MiniLM-L-6-v2 |
查询侧:交叉编码器精排 |
| 多样性排序 | SentenceTransformersDiversityRanker |
sentence-transformers/all-MiniLM-L6-v2 |
查询侧:多样性重排去冗余 |
安装方式(对应组件文档,如 sentencetransformersdocumentembedder.mdx):
pip install sentence-transformers-haystack
统一的组件生命周期
所有组件都遵循 Haystack 的标准组件协议,实现四个核心方法:
warm_up():初始化组件,负责把模型加载到内存/显存。Haystack Pipeline 在首次run前会自动调用;单独使用时需要手动调用(多数用例中首次run会延迟加载)。run(...):执行核心推理。嵌入器接收文本或文档列表,排序器接收query与documents。to_dict():把组件序列化为字典,便于存储、传输或保存为 YAML/JSON 管道配置。from_dict(data):从字典反序列化重建组件实例。
通用初始化参数
虽然各组件参数略有差异,但以下参数在几乎所有组件中语义一致:
token:访问 Hugging Face 私有或 gated 模型的 API 令牌。默认从HF_API_TOKEN或HF_TOKEN环境变量读取(strict=False表示环境变量缺失时不报错),也可用Secret.from_token("<your-api-key>")显式传入。详细机制见 docs-website/docs/concepts/secret-management.mdx。device:ComponentDevice | None,指定模型加载设备(CPU/GPU),覆盖自动选择的默认设备。backend:模型推理后端,取值"torch"(默认)、"onnx"、"openvino"。ONNX 与 OpenVINO 提供特定的加速优化,适用于对推理速度敏感的生产场景。model_kwargs/tokenizer_kwargs/config_kwargs:分别透传给模型、分词器、配置加载过程的额外关键字参数,用于精细控制加载行为。trust_remote_code:False时只允许 Hugging Face 官方验证过的模型架构;True时允许加载自定义模型与脚本。local_files_only:True时不尝试从 Hugging Face Hub 下载,只使用本地缓存文件。
稠密嵌入:SentenceTransformersTextEmbedder 与 SentenceTransformersDocumentEmbedder
SentenceTransformersTextEmbedder:查询侧编码
SentenceTransformersTextEmbedder 将单个字符串编码为稠密向量,用于把用户查询转换为向量后交给嵌入检索器。组件文档见 sentencetransformerstextembedder.mdx。
完整构造签名(来自 API 参考):
__init__(
*,
model: str = "sentence-transformers/all-mpnet-base-v2",
device: ComponentDevice | None = None,
token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False),
prefix: str = "",
suffix: str = "",
batch_size: int = 32,
progress_bar: bool = True,
normalize_embeddings: bool = False,
trust_remote_code: bool = False,
local_files_only: bool = False,
truncate_dim: int | None = None,
model_kwargs: dict[str, Any] | None = None,
tokenizer_kwargs: dict[str, Any] | None = None,
config_kwargs: dict[str, Any] | None = None,
precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = "float32",
encode_kwargs: dict[str, Any] | None = None,
backend: Literal["torch", "onnx", "openvino"] = "torch",
revision: str | None = None,
quantization_ranges: list[list[float]] | None = None
) -> None
运行示例:
from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersTextEmbedder
text_embedder = SentenceTransformersTextEmbedder()
print(text_embedder.run("I love pizza!"))
# {'embedding': [-0.07804739475250244, 0.1498992145061493, ...]}
run(text: str) -> dict[str, Any] 返回键 embedding,即输入文本的向量。
SentenceTransformersDocumentEmbedder:索引侧编码
SentenceTransformersDocumentEmbedder 计算文档列表的嵌入并写入每个 Document 的 embedding 字段,同时支持把文档元数据一并嵌入。它通常出现在索引管道中,位于 DocumentWriter 之前。组件文档见 sentencetransformersdocumentembedder.mdx。
完整构造签名:
__init__(
*,
model: str = "sentence-transformers/all-mpnet-base-v2",
device: ComponentDevice | None = None,
token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False),
prefix: str = "",
suffix: str = "",
batch_size: int = 32,
progress_bar: bool = True,
normalize_embeddings: bool = False,
meta_fields_to_embed: list[str] | None = None,
embedding_separator: str = "\n",
trust_remote_code: bool = False,
local_files_only: bool = False,
truncate_dim: int | None = None,
model_kwargs: dict[str, Any] | None = None,
tokenizer_kwargs: dict[str, Any] | None = None,
config_kwargs: dict[str, Any] | None = None,
precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = "float32",
encode_kwargs: dict[str, Any] | None = None,
backend: Literal["torch", "onnx", "openvino"] = "torch",
revision: str | None = None,
quantization_ranges: list[list[float]] | None = None
) -> None
关键参数详解
model:嵌入模型,可传 Hugging Face 模型 ID 或本地路径。默认sentence-transformers/all-mpnet-base-v2。如今 [MTEB 排行榜]上的大多数模型都兼容 Sentence Transformers,具体兼容性可查看模型卡片说明。prefix/suffix:在文本前后追加的字符串。部分检索模型要求指令前缀才能发挥最佳效果,例如 E5 系列需要"passage: "前缀、bge 系列需要特定指令。用法示例:
embedder = SentenceTransformersDocumentEmbedder(
model="intfloat/e5-large-v2",
prefix="passage: ",
)
对应的查询侧(TextEmbedder)若使用 BAAI/bge-large-en-v1.5,则应设置 prefix="Represent this sentence for searching relevant passages:"。
meta_fields_to_embed:需要与文档正文一同嵌入的元数据字段列表。当元数据具有区分性、语义价值时可显著提升检索效果。embedding_separator(默认"\n")决定元数据与正文的拼接分隔符。示例:
from haystack import Document
from haystack_integrations.components.embedders.sentence_transformers import (
SentenceTransformersDocumentEmbedder,
)
doc = Document(content="some text", meta={"title": "relevant title", "page number": 18})
embedder = SentenceTransformersDocumentEmbedder(meta_fields_to_embed=["title"])
docs_w_embeddings = embedder.run(documents=[doc])["documents"]
normalize_embeddings:True时对嵌入做 L2 归一化,使每个向量范数为 1,便于使用余弦相似度比较。batch_size:每次编码的文档数量,默认 32。增大可提速但更耗内存。truncate_dim:把嵌入截断到指定维度,None表示不截断。注意:如果模型未经 Matryoshka Representation Learning 训练,截断会显著损害效果。precision:嵌入精度,取值float32、int8、uint8、binary、ubinary。除float32外均为量化嵌入:体积更小、计算更快,但精度可能下降,适合压缩大规模语料库的嵌入存储(如语义搜索场景)。quantization_ranges:当precision为int8/uint8时使用的校准范围,形状为(2, embedding_dim)——第一行是最小值、第二行是最大值。标量量化默认从当前批次动态校准 min/max 范围,小批次时退化、跨批次不一致;对单个文本(TextEmbedder)甚至会产生无意义结果。因此建议预先用有代表性的嵌入样本计算范围后传入,以获得稳定、与查询侧一致的量化嵌入。encode_kwargs:透传给SentenceTransformer.encode的额外参数,用于精细定制。注意不要与已设置参数冲突,且避免传入会改变输出类型的参数。revision:模型的具体版本,可为分支名、标签名或 commit id。
run(documents: list[Document]) -> dict[str, list[Document]] 返回键 documents,即补充了 embedding 的文档列表。
组合成完整的语义检索管道
将 DocumentEmbedder 用于索引、TextEmbedder 用于查询,配合 InMemoryEmbeddingRetriever 即可组成端到端 RAG 检索链路:
from haystack import Document, Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.writers import DocumentWriter
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack_integrations.components.embedders.sentence_transformers import (
SentenceTransformersTextEmbedder,
SentenceTransformersDocumentEmbedder,
)
document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
documents = [
Document(content="My name is Wolfgang and I live in Berlin"),
Document(content="I saw a black horse running"),
Document(content="Germany has many big cities"),
]
indexing_pipeline = Pipeline()
indexing_pipeline.add_component("embedder", SentenceTransformersDocumentEmbedder())
indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
indexing_pipeline.connect("embedder", "writer")
query_pipeline = Pipeline()
query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
query = "Who lives in Berlin?"
indexing_pipeline.run({"documents": documents})
result = query_pipeline.run({"text_embedder": {"text": query}})
print(result["retriever"]["documents"][0])
提示:若 TextEmbedder 与 DocumentEmbedder 使用同一模型,Haystack 底层会共享同一模型资源,节省内存。
稀疏嵌入:SPLADE 模型与 SentenceTransformersSparseTextEmbedder / SparseDocumentEmbedder
稀疏嵌入用于稀疏检索:每个非零值代表词汇表中某个词的重要度权重。SPLADE(SParse Lexical AnD Expansion)技术把学习式稀疏表示与传统稀疏检索的效率结合,同时支持 prefix/suffix 与元数据嵌入。
SentenceTransformersSparseTextEmbedder
用于把查询字符串编码为稀疏向量,供稀疏嵌入检索器使用。默认模型 prithivida/Splade_PP_en_v2。
from haystack_integrations.components.embedders.sentence_transformers import SentenceTransformersSparseTextEmbedder
text_embedder = SentenceTransformersSparseTextEmbedder()
print(text_embedder.run("I love pizza!"))
# {'sparse_embedding': SparseEmbedding(indices=[999, 1045, ...], values=[0.918, 0.867, ...])}
构造签名与参数:
__init__(
*,
model: str = "prithivida/Splade_PP_en_v2",
device: ComponentDevice | None = None,
token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False),
prefix: str = "",
suffix: str = "",
trust_remote_code: bool = False,
local_files_only: bool = False,
model_kwargs: dict[str, Any] | None = None,
tokenizer_kwargs: dict[str, Any] | None = None,
config_kwargs: dict[str, Any] | None = None,
backend: Literal["torch", "onnx", "openvino"] = "torch",
revision: str | None = None
) -> None
run(text: str) -> dict[str, Any] 返回键 sparse_embedding,为 SparseEmbedding(indices=..., values=...) 结构。
SentenceTransformersSparseDocumentEmbedder
为文档列表计算稀疏嵌入并写入 sparse_embedding 字段,位于索引管道的 DocumentWriter 之前。除默认模型外,参数与稠密版一致,同样支持 meta_fields_to_embed、embedding_separator、batch_size、progress_bar 等。
from haystack import Document
from haystack_integrations.components.embedders.sentence_transformers import (
SentenceTransformersSparseDocumentEmbedder,
)
doc = Document(content="I love pizza!")
doc_embedder = SentenceTransformersSparseDocumentEmbedder()
result = doc_embedder.run([doc])
print(result['documents'][0].sparse_embedding)
# SparseEmbedding(indices=[999, 1045, ...], values=[0.918, 0.867, ...])
稀疏嵌入检索的更多背景,可参见 docs-website/docs/pipeline-components/retrievers.mdx 中关于稀疏嵌入检索器的章节。SPLADE 兼容模型可在 Hugging Face 上按关键词搜索获得。
多模态嵌入:SentenceTransformersDocumentImageEmbedder
SentenceTransformersDocumentImageEmbedder 使用能够将文本与图像映射到同一向量空间的模型(如 CLIP),为图片或 PDF 文档计算图像嵌入。它要求每个 Document 的某个元数据字段(默认 file_path)包含图片/PDF 文件路径,加载图像、计算嵌入后写入 embedding 字段,同时会在元数据中记录 embedding_source(含 type: 'image' 与 file_path_meta_field)。组件文档见 sentencetransformersdocumentimageembedder.mdx。
完整构造签名:
__init__(
*,
file_path_meta_field: str = "file_path",
root_path: str | None = None,
model: str = "sentence-transformers/clip-ViT-B-32",
device: ComponentDevice | None = None,
token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False),
batch_size: int = 32,
progress_bar: bool = True,
normalize_embeddings: bool = False,
trust_remote_code: bool = False,
local_files_only: bool = False,
model_kwargs: dict[str, Any] | None = None,
tokenizer_kwargs: dict[str, Any] | None = None,
config_kwargs: dict[str, Any] | None = None,
precision: Literal["float32", "int8", "uint8", "binary", "ubinary"] = "float32",
encode_kwargs: dict[str, Any] | None = None,
backend: Literal["torch", "onnx", "openvino"] = "torch"
) -> None
关键参数详解
file_path_meta_field:Document 元数据中存放图片/PDF 路径的字段名,默认"file_path"。root_path:文档文件所在的根目录。提供时,元数据中的路径会相对于该目录解析;为None时按绝对路径处理。model:必须能同时嵌入图像与文本到同一向量空间。官方列出的兼容模型包括:sentence-transformers/clip-ViT-B-32(默认)sentence-transformers/clip-ViT-L-14sentence-transformers/clip-ViT-B-16sentence-transformers/clip-ViT-B-32-multilingual-v1jinaai/jina-embeddings-v4jinaai/jina-clip-v1jinaai/jina-clip-v2
- 其余参数(
device、batch_size、progress_bar、normalize_embeddings、precision、encode_kwargs、backend等)语义与稠密嵌入器一致。
独立运行示例
from haystack import Document
from haystack_integrations.components.embedders.sentence_transformers import (
SentenceTransformersDocumentImageEmbedder,
)
embedder = SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32")
documents = [
Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}),
Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}),
]
result = embedder.run(documents=documents)
documents_with_embeddings = result["documents"]
print(documents_with_embeddings)
# [Document(id=...,
# content='A photo of a cat',
# meta={'file_path': 'cat.jpg',
# 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}},
# embedding=vector of size 512),
# ...]
多模态索引 + 文本检索管道
索引管道由 ImageFileToDocument 转换器(生成含 meta.file_path 的空文档)、SentenceTransformersDocumentImageEmbedder 与 DocumentWriter 组成;检索管道则用同模型的 SentenceTransformersTextEmbedder + InMemoryEmbeddingRetriever,实现"文本查询图像库":
from haystack import Pipeline
from haystack.components.converters.image import ImageFileToDocument
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack.components.writers import DocumentWriter
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack_integrations.components.embedders.sentence_transformers import (
SentenceTransformersTextEmbedder,
SentenceTransformersDocumentImageEmbedder,
)
document_store = InMemoryDocumentStore()
# Indexing pipeline
indexing_pipeline = Pipeline()
indexing_pipeline.add_component("image_converter", ImageFileToDocument())
indexing_pipeline.add_component(
"embedder",
SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32"),
)
indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
indexing_pipeline.connect("image_converter", "embedder")
indexing_pipeline.connect("embedder", "writer")
indexing_pipeline.run(data={"image_converter": {"sources": ["dog.jpg", "hyena.jpeg"]}})
# Multimodal retrieval pipeline
retrieval_pipeline = Pipeline()
retrieval_pipeline.add_component(
"embedder",
SentenceTransformersTextEmbedder(model="sentence-transformers/clip-ViT-B-32"),
)
retrieval_pipeline.add_component(
"retriever",
InMemoryEmbeddingRetriever(document_store=document_store, top_k=2),
)
retrieval_pipeline.connect("embedder", "retriever")
result = retrieval_pipeline.run(data={"text": "man's best friend"})
print(result)
# {'retriever': {'documents': [
# Document(id=0c96..., meta={'file_path': 'dog.jpg', ...}, score=32.02),
# Document(id=5e76..., meta={'file_path': 'hyena.jpeg', ...}, score=20.65)
# ]}}
排序器:SentenceTransformersSimilarityRanker
SentenceTransformersSimilarityRanker 基于预训练的交叉编码器模型(cross-encoder)对查询与文档进行语义精排,返回按相似度从高到低排列的文档列表。它最适合放在查询管道中、检索器之后(如 RAG 管道或文档搜索管道),用于保证检索结果按相关性排序。组件文档见 sentencetransformerssimilarityranker.mdx。
完整构造签名:
__init__(
*,
model: str | Path = "cross-encoder/ms-marco-MiniLM-L-6-v2",
device: ComponentDevice | None = None,
token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False),
top_k: int = 10,
query_prefix: str = "",
query_suffix: str = "",
document_prefix: str = "",
document_suffix: str = "",
meta_fields_to_embed: list[str] | None = None,
embedding_separator: str = "\n",
scale_score: bool = True,
score_threshold: float | None = None,
trust_remote_code: bool = False,
model_kwargs: dict[str, Any] | None = None,
tokenizer_kwargs: dict[str, Any] | None = None,
config_kwargs: dict[str, Any] | None = None,
backend: Literal["torch", "onnx", "openvino"] = "torch",
batch_size: int = 16
) -> None
关键参数详解
model:交叉编码器模型,可传本地路径或 Hugging Face 模型名,默认cross-encoder/ms-marco-MiniLM-L-6-v2。top_k:每次查询最多返回的文档数,默认 10,必须大于 0,否则抛出ValueError。query_prefix/query_suffix:排序前在查询文本前后追加的字符串,用于满足重排模型(如bge需要指令前缀、qwen需要指令后缀)的要求。document_prefix/document_suffix:排序前在每个文档前后追加的字符串,用途同上。meta_fields_to_embed/embedding_separator:决定哪些元数据字段随文档内容一起参与编码。scale_score:True时用 Sigmoid 激活函数对原始 logit 预测进行缩放,得到 0~1 之间的分数;False则直接输出原始 logit。score_threshold:只返回分数高于该阈值的文档。batch_size:推理批大小,默认 16。批越大内存占用越高,遇到内存不足可调小。
run(query, documents, top_k=None, scale_score=None, score_threshold=None) 支持在运行时覆盖初始化时设置的 top_k、scale_score、score_threshold。排序前会按文档 id 去重,保留(若有 score 的)得分最高的文档。
独立使用示例
from haystack import Document
from haystack_integrations.components.rankers.sentence_transformers import SentenceTransformersSimilarityRanker
ranker = SentenceTransformersSimilarityRanker()
docs = [Document(content="Paris"), Document(content="Berlin")]
query = "City in Germany"
result = ranker.run(query=query, documents=docs)
docs = result["documents"]
print(docs[0].content) # 输出与查询最相似的文档
管道内使用:检索器 + 精排
from haystack import Document, Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
from haystack_integrations.components.rankers.sentence_transformers import (
SentenceTransformersSimilarityRanker,
)
docs = [
Document(content="Paris is in France"),
Document(content="Berlin is in Germany"),
Document(content="Lyon is in France"),
]
document_store = InMemoryDocumentStore()
document_store.write_documents(docs)
retriever = InMemoryBM25Retriever(document_store=document_store)
ranker = SentenceTransformersSimilarityRanker()
document_ranker_pipeline = Pipeline()
document_ranker_pipeline.add_component(instance=retriever, name="retriever")
document_ranker_pipeline.add_component(instance=ranker, name="ranker")
document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
query = "Cities in France"
document_ranker_pipeline.run(
data={
"retriever": {"query": query, "top_k": 3},
"ranker": {"query": query, "top_k": 2},
},
)
关于 top_k 的调优建议:Retriever 的
top_k决定召回多少文档,Ranker 的top_k决定返回/转发多少文档。若 Ranker 是管道末组件,输出即为 Ranker 的top_k个文档。将 Retriever 的top_k设小一些,可减少 Ranker 需要处理的文档数,从而加速整条管道。
排序器:SentenceTransformersDiversityRanker
SentenceTransformersDiversityRanker 通过两种策略对文档重排,最大化结果的整体多样性,适合需要覆盖多个话题维度、避免结果高度雷同的检索场景。默认模型为 sentence-transformers/all-MiniLM-L6-v2。组件文档见 sentencetransformersdiversityranker.mdx。
两种排序策略
- Greedy Diversity Order(
greedy_diversity_order,默认):用预训练的 Sentence Transformers 模型编码查询与文档,按"最大化整体多样性"的方式排序,同时考虑文档与查询的相似度。 - Maximum Margin Relevance(
maximum_margin_relevance):对每个文档基于"与查询的相关性"和"与已选文档的差异性"计算 MMR 分数,迭代选择文档,在相关性与多样性之间取得平衡。lambda_threshold(默认0.5)控制这一权衡。
排序前会按文档 id 去重,保留(若有 score 的)得分最高的文档。
完整构造签名
__init__(
*,
model: str = "sentence-transformers/all-MiniLM-L6-v2",
top_k: int = 10,
device: ComponentDevice | None = None,
token: Secret | None = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], strict=False),
similarity: str | DiversityRankingSimilarity = "cosine",
query_prefix: str = "",
query_suffix: str = "",
document_prefix: str = "",
document_suffix: str = "",
meta_fields_to_embed: list[str] | None = None,
embedding_separator: str = "\n",
strategy: str | DiversityRankingStrategy = "greedy_diversity_order",
lambda_threshold: float = 0.5,
model_kwargs: dict[str, Any] | None = None,
tokenizer_kwargs: dict[str, Any] | None = None,
config_kwargs: dict[str, Any] | None = None,
backend: Literal["torch", "onnx", "openvino"] = "torch"
) -> None
关键参数详解
top_k:每次查询最多返回的文档数,默认 10。similarity:比较嵌入的相似度指标,可为"dot_product"或"cosine"(默认),也接受DiversityRankingSimilarity枚举值(可用from_str从字符串转换)。strategy:多样性排序策略,"greedy_diversity_order"(默认)或"maximum_margin_relevance",也接受DiversityRankingStrategy枚举值。lambda_threshold:MMR 策略中相关性与多样性的权衡参数(默认0.5),仅在maximum_margin_relevance策略下生效。query_prefix/query_suffix/document_prefix/document_suffix:查询与文档文本的前后缀指令,用途与嵌入器一致(如 E5、BGE 模型需要指令)。meta_fields_to_embed/embedding_separator:参与嵌入的元数据字段及拼接分隔符。
run(query, documents, top_k=None, lambda_threshold=None) 支持在运行时覆盖 top_k 与 lambda_threshold;若 top_k <= 0 抛出 ValueError。
独立使用示例
from haystack import Document
from haystack_integrations.components.rankers.sentence_transformers import SentenceTransformersDiversityRanker
ranker = SentenceTransformersDiversityRanker(
model="sentence-transformers/all-MiniLM-L6-v2",
similarity="cosine",
)
docs = [
Document(content="Regular Exercise"),
Document(content="Balanced Nutrition"),
Document(content="Positive Mindset"),
Document(content="Eating Well"),
Document(content="Doing physical activities"),
Document(content="Thinking positively"),
]
query = "How can I maintain physical fitness?"
output = ranker.run(query=query, documents=docs)
docs = output["documents"]
print(docs)
管道内使用:BM25 召回 + 多样性重排
from haystack import Document, Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
from haystack_integrations.components.rankers.sentence_transformers import (
SentenceTransformersDiversityRanker,
)
docs = [
Document(content="The iconic Eiffel Tower is a symbol of Paris"),
Document(content="Visit Luxembourg Gardens for a haven of tranquility in Paris"),
Document(content="The Point Alexandre III bridge in Paris is famous for its Beaux-Arts style"),
]
document_store = InMemoryDocumentStore()
document_store.write_documents(docs)
retriever = InMemoryBM25Retriever(document_store=document_store)
ranker = SentenceTransformersDiversityRanker()
document_ranker_pipeline = Pipeline()
document_ranker_pipeline.add_component(instance=retriever, name="retriever")
document_ranker_pipeline.add_component(instance=ranker, name="ranker")
document_ranker_pipeline.connect("retriever.documents", "ranker.documents")
query = "Most famous iconic sight in Paris"
document_ranker_pipeline.run(
data={
"retriever": {"query": query, "top_k": 3},
"ranker": {"query": query, "top_k": 2},
},
)
配套枚举类型
DiversityRankingStrategy(Enum):定义多样性排序策略,提供from_str(string)从字符串转换。DiversityRankingSimilarity(Enum):定义嵌入相似度指标,提供from_str(string)从字符串转换。
序列化:to_dict 与 from_dict
所有组件都实现了标准序列化协议:
to_dict() -> dict[str, Any]:返回包含全部初始化参数的字典(type字段指向组件类路径),可持久化到 JSON/YAML 或随管道配置保存。Haystack 的 YAML 编组工具 依赖此方法实现管道图与参数的完整还原。from_dict(data: dict[str, Any]) -> <Component>:类方法,从字典重建组件实例。反序列化时会恢复模型 ID、设备、后端、token 引用(注意 Secret 通常以环境变量引用形式序列化,不会明文落盘)等全部配置。
embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")
data = embedder.to_dict()
# {'type': 'haystack_integrations.components.embedders.sentence_transformers.sentence_transformers_document_embedder.SentenceTransformersDocumentEmbedder', 'init_parameters': {...}}
restored = SentenceTransformersDocumentEmbedder.from_dict(data)
实战组合:稠密 + 稀疏混合检索管道
将本文组件组合成混合检索(Hybrid Search)管道:文档侧同时生成稠密与稀疏嵌入并写入同一个 Document Store,查询侧并行使用两种检索器,再交由排序器精排,兼顾语义理解与关键词精确匹配:
from haystack import Document, Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.writers import DocumentWriter
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever, InMemoryBM25Retriever
from haystack.components.joiners import DocumentJoiner
from haystack_integrations.components.embedders.sentence_transformers import (
SentenceTransformersDocumentEmbedder,
SentenceTransformersTextEmbedder,
)
from haystack_integrations.components.rankers.sentence_transformers import SentenceTransformersSimilarityRanker
document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
docs = [
Document(content="Haystack is an open-source AI orchestration framework"),
Document(content="Build modular pipelines for retrieval-augmented generation"),
Document(content="Sentence Transformers provide local embedding models"),
]
indexing = Pipeline()
indexing.add_component("doc_embedder", SentenceTransformersDocumentEmbedder())
indexing.add_component("writer", DocumentWriter(document_store=document_store))
indexing.connect("doc_embedder", "writer")
indexing.run({"documents": docs})
query_pipeline = Pipeline()
query_pipeline.add_component("query_embedder", SentenceTransformersTextEmbedder())
query_pipeline.add_component("dense_retriever", InMemoryEmbeddingRetriever(document_store=document_store, top_k=10))
query_pipeline.add_component("sparse_retriever", InMemoryBM25Retriever(document_store=document_store, top_k=10))
query_pipeline.add_component("joiner", DocumentJoiner())
query_pipeline.add_component("ranker", SentenceTransformersSimilarityRanker(top_k=3))
query_pipeline.connect("query_embedder.embedding", "dense_retriever.query_embedding")
query_pipeline.connect("dense_retriever.documents", "joiner.documents")
query_pipeline.connect("sparse_retriever.documents", "joiner.documents")
query_pipeline.connect("joiner.documents", "ranker.documents")
result = query_pipeline.run({
"query_embedder": {"text": "What framework builds LLM pipelines?"},
"sparse_retriever": {"query": "What framework builds LLM pipelines?"},
"ranker": {"query": "What framework builds LLM pipelines?"},
})
print(result["ranker"]["documents"])
总结与适用边界
- 稠密嵌入(TextEmbedder / DocumentEmbedder)适用于大多数语义检索与 RAG 场景,默认
all-mpnet-base-v2开箱即用,可自由替换为任意兼容的 Sentence Transformers 模型。 - 稀疏嵌入(SparseTextEmbedder / SparseDocumentEmbedder)基于 SPLADE 模型,擅长关键词精确匹配与可解释检索,适合与稠密检索构成混合检索。
- 多模态嵌入(DocumentImageEmbedder)使用 CLIP 系列模型实现"文本查图像"或"图像查图像",注意检索时必须使用与索引相同的模型。
- 相似度排序(SimilarityRanker)基于交叉编码器,精度高于双塔嵌入检索,适合对召回结果做精排,但推理成本更高。
- 多样性排序(DiversityRanker)在保证相关性的同时提升结果覆盖度,适合百科问答、新闻聚合等需要多角度答案的场景。
所有组件均支持 torch/onnx/openvino 三种推理后端与多种量化精度,可在性能与准确性之间灵活权衡;组件均遵循 Haystack 标准的 warm_up/run/to_dict/from_dict 生命周期,便于在 docs-website/docs/pipeline-components/ 中展示的各种索引、查询与 RAG 管道中即插即用。