SentenceTransformersTextEmbedder

SentenceTransformersTextEmbedder

SentenceTransformersTextEmbedder 는 문자열(주로 검색 질의)을 Sentence Transformers 라이브러리와 호환되는 임베딩 모델로 벡터로 바꿔 주는 컴포넌트예요. 임베딩 리트리버를 쓰기 전에 질의를 벡터로 변환해 주는 역할을 하죠.

출처: 문서

본문

개요 (Overview)

이 컴포넌트는 단일 문자열(예: 질의)을 벡터로 임베딩할 때 사용해요. 문서 목록을 임베딩할 때는 SentenceTransformersDocumentEmbedder 를 쓰면 되는데, 이쪽은 문서에 계산된 임베딩(벡터)을 붙여 주는 역할을 해요.

인증 (Authentication)

Hugging Face API 토큰 인증은 Serverless Inference API나 Inference Endpoints를 통해 비공개 또는 gated 모델에 접근할 때만 필요해요. 이 컴포넌트는 HF_API_TOKEN 이나 HF_TOKEN 환경 변수를 사용하고, 초기화 시점에 Hugging Face API 토큰을 직접 넘겨줄 수도 있어요. 자세한 내용은 Secret Management 페이지를 참고하세요.

text_embedder = SentenceTransformersTextEmbedder(
    token=Secret.from_token(""),
)

호환 모델 (Compatible Models)

기본 임베딩 모델은 sentence-transformers/all-mpnet-base-v2 예요. 다른 모델을 쓰고 싶으면 컴포넌트 초기화 시 model 파라미터로 지정하면 돼요. 원본 모델 목록은 Sentence Transformers 문서에서 확인할 수 있어요. 요즘은 MTEB(대규모 텍스트 임베딩 벤치마크) 리더보드의 대부분 모델이 Sentence Transformers와 호환돼요. 모델 카드에서 호환 여부를 확인할 수 있는데, BGE 모델 관련 예시를 참고하면 좋아요.

지시문 (Instructions)

MTEB에서 볼 수 있는 최근 모델 중에는 검색 성능을 높이기 위해 텍스트 앞에 지시문(instruction)을 붙여야 하는 모델이 있어요. 예를 들어 BAAI/bge-large-en-v1.5 를 쓴다면 질의 앞에 다음과 같은 지시문을 붙여야 해요: "Represent this sentence for searching relevant passages:"

SentenceTransformersTextEmbedder 에서는 이렇게 동작해요:

instruction = "Represent this sentence for searching relevant passages:"
embedder = SentenceTransformersTextEmbedder(
    model="BAAI/bge-large-en-v1.5",
    prefix=instruction,
)

팁: 같은 모델 기반의 Text Embedder와 Document Embedder를 만들면 Haystack이 내부적으로 같은 리소스를 재사용해서 자원을 아껴 줘요.

사용법 (Usage)

SentenceTransformersTextEmbedder 를 쓰려면 sentence-transformers-haystack 패키지를 설치해야 해요:

pip install sentence-transformers-haystack

단독으로 쓰기

from haystack_integrations.components.embedders.sentence_transformers import (
    SentenceTransformersTextEmbedder,
)

text_to_embed = "I love pizza!"
text_embedder = SentenceTransformersTextEmbedder()
print(text_embedder.run(text_to_embed))
# {'embedding': [-0.07804739475250244, 0.1498992145061493, ...]}

파이프라인에서 쓰기

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

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?"
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', score: ...)

더 알아보기 (Learn more)