TwelveLabsTextEmbedder

TwelveLabs의 Marengo 다중 모달 임베딩 모델로 문자열을 벡터로 바꿔 주는 컴포넌트예요. 임베딩 Retriever로 검색하기 전에 쿼리를 임베딩할 때 써요.

파이프라인에서 가장 흔한 위치: 쿼리/RAG 파이프라인의 임베딩 Retriever 앞 필수 init 변수: api_key — TwelveLabs API 키. TWELVELABS_API_KEY 환경 변수로도 설정할 수 있어요. 필수 run 변수: text — 문자열 출력 변수: embedding — float 리스트 / meta — 메타데이터 딕셔너리 API 레퍼런스: TwelveLabs GitHub 링크: https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/twelvelabs 패키지 이름: twelvelabs-haystack

출처: 문서

본문

개요 (Overview)

TwelveLabsTextEmbedder는 단순한 문자열(예: 쿼리)을 벡터로 임베딩해요. 문서 리스트를 임베딩할 때는 TwelveLabsDocumentEmbedder를 사용해요. 이 컴포넌트는 각 문서에 계산된 임베딩을 추가해 줘요. 기본 모델은 marengo3.0이에요.

Marengo는 하나의 공유 공간으로 임베딩하기 때문에, 텍스트에서 만들어진 임베딩은 같은 모델의 이미지·오디오·비디오 임베딩과 직접 비교(코사인 유사도)할 수 있어요. 그래서 크로스 모달 검색이 가능해져요.

Haystack에서 이 통합을 쓰려면 패키지를 설치해요:

pip install twelvelabs-haystack

이 컴포넌트는 기본적으로 TWELVELABS_API_KEY 환경 변수를 사용해요. 그렇지 않으면 초기화할 때 api_key로 API 키를 넘길 수 있어요:

from haystack.utils import Secret
from haystack_integrations.components.embedders.twelvelabs import TwelveLabsTextEmbedder

embedder = TwelveLabsTextEmbedder(api_key=Secret.from_token("<your-api-key>"))

API 키를 얻으려면 playground.twelvelabs.io로 가면 돼요.

사용법 (Usage)

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

컴포넌트를 단독으로 쓰는 방법은 이래요:

from haystack_integrations.components.embedders.twelvelabs import TwelveLabsTextEmbedder

text_embedder = TwelveLabsTextEmbedder()

result = text_embedder.run(text="a cat playing piano")
print(result["embedding"])
# [-0.043398008, -0.025287028, -0.0061081843, ...]
print(result["meta"])
# {'model': 'marengo3.0'}

info

TWELVELABS_API_KEY는 파라미터로 설정하는 것보다 환경 변수로 설정하는 걸 권장해요.

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

from haystack import Document, Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.writers import DocumentWriter
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack_integrations.components.embedders.twelvelabs import (
    TwelveLabsDocumentEmbedder,
    TwelveLabsTextEmbedder,
)

document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")

documents = [
    Document(content="a cat playing piano"),
    Document(content="a dog catching a frisbee at the beach"),
    Document(content="a timelapse of a city skyline at night"),
]

indexing_pipeline = Pipeline()
indexing_pipeline.add_component("embedder", TwelveLabsDocumentEmbedder())
indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
indexing_pipeline.connect("embedder", "writer")
indexing_pipeline.run({"embedder": {"documents": documents}})

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

result = query_pipeline.run({"text_embedder": {"text": "feline making music"}})
print(result["retriever"]["documents"][0].content)
# a cat playing piano

TwelveLabsTextEmbedder