Twelve Labs Embed APIとMongoDB Atlasを使用した、セマンティックビデオ検索の構築

TLDR: Twelve Labsの高度なマルチモーダル埋め込みとMongoDB Atlas Vector Searchを組み合わせることで、強力なセマンティック動画検索アプリケーションを作成する方法をご紹介します。このガイドでは、セットアップ、埋め込み生成、データ保存、インデックス作成、そして動画コンテンツから価値あるインサイトを得るためのベクトル検索の実行手順を順を追って説明します。この統合ガイドの作成にあたり、ご協力いただいたMongoDBチーム（Soumya Pradhan、Ashwin Gangadhar、Rafael Liou、およびGregory Maxson）に深く感謝いたします。

‍

1 - はじめに

データ主導の現代において、効果的な動画検索は極めて重要です。従来の検索方法では、視覚的な手がかり、ボディーランゲージ、話し言葉、文脈などが含まれる複雑な動画データの性質に対応するのが困難でした。セマンティック動画検索は、この課題を解決します。

高度な基盤モデルを使用するセマンティック動画検索は、動画コンテンツを深く解釈し、正確で関連性の高い検索結果を可能にします。動画コンテンツの数値表現である埋め込み（Embeddings）を採用することで、豊かで多面的な情報を捉え、分類、クラスタリング、パーソナライズされたレコメンデーションなどのタスクを可能にします。

Twelve LabsのEmbed APIは、時間の経過に伴う動画コンテンツの相互作用を捉える、最先端のマルチモーダル埋め込みを提供します。スケーラブルなベクトルデータベースであるMongoDB Atlas Vector Searchと組み合わせることで、開発者は強力なセマンティック動画検索アプリケーションを作成し、動画データからインサイトを得ることができます。

このガイドでは、Twelve Labs Embed APIとMongoDB Atlas Vector Searchを使用して、セマンティック動画検索アプリを構築する方法を説明します。環境のセットアップ、動画埋め込み（Video Embeddings）の生成、それらのMongoDBへの保存、ベクトル検索インデックスの作成、そして関連する動画コンテンツをレトリーバルするためのベクトル検索の実行方法について学びます。最後まで進めると、動画検索ワークフローを強化するための堅牢なフレームワークが手に入ります。

‍

2 - 前提条件

Twelve Labs Embed APIとMongoDB Atlas Vector Searchを使用してセマンティック動画検索アプリケーションの構築を開始する前に、以下の前提条件が整っていることを確認してください。

• Twelve LabsのアカウントとAPIキー：Twelve Labsのプラットフォームでアカウントを登録し、APIキーを取得します。このキーはEmbed APIへのリクエストを認証するために使用されます。この機能は現在、限定ベータ版であり、特定のユーザーグループのみに提供されています。アクセスをリクエストするには、こちらのウェイティングリストにご登録ください。

• MongoDB Atlasのアカウントとクラスター：MongoDB Atlasでアカウントを作成し、動画埋め込みを保存および管理するクラスターをセットアップします。

• プログラミング環境のセットアップ：必要なツールとライブラリを使用して開発環境をセットアップします。この実装にはPythonの使用を推奨します。Pythonがインストールされていること、および以下のライブラリがインストールされていることを確認してください。

  • twelvelabs：Twelve Labs SDKと連携するため。

  • pymongo：MongoDB SDKと連携するため。

  • dotenv：環境変数を管理するため（オプションですが推奨）。

‍

3 - 環境のセットアップ

このセクションでは、Twelve Labs Embed APIおよびMongoDB Atlasと連携するためのプログラム環境のセットアップ手順を説明します。

‍

3.1 - 必要なライブラリのインストール

まず、必要なPythonライブラリをインストールします。これはpipを使用して行えます。

pip install twelvelabs pymongo python-dotenv

これにより、Twelve Labs SDKとMongoDB Pythonドライバーがインストールされ、両方のサービスとプログラムで連携できるようになります。

‍

3.2 - Twelve Labs APIクライアントの設定

次に、Twelve Labs APIクライアントを設定します。APIキーを安全に保存するために、プロジェクトディレクトリに.envファイルを作成します。

TL_API_KEY=your_twelve_labs_api_key

次に、Pythonスクリプト（例：config.py）を作成し、.envファイルからAPIキーをロードします。

import os
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Retrieve Twelve Labs API key
TL_API_KEY = os.getenv("TL_API_KEY")

