Twelve LabsとRoe AIでビデオ検索を強力に強化

TLDR: このチュートリアルでは、Twelve LabsのEmbed APIをRoe AIのプラットフォームと統合して、強力なセマンティック動画検索ソリューションを作成する方法を説明します。これらの手順に従うことで、開発者は最先端の動画埋め込みを活用した、正確でコンテキストを認識する動画検索システムを迅速に構築できます。このチュートリアルの共同制作にご協力いただいたRoe AIチーム（Sam Liang氏とRichard Meng氏）に心より感謝申し上げます。

‍

はじめに

このチュートリアルでは、Twelve LabsのEmbed APIとRoe AIのSQLベースのAIプラットフォームの統合に焦点を当て、動画理解のための高度なツールを開発者に提供します。この統合により、Twelve Labsの動画埋め込みモデルとRoe AIのデータ管理および検索機能が融合し、洗練された動画検索ソリューションの構築が可能になります。

開発者は、この統合を活用して、動画データ内の多様なモダリティにわたるコンテキスト、コンテンツ、ニュアンスを理解するアプリケーションを構築する方法を学ぶことができます。このチュートリアルでは、この統合がどのように複雑な動画データの取り扱いを簡素化し、動画検索機能の精度と効率を向上させるかを探ります。コンテンツプラットフォーム、動画分析ツール、または動画データを伴うあらゆるアプリケーションの開発において、これらの技術をプロジェクトに実装するための貴重な知見を得ることができます。

ステップ 1: app.roe-ai.com から API トークンを取得する

Roe AIを使い始めるには、リクエストの認証に必要となるAPIトークンを取得する必要があります。以下の手順に従ってAPIトークンを取得してください。

1. サインアップまたはログイン: app.roe-ai.com にアクセスし、新規アカウントを作成するか、すでにアカウントをお持ちの場合はログインします。

2. API設定へのアクセス: ログイン後、API設定またはアカウント設定に移動し、APIトークンを生成または表示するオプションを見つけます。

3. APIトークンのコピー: トークンを生成したら、クリップボードにコピーします。このトークンはAPIリクエストで使用されるため、安全に保管してください。

4. コードへのトークンの組み込み: 以下のコードスニペットを使用して、APIリクエストを送信するためのヘッダーを設定します。<Your API Token> をコピーしたトークンに置き換えてください。

import requests
import json

headers = {
  'Authorization': 'Bearer <Your API Token>'
}

base_api_url = "https://api.roe-ai.com/v1"

これで、トークンを使用してRoe AI APIを実行し、ワークフローの次のステップに進む準備が整いました！

‍

ステップ 2: 動画を保存する Roe データセットを作成する

動画をRoe AIに保存するには、データセットを作成する必要があります。以下の手順に従って、新しいデータセットを作成してください。

1. データセット名の定義: 後で識別しやすいように、データセットの名前を決めます。この例では「My Video Dataset」を使用します。お好みの名前に変更していただいて構いません。

2. APIリクエストの設定: 以下のコードスニペットを使用して、データセットを作成します。ステップ1で設定したヘッダーとベースAPI URLが定義されていることを確認してください。

create_dataset_url = f"{base_api_url}/datasets/"

dataset_name = "My Video Dataset"  # Replace with your dataset name

form_data = {
    "name": dataset_name
}

response = requests.post(create_dataset_url, headers=headers, data=form_data)

if response.status_code == 201:
    print("Success")
else:
    print("Failure!")

dataset_id = response.json().get("id") if response.status_code == 201 else None

print(f"Dataset ID: {dataset_id}")

1. コードの実行: Python環境でコードスニペットを実行します。

2. レスポンスの確認: データセットが正常に作成されると、コンソールに「Success」とデータセットIDが表示されます。失敗した場合は「Failure!」と表示され、データセットIDは None になります。

3. トラブルシューティング: エラーが発生した場合は、APIトークンが有効であること、およびRoe AIでデータセットを作成するために必要な権限があることを確認してください。

データセットが正常に作成されたら、次のステップで動画ファイルのアップロードに進むことができます。

‍

ステップ 3: 作成した Roe データセットに動画ファイルをアップロードする

データセットが作成できたので、次は動画ファイルをアップロードします。以下の手順に従って、動画をアップロードしてください。

1. 動画ファイルを準備する: アップロードする動画ファイルがすべて揃っていることを確認します。この例では、"/path/to/video1.mp4" に "video1.mp4" という名前のファイルがあると仮定します。

2. APIリクエストの設定: 以下のコードスニペットを使用して、動画ファイルをデータセットにアップロードします。前ステップで取得したデータセットIDが設定されていることを確認してください。

