TwelveLabs와 Qdrant로 시맨틱 비디오 검색 워크플로우 구축하기

이 튜토리얼을 위해 함께 협업해 준 Qdrant 팀의 (David Myriel 및 Anush Shetty)에게 진심으로 감사 드립니다.

소개

오늘날의 데이터 중심 시대에서 비디오 콘텐츠는 시각, 오디오, 텍스트를 비롯한 여러 모달리티가 결합된 풍부한 정보의 원천입니다. 그러나 비디오가 가진 복잡성 때문에 비디오에서 의미 있는 인사이트를 추출하고 의미론적(semantic) 검색을 구현하는 작업은 까다로울 수 있습니다. 이때 TwelveLabs Embed API와 Qdrant의 강력한 통합이 빛을 발합니다.

TwelveLabs Embed API를 활용하면 개발자는 시각적 표현, 보디랭귀지, 음성 언어 및 맥락적 신호를 포함하는 비디오 콘텐츠의 본질을 완벽하게 포착하는 멀티모달 임베딩을 생성할 수 있습니다. 이 임베딩은 통합된 벡터 공간에 최적화되어 있어 매끄러운 크로스 모달 이해를 가능하게 합니다. 반면, Qdrant는 이러한 임베딩을 효율적으로 저장하고 쿼리할 수 있도록 지원하는 강력한 벡터 유사도 검색 엔진입니다.

본 튜토리얼에서는 TwelveLabs의 멀티모달 임베딩 기능과 Qdrant의 벡터 검색 엔진을 결합하여 의미론적 비디오 검색 워크플로우를 구축하는 방법을 보여줍니다. 이 가이드를 마칠 때쯤 여러분은 다음과 같은 작업을 수행할 수 있게 됩니다.

• TwelveLabs Embed API를 사용하여 비디오용 멀티모달 임베딩을 생성합니다.

• 이러한 임베딩을 Qdrant에 저장하고 관리합니다.

• 텍스트 또는 기타 모달리티를 사용하여 비디오 콘텐츠 전반에 걸쳐 의미론적 검색을 수행합니다.

이 워크플로우는 비디오 인덱싱, 콘텐츠 추천 시스템, 맥락적 검색 엔진과 같은 애플리케이션에 이상적입니다.

1 - 환경 설정

구현에 들어가기 앞서, 필요한 도구와 라이브러리를 설치해 보겠습니다. 이번 튜토리얼에서는 Colab 노트북 환경에서 Python을 준비해 사용합니다.

단계 1: 필수 SDK 설치

Colab 노트북에서 다음 명령을 실행하여 TwelveLabs 및 Qdrant SDK를 설치합니다.

!pip install twelvelabs qdrant-client

단계 2: API 클라이언트 구성

그 다음, 각각의 라이브러리를 임포트하고 API 키를 사용하여 초기화함으로써 TwelveLabs 및 Qdrant 클라이언트를 구성합니다.

from twelvelabs import TwelveLabs
from qdrant_client import QdrantClient

# Get your API keys from: https://playground.twelvelabs.io/dashboard/api-key
from google.colab import userdata
TL_API_KEY=userdata.get('TL_API_KEY')

twelvelabs_client = TwelveLabs(api_key=TL_API_KEY)
qdrant_client = QdrantClient(":memory:")

2 - TwelveLabs로 멀티모달 임베딩 생성하기

TwelveLabs Embed API를 사용하면 시각 정보, 오디오, 텍스트와 같은 모달리티 전반에 걸쳐 비디오 콘텐츠의 본질을 완벽히 포착하는 멀티모달 임베딩을 생성할 수 있습니다. 이 임베딩은 고차원 벡터로 표현되어 매끄러운 의미론적 검색과 크로스 모달 이해를 구현합니다. 이번 세션에서는 Marengo-retrieval-2.7 엔진을 활용하여 비디오용 비디오 임베딩을 생성하는 방법을 보여드립니다.

단계 1: 임베딩 프로세스 이해하기