新しいPythonスクリプト（例：twelvelabs_client.py）で、Twelve Labsのクライアントを作成し、クラスターに接続します。

from twelvelabs import TwelveLabs
from config import TL_API_KEY

# Initialize the Twelve Labs client
tl_client = TwelveLabs(api_key=TL_API_KEY)

3.3 - MongoDB Atlasクラスターへの接続

MongoDB Atlasクラスターに接続するには、MongoDBから提供される接続文字列が必要です。この接続文字列を.envファイルに保存します。

MONGODB_URI=your_mongodb_connection_string

次に、config.pyを更新してMongoDB URIをロードします。

# Retrieve MongoDB URI
MONGODB_URI = os.getenv("MONGODB_URI")

新しいPythonスクリプト（例：mongo_client.py）で、MongoDBクライアントを作成し、クラスターに接続します。

from pymongo import MongoClient
from config import MONGODB_URI

# Create a MongoDB client
mongo_client = MongoClient(MONGODB_URI)

# Connect to your database
db = mongo_client.your_database_name

3.4 - セットアップの検証

すべてが正しくセットアップされているか確認するために、MongoDBデータベース内のコレクション名を出力する簡単なスクリプトを実行します。

from mongo_client import db

# Print the names of collections in the database
print(db.list_collection_names())

スクリプトがエラーなしで実行され、コレクション名が出力されれば、環境のセットアップは完了です。動画のアップロードと埋め込みの作成に進む準備が整いました。

‍

4 - 動画のアップロードと埋め込みの作成

このセクションでは、Twelve Labsに動画をアップロードし、Embed APIを使用して動画埋め込みを作成するプロセスを説明します。これらの埋め込みは、動画コンテンツの豊かなマルチモーダルコンテキストを捉えます。

‍

4.1 - Twelve Labsへの動画のアップロード

まず、Twelve Labsに動画をアップロードする必要があります。手順は以下の通りです。

1. 動画ファイルの準備：動画ファイルがサポートされているフォーマットであり、ローカルマシンまたはURLからアクセス可能であることを確認します。

2. 埋め込みタスクの作成：Twelve Labs Embed APIを使用して、新しい動画埋め込みタスクを作成します。このタスクが、動画のアップロードと処理を実行し、埋め込みを生成します。

以下は、埋め込みタスクを作成するためのPythonスクリプトのサンプルです。

from twelvelabs import TwelveLabs
from config import TL_API_KEY
from twelvelabs.models.embed import EmbeddingsTask

# Initialize the Twelve Labs client
tl_client = TwelveLabs(api_key=TL_API_KEY)

# Create a video embedding task for the uploaded video
task = tl_client.embed.task.create(
    engine_name="Marengo-retrieval-2.6",
    video_url="your-video-url"
)
print(
    f"Created task: id={task.id} engine_name={task.engine_name} status={task.status}"
)

このコマンドにより、アップロードされた動画の埋め込み処理が開始されます。

‍

4.2 - タスク進捗の監視

動画埋め込みタスクが正常に完了したことを確認するために、タスクのステータスを監視する必要があります。以下のコードを使用して、埋め込みタスクのステータスを定期的にチェックします。

# Monitor the status of the video embedding task
def on_task_update(task: EmbeddingsTask):
    print(f"  Status={task.status}")

status = task.wait_for_done(
    sleep_interval=2,
    callback=on_task_update
)
print(f"Embedding done: {status}")

この関数は、2秒ごとに埋め込みタスクのステータスをチェックし、タスクが完了するか失敗するまでステータスを出力し続けます。

‍

5 - 動画埋め込みの取得と保存

動画埋め込みタスクが完了したら、埋め込みを取得し、効率的なベクトル検索とレトリーバルのためにMongoDB Atlasに保存できます。

‍

5.1 - 完了した埋め込みのフェッチ

以下のコードを使用して、Twelve Labsから作成済みの埋め込みをフェッチします。

# Retrieve the video embeddings
task_result = tl_client.embed.task.retrieve(task.id)
map(dict, task_result.video_embeddings)

# Store returned embeddings in an array called "records"
records = []
for ele in task_result.video_embeddings:
  foo = dict(ele)
  foo['embedding'] = foo['embedding'].float
  records += [foo]

5.2 - MongoDB向け構造化データへの変換

MongoDBに挿入するために、埋め込みデータを準備します。各埋め込みは、MongoDBコレクション内のドキュメントとして保存できます。

from pymongo import MongoClient
from config import MONGODB_URI