upload_files_url = f"{base_api_url}/datasets/files/upload/"

payload = {
    'dataset_id': f"{dataset_id}",
}

# REQUIRED: Add all your VIDEO FILES HERE
files = [
    ('file', ('video1.mp4', open('/path/to/video1.mp4', 'rb'), 'video/mp4')),
    # Add more files as needed
]

response = requests.request("POST", upload_files_url, headers=headers, data=payload, files=files)

if response.status_code == 200:
    print("Success")
else:
    print("Failure!")

1. ファイル詳細の書き換え: 'video1.mp4' を実際の動画ファイル名に、'/path/to/video1.mp4' をローカルマシン上の正しいファイルパスに置き換えます。アップロードする各動画について、files リストに項目を追加してください。

2. コードの実行: Python環境でコードスニペットを実行します。

3. レスポンスの確認: アップロードが成功すると、コンソールに「Success」と表示されます。失敗した場合は「Failure!」と表示されます。

4. トラブルシューティング: エラーが発生した場合は、APIトークンが有効であること、データセットIDが正しいこと、およびデータセットにファイルをアップロードする権限があることを確認してください。

動画ファイルのアップロードが成功したら、次のステップでデータセットからテーブルの作成に進むことができます。

‍

ステップ 4: Roe データセットからテーブルを作成する

データセットに動画ファイルをアップロードした後の次のステップは、そのデータセットからテーブルを作成することです。このテーブルは、セマンティック動画検索の基盤となります。以下の手順に従ってください。

1. テーブル名の決定: 後で識別しやすいように、テーブルの名前を決めます。この例では「my_video_table」を使用します。名前にハイフン（`-`）が含まれないようにしてください。

2. APIリクエストの設定: 以下のコードスニペットを使用して、データセットからテーブルを作成します。前ステップで取得したデータセットIDが設定されていることを確認してください。

create_table_url = f"{base_api_url}/database/table/import/roe-dataset/"

table_name = "my_video_table"  # Replace with your desired table name

form_data = {
    "table_name": table_name,
    "dataset_id": f"{dataset_id}",
    "sync_dataset": "false",  # Set to "true" if you want to sync the dataset with the table
}

response = requests.post(create_table_url, headers=headers, data=form_data)

if response.status_code == 200:
    print("Success")
else:
    print("Failure!")

1. データセットの同期オプション: sync_dataset パラメータは、テーブルをデータセットと同期させたいかどうかを指定します。"true" に設定すると、データセットに加えられた変更がテーブルに反映されます。この例では、"false" に設定しています。

2. コードの実行: Python環境でコードスニペットを実行します。

3. レスポンスの確認: テーブルが正常に作成されると、コンソールに「Success」と表示されます。失敗した場合は「Failure!」と表示されます。

4. トラブルシューティング: エラーが発生した場合は、APIトークンが有効であること、データセットIDが正しいこと、およびRoe AIでテーブルを作成する権限があることを確認してください。

テーブルが正常に作成されたら、次のステップでテーブルの列情報を取得します。

‍

ステップ 5: テーブルの列を取得して利用可能なデータを確認する

テーブル内のデータの構造を理解するために、テーブルの列（カラム）を読み取る必要があります。これにより、検索インデックスに使用する関連フィールドを特定できます。以下の手順に従ってください。

1. APIリクエストの設定: 以下のコードスニペットを使用して、作成したテーブルから列を取得します。前ステップで指定した正しいテーブル名が設定されていることを確認してください。

table_cols_url = f"{base_api_url}/database/table/{table_name}/columns"

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

if response.status_code == 200:
    columns = response.json()  # Parsing the JSON response
    print("Success")
    print("Columns:", columns)
else:
    print("Failure! Status Code:", response.status_code)

1. コードの実行: Python環境でコードスニペットを実行します。

2. レスポンスの確認: リクエストが成功すると、コンソールに「Success」と表示され、テーブルに存在する列のリストが出力されます。失敗した場合は、「Failure!」とステータスコードが表示されます。

3. トラブルシューティング: エラーが発生した場合は、以下を確認してください。

   • APIトークンが有効であり、必要な権限があること。

   • テーブル名が正しく、前のステップで作成したものと一致していること。

   • 401 ステータスコードを受け取った場合は、リクエストが未認可であることを示しており、通常はAPIトークンに問題があります。

4. 関連する列の選択: 列を取得できたら、動画データに対応する 'files' という名前の列を確認します。検索インデックス用の選択された列のリストを以下のように作成できます。

# Assuming the columns are retrieved successfully
selected_columns = [columns[2]]  # Adjust the index based on the actual structure of the response