Marengo-retrieval-2.7 엔진은 1024 차원의 비디오 네이티브 임베딩에 최적화되어 있습니다. 이 엔진은 벡터 비교를 위해 코사인 유사도(cosine similarity)를 지원하므로 의미론적 검색이나 검색(retrieval) 작업에 적합합니다. 또한 이 엔진을 사용하면 오디오, 텍스트, 이미지를 동일한 벡터 공간에 임베딩하여 크로스 모달 검색을 구현할 수 있습니다. 참고로 이 엔진은 TwelveLabs의 최첨단 비디오 임베딩 모델인 Marengo 2.7을 기반으로 개발되었습니다.

단계 2: 비디오 임베딩 생성하기

비디오용 임베딩을 생성하려면 다음 단계를 따르세요.

1. 비디오 URL 지정: 처리하고자 하는 비디오의 URL을 제공합니다.

2. 임베딩 태스크 생성: TwelveLabs 클라이언트를 사용하여 임베딩 태스크를 시작합니다.

3. 태스크 완료 대기: 태스크 상태를 모니터링하며 완료될 때까지 기다립니다.

4. 임베딩 결과 가져오기: 완료되면 태스크 결과에서 벡터 임베딩을 가져옵니다.

다음은 Python 구현 코드입니다:

# Step 1: Create an embedding task
task = twelvelabs_client.embed.task.create(
    model_name="Marengo-retrieval-2.7",  # Specify the model
    video_url="https://sample-videos.com/video321/mp4/720/big_buck_bunny_720p_2mb.mp4"  # Video URL
)

# Step 2: Wait for the task to complete
task.wait_for_done(sleep_interval=3)  # Check every 3 seconds

# Step 3: Retrieve the embeddings
task_result = twelvelabs_client.embed.task.retrieve(task.id)

# Display the embedding results
print("Embedding Vector (First 10 Dimensions):", task_result.embeddings[:10])
print("Embedding Dimensionality:", len(task_result.embeddings))

단계 3: 크로스 모달리티 임베딩 (선택 사항)

동일한 엔진을 사용하여 다른 모달리티(예: 텍스트, 오디오, 이미지)를 통합 벡터 공간에 임베딩할 수 있습니다. 예를 들면 다음과 같습니다.

• 텍스트: "자전거를 타고 있는 사람"과 같은 설명형 텍스트를 입력합니다.

• 오디오: 오디오 파일 URL을 사용하여 의미론적 표현 성분을 추출합니다.

• 이미지: 임베딩을 생성할 이미지 URL을 제공합니다.

이러한 유연성 덕분에 텍스트나 오디오 설명을 사용하여 비디오 컬렉션을 쿼리하는 등 크로스 모달리티 검색을 수행할 수 있습니다.

단계 4: 다음 단계

임베딩을 정상적으로 생성했다면, 효율적인 유사도 검색을 위해 Qdrant와 같은 벡터 데이터베이스에 저장할 수 있습니다. 다음 섹션에서는 이러한 임베딩을 Qdrant에 삽입할 수 있도록 준비하고, 비디오 콘텐츠 전반에 걸쳐 의미론적 검색을 수행하는 방안을 알아보겠습니다.

3 - Qdrant용 데이터 준비하기

TwelveLabs Embed API를 사용해 멀티모달 임베딩을 생성했다면, 다음 단계는 이 임베딩을 Qdrant에 삽입할 수 있도록 변환하는 것입니다. Qdrant는 벡터, 선택적 고유 ID, 그리고 추가 메타데이터가 포함된 페이로드(payload)로 구성된 포인트(point)를 기반으로 작동합니다. 이번 튜토리얼에서는 각 비디오 세그먼트의 임베딩을 Qdrant 고유의 PointStruct 포맷으로 변환해 보겠습니다.

단계 1: 임베딩 세그먼트 추출하기

TwelveLabs Embed API는 비디오 세그먼트별로 임베딩을 생성하며, 각 세그먼트에는 다음 정보가 포함됩니다.

• 벡터(Vector): 고차원 임베딩 값.

• 메타데이터(Metadata): 시작 및 종료 타임스탬프(start_offset_sec 및 end_offset_sec)와 임베딩 범위(scope)가 포함됩니다.

단계 2: Qdrant 포인트로 변환하기

비디오 임베딩 세그먼트를 순회하며 Qdrant 호환 포인트로 변환하겠습니다. 메타데이터는 각 포인트의 페이로드(payload) 내에 저장됩니다.

이를 구현하는 Python 코드는 다음과 같습니다:

