Twelve LabsとFiftyOneプラグインで動画をセマンティックに検索する

このチュートリアルは、Voxel51のMLエバンジェリストであるDaniel Gural氏との共著です。

‍

動画は膨大なデータの宝庫であり、そのすべてが小さなペイロードに詰め込まれています。単一のモダリティとは異なり、動画には画像データと音声データが満載されており、時間の経過に伴う変化も考慮に入れる必要があります。データサイエンティストたちは、これらすべてを解きほぐし、動画の内容を正確に把握するための最善の方法を何年も研究してきました。

新しい時代は新しい課題をもたらします。多くのデータサイエンティストや機械学習エンジニアは、テラバイト規模の動画に直面し、モデルのトレーニングに不可欠なものだけを選択するよう求められています。かつては気が遠くなるような作業でしたが、最新の動画理解技術である「動画セマンティック検索」のおかげで、今では非常に簡単になりました。

このチュートリアルでは、Twelve Labsの動画セマンティック検索のパワーを活用し、高速で再現性の高い検索ワークフローを作成できるFiftyOneプラグインの構築方法を学びます。Twelve Labs APIを活用したい経験豊富なデベロッパーにとっても、FiftyOneオープンソースツールの機能を試してみたい熱心な開発者にとっても、このチュートリアルは動画セマンティック検索をプロジェクトにシームレスに統合するための知識とスキルを身に付けるのに役立ちます。

チュートリアルの完成した成果物は、Semantic Video Search Plugin GitHubページで確認できます。また、この実演の動画はTwelve LabsのYouTubeページ（こちら）でもご覧いただけます。

はじめに

始める前に、プラグインを構築するために必要なものを確認しておきましょう。以下が必要になります：

1. Twelve Labsのアカウント：Twelve Labsは、自然言語クエリを使用したセマンティック検索、ゼロショット分類、動画コンテンツからのテキスト生成などのダウンストリームタスクを可能にする、強力な動画理解用基盤モデルを構築しています。まだ登録していない場合は、無料で参加してください！

2. FiftyOneのGitHubクローンリポジトリ：FiftyOneは、高品質のデータセットとコンピュータビジョンモデルを構築するためのオープンソースツールであり、Voxel51によってメンテナンスされています。

3. FiftyOne Pluginsのクローンリポジトリ：FiftyOneは、ツールの機能を拡張およびカスタマイズできる強力なプラグインフレームワークを提供しています。FiftyOneプラグインの管理や新しいプラグインの開発を行うためのユーティリティが含まれている「FiftyOne Plugins Management and Development」プラグインをインストールしてください。

4. 動画データセット。

必要なものが揃ったら、始め方を見ていきましょう！まず、データをFiftyOneにロードし、Twelve Labs APIが正しく設定されているかテストします。

データセットには、FiftyOneのquickstart-videoデータセットを使用します。これは簡単かつ迅速に起動できます：

import fiftyone as fo
import fiftyone.zoo as foz

dataset = foz.load_zoo_dataset("quickstart-video")

session = fo.launch_app(dataset)

次に、使用するTwelve LabsのAPIキーとAPI URLが定義されていることを確認してください。既存のインデックスを取得することで、正しく設定されているか簡単なテストを行うことができます。まず、キーとURLを環境変数に設定しましょう：

export TWELVE_API_KEY=<YOUR_API_KEY>

または

import os

os.environ['TWELVE_API_KEY'] = <YOUR_API_KEY>

次に、Twelve Labs APIを使用して、既存のインデックスがあるかどうか、また変数が正しく設定されているかを確認します。

import time
import requests
import glob
from pprint import pprint
import os

API_URL = os.getenv("TWELVE_API_URL")
assert API_URL

API_KEY = os.getenv("TWELVE_API_KEY")
assert API_KEY

INDEXES_URL = f"{API_URL}/indexes"

headers = {
	"x-api-key": API_KEY,
	"Content-Type": "application/json"
}

response = requests.get(INDEXES_URL, headers=headers)

レスポンスがエラーではなく、成功のメッセージを返していることを確認してください！

動画セマンティック検索の実行

接続が成功したら、プラグインで実現したい必要なステップを分解できます。達成したい主なゴールは3つあります：

1. インデックスの作成

2. データセットのインデックス登録

3. データセットの検索

ゴール1と2を1つのオペレーターにまとめ、検索用の2つ目のオペレーターを作成します。まずはJupyter Notebookだけで、最初から最後までの一連の流れを試してみましょう。詳細については、FiftyOneドキュメントまたはTwelve Labsドキュメントを参照してください。

1 - 「VideoSearch」という名前のインデックスを作成する

このインデックスでは、visual、text_in_video、またはlogosに沿って検索できます。動画に音声が含まれている場合、Twelve Labsはconversations（対話）も提供しています。

INDEXES_URL = f"{API_URL}/indexes"