テーブルの列を正常に取得できたら、次のステップでテーブルに検索インデックスを作成します。

ステップ 6: Twelve Labs の Marengo-2.6 動画埋め込みモデルを使用してテーブルに検索インデックスを作成する

動画データに対してセマンティック検索を可能にするために、Twelve LabsのMarengo-2.6埋め込みモデルを使用して検索インデックスを作成する必要があります。このステップでは、異なるデータ型に対して適切な埋め込みモデルを適用するようにインデックスを構成します。以下の手順に従ってください。

1. APIリクエストの設定: 以下のコードスニペットを使用して検索インデックスを作成します。これまでのステップで取得した正しいテーブル名と選択された列が設定されていることを確認してください。

create_index_url = f"{base_api_url}/index/"
search_index_config = {
    "version": '1.0',
    "pdf": {
        "text_embedder_name": "jina-clip-v1",
        "image_embedder_name": "jina-clip-v1",
    },
    "text": {
        "embedder_name": "text-embedding-3-small",
    },
    "image": {
        "embedder_name": "jina-clip-v1",
    },
    "audio": {
        "embedder_name": 'None',
    },
    "video": {
        "embedder_name": "Marengo-retrieval-2.6",
    },
}

index_name = "my_search_index"  # Replace with your desired index name

form_data = {
    "name": index_name,
    "table_name": table_name,
    "id_column_name": "r_uuid",  # Replace with the actual ID column name if different
    "column_names": json.dumps(selected_columns),
    "search_index_config": json.dumps(search_index_config),
    "display_name": index_name,
}

response = requests.post(create_index_url, headers=headers, data=form_data)

if response.status_code == 201:
    print("Success")
else:
    print("Failure!")

index_id = response.json().get("id") if response.status_code == 201 else None
print(f"Index ID: {index_id}")

1. 検索インデックスの構成: search_index_config 辞書は、データ型ごとの埋め込みモデルを指定します。

   • テキスト (Text): テキストデータには "text-embedding-3-small" モデルを使用します。

   • 動画 (Video): 動画データには "Marengo-retrieval-2.6" モデルを使用します。動作の仕組みについては、こちらのドキュメントを参照してください: https://docs.twelvelabs.io/docs/create-video-embeddings

   • PDFと画像 (PDF and Image): 両方に "jina-clip-v1" を使用します。

   • 音声 (Audio): 今回は音声埋め込みを使用しないため、'None' に設定します。

2. コードの実行: Python環境でコードスニペットを実行します。

3. レスポンスの確認: インデックスが正常に作成されると、コンソールに「Success」と表示されます。失敗した場合は、「Failure!」とステータスコードが表示されます。

4. トラブルシューティング: エラーが発生した場合は、以下を確認してください。

   • APIトークンが有効であり、必要な権限があること。

   • テーブル名と選択された列が正しいこと。

   • ステータスコードが 201 以外の場合は、リクエストに問題があることを示しています。特定の要件についてAPIドキュメントを確認する必要がある場合があります。

5. インデックスID: インデックスの作成に成功すると、インデックスIDが出力されます。これは今後のクエリ操作などで使用します。

このステップを完了すると、Twelve LabsのMarengo-2.6モデルの高度な機能を活用した検索インデックスが設定され、動画データに対する効率的で効果的なセマンティック検索が可能になります。

‍

ステップ 7: 検索インデックス作成のステータスを確認する

検索インデックスの作成を開始した後は、プロセスが正常に完了することを確認するためにステータスを監視することが重要です。以下の手順に従って、作成ステータスを確認してください。

1. APIリクエストの設定: 以下のコードスニペットを使用して検索インデックスのステータスを確認します。前ステップで取得した正しいインデックスIDが設定されていることを確認してください。

import time

check_status_url = f"{base_api_url}/index/{index_id}/status/"

max_retries = 120  # Maximum number of retries to check the status

# Start a loop to continuously check the status
for _ in range(max_retries):
    response = requests.get(check_status_url, headers=headers)

    if response.status_code == 200:
        status = response.json().get('status')

        # Check if the index creation is complete
        if status == 'SUCCESS':
            print("Index creation succeeded.")
            break
        elif status == 'FAILURE' or status == 'REVOKED':
            print("Index creation failed.")
            break

        print(f"Index status: {status}. Checking again in 10 seconds...")
        # Wait for 10 seconds before checking again
        time.sleep(10)
    else:
        print(f"Failed to get status: {response.status_code}")
        break
else:
    print("Max retries reached, exiting.")

1. コードの実行: Python環境でコードスニペットを実行します。

