TwelveLabsVideoConverter

비디오를 TwelveLabs의 Pegasus 비디오-언어 모델로 분석해 Haystack Document로 바꿔 주는 컴포넌트예요. 각 소스 비디오가 하나의 Document가 돼요.

파이프라인에서 가장 흔한 위치: 인덱싱 파이프라인의 시작, PreProcessor나 embedder 앞 필수 init 변수: api_key — TwelveLabs API 키. TWELVELABS_API_KEY 환경 변수로도 설정할 수 있어요. 필수 run 변수: sources — 비디오 URL 또는 로컬 파일 경로 리스트 출력 변수: documents — 문서 리스트 API 레퍼런스: TwelveLabs GitHub 링크: https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/twelvelabs 패키지 이름: twelvelabs-haystack

출처: 문서

본문

개요 (Overview)

TwelveLabsVideoConverter는 비디오 소스 리스트를 받아 소스마다 하나의 Document를 만들어요. Document의 content는 Pegasus의 텍스트 분석 결과로 설정돼요. Pegasus는 각 비디오를 그 자리에서 분석하는데, 시각 정보 그리고 (ASR을 통한) 자체 오디오까지 함께 봐요. 그래서 결과 텍스트가 나오고, 각 소스 비디오는 하나의 Document가 되며 그 content는 Pegasus의 분석(예: 설명 + 트랜스크립트)이에요. 프레임 추출이나 별도의 전사 단계는 없어요.

소스는 공개적으로 접근 가능한 직접 비디오 URL이거나 로컬 파일 경로(최대 200MB, TwelveLabs에 업로드됨)일 수 있어요. 처리에 실패한 소스는 경고를 남기고 건너뛰기 때문에, 하나의 잘못된 소스가 전체 배치를 실패시키지 않아요.

만들어진 각 Document는 요청에 관한 메타데이터를 담아요. source, asset_id, analysis_id, model, provider가 포함되죠. 기본 모델은 pegasus1.5이에요.

분석을 커스텀 prompt로 유도할 수 있고, temperature와 max_tokens도 조정할 수 있어요.

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

pip install twelvelabs-haystack

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

사용법 (Usage)

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

from haystack_integrations.components.converters.twelvelabs import (
    TwelveLabsVideoConverter,
)

converter = TwelveLabsVideoConverter()
result = converter.run(sources=["https://example.com/clip.mp4"])
document = result["documents"][0]
print(document.content)  # Pegasus's description + transcript of the video
print(document.meta)  # includes source, asset_id, analysis_id, model, provider

info

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

커스텀 프롬프트 사용하기 (With a custom prompt)

from haystack_integrations.components.converters.twelvelabs import (
    TwelveLabsVideoConverter,
)

converter = TwelveLabsVideoConverter(
    prompt="Summarize this video in three bullet points and list any products shown.",
    temperature=0.2,
    max_tokens=1024,
)
result = converter.run(sources=["https://example.com/clip.mp4"])
print(result["documents"][0].content)

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

아래 인덱싱 파이프라인은 Pegasus로 비디오를 분석하고, 결과 분석을 TwelveLabsDocumentEmbedder로 임베딩한 뒤 document store에 써요:

from haystack import Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.writers import DocumentWriter
from haystack_integrations.components.converters.twelvelabs import (
    TwelveLabsVideoConverter,
)
from haystack_integrations.components.embedders.twelvelabs import (
    TwelveLabsDocumentEmbedder,
)

document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")

indexing_pipeline = Pipeline()
indexing_pipeline.add_component("converter", TwelveLabsVideoConverter())
indexing_pipeline.add_component("embedder", TwelveLabsDocumentEmbedder())
indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
indexing_pipeline.connect("converter", "embedder")
indexing_pipeline.connect("embedder", "writer")
indexing_pipeline.run({"converter": {"sources": ["https://example.com/clip.mp4"]}})

메타데이터 붙이기 (Attaching metadata)

딕셔너리 하나를 넘기면 모든 출력 Document에 같은 메타데이터가 적용되고, 리스트를 넘기면 소스마다 메타데이터를 다르게 설정할 수 있어요:

from haystack_integrations.components.converters.twelvelabs import (
    TwelveLabsVideoConverter,
)

converter = TwelveLabsVideoConverter()

# Same metadata for all sources
result = converter.run(
    sources=["https://example.com/a.mp4", "https://example.com/b.mp4"],
    meta={"campaign": "demo"},
)

# Per-source metadata
result = converter.run(
    sources=["https://example.com/a.mp4", "https://example.com/b.mp4"],
    meta=[{"title": "Clip A"}, {"title": "Clip B"}],
)

TwelveLabsVideoConverter