# Create a MongoDB client and connect to the database
mongo_client = MongoClient(MONGODB_URI)
db = mongo_client["mydatabase"]
collection = db["embeddings"]

# Insert the embeddings into the MongoDB collection
collection.insert_many(records)
num_embeddings = collection.count_documents({})
print(f"Inserted {num_embeddings} embeddings into MongoDB.")

5.3 - データ保存の検証

埋め込みが正しく保存されたかを検証するために、MongoDBコレクションにクエリを実行してサンプルのドキュメントを出力します。

# Retrieve and print a sample document
sample_document = collection.find_one()
print("Sample document from MongoDB:", sample_document)

このコードは、関連する埋め込みを組み込んでプロンプトを構築し、LLMに送信して回答を生成します。LLMは提供された埋め込みの文脈（コンテキスト）を利用して、より正確で文脈に沿ったアウトプットを生成します。

‍

6 - Atlasでのベクトル検索インデックスの作成

動画埋め込みの効率的なレトリーバルを可能にするために、MongoDB Atlasでベクトル検索インデックスを作成する必要があります。このインデックスにより、保存された埋め込みに対して類似度検索を実行できるようになります。

‍

6.1. インデックス設定の定義

まず、ベクトル検索インデックスの設定を定義します。MongoDB Atlasでは、ベクトル検索のためにインデックス化される特定のフィールドが必要です。設定例は以下の通りです。

{
  "fields": [{
    "type": "vector",
    "path": "embedding",
    "numDimensions": 1024,
    "similarity": "cosine"
  }]
}

この設定は、1024次元のベクトル次元を持つembeddingフィールドがベクトル検索用にインデックス化されることを指定しています。

‍

6.2 - MongoDB Atlas UIを使用したインデックスの作成

MongoDB AtlasのUIからインデックスを作成するには、以下のドキュメントに従ってください。

1. クラスターに移動：MongoDB Atlasのダッシュボードに移動し、お使いのクラスターを選択します。

2. コレクションにアクセス：「Collections」タブをクリックします。

3. データベースとコレクションを選択：埋め込みが保存されているデータベースとコレクションを選択します。

4. インデックスを作成：「Indexes」タブをクリックし、「Create Index」をクリックします。

5. インデックスを設定：上記のようにインデックス設定を入力し、インデックスを作成します。

‍

6.3 - プログラムによるインデックスの作成

あるいは、Pythonを使用してプログラムでインデックスを作成することもできます。

from pymongo import MongoClient, SearchIndexModel
from config import MONGODB_URI

# Connect to MongoDB Atlas
mongodb_client = MongoClient(MONGODB_URI)
db = mongo_client["mydatabase"]
collection = db["embeddings"]

# Define the index configuration
vector_index_model = SearchIndexModel(
 definition={
   "fields": [
     {
       "type": "vector",
       "numDimensions": 1024,
       "path": "embedding",
       "similarity": "cosine"
     }
   ]
 },
 name="vector_index",
 type="vectorSearch",
)

# Create the vector search index
collection.create_search_index(model=vector_index_model)
print("Vector search index created successfully.")

このスクリプトは、MongoDB Atlasクラスターに接続し、データベースとコレクションを選択し、embeddingフィールドにベクトル検索インデックスを作成します。numDimensionsパラメーターは埋め込みの次元数と一致している必要があり、similarityパラメーターは使用する類似度指標（例：コサイン類似度）を指定します。

‍

7 - ベトル検索の実行

ベクトル検索インデックスが作成できたら、ベクトル検索を実行して類似する動画埋め込みを見つけることができます。このセクションでは、クエリ埋め込みの生成、ベクトル検索クエリの構築、および関連する結果の取得方法を説明します。

‍

7.1 - クエリ埋め込みの生成

ベクトル検索を実行するには、まずクエリ埋め込みが必要です。Twelve Labs Embed APIを使用して、クエリ用の動画またはテキストの埋め込みを生成します。以下のコードは、テキストに対してそれを実行する方法を示しています（詳細はドキュメントをご参照ください）。

from twelvelabs import TwelveLabs
from config import TL_API_KEY

# Initialize the Twelve Labs client
tl_client = TwelveLabs(api_key=TL_API_KEY)

# Create a text embedding task for the text
embedding = tl_client.embed.create(
  engine_name="Marengo-retrieval-2.6",
  text="your-text"
)

