
pipeline 中的最常见位置	在索引管道中的 `DocumentWriter` 之前
必需的初始化变量	"token"（仅适用于私有模型）：Hugging Face API 令牌。可以设置为`HF_API_TOKEN` 或`HF_TOKEN` 环境变量设置。
强制运行变量	"documents": 文档列表，其中包含一个包含图像文件路径的 meta 字段
输出变量	"documents": 文档列表（已添加 embedding）
API 参考	Embedders (嵌入器)
GitHub 链接	https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/image/sentence_transformers_doc_image_embedder.py

概述

SentenceTransformersDocumentImageEmbedder 期望文档列表包含一个元字段中的图像或 PDF 文件路径。元字段可以通过file_path_meta_field 初始化参数指定。

该嵌入器高效加载图像，使用 Sentence Transformers 模型计算嵌入，并将每个嵌入存储在embedding 字段中。

SentenceTransformersDocumentImageEmbedder 通常用于索引管道。在检索时，您需要使用相同的模型和SentenceTransformersTextEmbedder 来嵌入查询，然后才能使用 Embedding Retriever。

您可以设置device 参数以在 CPU 或 GPU 上使用 HF 模型。

此外，您还可以选择用于 Sentence Transformers 模式的后端，使用backend 参数。torch（默认），onnx，或openvino。ONNX 和 OpenVINO 支持特定的速度优化；更多信息请参阅 Sentence Transformers 文档。

身份验证

只有在访问私有或受限模型时才需要使用 Hugging Face API 令牌进行身份验证。

该组件使用HF_API_TOKEN 或HF_TOKEN 环境变量，或者您可以在初始化时传递 Hugging Face API Token。有关更多信息，请参阅我们的 Secret Management 页面。

兼容的模型

为了与此组件一起使用，模型必须与 Sentence Transformers 兼容，并且

能够将图像和文本嵌入到同一个向量空间。兼容的模型包括

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

用法

单独使用

from haystack import Document
from haystack.components.embedders.image import SentenceTransformersDocumentImageEmbedder

embedder = SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32")
embedder.warm_up()

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),
#  ...]

在 pipeline 中

在此示例中，我们可以看到一个包含 3 个组件的索引管道

ImageFileToDocument 转换器，它创建空文档，并在 meta.file_path 字段，
SentenceTransformersDocumentImageEmbedder，它会加载图像，计算嵌入并将它们存储在文档中。
DocumentWriter，它将文档写入InMemoryDocumentStore

还有一个多模态检索管道，由一个SentenceTransformersTextEmbedder（使用与之前相同的模型）和一个InMemoryEmbeddingRetriever.

from haystack import Pipeline
from haystack.components.converters.image import ImageFileToDocument
from haystack.components.embedders import SentenceTransformersTextEmbedder
from haystack.components.embedders.image import SentenceTransformersDocumentImageEmbedder
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack.components.writers import DocumentWriter
from haystack.document_stores.in_memory import InMemoryDocumentStore

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',
#                     'embedding_source': {
#                         'type': 'image',
#                         'file_path_meta_field': 'file_path'
#                     }
#                 },
#                 score=32.025817780129856
#             ),
#             Document(
#                 id=5e76...,
#                 meta={
#                     'file_path': 'hyena.jpeg',
#                     'embedding_source': {
#                         'type': 'image',
#                         'file_path_meta_field': 'file_path'
#                     }
#                 },
#                 score=20.648225327085242
#             )
#         ]
#     }
# }

其他参考资料

🧑‍🍳 食谱：M 模态简介