
pipeline 中的最常见位置	在索引管道中的 `DocumentWriter` 之前
必需的初始化变量	"api_type": 要使用的 Hugging Face API 类型 "api_params": 一个包含以下键之一的字典 - `model`: Hugging Face 模型 ID。当`api_type` 是`SERVERLESS_INFERENCE_API` 时必需。或 -`url`: 推理终结点的 URL。当`api_type` 是`INFERENCE_ENDPOINTS` 或`TEXT_EMBEDDINGS_INFERENCE 时必需。`. "token": Hugging Face API 令牌。可以通过`HF_API_TOKEN` 或`HF_TOKEN` 环境变量设置。
强制运行变量	“documents”：要计算 embedding 的文档列表
输出变量	“documents”：一个要嵌入的文档列表（已丰富了嵌入信息）
API 参考	Embedders (嵌入器)
GitHub 链接	https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/hugging_face_api_document_embedder.py

概述

HuggingFaceAPIDocumentEmbedder 可用于通过不同的 Hugging Face API 来计算文档嵌入。

📘
此组件应与文档列表一起使用以计算文档嵌入。要嵌入一个字符串，请使用 HuggingFaceAPITextEmbedder。

该组件默认使用默认情况下，使用 HF_API_TOKEN 环境变量。否则，您可以在初始化时通过 token 来传递 Hugging Face API 令牌——请参见下面的代码示例。
令牌是必需的

如果您使用无服务器推理 API，或者
如果您使用推理终结点。

用法

与其他的 Document Embedders 类似，此组件允许添加前缀（和后缀）以包含指令和嵌入元数据。
有关更精细的细节，请参阅该组件的API 参考。

单独使用

使用免费的无服务器推理 API

以前称为（免费）Hugging Face 推理 API，此 API 允许您快速尝试 Hugging Face Hub 上托管的许多模型，并将推理交给 Hugging Face 服务器处理。它受到速率限制，不适用于生产环境。

要使用此 API，您需要一个免费的 Hugging Face 令牌。
Embedder 期望model 在api_params.

from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
from haystack.utils import Secret
from haystack.dataclasses import Document

doc = Document(content="I love pizza!")

document_embedder = HuggingFaceAPIDocumentEmbedder(api_type="serverless_inference_api",
                                              api_params={"model": "BAAI/bge-small-en-v1.5"},
                                              token=Secret.from_token("<your-api-key>"))

result = document_embedder.run([doc])
print(result["documents"][0].embedding)

# [0.017020374536514282, -0.023255806416273117, ...]

使用付费推理终结点

在这种情况下，Hugging Face 会部署模型的私有实例，您通常按小时付费。

要了解如何启动推理终结点，请访问 Hugging Face 文档。

此外，在这种情况下，您需要提供您的 Hugging Face 令牌。
Embedder 期望url 的您的终结点在api_params.

from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
from haystack.utils import Secret
from haystack.dataclasses import Document

doc = Document(content="I love pizza!")

document_embedder = HuggingFaceAPIDocumentEmbedder(api_type="inference_endpoints",
                                              api_params={"url": "<your-inference-endpoint-url>"},
                                              token=Secret.from_token("<your-api-key>"))

result = document_embedder.run([doc])
print(result["documents"][0].embedding)

# [0.017020374536514282, -0.023255806416273117, ...]

使用自托管的文本嵌入推理（TEI）

Hugging Face Text Embeddings Inference 是一个用于高效部署和提供文本嵌入模型的工具包。

虽然它支持无服务器推理 API 和推理终结点的最新版本，但也可以通过 Docker 轻松地在本地使用。

例如，您可以像这样运行一个 TEI 容器：

model=BAAI/bge-large-en-v1.5
revision=refs/pr/5
volume=$PWD/data # share a volume with the Docker container to avoid downloading weights every run

docker run --gpus all -p 8080:80 -v $volume:/data --pull always ghcr.io/huggingface/text-embeddings-inference:1.2 --model-id $model --revision $revision

有关更多信息，请参阅官方 TEI 存储库。

Embedder 期望在 url 中提供您的 TEI 实例的api_params.

from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder
from haystack.dataclasses import Document

doc = Document(content="I love pizza!")

document_embedder = HuggingFaceAPIDocumentEmbedder(api_type="text_embeddings_inference",
                                              api_params={"url": "https://:8080"})

result = document_embedder.run([doc])
print(result["documents"][0].embedding)

# [0.017020374536514282, -0.023255806416273117, ...]

在 pipeline 中

from haystack import Document
from haystack import Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.embedders import HuggingFaceAPITextEmbedder, HuggingFaceAPIDocumentEmbedder
from haystack.components.writers import DocumentWriter
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever

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")]

document_embedder = HuggingFaceAPIDocumentEmbedder(api_type="serverless_inference_api",
				                                           api_params={"model": "BAAI/bge-small-en-v1.5"})

indexing_pipeline = Pipeline()
indexing_pipeline.add_component("document_embedder", document_embedder)
indexing_pipeline.add_component("doc_writer", DocumentWriter(document_store=document_store)
indexing_pipeline.connect("document_embedder", "doc_writer")
indexing_pipeline.run({"document_embedder": {"documents": documents}})

text_embedder = HuggingFaceAPITextEmbedder(api_type="serverless_inference_api",
                                           api_params={"model": "BAAI/bge-small-en-v1.5"})

query_pipeline = Pipeline()
query_pipeline.add_component("text_embedder", text_embedder)
query_pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")

query = "Who lives in Berlin?"

result = query_pipeline.run({"text_embedder":{"text": query}})

print(result['retriever']['documents'][0])

# Document(id=..., content: 'My name is Wolfgang and I live in Berlin', ...)