2. ステータスの監視: このコードは、最大120回（または確定ステータスを受信するまで）インデックス作成のステータスを確認します。確認の間隔は10秒です。

3. レスポンスの確認:

   • ステータスが SUCCESS の場合、コンソールに「Index creation succeeded.」（インデックス生成成功）と表示されます。

   • ステータスが FAILURE または REVOKED の場合、「Index creation failed.」（インデックス生成失敗）と表示されます。

   • ステータスがまだ「保留中」(pending) の場合は、現在のステータスを表示し、確認を続行します。

4. トラブルシューティング: ステータスの取得に失敗した場合は、以下を確認してください。

   • APIトークンが有効であり、必要な権限があること。

   • インデックスIDが正しいこと。

5. 最大リトライ回数: 最終的なステータスが得られないまま最大リトライ回数に達した場合、コードは「Max retries reached, exiting.」（最大試行回数に達したため終了します）と出力します。これは、インデックスの作成プロセスに想定以上の時間がかかっていることを示します。

検索インデックス作成のステータスが正常に確認できれば、次のステップで検索クエリを実行する準備が整います。

‍

ステップ 8: 検索インデックスにクエリを送信し、検索条件に基づいて関連する動画を検索する

これで検索インデックスが作成され検証されたので、特定の検索条件に基づいてクエリを実行し、関連する動画を検索できます。検索を実行するには、以下の手順に従ってください。

1. APIリクエストの設定: 以下のコードスニペットを使用して、検索インデックスにクエリを送信します。これまでのステップで取得した正確なインデックスIDが設定されていることを確認してください。

search_index_url = f"{base_api_url}/index/{index_id}/search/"

form_data = {
    "query": "tennis on grass",  # Replace with your search query
    "limit": "10"  # Optional: Limit the number of results returned
}

response = requests.post(search_index_url, headers=headers, data=form_data)

results = response.json().get("result_rows")

print("Videos from most to least relevant:\n")
for idx, result in enumerate(results):
    print(f"{idx + 1}: {result[1]}")

1. クエリのカスタマイズ: form_data 辞書の "tennis on grass" を、希望する検索クエリに変更します。また、取得する検索結果の数を調整するために limit パラメータを変更することもできます。

2. コードの実行: Python環境でコードスニペットを実行します。

3. レスポンスの確認: コードは検索インデックスにリクエストを送信し、結果を取得します。リクエストが成功すると、検索条件に基づいて関連性の高い順に動画が出力されます。

4. 結果の解釈: 結果は番号順のリスト形式で表示され、各項目はクエリに一致する動画に対応します。コードの result[1] の記述は、結果タプルの2番目の要素に関連動画情報（タイトルやURLなど）が含まれていることを想定しています。結果のデータ構造が異なる場合は、必要に応じてインデックスを調整してください。

5. トラブルシューティング: 検索クエリで問題が発生した場合:

   • APIトークンが有効であり、必要な権限があることを確認してください。

   • インデックスIDが正しく、インデックスが正常に作成されていることを確認してください。

このステップを完了すると、検索インデックスへのクエリ送信と、指定した条件に基づく関連動画の取得が効率的に行えるようになり、Twelve Labs Embed APIとRoe AIの強力な統合機能が実証されます。

‍

おわりに

このチュートリアルでは、Twelve Labsの動画埋め込み機能とRoe AIのデータ管理プラットフォームを統合し、動画の検索と分析のための強力なツールを提供する方法を説明しました。ここで紹介した手順に従うことで、この統合技術が持つ可能性を示す、実用的なセマンティック動画検索ソリューションを作成・体験できました。

開発者にとって、この統合は動画処理における新たな可能性を切り拓くものです。Twelve Labsの高度な動画理解技術と、Roe AIの柔軟なデータ処理能力を組み合わせることで、よりインテリジェントでコンテキストを認識するアプリケーションの開発が可能になります。これらのツールにより、これまで困難または実用的ではなかった方法で動画コンテンツを処理し理解できるようになります。

今後の開発作業において、これらの技術をご自身のプロジェクトにどのように適用できるかぜひ検討してみてください。コンテンツ推奨システム、動画分析ツール、あるいは大規模な動画データを扱うアプリケーションのどれを構築する場合でも、この統合は、洗練されたAI駆動型の動画特化型ソリューションを実装するための強固な基盤を提供します。

‍

付録

今後のさらなる参照と探究のために:

1. 完成版の Colab Notebook

2. Twelve Labs API ドキュメント

3. Roe AI ドキュメント

あなたが何を構築するのか、とても楽しみにしています！完成したプロジェクトや開発体験をぜひTwelve LabsおよびRoe AIのコミュニティで共有してください。ハッピーコーディング！