from qdrant_client.models import PointStruct

# Convert embedding segments to Qdrant points
points = [
    PointStruct(
        id=idx,  # Unique identifier for each vector
        vector=v.embeddings_float,  # Embedding vector
        payload={
            "start_offset_sec": v.start_offset_sec,  # Start time of the segment
            "end_offset_sec": v.end_offset_sec,      # End time of the segment
            "embedding_scope": v.embedding_scope,   # Scope of the embedding
        },
    )
    for idx, v in enumerate(task_result.video_embedding.segments)
]

print(f"Prepared {len(points)} points for insertion into Qdrant.")

이제 데이터를 Qdrant 컬렉션에 바로 삽입할 준비가 완료되었습니다.

4 - Qdrant 컬렉션 빌드하기

Qdrant는 벡터들을 명명된 포인트 세트인 컬렉션(collections)으로 구조화하여 구성합니다. 각 컬렉션은 벡터의 차원 수, 거리 측정법(예: 코사인 유사도) 등의 특정 파라미터를 가집니다. 준비해 둔 포인트를 저장할 컬렉션을 하나 만듭니다.

단계 1: 컬렉션 파라미터 정의하기

이번 튜토리얼 설정 값:

• 벡터 크기(Vector Size): 1024 (TwelveLabs 임베딩의 차원 수와 일치시킵니다).

• 거리 측정법(Distance Metric): 코사인 유사도(정규화된 벡터 비교에 최적화된 방식).

단계 2: 컬렉션 생성

다음 코드를 빌드하여 Qdrant 내에 컬렉션을 생성합니다.

from qdrant_client.models import VectorParams, Distance

# Define collection name
collection_name = "twelve_labs_collection"

# Create a collection with specified parameters
qdrant_client.create_collection(
    collection_name,
    vectors_config=VectorParams(
        size=1024,  # Dimensionality of vectors
        distance=Distance.COSINE,  # Similarity metric
    ),
)

print(f"Collection '{collection_name}' created successfully.")

단계 3: 컬렉션에 포인트 삽입하기

컬렉션이 준비되었으므로, 변환해 두었던 포인트를 삽입합니다.

# Insert points into the collection
qdrant_client.upsert(collection_name, points)

print(f"Inserted {len(points)} points into '{collection_name}'.")

요약

여기까지 도달했을 때 수행된 작업들:

1. 임베딩 결과가 Qdrant와 호환되는 포인트 형태로 포맷팅되었습니다.

2. 적절한 파라미터 규격을 갖춘 새로운 컬렉션이 생성되었습니다.

3. 포인틀들이 해당 컬렉션 내부로 완벽하게 삽입되었습니다.

다음 섹션에서는 이 컬렉션을 쿼리하여 실제 비디오에서 의미론적 검색을 수행해 보겠습니다.

5 - 의미론적 검색 실행하기

임베딩이 Qdrant에 적재되었으므로 이제 텍스트, 오디오, 이미지 등 상이한 성격의 모달리티를 사용해 의미론적 검색을 가동할 수 있습니다. 이 섹션은 TwelveLabs Embed API를 통해 생성된 임베딩 쿼리를 이용해 Qdrant 컬렉션을 조회하는 과정을 예시로 설명합니다.

단계 1: 텍스트를 사용해 쿼리하기

텍스트 기반 쿼리를 사용하면 지정된 글자 묘사와 의미적으로 부합하는 비디오 구간 세그먼트를 찾을 수 있게 됩니다. 예컨대, "하얀 토끼 (A white rabbit)"에 상응하는 비디오 조각들을 발굴해 보겠습니다.

# Generate text embedding
text_segment = twelvelabs_client.embed.create(
    model_name="Marengo-retrieval-2.7",
    text="A white rabbit",  # Input query
).text_embedding.segments[0]

# Perform semantic search in Qdrant
text_results = qdrant_client.query_points(
    collection_name=collection_name,
    query=text_segment.embeddings_float,  # Use the embedding vector
)

print("Text Query Results:", text_results)

단계 2: 오디오를 활용해 쿼리하기

오디오 기반 쿼리 기능으로 특정 음반/소리 파일 내에 담긴 청각적 맥락과 조화를 이루는 영상 영역을 추출할 수 있습니다. 예를 들어 음성/소리 클립 주소를 가져와 요청하는 코드입니다.

