HuggingFaceAPITextEmbedder

다양한 Hugging Face API를 사용해 문자열을 임베딩하는 구성 요소예요.

출처: 문서

본문

HuggingFaceAPITextEmbedder는 서로 다른 Hugging Face API로 문자열을 임베딩하는 데 사용할 수 있어요:

이 컴포넌트는 일반 텍스트를 임베딩하는 데 사용해야 해요. 문서 리스트를 임베딩하려면 HuggingFaceAPIDocumentEmbedder를 사용하세요. 컴포넌트는 기본적으로 HF_API_TOKEN 환경 변수를 사용해요. 그렇지 않으면 초기화 시점에 token으로 Hugging Face API 토큰을 전달할 수 있어요. 토큰이 필요한 경우:

Serverless Inference API를 사용할 때, 또는
Inference Endpoints를 사용할 때.
대표적인 파이프라인 위치: 쿼리/RAG 파이프라인에서 임베딩 Retriever 앞
필수 init 변수: api_type — 사용할 Hugging Face API 유형 / api_params — 다음 키 중 하나를 담은 딕셔너리: model(Hugging Face 모델 ID. api_type이 SERVERLESS_INFERENCE_API일 때 필요) 또는 url(inference endpoint URL. api_type이 INFERENCE_ENDPOINTS 또는 TEXT_EMBEDDINGS_INFERENCE일 때 필요)
필수 run 변수: text — 문자열
출력 변수: embedding — float 리스트
API reference: Hugging Face API
패키지명: huggingface-api-haystack

Usage

pip install huggingface-api-haystack

다른 text Embedder처럼 이 컴포넌트는 instruction을 포함하도록 prefix(그리고 postfix)를 추가할 수 있어요. 자세한 내용은 컴포넌트의 API reference를 참조하세요.

On its own

Using Free Serverless Inference API

이전에 (무료) Hugging Face Inference API로 알려졌던 이 API는 Hugging Face Hub에 호스팅된 많은 모델로 빠르게 실험하게 해 주고, 추론을 Hugging Face 서버에 오프로드해요. rate-limited이며 프로덕션용이 아니에요. 이 API를 사용하려면 무료 Hugging Face 토큰이 필요해요. Embedder는 api_params에서 model을 기대해요.

from haystack_integrations.components.embedders.huggingface_api import (
    HuggingFaceAPITextEmbedder,
)
from haystack.utils import Secret

text_embedder = HuggingFaceAPITextEmbedder(
    api_type="serverless_inference_api",
    api_params={"model": "BAAI/bge-small-en-v1.5"},
    token=Secret.from_token("<your-api-key>"),
)
print(text_embedder.run("I love pizza!"))
# {'embedding': [0.017020374536514282, -0.023255806416273117, ...]}

Using Paid Inference Endpoints

이 경우 모델의 비공개 인스턴스를 Hugging Face가 배포하고, 보통 시간당 요금을 내요. Inference Endpoint를 켜는 방법은 Hugging Face 문서를 보세요. 이 경우에도 Hugging Face 토큰을 제공해야 해요. Embedder는 api_params에서 엔드포인트의 url을 기대해요.

from haystack_integrations.components.embedders.huggingface_api import (
    HuggingFaceAPITextEmbedder,
)
from haystack.utils import Secret

text_embedder = HuggingFaceAPITextEmbedder(
    api_type="inference_endpoints",
    api_params={"url": "<your-inference-endpoint-url>"},
    token=Secret.from_token("<your-api-key>"),
)
print(text_embedder.run("I love pizza!"))
# {'embedding': [0.017020374536514282, -0.023255806416273117, ...]}

Using Self-Hosted Text Embeddings Inference (TEI)

Hugging Face Text Embeddings Inference는 텍스트 임베딩 모델을 효율적으로 배포·서빙하는 툴킷이에요. Serverless Inference API와 Inference Endpoints의 최신 버전을 구동하지만, 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는 api_params에서 TEI 인스턴스의 url을 기대해요.

from haystack_integrations.components.embedders.huggingface_api import (
    HuggingFaceAPITextEmbedder,
)
from haystack.utils import Secret

text_embedder = HuggingFaceAPITextEmbedder(
    api_type="text_embeddings_inference",
    api_params={"url": "http://localhost:8080"},
)
print(text_embedder.run("I love pizza!"))
# {'embedding': [0.017020374536514282, -0.023255806416273117, ...]}

In a pipeline

from haystack import Document
from haystack import Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack_integrations.components.embedders.huggingface_api import (
    HuggingFaceAPITextEmbedder,
    HuggingFaceAPIDocumentEmbedder,
)
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"},
)
documents_with_embeddings = document_embedder.run(documents)["documents"]
document_store.write_documents(documents_with_embeddings)

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', ...)

HuggingFaceAPITextEmbedder