VLLMTextEmbedder

vLLM으로 서빙된 모델로 문자열의 임베딩을 계산해 주는 컴포넌트예요. 쿼리를 임베딩 검색에 넘기기 전에 임베딩할 때 사용해요.

파이프라인에서 가장 흔한 위치: 쿼리/RAG 파이프라인의 임베딩 Retriever 앞 필수 init 변수: model — vLLM이 서빙하는 모델 이름 필수 run 변수: text — 문자열 출력 변수: embedding — 벡터(float 리스트) API 레퍼런스: vLLM GitHub 링크: https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/vllm 패키지 이름: vllm-haystack

출처: 문서

본문

개요 (Overview)

vLLM은 LLM을 위한 고처리량·메모리 효율적 추론/서빙 엔진이에요. OpenAI 호환 HTTP 서버를 노출하는데, VLLMTextEmbedder가 Embeddings API를 통해 임베딩을 계산하는 데 사용해요.

VLLMTextEmbedder는 api_base_url 파라미터(기본 http://localhost:8000/v1)에서 접근 가능한 vLLM 서버가 실행 중이어야 해요. 이 컴포넌트를 사용해 단순한 문자열(예: 쿼리)을 벡터로 임베딩해요. 문서 리스트를 임베딩할 때는 VLLMDocumentEmbedder를 사용해요.

임베딩 검색을 수행할 때는 이 컴포넌트를 먼저 사용해 쿼리를 벡터로 변환해요. 그런 다음 임베딩 Retriever가 그 벡터로 유사하거나 관련 있는 문서를 검색해요.

vLLM 서버를 --api-key로 시작했다면, Haystack의 Secret API를 통해 VLLM_API_KEY 환경 변수나 api_key init 파라미터로 API 키를 제공하세요.

호환 모델 (Compatible models)

vLLM은 다양한 임베딩 모델을 지원해요. 지원되는 아키텍처와 모델 목록은 vLLM pooling models 문서를 참고하세요.

vLLM 특유 파라미터 (vLLM-specific parameters)

extra_parameters 딕셔너리로 vLLM 특유 파라미터를 전달할 수 있어요. 이 값들은 OpenAI 호환 임베딩 엔드포인트에 extra_body로 전달돼요. 표준 OpenAI Embeddings API에 없는 파라미터(예: truncate_prompt_tokens, truncation_side)를 넘길 때 사용해요. 자세한 내용은 vLLM Embeddings API 문서를 참고하세요.

embedder = VLLMTextEmbedder(
    model="google/embeddinggemma-300m",
    extra_parameters={"truncate_prompt_tokens": 256, "truncation_side": "right"},
)

Matryoshka 임베딩 (Matryoshka embeddings)

모델이 Matryoshka Representation Learning으로 학습됐다면, dimensions 파라미터로 출력 벡터의 차원을 줄일 수 있어요. 자세한 내용은 vLLM Matryoshka 문서를 참고하세요.

지시어 (Instructions)

일부 임베딩 모델은 검색에 더 잘 동작하도록 텍스트 앞에 지시어(instruction)를 붙여야 해요. 예를 들어 BAAI/bge-large-en-v1.5를 쓴다면 쿼리 앞에 다음과 같은 지시어를 붙여야 해요: "Represent this sentence for searching relevant passages:".

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

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

사용법 (Usage)

VLLMTextEmbedder를 쓰려면 vllm-haystack 패키지를 설치해요:

pip install vllm-haystack

vLLM 서버 시작 (Starting the vLLM server)

이 컴포넌트를 쓰기 전에 임베딩 모델로 vLLM 서버를 시작하세요:

vllm serve google/embeddinggemma-300m

서버 옵션에 대한 자세한 내용은 vLLM CLI 문서를 참고하세요.

단독으로 사용하기 (On its own)

from haystack_integrations.components.embedders.vllm import VLLMTextEmbedder

text_embedder = VLLMTextEmbedder(model="google/embeddinggemma-300m")
print(text_embedder.run("I love pizza!"))
# {'embedding': [-0.0215301513671875, 0.01499176025390625, ...], 'meta': {...}}

파이프라인 안에서 사용하기 (In a pipeline)

from haystack import Document, Pipeline
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack_integrations.components.embedders.vllm import (
    VLLMDocumentEmbedder,
    VLLMTextEmbedder,
)

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 = VLLMDocumentEmbedder(model="google/embeddinggemma-300m")
documents_with_embeddings = document_embedder.run(documents)["documents"]
document_store.write_documents(documents_with_embeddings)

query_pipeline = Pipeline()
query_pipeline.add_component(
    "text_embedder",
    VLLMTextEmbedder(model="google/embeddinggemma-300m"),
)
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: ...)

VLLMTextEmbedder