# Generate audio embedding
audio_segment = twelvelabs_client.embed.create(
    model_name="Marengo-retrieval-2.7",
    audio_url="https://codeskulptor-demos.commondatastorage.googleapis.com/descent/background%20music.mp3",  # Audio file URL
).audio_embedding.segments[0]

# Perform semantic search in Qdrant
audio_results = qdrant_client.query_points(
    collection_name=collection_name,
    query=audio_segment.embeddings_float,  # Use the embedding vector
)

print("Audio Query Results:", audio_results)

단계 3: 이미지를 활용해 쿼리하기

이미지 기반의 쿼리를 태우면 전달된 특정 정지화면 스냅샷 이미지와 의미상 가장 부합하는 영상 세그먼틀들을 찾아내 줍니다. 예제 코드는 하단과 같습니다.

# Generate image embedding
image_segment = twelvelabs_client.embed.create(
    model_name="Marengo-retrieval-2.7",
    image_url="https://gratisography.com/wp-content/uploads/2024/01/gratisography-cyber-kitty-1170x780.jpg",  # Image URL
).image_embedding.segments[0]

# Perform semantic search in Qdrant
image_results = qdrant_client.query_points(
    collection_name=collection_name,
    query=image_segment.embeddings_float,  # Use the embedding vector
)

print("Image Query Results:", image_results)

결론 요약

TwelveLabs Embed API와 Qdrant를 연동하는 것으로 다음과 같은 효과를 거둘 수 있습니다.

• 문자 설명(text), 소리(audio), 이미지(image) 등 임의의 형태로 질문을 기동하여 크로스 모달 통합 검색을 구현할 수 있습니다.

• 공동의 일원화된 고유 메트릭 공간 설계 덕분에 이종 모달리티에서 축적된 벡터 요소를 균일하게 비교 연산할 수 있어 정교한 멀티모달 검색 시나리오를 탄생시킵니다.

6 - 결론 및 다음 단계

이 도움말에서는 TwelveLabs Embed API와 Qdrant를 융합하여 강력한 의미론적 비디오 검색 워크플로우를 구현해 냈습니다. 동영상 클립 수준에서 추출된 고도화된 하이브리드 미디어형 임베딩 요소와 Qdrant만의 탁월한 벡터 컨트롤러 저장소를 결합시켜 텍스트, 사운드 데시벨, 스틸컷 원본을 오고 가는 유려한 서치 구조가 확보되었습니다. 이는 복잡한 대량 비디오 정보를 빠르고 정교하게 인덱싱하고 추출하는 핵심 열쇠가 될 비즈니스 레퍼런스입니다.

주요 핵심 요약

• TwelveLabs Embed API는 비디오 내의 비주얼 이미지, 소리 음향, 자막 캡션 등 이기종 복합 미디어 장벽을 아우르는 동급 최강의 완벽한 멀티모달 분석 벡터를 구축해 냅니다.

• Qdrant는 수없이 유입되는 대규모 벡터 포인트를 유연하고 안전하게 저장하고 빠르고 정교하게 탐색할 수 있도록 고성능 엔진 기능을 상시 제공합니다.

• TwelveLabs 구조 엔진이 제공하는 완결성 높은 단일 차원 축은 글, 음성 전조, 관련 단정적인 그림들로 통합 쿼링 영역을 자유로이 교차하여 매끄러운 조회를 구현시킵니다.
  
  

새로운 가능성을 직접 열어보세요

성장하는 시장 속에 있는 여러 혁신 개발팀 및 엔터프라이즈 사들이 TwelveLabs 기술과 Qdrant 인프라를 활용하여 기존에 없었던 고효율 차세대 인공지능 탐사 앱을 직접 창조해 보기를 권해 드립니다. 시맨틱 동영상 분석, 취향 기반 동반 큐레이션, 진보한 지식 RAG 파이프라인 개발 등 멀티모달 데이터를 마주하는 완전히 새롭고 스마트한 규칙을 함께 수립할 수 있습니다.

• Colab 실습 노트북 공간

• Qdrant 문서 내 Twelve Labs 연동 개발 가이드

• Twelve Labs Embed API 개발 문서 가이드