TwelveLabsとQdrantを使用したセマンティックビデオ検索ワークフローの構築

このチュートリアルでご協力いただいたQdrantチーム（David Myriel氏およびAnush Shetty氏）に深く感謝いたします。

はじめに

今日のデータ駆動型の世界において、動画コンテンツはビジュアル、音声、テキストなどの複数のモダリティ（様式）を組み合わせた豊富な情報源です。しかし、動画から有意義なインサイトを抽出し、それらに対するセマンティック検索を可能にすることは、その複雑さゆえに困難な場合があります。ここで、TwelveLabs Embed APIとQdrantの連携が力を発揮します。

TwelveLabs Embed APIは、視覚的表現、ボディランゲージ、話し言葉、文脈的ヒントを含む、動画コンテンツの本質を捉えるマルチモーダルな埋め込み（embeddings）の作成をディベロッパーに可能にします。これらの埋め込みは統一されたベクトル空間に対して最適化されており、シームレスなクロスモーダル理解を実現します。一方で、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次元の動画ネイティブな埋め込みに最適化されています。ベクトル比較のためのコサイン類似度をサポートしており、セマンティック検索や検索（リトリーバル）などのタスクに適しています。また、このエンジンを使用して音声、テキスト、画像を同じベクトル空間に埋め込むことができ、クロスモダリティ検索を実現できます。ちなみに、このエンジンは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は points として動作します。これは、ベクトル、オプションのユニークID、および追加のメタデータを持つペイロードで構成されています。このチュートリアルでは、各動画セグメントの埋め込みをQdrantの PointStruct フォーマットにマッピングします。

ステップ 1: 埋め込みセグメントの抽出

TwelveLabs Embed APIは、以下を含む動画セグメントの埋め込みを生成します：

• ベクトル：高次元の埋め込み。

• メタデータ：開始および終了タイムスタンプ（start_offset_sec と end_offset_sec）および埋め込み範囲（scope）を含みます。

ステップ 2: Qdrantポイントへの変換

動画埋め込みセグメントをループ処理し、Qdrant互換の「points」に変換します。メタデータは各ポイントの 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: コレクションパラメータの定義

このチュートリアルでは：

• ベクトルサイズ：1024（TwelveLabsの埋め込みの次元数に一致）。

• 距離指標：コサイン類似度（正規化されたベクトルを比較するのに最適）。

ステップ 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互換の「points」に変換されました。

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を活用することで：

• テキスト、音声、画像などをクエリとして使用して、クロスモーダル検索を実行できます。

• 統一されたベクトル空間により、異なるモダリティからの埋め込みを比較可能にし、シームレスなマルチモーダル検索を実現します。

6 - 結論と次のステップ

このチュートリアルでは、TwelveLabs Embed APIとQdrantを統合することで、セマンティック動画検索ワークフローを構築する方法について学びました。動画コンテンツからマルチモーダル埋め込みを生成し、Qdrantのベクトルデータベースを活用することで、テキスト、音声、画像などの多様なモダリティにわたってセマンティック検索を実行できる強力なシステムを作成しました。このワークフローは、最先端のAIモデルを拡張性のあるベクトル検索技術と組み合わせ、動画の理解と検索における新たな可能性を切り開くポテンシャルを示しています。

主なポイント

• TwelveLabs Embed APIは、視覚、音声、テキストなどのモダリティ全般にわたって動画コンテンツの本質を捉える、最先端のマルチモーダル埋め込みを提供します。

• Qdrantは、その柔軟なコレクション構造と高性能なクエリ機能を使用して、これらの埋め込みの効率的な保存と類似度検索を可能にします。

• TwelveLabsのモデルによって作成された統一ベクトル空間は、シームレスなクロスモーダル検索を可能にし、テキストによる記述、音声クリップ、画像などを使った動画のクエリを実現します。
  
  

コール・トゥ・アクション（次のアクション）

今後、ディベロッパーや企業の皆様には、次世代のAIアプリケーション構築に向けて、TwelveLabsとQdrantを組み合わせたパワーをぜひ探求していただきたいと考えています。セマンティック動画検索、パーソナライズされた推薦システム、革新的なRAGワークフローなど、このパートナーシップはマルチモーダルデータとのインタラクションのあり方を再定義する準備が整っています。

• Colab ノートブック

• Qdrant ドキュメント：Twelve Labs

• Twelve Labs Embed API ドキュメント