print("Created a text embedding")
print(f" Engine: {embedding.engine_name}")
print(f" Embedding: {embedding.text_embedding.float}")

# Extract the query embedding
query_embedding = embedding.text_embedding.float
print("Query embedding generated successfully.")

7.2 - ベクトル検索クエリの構築とベクトル検索の実行

まず、生成されたクエリ埋め込みを使用してベクトル検索クエリを構築します。MongoDB Atlasは、$vectorSearch演算子を介してベクトル検索をサポートしています。

次に、ベクトル検索クエリを実行し、MongoDB Atlasから結果を読み込みます。

# Perform the vector search
search_results = collection.aggregate([
		{"$vectorSearch": 
			{
			  "queryVector": query_embedding,
			  "path": "embedding",
			  "numCandidates": 3,
			  "index": "vector_index",
			  "limit": 2,
			}
		}
	]
)

# Process and display the search results
for result in search_results:
    print(result['embedding'])

8 - アプリケーションの拡張

基本的なセマンティック動画検索機能が完成したら、アプリケーションをさらに堅牢で使いやすくするために、いくつか拡張できる方法があります。

1. ページネーションの実装：大量の検索結果がある場合に、ユーザー体験を向上させ、各クエリが読み込むデータ量を制限するためにページネーションを実装します。これは、MongoDBのskip関数とlimit関数を使用して結果のサブセットを取得することで実現できます。

2. メタデータフィルタリングの追加：動画の時間、アップロード日、タグなどの動画メタデータに基づいたフィルターを追加して、検索機能を強化します。これにより、ユーザーは検索結果を絞り込み、最も関連性の高いコンテンツを迅速に見つけることができます。

3. 検索パフォーマンスの最適化：インデックスの設定やクエリのパラメーターを調整して、ベクトル検索のパフォーマンスを最適化します。ベクトル検索を実行する前にデータを前処理・フィルタリングするために、MongoDBの集計フレームワーク（Aggregation Framework）を使用することを検討してください。

‍

9 - ベストプラクティスと留意事項

セマンティック動画検索アプリケーションの成功と信頼性を確保するために、以下のベストプラクティスとガイドラインを考慮してください。

1. 大量の動画コレクションの処理：大規模な動画コレクションを処理する場合は、システムが効率的にスケールできるようにします。MongoDB Atlasのシャーディング機能を使用して複数のノードにデータを分散させ、パフォーマンスと信頼性を向上させます。

2. 変更された動画の埋め込み更新：動画が変更または更新された場合は、検索結果の正確性を維持するために、データベース内の埋め込みを再生成して更新します。変更を追跡し、シームレスに更新を管理するためのバージョン管理システムを導入してください。

3. APIキーとデータベース接続の保護：Twelve LabsのAPIキーやMongoDBの接続文字列は、環境変数やシークレット管理サービスなどに安全に保存して保護します。定期的にキーをローテーションし、最小特権のアクセス制御を適用してください。

‍

10 - おわりに

このガイドでは、Twelve Labs Embed APIとMongoDB Atlas Vector Searchを使用してセマンティック動画検索アプリケーションを構築する手順を説明しました。Twelve Labsの高度なマルチモーダル埋め込みとMongoDBの効率的なベクトル検索機能を活用することで、動画コンテンツから強力なインサイトを発見できるようになります。環境のセットアップや埋め込みの生成から、ベクトル検索インデックスの作成、検索の実行に至るまで、動画検索ワークフローを向上させるための堅牢なフレームワークが完成しました。

セマンティック動画検索アプリケーションの開発と最適化をさらに進めるために、以下の有用なリソースを参考にしてください。

• Colab ノートブック：このチュートリアルのサンプルコードを収録したノートブックです。

• Twelve Labs ドキュメント：Embed APIを使用するための包括的なガイドとAPIリファレンスです。

• MongoDB Atlas ドキュメント：ベクトル検索機能など、MongoDB Atlasクラスターの設定と管理に関する詳細な導入手順です。

• Twelve Labs Python ライブラリ：Pythonを使用してTwelve Labsと連携するための公式ドキュメントです。

• Pymongo ライブラリ：Pythonを使用してMongoDBと連携するための公式ドキュメントです。

• コミュニティフォーラム：サポートやコラボレーションのために、Twelve Labs DiscordやMongoDB フォーラムで、他の開発者やエキスパートと交流しましょう。

これらのリソースは、Twelve LabsとMongoDBの強力な統合についての理解を深め、最大限に活用するのに役立ちます。