Haystack 中的 Sentence Transformers 集成:稠密/稀疏/多模态嵌入与语义排序完整指南

原创2026-09-11 23:48:011,840 阅读
文章标签:人工智能大模型RAGAI AgentAgent 框架Agent 编排AI 应用提示工程

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-14
    • sentence-transformers/clip-ViT-B-16
    • sentence-transformers/clip-ViT-B-32-multilingual-v1
    • jinaai/jina-embeddings-v4
    • jinaai/jina-clip-v1
    • jinaai/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。

两种排序策略

  1. Greedy Diversity Order(greedy_diversity_order,默认):用预训练的 Sentence Transformers 模型编码查询与文档,按"最大化整体多样性"的方式排序,同时考虑文档与查询的相似度。
  2. 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 管道中即插即用。

登录后查看全文
haystack