INDEX_NAME = "VideoSearch" # Use a descriptive name for your index

headers = {
    "x-api-key": API_KEY
}

data = {
  "engine_id": "marengo2.5",
  "index_options": ["visual",  "text_in_video", "logo"],
  "index_name": INDEX_NAME,
}

response = requests.post(INDEXES_URL, headers=headers, json=data)
INDEX_ID = response.json().get('_id')
print (f'Status code: {response.status_code}')
pprint (response.json())

2 - データセットのインデックス登録

Twelve Labsの要件を満たすために、サンプル動画が4秒以上あるか確認する必要があります。各動画について、Twelve Labsにプッシュし、確認が取れてから次の動画に進みます。

TASKS_URL = f"{API_URL}/tasks"

videos = dataset
for sample in videos:
	if sample.metadata.duration < 4:
    	continue
	else:
    	file_name = sample.filepath.split("/")[-1]
    	file_path = sample.filepath
    	file_stream = open(file_path,"rb")
    
    	headers = {
        	"x-api-key": API_KEY
    	}
    
    	data = {
        	"index_id": INDEX_ID,
        	"language": "en"
    	}
    
    	file_param=[
        	("video_file", (file_name, file_stream, "application/octet-stream")),]
    
    	response = requests.post(TASKS_URL, headers=headers, data=data, files=file_param)
    	TASK_ID = response.json().get("_id")
    	print (f"Status code: {response.status_code}")
    	pprint (response.json())
    
    	TASK_STATUS_URL = f"{API_URL}/tasks/{TASK_ID}"
    	while True:
        	response = requests.get(TASK_STATUS_URL, headers=headers)
        	STATUS = response.json().get("status")
        	if STATUS == "ready":
            	break
        	time.sleep(10)
   	 
    	VIDEO_ID = response.json().get('video_id')
    	sample["Twelve ID"] = VIDEO_ID
    	sample.save()
      
    	print (f"Status code: {STATUS}")
    	print(f"VIDEO ID: {VIDEO_ID}")
    	pprint (response.json())

3 - データセットの検索クエリを実行する

例えば、「sunny day」（晴れの日）と検索すると、このクエリに一致する検索結果が得られます。

prompt = "sunny day"
SEARCH_URL = f"{API_URL}/search"

headers = {
	"x-api-key": API_KEY
}

data = {
	"query": prompt,
	"index_id": INDEX_ID,
	"search_options": ["visual", "text_in_video", "logo"],
}

response = requests.post(SEARCH_URL, headers=headers, json=data)

ワークフローをテストして検証できたら、それをFiftyOneプラグインに組み込みましょう！まずはFiftyOneのスケルトンオペレーターを構築し、開始用コードを作成します。幸いなことに、FiftyOne Management & Development Pluginがこれに役立ちます！ `build operator skeleton` オペレーターを使用することで、すべてのカスタムコードブロックを作成できます。

プラグイン構築の出発点ができたら、`build plugin component` オペレーターも活用して、残りの入力フィールドやメッセージを構築します。これは、プラグインに追加したいUIモジュールを試すための非常に簡単で素晴らしい方法です。すべてのコードはPythonで提供されるため、含めたいものを簡単に微調整して試すことができます。

スケルトンコードが完成し、Twelve Labsのワークフローが定義されたら、最後のステップはこれらすべてを統合することです！2つのオペレーターに適切なコードを流し込み、保存し、アプリをリフレッシュして、プラグインをテストします！

まとめ

Twelve Labsの動画セマンティック検索を活用することで、デベロッパーはソーシャルメディア、ブランドインサイト、ポッドキャスト、ユーザー生成コンテンツなど、さまざまな業界にわたる幅広いアプリケーションを開発できます。この強力なツールは、文脈に沿った効率的な動画分析と動画コンテンツの検索を可能にし、教育コンテンツの検索、企業ナレッジ管理、動画編集スイートプラットフォームにとって非常に価値のあるものになります。

Twelve Labsは、動画理解のための基盤モデルの構築に特化した先駆的なスタートアップです。当社の最新の動画・言語基盤モデルであるPegasus-1と、一連のvideo-to-text APIは、動画データを総合的に理解するための最先端のソリューションを提供します。一方で、Voxel51は、データ探索と可視化のための強力なプラットフォームを提供するオープンソースツールFiftyOneを手がける企業であり、Twelve Labsの動画セマンティック検索をプロジェクトに統合したいデベロッパーにとって、理想的なパートナーです。

次のステップは？

• クイックスタートチュートリアルをチェックして、Twelve Labsで素晴らしいアプリの構築を始めましょう。

• Playgroundをお試しください。デフォルトの動画クレジットは10時間分です。

• X (Twitter)とLinkedInで最新情報をフォローしてください。

• 他のユーザーやデベロッパーとつながるために、Discordコミュニティに参加しましょう。