パートナーシップ
ビデオインテリジェンスの解放:TwelveLabsマルチモーダルエンベディングAPIとOracle Database 23aiの統合チュートリアル
ジェームズ・レ、マニッシュ・マヘシュワリ、ダニー・ニコプロス、アレックス・オーウェン、ウィル・ブレナン
開発者は、Twelve LabsのEmbed APIとOracle Database 23aiを統合することで、意味論的な(セマンティック)ビデオ検索アプリケーションを構築できます。マルチモーダルなビデオ埋め込み(エンベディング)をOracleネイティブのベクトル検索インフラストラクチャに直接保存し、独自のベクトルデータベースを別途用意することなく、自然言語を使用してクエリを実行できます。
開発者は、Twelve LabsのEmbed APIとOracle Database 23aiを統合することで、意味論的な(セマンティック)ビデオ検索アプリケーションを構築できます。マルチモーダルなビデオ埋め込み(エンベディング)をOracleネイティブのベクトル検索インフラストラクチャに直接保存し、独自のベクトルデータベースを別途用意することなく、自然言語を使用してクエリを実行できます。

この記事の内容
ニュースレターに登録する
ニュースレターに登録する
ビデオ理解に関する最新の技術進歩、チュートリアル、業界の動向をお届けします
ビデオ理解に関する最新の技術進歩、チュートリアル、業界の動向をお届けします
AIを活用してビデオを検索、分析、探索します。
2025/04/03
15分
記事へのリンクをコピー
インテグレーションや今回のブログ記事執筆にあたり、私たちと緊密に連携してくださった Maxwell Bauman 氏、Douglas Hood 氏、Sean Stacey 氏、Malu Castellanos 氏をはじめ、Oracle チームの皆様に心より感謝申し上げます!
マルチモーダルなビデオ理解とエンタープライズグレードのベクトル検索機能の融合は、ジェネレーティブ AI アプリケーションにおける大きな進歩を意味します。このチュートリアルでは、TwelveLabs の最先端の Embed API と Oracle Database 23ai の AI Vector Search のインテグレーションについて探求し、セマンティックな理解を通じて動画コンテンツを保存、分析、検索するための強力なソリューションを開発者に提供します。
このガイドに沿って進めることで、これら 2 つの補完的なテクノロジーを活用し、堅牢なデータベースインフラの恩恵を受けながら、視覚、音声、文脈要素の豊かさを捉えた高度な動画検索・分析アプリケーションを構築する方法を学ぶことができます。
1 - はじめに
TwelveLabs Embed API

当社の Embed API は、動画データを高度なベクトル表現(すなわち真の埋め込み)に変換することで、動画理解に革命をもたらします。単一のモダリティに焦点を当てる従来のアプローチとは異なり、当社のマルチモーダル埋め込みテクノロジーは、視覚的な表現、話し言葉、ボディーランゲージ、そして文脈上の関係性をシームレスに捉えます。私たちは動画を、単純なフレームごとの処理を超えた、時間的ダイナミクスを持つネイティブなメディアとして扱います。
当社の統一されたベクトル空間テクノロジーは、複数のモダリティを論理的な1つの表現に統合し、会話、視覚、文脈の間の豊かな相互作用を維持します。これにより、大規模な動画ライブラリの処理時間を大幅に短縮しながら、ニュアンスのある検索機能を実現します。
また、柔軟な動画セグメンテーションオプションも提供しており、異なる動画セグメントから複数の埋め込みを作成することも、動画全体に対して単一の埋め込みを作成することも可能です。これにより、動画内の特定の瞬間を正確に検索することができます。
Oracle 23ai Vector Search の機能

パートナーである Oracle は、コンバージドデータベース戦略のコア機能として、Oracle Database 23ai に AI Vector Search を組み込んでいます。Oracle のアプローチは、専用のインデックスと SQL 関数を使用して、ネイティブなベクトル保存と類似性検索を提供します。サイロ化を生み出すスタンドアロンのベクトルデータベースとは異なり、Oracle はベクトル機能をリレーショナルデータベースに直接統合しているため、構造化データと非構造化データをまたいだシームレスなクエリが可能です。
このシステムは、複数の距離メトリック(コサイン、ユークリッド、ユークリッド自乗、内積、マンハッタン、ハミング、ジャッカード)をサポートしており、ユースケースのニーズに基づいて類似性を柔軟に定義できます。スケールに合わせて最適化されているため、数百万件のレコードがある場合でもベクトル検索は効率を維持し、本番環境に対応可能です。
Oracle の確立されたインフラ内にベクトルを統合することで、開発者は使い慣れた SQL 構文と既存のセキュリティモデルを維持しながら、最先端の AI 機能を使用できます。これにより、個別の専用システムを用意する必要がなくなり、全体的なデータアーキテクチャの複雑さが軽減されます。
インテグレーションのビジネス価値
Oracle Database 23ai とのインテグレーションは、ベクトル埋め込みとリレーショナルデータストレージを統一する簡素化されたアーキテクチャを通じて、大きなビジネス価値をもたらします。これにより、別々のシステム間での同期が不要になり、不整合やメンテナンスコストが削減されます。さらに、クエリの複雑さ(リレーショナル DB とベクトルストアへの個別クエリの実行およびその後の結果の結合)や、結果が早く返ることによる遅延も減少します。
当社のソリューションは、ユーザーがキーワードではなく意味に基づいてコンテンツを見つける セマンティック動画検索 を可能にし、検索精度の向上や、テキストやビジュアルコンテンツを使用したクロスモーダルクエリをサポートします。
Oracle のエンタープライズグレードの信頼性、セキュリティ、スケーラビリティを活用することで、本番デプロイ用の堅牢な基盤を提供します。企業は、データ量が増加してもベクトル操作が効率的に維持されるよう構築されたミッションクリティカルなワークロード向けの Oracle Database テクノロジーを使用して、当社の動画理解テクノロジーを安心して導入できます。
また、当社のインテグレーションにより、動画コンテンツの高度な分析が可能になり、手作業によるレビューや従来の処理では検出不可能だったパターンやインサイトを企業が発見できるようになります。
このチュートリアルでは、インフラのセットアップから高度な動画検索アプリケーションの構築まで、実際の導入手順をカバーし、真のビジネス価値をもたらすインテリジェントな動画アプリケーションを作成するための包括的な知識を提供します。
2 - Oracle Autonomous Database の作成
Oracle Cloud のセットアップ
https://www.oracle.com/cloud/free/ で Oracle Cloud Free Tier アカウントに登録します。30 日間無料で使用できる 300 ドル分のクレジットと、Always Free(常時無料)サービスが提供されます。認証目的のみでクレジットカードが必要です。
データベースの作成
https://cloud.oracle.com/db/adb にログインします
Oracle Database → Autonomous Data Warehouse の順に進みます
「Autonomous Databaseの作成」をクリックします
設定の構成
表示名: 「VideoEmbeddingsDB」(最大 14 文字)
ワークロード・タイプ: データ・ウェアハウス
デプロイメント・タイプ: サーバーレス
必須構成
データベース・バージョン: ベクトル機能を使用するために「23ai」を選択します
「Always Free」を選択します(2 OCPU、20GB ストレージ)
注意: データベースは 7 日間非アクティブ状態が続くと自動停止しますが、30 日の間に使用し続ければ、(無料で)永久に存在し続けます。
管理者パスワードの設定
ADMIN ユーザー用に、強力なパスワード(12〜30文字、大文字、小文字、数字、特殊文字を含む)を作成します。
ネットワーク・アクセス
開発用: 「セキュアなアクセスをどこからでも許可」を選択します
データベースの作成
「Autonomous Databaseの作成」をクリックします。プロビジョニングには 2〜5 分かかります。ステータスが「使用可能」になるまで待ちます。
接続ウォレットの取得
データベースの詳細ページに移動します
「データベース接続」 → 「ウォレットのダウンロード」をクリックします
ウォレットのパスワードを設定します
ウォレットの ZIP ファイルを安全に保存します
アプリケーションで ORACLE_DB_WALLET_PATH を使用します
これで、Twelve Labs Embed API と統合するデータベースの準備が整いました。次に、必要な環境変数を設定します。
3 - 事前準備と環境変数の設定
TwelveLabs Embed API と Oracle Database 23ai を統合する前に、必要なツールと資格情報がセットアップされていることを確認してください。このセクションでは、必要なソフトウェアのインストールと環境構成について説明します。
必要なソフトウェアのインストール
このチュートリアルを正常に完了するには、以下が必要になります。
AI Vector Search 機能を備えた Oracle Database 23.4 以降
開発マシンにインストールされた Python 3.8 以降
データベース接続用の Oracle Client ライブラリ
Embed API にアクセスするための TwelveLabs API キー
必要な Python パッケージをインストールします。
oracledb パッケージは Python から Oracle Database への接続を提供し、twelvelabs パッケージは Twelve Labs の API サービスへの便利なインターフェースを提供します。
環境構成
接続資格情報を安全に保存するために、以下の環境変数を設定します。
export ORACLE_DB_USERNAME=your_username export ORACLE_DB_PASSWORD=your_password export ORACLE_DB_CONNECT_STRING=your_connect_string export ORACLE_DB_WALLET_PATH=/path/to/wallet export TWELVE_LABS_API_KEY
プレースホルダーの値を実際の資格情報に置き換えてください。
your_username: データベースのユーザー名(通常、新しい Autonomous Database の場合は ADMIN)
your_password: データベースのプロビジョニング中に作成したパスワード
your_connect_string: ウォレット内の tnsnames.ora ファイルに記載されているサービス名
/path/to/wallet: Oracle ウォレットファイルを展開したディレクトリのパス
your_api_key: 開発者ポータルから取得した TwelveLabs の API キー
4 - データベース・スキーマのセットアップ
このセクションでは、TwelveLabs から取得した動画の埋め込みを保存し、クエリを実行するために必要なデータベース・スキーマを作成します。Python スクリプトを使用して接続を確立し、適切なベクトル・インデックスを持つテーブル構造を作成します。
Oracle Database への接続
create_schema_video_embeddings.py スクリプトは、前のセクションで設定した環境変数を使用して、Oracle Database インスタンスへの接続を処理します。このスクリプトの主要なコンポーネントを見てみましょう。
import oracledb # Connect to Oracle Database 23.7 with oracledb.connect( user=db_username, password=db_password, dsn=db_connect_string, config_dir=db_wallet_path, wallet_location=db_wallet_path, wallet_password=db_password ) as connection: # Script operations will go here
動画埋め込み用テーブルの作成
このスクリプトは、以下の構造を持つ video_embeddings テーブルを作成します。
CREATE TABLE video_embeddings ( id VARCHAR2(100) PRIMARY KEY, video_file VARCHAR2(1000), start_time NUMBER, end_time NUMBER, embedding_vector VECTOR(1024, float64) )
このテーブルには以下が含まれます。
id: 各埋め込みの一意の識別子video_file: ソース動画のファイル名またはパスstart_timeおよびend_time: 動画セグメントのタイムスタンプマーカーembedding_vector: Twelve Labs の埋め込みを保存するための、float64 精度を使用した 1024 次元のベクトル
ベクトル・インデックスのセットアップ
テーブルの作成が完了したら、create_vector_index を呼び出して類似性検索用のベクトル・インデックスを作成します。ターゲット精度 95% のコサイン類似度(DISTANCE COSINE)を使用します。
def create_vector_index(cursor): cursor.execute(""" CREATE VECTOR INDEX video_embeddings_idx ON video_embeddings(embedding_vector) ORGANIZATION NEIGHBOR PARTITIONS DISTANCE COSINE WITH TARGET ACCURACY 95 """)
スキーマ作成スクリプトの実行
スキーマ作成スクリプトを実行します。
このスクリプトは以下の処理を行います。
Oracle データベースに接続します
既存のテーブルがある場合は削除します
新しい
video_embeddingsテーブルを作成します指定されたベクトル・インデックスを作成します
コンソール出力で作成成功を確認します
スキーマのセットアップが完了すると、Oracle Database 23ai インスタンスに TwelveLabs の動画埋め込みを保存し、クエリを実行するための基盤が整います。
5 - 動画埋め込みの保存
データベース・スキーマをセットアップした後の次のステップは、TwelveLabs Embed API を使用して動画を処理し、結果の埋め込みを Oracle Database に保存することです。store_video_embeddings.py スクリプトがこのプロセス全体を処理し、埋め込みの生成とデータベースへの保存の両方を管理します。
スクリプト・ワークフローの理解
このスクリプトは、いくつかの重要な操作を実行します。
環境変数を使用して Oracle Database に接続します
API キーを使用して TwelveLabs クライアントを初期化します
TwelveLabs の Marengo モデル を使用して動画の埋め込みを作成します
埋め込みをデータベースのテーブルに保存します
重複処理を避けるため、処理済みの動画の記録を保持します
主な関数
埋め込みの作成
def create_video_embeddings(client, video_file): """Create embeddings for a video file using Twelve Labs Marengo""" task = client.embed.task.create( model_name=EMBEDDING_MODEL, video_file=video_file, video_clip_length=SEGMENT_DURATION ) print(f"Created task: id={task.id} model_name={EMBEDDING_MODEL} status={task.status}") status = task.wait_for_done( sleep_interval=2, callback=on_task_update ) print(f"Embedding done: {status}") return task.id
この関数は動画を TwelveLabs に送信し、Marengo 2.7 モデルを使用して動画を処理します。動画は 6 秒のクリップ(SEGMENT_DURATION 定数で構成可能)に分割され、各セグメントがそれぞれ独自の埋め込みベクトルを受け取ります。関数は、処理が完了した後に埋め込みを取得するために使用されるタスク ID を返します。
埋め込みの保存
def store_embeddings_in_db(connection, task_id, video_file): """Store video embeddings in Oracle DB""" # Get embeddings from the task task = twelvelabs_client.embed.task.retrieve(task_id) # Get embeddings from the task if not task.video_embedding or not task.video_embedding.segments: print("No embeddings found") return insert_sql = """ INSERT INTO video_embeddings ( id, video_file, start_time, end_time, embedding_vector ) VALUES ( :1, :2, :3, :4, :5 )""" BATCH_SIZE = 1000 data_batch = [] # Process in batches of 1000 for efficiency with connection.cursor() as cursor: for idx, segment in enumerate(task.video_embedding.segments): id = f"{task_id}_{idx}" vector = array.array("f", segment.embeddings_float) data_batch.append([ id, video_file, segment.start_offset_sec, segment.end_offset_sec, vector ]) # Execute and commit every BATCH_SIZE rows if len(data_batch) >= BATCH_SIZE: print("insert data") cursor.executemany(insert_sql, data_batch) connection.commit() data_batch = [] # Insert any remaining rows if data_batch: print("insert data final") cursor.executemany(insert_sql, data_batch) connection.commit() print(f"Stored {len(task.video_embedding.segments)} embeddings in database")
この関数は、TwelveLabs から完了した埋め込みを取得し、それを Oracle に保存します。各埋め込みは、以下を含むメタデータとともに保存されます。
タスク ID とセグメント・インデックスを組み合わせた一意の ID
ソース動画のファイル名
動画セグメントの開始および終了タイムスタンプ
埋め込みベクトル自体(1024 次元)
この関数は、最適なデータベース・パフォーマンスを実現するために、埋め込みを 1000 件ずつのバッチで処理します。
タスク ID の管理
def load_task_ids(): """Load existing task IDs from JSON file""" try: with open('video_task_ids.json', 'r') as f: return json.load(f) except FileNotFoundError: return {}
スクリプトは、動画パスを TwelveLabs のタスク ID にマッピングする video_task_ids.json ファイルを維持します。これにより、スクリプトはすでに埋め込み済みの動画の再処理をスキップでき、時間と API コストの両方を削減できます。動画を再埋め込みする必要がある場合は、このファイルから該当するエントリを削除するか、ファイル自体を削除してください。
スクリプトの実行
スクリプトは 2 つの方法で使用できます。
単一の動画ファイルの場合:
動画ディレクトリの場合:
ディレクトリを処理する場合、スクリプトは一般的な動画ファイルの拡張子(.mp4、.avi、.mov、.mkv、.webm)を自動的にフィルタリングし、一致する各ファイルを処理します。
進捗状況のモニタリング
スクリプトは、以下に関するリアルタイムの更新情報を提供します。
Oracle Database への接続ステータス
TwelveLabs からのタスク作成およびステータス更新
バッチ挿入の確認を含む、埋め込み保存の進捗状況
保存された埋め込みの数を示す完了サマリー
スクリプトが完了すると、動画埋め込みは video_embeddings テーブルに保存され、類似性検索を実行する準備が整います。これについては次のセクションで説明します。
6 - 動画埋め込みへのクエリ実行
動画埋め込みを Oracle Database に保存した後の最大の強みは、自然言語を使用して動画コンテンツを検索できることです。query_video_embeddings.py スクリプトを使用すると、動画リポジトリ全体にわたってセマンティック検索を実行し、単なるキーワードではなく、クエリの意味に一致する瞬間を見つけることができます。
基本的な類似性検索
検索機能の核心は、スクリプト内の以下の SQL クエリに依存しています。
SELECT video_file, start_time, end_time FROM video_embeddings ORDER BY vector_distance(embedding_vector, :1, COSINE) FETCH FIRST :2 ROWS ONLY
このクエリは、Oracle ネイティブの vector_distance 関数を COSINE 類似度メトリックとともに使用して、クエリの埋め込みと保存されているすべての動画埋め込みを比較します。結果は類似度順にソートされ、上位 2 つの一致に制限されます。
主要な関数の説明
このスクリプトには、効率的な動画検索を提供するために連携して動作するいくつかの重要な関数が含まれています。
テキストから埋め込みへの変換
def similarity_search(connection, query_text): # Create embedding for query embedding = twelvelabs_client.embed.create( model_name=EMBEDDING_MODEL, text=query_text, text_truncate="start", ) if len(embedding.text_embedding.segments) > 1: print(f"Warning: Query generated {len(embedding.text_embedding.segments)} segments. Using only the first segment.") query_vector = array.array("d", embedding.text_embedding.segments[0].embeddings_float) # Search query search_sql = """ SELECT video_file, start_time, end_time FROM video_embeddings ORDER BY vector_distance(embedding_vector, :1, COSINE) FETCH FIRST :2 ROWS ONLY """ results = [] cursor = connection.cursor() cursor.execute(search_sql, [query_vector, TOP_K]) for row in cursor: results.append({ 'video_file': row[0], 'start_time': row[1], 'end_time': row[2] }) cursor.close() return results
この関数は、テキストクエリを Twelve Labs の API に送信し、テキストのセマンティック(意味的な)内容を捉えた埋め込みベクトルを返します。スクリプトは、text_truncate="start" を使用してテキストの先頭部分を維持することにより、長いクエリの切り捨てを自動的に処理します。
複数クエリの同時処理
def similarity_search_multiple(connection, query_texts, batch_size=1000): """Perform multiple similarity searches using a list of query texts in batches""" results_by_query = {} # Process queries in batches for i in range(0, len(query_texts), batch_size): batch_queries = query_texts[i:i + batch_size] print(f"\nProcessing batch {i//batch_size + 1} ({len(batch_queries)} queries)") # Create embeddings for batch queries embeddings = [] for query_text in batch_queries: embedding = twelvelabs_client.embed.create( model_name=EMBEDDING_MODEL, text=query_text, text_truncate="start", ) if len(embedding.text_embedding.segments) > 1: print(f"Warning: Query '{query_text}' generated {len(embedding.text_embedding.segments)} segments. Using only the first segment.") query_vector = array.array("d", embedding.text_embedding.segments[0].embeddings_float) embeddings.append(query_vector) # Search query search_sql = """ SELECT video_file, start_time, end_time FROM video_embeddings ORDER BY vector_distance(embedding_vector, :1, COSINE) FETCH FIRST :2 ROWS ONLY """ with connection.cursor() as cursor: for query_text, query_vector in zip(batch_queries, embeddings): results = [] for row in cursor.execute(search_sql, [query_vector, TOP_K]): results.append({ 'video_file': row[0], 'start_time': row[1], 'end_time': row[2] }) results_by_query[query_text] = results return results_by_query
複数のクエリで検索する際の効率向上のために、この関数はクエリをバッチ処理し、データベース接続と API コール数。簡単に結果を取得して表示できるように、各クエリをその結果にマッピングする辞書を保持します。
データベース接続の管理
def query_video_embeddings(query_text): connection = oracledb.connect( user=db_username, password=db_password, dsn=db_connect_string, config_dir=db_wallet_path, wallet_location=db_wallet_path, wallet_password=db_password ) # Verify DB version db_version = tuple(int(s) for s in connection.version.split("."))[:2] if db_version < (23, 7): sys.exit("This example requires Oracle Database 23.7 or later") print("Connected to Oracle Database") print("\nSearching for relevant video segments...") results = similarity_search(connection, query_text) print("\nResults:") print("========") for r in results: print(f"Video: {r['video_file']}") print(f"Segment: {r['start_time']:.1f}s to {r['end_time']:.1f}s\n")
このスクリプトは、環境変数を使用してすべてのデータベース接続詳細を処理し、Oracle Database インスタンスへの安全で効率的なアクセスを保証します。
スクリプトの実行
クエリに一致する動画セグメントを検索するには、1つ以上のテキストクエリを引数としてスクリプトを実行します。
python3 query_video_embeddings.py "people dancing at a party" "someone explaining AI concepts"
スクリプトは任意の数のクエリを受け入れ、それらを効率的に処理します。各クエリは:
Twelve Labs の Marengo-2.7 モデルを使用して、埋め込みベクトルに変換されます
コサイン類似度を使用して、すべての動画セグメント埋め込みと比較されます
意味的に最も類似している上位2つの動画セグメントと一致させます
結果の理解
スクリプトは、読みやすい形式で結果を出力します:
Connected to Oracle Database Searching for relevant video segments... Results: ======== Query: 'people dancing at a party' ---------------------------------- Video: birthday_celebration.mp4 Segment: 15.0s to 21.0s Video: summer_festival.mp4 Segment: 45.5s to 51.5s Query: 'someone explaining AI concepts' -------------------------------------- Video: tech_lecture.mp4 Segment: 120.0s to 126.0s Video: developer_conference.mp4 Segment: 75.5s to 81
各クエリについて、最も関連性の高い動画セグメントがファイル名と正確なタイムスタンプとともにリストされます。これにより、検索基準に一致する動画の特定の部分をすばやく見つけて視聴することができます。
コサイン類似度メトリックにより、結果は完全なキーワードの一致ではなく、セマンティックな意味に基づいていることが保証されます。つまり、クエリの正確な単語が動画の画像フレーム、音声、または字幕に表示されない場合でも、関連するコンテンツを見つけることができます。
7 - まとめ
当社の Embed API と Oracle Database 23ai とのインテグレーションは、動画の理解と検索機能における重要なマイルストーンとなります。当社の高度なマルチモーダル埋め込みと Oracle の堅牢なベクトル検索機能を組み合わせることで、開発者は人間のような知覚で動画コンテンツを処理および理解する、洗練された動画アプリケーションを構築できます。
ビジネス価値
当社のソリューションは、企業にいくつかの重要なメリットをもたらします:
強化された動画検索:当社の セマンティック動画検索 機能により、ユーザーはキーワードではなく意味に基づいて関連する動画セグメントを見つけることができ、ユーザーエンゲージメントとコンテンツ発見が向上します。
統合されたインフラストラクチャ:Oracle のコンバージドデータベース戦略と連動することで、個別の専用データベースの必要性を排除し、スケーラビリティとセキュリティを強化しながら、複雑さとコストを削減します。
イノベーションとリーダーシップ:当社の最先端の AI テクノロジーを通じて、組織は市場での差別化を図り、動画コンテンツ管理および分析におけるリーダーシップを確立できます。
技術的な利点
当社のインテグレーションは開発者に以下を提供します:
合理化された開発:リレーショナルデータとベクトルデータの両方に対応する統合プラットフォームを通じて、高度な動画理解機能にアクセスし、開発ワークフローを簡素化します。
高性能検索:当社の最先端の 埋め込み(Embeddings) 技術と Oracle のベクトルインデックスを組み合わせることで、大規模な動画ライブラリにわたり、高速かつ正確な類似性検索を可能にします。
スケーラビリティと信頼性:Oracle Cloud Infrastructure (OCI) 上でトレーニングされた当社の 動画基礎モデル(Video Foundation Models) は、エンタープライズグレードの信頼性とスケーラビリティを保証します。
「Better Together(共創)」のストーリー
Oracle と当社の関係は深く、私たちは Oracle Cloud Infrastructure を活用して動画基礎モデルをトレーニングしており、人間とそれ以上に動画を理解するモデルの開発を可能にしています。Embed API を Oracle Database 23ai と統合することで、私たちの補完的なテクノロジーがお客様に強力なソリューションを提供できることを実証しています。
結論として、当社の Embed API と Oracle Database 23ai のインテグレーションは、動画コンテンツの可能性を最大限に引き出したい企業や開発者にとって画期的な進歩を意味します。このパートナーシップは、当社の高度な動画理解テクノロジーが Oracle のエンタープライズグレードのインフラストラクチャと組み合わさることで、どのように産業を変革できるかを示す一例です。
リソース一覧
チュートリアルのコードを格納した GitHub リポジトリ: https://github.com/twelvelabs-io/twelvelabs-developer-experience/tree/main/integrations/Oracle
TwelveLabs Embed API ドキュメント: https://docs.twelvelabs.io/v1.3/docs/guides/create-embeddings/video
Oracle AI Vector Search ユーザーズ・ガイド: https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/overview-node.html
インテグレーションや今回のブログ記事執筆にあたり、私たちと緊密に連携してくださった Maxwell Bauman 氏、Douglas Hood 氏、Sean Stacey 氏、Malu Castellanos 氏をはじめ、Oracle チームの皆様に心より感謝申し上げます!
マルチモーダルなビデオ理解とエンタープライズグレードのベクトル検索機能の融合は、ジェネレーティブ AI アプリケーションにおける大きな進歩を意味します。このチュートリアルでは、TwelveLabs の最先端の Embed API と Oracle Database 23ai の AI Vector Search のインテグレーションについて探求し、セマンティックな理解を通じて動画コンテンツを保存、分析、検索するための強力なソリューションを開発者に提供します。
このガイドに沿って進めることで、これら 2 つの補完的なテクノロジーを活用し、堅牢なデータベースインフラの恩恵を受けながら、視覚、音声、文脈要素の豊かさを捉えた高度な動画検索・分析アプリケーションを構築する方法を学ぶことができます。
1 - はじめに
TwelveLabs Embed API

当社の Embed API は、動画データを高度なベクトル表現(すなわち真の埋め込み)に変換することで、動画理解に革命をもたらします。単一のモダリティに焦点を当てる従来のアプローチとは異なり、当社のマルチモーダル埋め込みテクノロジーは、視覚的な表現、話し言葉、ボディーランゲージ、そして文脈上の関係性をシームレスに捉えます。私たちは動画を、単純なフレームごとの処理を超えた、時間的ダイナミクスを持つネイティブなメディアとして扱います。
当社の統一されたベクトル空間テクノロジーは、複数のモダリティを論理的な1つの表現に統合し、会話、視覚、文脈の間の豊かな相互作用を維持します。これにより、大規模な動画ライブラリの処理時間を大幅に短縮しながら、ニュアンスのある検索機能を実現します。
また、柔軟な動画セグメンテーションオプションも提供しており、異なる動画セグメントから複数の埋め込みを作成することも、動画全体に対して単一の埋め込みを作成することも可能です。これにより、動画内の特定の瞬間を正確に検索することができます。
Oracle 23ai Vector Search の機能

パートナーである Oracle は、コンバージドデータベース戦略のコア機能として、Oracle Database 23ai に AI Vector Search を組み込んでいます。Oracle のアプローチは、専用のインデックスと SQL 関数を使用して、ネイティブなベクトル保存と類似性検索を提供します。サイロ化を生み出すスタンドアロンのベクトルデータベースとは異なり、Oracle はベクトル機能をリレーショナルデータベースに直接統合しているため、構造化データと非構造化データをまたいだシームレスなクエリが可能です。
このシステムは、複数の距離メトリック(コサイン、ユークリッド、ユークリッド自乗、内積、マンハッタン、ハミング、ジャッカード)をサポートしており、ユースケースのニーズに基づいて類似性を柔軟に定義できます。スケールに合わせて最適化されているため、数百万件のレコードがある場合でもベクトル検索は効率を維持し、本番環境に対応可能です。
Oracle の確立されたインフラ内にベクトルを統合することで、開発者は使い慣れた SQL 構文と既存のセキュリティモデルを維持しながら、最先端の AI 機能を使用できます。これにより、個別の専用システムを用意する必要がなくなり、全体的なデータアーキテクチャの複雑さが軽減されます。
インテグレーションのビジネス価値
Oracle Database 23ai とのインテグレーションは、ベクトル埋め込みとリレーショナルデータストレージを統一する簡素化されたアーキテクチャを通じて、大きなビジネス価値をもたらします。これにより、別々のシステム間での同期が不要になり、不整合やメンテナンスコストが削減されます。さらに、クエリの複雑さ(リレーショナル DB とベクトルストアへの個別クエリの実行およびその後の結果の結合)や、結果が早く返ることによる遅延も減少します。
当社のソリューションは、ユーザーがキーワードではなく意味に基づいてコンテンツを見つける セマンティック動画検索 を可能にし、検索精度の向上や、テキストやビジュアルコンテンツを使用したクロスモーダルクエリをサポートします。
Oracle のエンタープライズグレードの信頼性、セキュリティ、スケーラビリティを活用することで、本番デプロイ用の堅牢な基盤を提供します。企業は、データ量が増加してもベクトル操作が効率的に維持されるよう構築されたミッションクリティカルなワークロード向けの Oracle Database テクノロジーを使用して、当社の動画理解テクノロジーを安心して導入できます。
また、当社のインテグレーションにより、動画コンテンツの高度な分析が可能になり、手作業によるレビューや従来の処理では検出不可能だったパターンやインサイトを企業が発見できるようになります。
このチュートリアルでは、インフラのセットアップから高度な動画検索アプリケーションの構築まで、実際の導入手順をカバーし、真のビジネス価値をもたらすインテリジェントな動画アプリケーションを作成するための包括的な知識を提供します。
2 - Oracle Autonomous Database の作成
Oracle Cloud のセットアップ
https://www.oracle.com/cloud/free/ で Oracle Cloud Free Tier アカウントに登録します。30 日間無料で使用できる 300 ドル分のクレジットと、Always Free(常時無料)サービスが提供されます。認証目的のみでクレジットカードが必要です。
データベースの作成
https://cloud.oracle.com/db/adb にログインします
Oracle Database → Autonomous Data Warehouse の順に進みます
「Autonomous Databaseの作成」をクリックします
設定の構成
表示名: 「VideoEmbeddingsDB」(最大 14 文字)
ワークロード・タイプ: データ・ウェアハウス
デプロイメント・タイプ: サーバーレス
必須構成
データベース・バージョン: ベクトル機能を使用するために「23ai」を選択します
「Always Free」を選択します(2 OCPU、20GB ストレージ)
注意: データベースは 7 日間非アクティブ状態が続くと自動停止しますが、30 日の間に使用し続ければ、(無料で)永久に存在し続けます。
管理者パスワードの設定
ADMIN ユーザー用に、強力なパスワード(12〜30文字、大文字、小文字、数字、特殊文字を含む)を作成します。
ネットワーク・アクセス
開発用: 「セキュアなアクセスをどこからでも許可」を選択します
データベースの作成
「Autonomous Databaseの作成」をクリックします。プロビジョニングには 2〜5 分かかります。ステータスが「使用可能」になるまで待ちます。
接続ウォレットの取得
データベースの詳細ページに移動します
「データベース接続」 → 「ウォレットのダウンロード」をクリックします
ウォレットのパスワードを設定します
ウォレットの ZIP ファイルを安全に保存します
アプリケーションで ORACLE_DB_WALLET_PATH を使用します
これで、Twelve Labs Embed API と統合するデータベースの準備が整いました。次に、必要な環境変数を設定します。
3 - 事前準備と環境変数の設定
TwelveLabs Embed API と Oracle Database 23ai を統合する前に、必要なツールと資格情報がセットアップされていることを確認してください。このセクションでは、必要なソフトウェアのインストールと環境構成について説明します。
必要なソフトウェアのインストール
このチュートリアルを正常に完了するには、以下が必要になります。
AI Vector Search 機能を備えた Oracle Database 23.4 以降
開発マシンにインストールされた Python 3.8 以降
データベース接続用の Oracle Client ライブラリ
Embed API にアクセスするための TwelveLabs API キー
必要な Python パッケージをインストールします。
oracledb パッケージは Python から Oracle Database への接続を提供し、twelvelabs パッケージは Twelve Labs の API サービスへの便利なインターフェースを提供します。
環境構成
接続資格情報を安全に保存するために、以下の環境変数を設定します。
export ORACLE_DB_USERNAME=your_username export ORACLE_DB_PASSWORD=your_password export ORACLE_DB_CONNECT_STRING=your_connect_string export ORACLE_DB_WALLET_PATH=/path/to/wallet export TWELVE_LABS_API_KEY
プレースホルダーの値を実際の資格情報に置き換えてください。
your_username: データベースのユーザー名(通常、新しい Autonomous Database の場合は ADMIN)
your_password: データベースのプロビジョニング中に作成したパスワード
your_connect_string: ウォレット内の tnsnames.ora ファイルに記載されているサービス名
/path/to/wallet: Oracle ウォレットファイルを展開したディレクトリのパス
your_api_key: 開発者ポータルから取得した TwelveLabs の API キー
4 - データベース・スキーマのセットアップ
このセクションでは、TwelveLabs から取得した動画の埋め込みを保存し、クエリを実行するために必要なデータベース・スキーマを作成します。Python スクリプトを使用して接続を確立し、適切なベクトル・インデックスを持つテーブル構造を作成します。
Oracle Database への接続
create_schema_video_embeddings.py スクリプトは、前のセクションで設定した環境変数を使用して、Oracle Database インスタンスへの接続を処理します。このスクリプトの主要なコンポーネントを見てみましょう。
import oracledb # Connect to Oracle Database 23.7 with oracledb.connect( user=db_username, password=db_password, dsn=db_connect_string, config_dir=db_wallet_path, wallet_location=db_wallet_path, wallet_password=db_password ) as connection: # Script operations will go here
動画埋め込み用テーブルの作成
このスクリプトは、以下の構造を持つ video_embeddings テーブルを作成します。
CREATE TABLE video_embeddings ( id VARCHAR2(100) PRIMARY KEY, video_file VARCHAR2(1000), start_time NUMBER, end_time NUMBER, embedding_vector VECTOR(1024, float64) )
このテーブルには以下が含まれます。
id: 各埋め込みの一意の識別子video_file: ソース動画のファイル名またはパスstart_timeおよびend_time: 動画セグメントのタイムスタンプマーカーembedding_vector: Twelve Labs の埋め込みを保存するための、float64 精度を使用した 1024 次元のベクトル
ベクトル・インデックスのセットアップ
テーブルの作成が完了したら、create_vector_index を呼び出して類似性検索用のベクトル・インデックスを作成します。ターゲット精度 95% のコサイン類似度(DISTANCE COSINE)を使用します。
def create_vector_index(cursor): cursor.execute(""" CREATE VECTOR INDEX video_embeddings_idx ON video_embeddings(embedding_vector) ORGANIZATION NEIGHBOR PARTITIONS DISTANCE COSINE WITH TARGET ACCURACY 95 """)
スキーマ作成スクリプトの実行
スキーマ作成スクリプトを実行します。
このスクリプトは以下の処理を行います。
Oracle データベースに接続します
既存のテーブルがある場合は削除します
新しい
video_embeddingsテーブルを作成します指定されたベクトル・インデックスを作成します
コンソール出力で作成成功を確認します
スキーマのセットアップが完了すると、Oracle Database 23ai インスタンスに TwelveLabs の動画埋め込みを保存し、クエリを実行するための基盤が整います。
5 - 動画埋め込みの保存
データベース・スキーマをセットアップした後の次のステップは、TwelveLabs Embed API を使用して動画を処理し、結果の埋め込みを Oracle Database に保存することです。store_video_embeddings.py スクリプトがこのプロセス全体を処理し、埋め込みの生成とデータベースへの保存の両方を管理します。
スクリプト・ワークフローの理解
このスクリプトは、いくつかの重要な操作を実行します。
環境変数を使用して Oracle Database に接続します
API キーを使用して TwelveLabs クライアントを初期化します
TwelveLabs の Marengo モデル を使用して動画の埋め込みを作成します
埋め込みをデータベースのテーブルに保存します
重複処理を避けるため、処理済みの動画の記録を保持します
主な関数
埋め込みの作成
def create_video_embeddings(client, video_file): """Create embeddings for a video file using Twelve Labs Marengo""" task = client.embed.task.create( model_name=EMBEDDING_MODEL, video_file=video_file, video_clip_length=SEGMENT_DURATION ) print(f"Created task: id={task.id} model_name={EMBEDDING_MODEL} status={task.status}") status = task.wait_for_done( sleep_interval=2, callback=on_task_update ) print(f"Embedding done: {status}") return task.id
この関数は動画を TwelveLabs に送信し、Marengo 2.7 モデルを使用して動画を処理します。動画は 6 秒のクリップ(SEGMENT_DURATION 定数で構成可能)に分割され、各セグメントがそれぞれ独自の埋め込みベクトルを受け取ります。関数は、処理が完了した後に埋め込みを取得するために使用されるタスク ID を返します。
埋め込みの保存
def store_embeddings_in_db(connection, task_id, video_file): """Store video embeddings in Oracle DB""" # Get embeddings from the task task = twelvelabs_client.embed.task.retrieve(task_id) # Get embeddings from the task if not task.video_embedding or not task.video_embedding.segments: print("No embeddings found") return insert_sql = """ INSERT INTO video_embeddings ( id, video_file, start_time, end_time, embedding_vector ) VALUES ( :1, :2, :3, :4, :5 )""" BATCH_SIZE = 1000 data_batch = [] # Process in batches of 1000 for efficiency with connection.cursor() as cursor: for idx, segment in enumerate(task.video_embedding.segments): id = f"{task_id}_{idx}" vector = array.array("f", segment.embeddings_float) data_batch.append([ id, video_file, segment.start_offset_sec, segment.end_offset_sec, vector ]) # Execute and commit every BATCH_SIZE rows if len(data_batch) >= BATCH_SIZE: print("insert data") cursor.executemany(insert_sql, data_batch) connection.commit() data_batch = [] # Insert any remaining rows if data_batch: print("insert data final") cursor.executemany(insert_sql, data_batch) connection.commit() print(f"Stored {len(task.video_embedding.segments)} embeddings in database")
この関数は、TwelveLabs から完了した埋め込みを取得し、それを Oracle に保存します。各埋め込みは、以下を含むメタデータとともに保存されます。
タスク ID とセグメント・インデックスを組み合わせた一意の ID
ソース動画のファイル名
動画セグメントの開始および終了タイムスタンプ
埋め込みベクトル自体(1024 次元)
この関数は、最適なデータベース・パフォーマンスを実現するために、埋め込みを 1000 件ずつのバッチで処理します。
タスク ID の管理
def load_task_ids(): """Load existing task IDs from JSON file""" try: with open('video_task_ids.json', 'r') as f: return json.load(f) except FileNotFoundError: return {}
スクリプトは、動画パスを TwelveLabs のタスク ID にマッピングする video_task_ids.json ファイルを維持します。これにより、スクリプトはすでに埋め込み済みの動画の再処理をスキップでき、時間と API コストの両方を削減できます。動画を再埋め込みする必要がある場合は、このファイルから該当するエントリを削除するか、ファイル自体を削除してください。
スクリプトの実行
スクリプトは 2 つの方法で使用できます。
単一の動画ファイルの場合:
動画ディレクトリの場合:
ディレクトリを処理する場合、スクリプトは一般的な動画ファイルの拡張子(.mp4、.avi、.mov、.mkv、.webm)を自動的にフィルタリングし、一致する各ファイルを処理します。
進捗状況のモニタリング
スクリプトは、以下に関するリアルタイムの更新情報を提供します。
Oracle Database への接続ステータス
TwelveLabs からのタスク作成およびステータス更新
バッチ挿入の確認を含む、埋め込み保存の進捗状況
保存された埋め込みの数を示す完了サマリー
スクリプトが完了すると、動画埋め込みは video_embeddings テーブルに保存され、類似性検索を実行する準備が整います。これについては次のセクションで説明します。
6 - 動画埋め込みへのクエリ実行
動画埋め込みを Oracle Database に保存した後の最大の強みは、自然言語を使用して動画コンテンツを検索できることです。query_video_embeddings.py スクリプトを使用すると、動画リポジトリ全体にわたってセマンティック検索を実行し、単なるキーワードではなく、クエリの意味に一致する瞬間を見つけることができます。
基本的な類似性検索
検索機能の核心は、スクリプト内の以下の SQL クエリに依存しています。
SELECT video_file, start_time, end_time FROM video_embeddings ORDER BY vector_distance(embedding_vector, :1, COSINE) FETCH FIRST :2 ROWS ONLY
このクエリは、Oracle ネイティブの vector_distance 関数を COSINE 類似度メトリックとともに使用して、クエリの埋め込みと保存されているすべての動画埋め込みを比較します。結果は類似度順にソートされ、上位 2 つの一致に制限されます。
主要な関数の説明
このスクリプトには、効率的な動画検索を提供するために連携して動作するいくつかの重要な関数が含まれています。
テキストから埋め込みへの変換
def similarity_search(connection, query_text): # Create embedding for query embedding = twelvelabs_client.embed.create( model_name=EMBEDDING_MODEL, text=query_text, text_truncate="start", ) if len(embedding.text_embedding.segments) > 1: print(f"Warning: Query generated {len(embedding.text_embedding.segments)} segments. Using only the first segment.") query_vector = array.array("d", embedding.text_embedding.segments[0].embeddings_float) # Search query search_sql = """ SELECT video_file, start_time, end_time FROM video_embeddings ORDER BY vector_distance(embedding_vector, :1, COSINE) FETCH FIRST :2 ROWS ONLY """ results = [] cursor = connection.cursor() cursor.execute(search_sql, [query_vector, TOP_K]) for row in cursor: results.append({ 'video_file': row[0], 'start_time': row[1], 'end_time': row[2] }) cursor.close() return results
この関数は、テキストクエリを Twelve Labs の API に送信し、テキストのセマンティック(意味的な)内容を捉えた埋め込みベクトルを返します。スクリプトは、text_truncate="start" を使用してテキストの先頭部分を維持することにより、長いクエリの切り捨てを自動的に処理します。
複数クエリの同時処理
def similarity_search_multiple(connection, query_texts, batch_size=1000): """Perform multiple similarity searches using a list of query texts in batches""" results_by_query = {} # Process queries in batches for i in range(0, len(query_texts), batch_size): batch_queries = query_texts[i:i + batch_size] print(f"\nProcessing batch {i//batch_size + 1} ({len(batch_queries)} queries)") # Create embeddings for batch queries embeddings = [] for query_text in batch_queries: embedding = twelvelabs_client.embed.create( model_name=EMBEDDING_MODEL, text=query_text, text_truncate="start", ) if len(embedding.text_embedding.segments) > 1: print(f"Warning: Query '{query_text}' generated {len(embedding.text_embedding.segments)} segments. Using only the first segment.") query_vector = array.array("d", embedding.text_embedding.segments[0].embeddings_float) embeddings.append(query_vector) # Search query search_sql = """ SELECT video_file, start_time, end_time FROM video_embeddings ORDER BY vector_distance(embedding_vector, :1, COSINE) FETCH FIRST :2 ROWS ONLY """ with connection.cursor() as cursor: for query_text, query_vector in zip(batch_queries, embeddings): results = [] for row in cursor.execute(search_sql, [query_vector, TOP_K]): results.append({ 'video_file': row[0], 'start_time': row[1], 'end_time': row[2] }) results_by_query[query_text] = results return results_by_query
複数のクエリで検索する際の効率向上のために、この関数はクエリをバッチ処理し、データベース接続と API コール数。簡単に結果を取得して表示できるように、各クエリをその結果にマッピングする辞書を保持します。
データベース接続の管理
def query_video_embeddings(query_text): connection = oracledb.connect( user=db_username, password=db_password, dsn=db_connect_string, config_dir=db_wallet_path, wallet_location=db_wallet_path, wallet_password=db_password ) # Verify DB version db_version = tuple(int(s) for s in connection.version.split("."))[:2] if db_version < (23, 7): sys.exit("This example requires Oracle Database 23.7 or later") print("Connected to Oracle Database") print("\nSearching for relevant video segments...") results = similarity_search(connection, query_text) print("\nResults:") print("========") for r in results: print(f"Video: {r['video_file']}") print(f"Segment: {r['start_time']:.1f}s to {r['end_time']:.1f}s\n")
このスクリプトは、環境変数を使用してすべてのデータベース接続詳細を処理し、Oracle Database インスタンスへの安全で効率的なアクセスを保証します。
スクリプトの実行
クエリに一致する動画セグメントを検索するには、1つ以上のテキストクエリを引数としてスクリプトを実行します。
python3 query_video_embeddings.py "people dancing at a party" "someone explaining AI concepts"
スクリプトは任意の数のクエリを受け入れ、それらを効率的に処理します。各クエリは:
Twelve Labs の Marengo-2.7 モデルを使用して、埋め込みベクトルに変換されます
コサイン類似度を使用して、すべての動画セグメント埋め込みと比較されます
意味的に最も類似している上位2つの動画セグメントと一致させます
結果の理解
スクリプトは、読みやすい形式で結果を出力します:
Connected to Oracle Database Searching for relevant video segments... Results: ======== Query: 'people dancing at a party' ---------------------------------- Video: birthday_celebration.mp4 Segment: 15.0s to 21.0s Video: summer_festival.mp4 Segment: 45.5s to 51.5s Query: 'someone explaining AI concepts' -------------------------------------- Video: tech_lecture.mp4 Segment: 120.0s to 126.0s Video: developer_conference.mp4 Segment: 75.5s to 81
各クエリについて、最も関連性の高い動画セグメントがファイル名と正確なタイムスタンプとともにリストされます。これにより、検索基準に一致する動画の特定の部分をすばやく見つけて視聴することができます。
コサイン類似度メトリックにより、結果は完全なキーワードの一致ではなく、セマンティックな意味に基づいていることが保証されます。つまり、クエリの正確な単語が動画の画像フレーム、音声、または字幕に表示されない場合でも、関連するコンテンツを見つけることができます。
7 - まとめ
当社の Embed API と Oracle Database 23ai とのインテグレーションは、動画の理解と検索機能における重要なマイルストーンとなります。当社の高度なマルチモーダル埋め込みと Oracle の堅牢なベクトル検索機能を組み合わせることで、開発者は人間のような知覚で動画コンテンツを処理および理解する、洗練された動画アプリケーションを構築できます。
ビジネス価値
当社のソリューションは、企業にいくつかの重要なメリットをもたらします:
強化された動画検索:当社の セマンティック動画検索 機能により、ユーザーはキーワードではなく意味に基づいて関連する動画セグメントを見つけることができ、ユーザーエンゲージメントとコンテンツ発見が向上します。
統合されたインフラストラクチャ:Oracle のコンバージドデータベース戦略と連動することで、個別の専用データベースの必要性を排除し、スケーラビリティとセキュリティを強化しながら、複雑さとコストを削減します。
イノベーションとリーダーシップ:当社の最先端の AI テクノロジーを通じて、組織は市場での差別化を図り、動画コンテンツ管理および分析におけるリーダーシップを確立できます。
技術的な利点
当社のインテグレーションは開発者に以下を提供します:
合理化された開発:リレーショナルデータとベクトルデータの両方に対応する統合プラットフォームを通じて、高度な動画理解機能にアクセスし、開発ワークフローを簡素化します。
高性能検索:当社の最先端の 埋め込み(Embeddings) 技術と Oracle のベクトルインデックスを組み合わせることで、大規模な動画ライブラリにわたり、高速かつ正確な類似性検索を可能にします。
スケーラビリティと信頼性:Oracle Cloud Infrastructure (OCI) 上でトレーニングされた当社の 動画基礎モデル(Video Foundation Models) は、エンタープライズグレードの信頼性とスケーラビリティを保証します。
「Better Together(共創)」のストーリー
Oracle と当社の関係は深く、私たちは Oracle Cloud Infrastructure を活用して動画基礎モデルをトレーニングしており、人間とそれ以上に動画を理解するモデルの開発を可能にしています。Embed API を Oracle Database 23ai と統合することで、私たちの補完的なテクノロジーがお客様に強力なソリューションを提供できることを実証しています。
結論として、当社の Embed API と Oracle Database 23ai のインテグレーションは、動画コンテンツの可能性を最大限に引き出したい企業や開発者にとって画期的な進歩を意味します。このパートナーシップは、当社の高度な動画理解テクノロジーが Oracle のエンタープライズグレードのインフラストラクチャと組み合わさることで、どのように産業を変革できるかを示す一例です。
リソース一覧
チュートリアルのコードを格納した GitHub リポジトリ: https://github.com/twelvelabs-io/twelvelabs-developer-experience/tree/main/integrations/Oracle
TwelveLabs Embed API ドキュメント: https://docs.twelvelabs.io/v1.3/docs/guides/create-embeddings/video
Oracle AI Vector Search ユーザーズ・ガイド: https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/overview-node.html
インテグレーションや今回のブログ記事執筆にあたり、私たちと緊密に連携してくださった Maxwell Bauman 氏、Douglas Hood 氏、Sean Stacey 氏、Malu Castellanos 氏をはじめ、Oracle チームの皆様に心より感謝申し上げます!
マルチモーダルなビデオ理解とエンタープライズグレードのベクトル検索機能の融合は、ジェネレーティブ AI アプリケーションにおける大きな進歩を意味します。このチュートリアルでは、TwelveLabs の最先端の Embed API と Oracle Database 23ai の AI Vector Search のインテグレーションについて探求し、セマンティックな理解を通じて動画コンテンツを保存、分析、検索するための強力なソリューションを開発者に提供します。
このガイドに沿って進めることで、これら 2 つの補完的なテクノロジーを活用し、堅牢なデータベースインフラの恩恵を受けながら、視覚、音声、文脈要素の豊かさを捉えた高度な動画検索・分析アプリケーションを構築する方法を学ぶことができます。
1 - はじめに
TwelveLabs Embed API

当社の Embed API は、動画データを高度なベクトル表現(すなわち真の埋め込み)に変換することで、動画理解に革命をもたらします。単一のモダリティに焦点を当てる従来のアプローチとは異なり、当社のマルチモーダル埋め込みテクノロジーは、視覚的な表現、話し言葉、ボディーランゲージ、そして文脈上の関係性をシームレスに捉えます。私たちは動画を、単純なフレームごとの処理を超えた、時間的ダイナミクスを持つネイティブなメディアとして扱います。
当社の統一されたベクトル空間テクノロジーは、複数のモダリティを論理的な1つの表現に統合し、会話、視覚、文脈の間の豊かな相互作用を維持します。これにより、大規模な動画ライブラリの処理時間を大幅に短縮しながら、ニュアンスのある検索機能を実現します。
また、柔軟な動画セグメンテーションオプションも提供しており、異なる動画セグメントから複数の埋め込みを作成することも、動画全体に対して単一の埋め込みを作成することも可能です。これにより、動画内の特定の瞬間を正確に検索することができます。
Oracle 23ai Vector Search の機能

パートナーである Oracle は、コンバージドデータベース戦略のコア機能として、Oracle Database 23ai に AI Vector Search を組み込んでいます。Oracle のアプローチは、専用のインデックスと SQL 関数を使用して、ネイティブなベクトル保存と類似性検索を提供します。サイロ化を生み出すスタンドアロンのベクトルデータベースとは異なり、Oracle はベクトル機能をリレーショナルデータベースに直接統合しているため、構造化データと非構造化データをまたいだシームレスなクエリが可能です。
このシステムは、複数の距離メトリック(コサイン、ユークリッド、ユークリッド自乗、内積、マンハッタン、ハミング、ジャッカード)をサポートしており、ユースケースのニーズに基づいて類似性を柔軟に定義できます。スケールに合わせて最適化されているため、数百万件のレコードがある場合でもベクトル検索は効率を維持し、本番環境に対応可能です。
Oracle の確立されたインフラ内にベクトルを統合することで、開発者は使い慣れた SQL 構文と既存のセキュリティモデルを維持しながら、最先端の AI 機能を使用できます。これにより、個別の専用システムを用意する必要がなくなり、全体的なデータアーキテクチャの複雑さが軽減されます。
インテグレーションのビジネス価値
Oracle Database 23ai とのインテグレーションは、ベクトル埋め込みとリレーショナルデータストレージを統一する簡素化されたアーキテクチャを通じて、大きなビジネス価値をもたらします。これにより、別々のシステム間での同期が不要になり、不整合やメンテナンスコストが削減されます。さらに、クエリの複雑さ(リレーショナル DB とベクトルストアへの個別クエリの実行およびその後の結果の結合)や、結果が早く返ることによる遅延も減少します。
当社のソリューションは、ユーザーがキーワードではなく意味に基づいてコンテンツを見つける セマンティック動画検索 を可能にし、検索精度の向上や、テキストやビジュアルコンテンツを使用したクロスモーダルクエリをサポートします。
Oracle のエンタープライズグレードの信頼性、セキュリティ、スケーラビリティを活用することで、本番デプロイ用の堅牢な基盤を提供します。企業は、データ量が増加してもベクトル操作が効率的に維持されるよう構築されたミッションクリティカルなワークロード向けの Oracle Database テクノロジーを使用して、当社の動画理解テクノロジーを安心して導入できます。
また、当社のインテグレーションにより、動画コンテンツの高度な分析が可能になり、手作業によるレビューや従来の処理では検出不可能だったパターンやインサイトを企業が発見できるようになります。
このチュートリアルでは、インフラのセットアップから高度な動画検索アプリケーションの構築まで、実際の導入手順をカバーし、真のビジネス価値をもたらすインテリジェントな動画アプリケーションを作成するための包括的な知識を提供します。
2 - Oracle Autonomous Database の作成
Oracle Cloud のセットアップ
https://www.oracle.com/cloud/free/ で Oracle Cloud Free Tier アカウントに登録します。30 日間無料で使用できる 300 ドル分のクレジットと、Always Free(常時無料)サービスが提供されます。認証目的のみでクレジットカードが必要です。
データベースの作成
https://cloud.oracle.com/db/adb にログインします
Oracle Database → Autonomous Data Warehouse の順に進みます
「Autonomous Databaseの作成」をクリックします
設定の構成
表示名: 「VideoEmbeddingsDB」(最大 14 文字)
ワークロード・タイプ: データ・ウェアハウス
デプロイメント・タイプ: サーバーレス
必須構成
データベース・バージョン: ベクトル機能を使用するために「23ai」を選択します
「Always Free」を選択します(2 OCPU、20GB ストレージ)
注意: データベースは 7 日間非アクティブ状態が続くと自動停止しますが、30 日の間に使用し続ければ、(無料で)永久に存在し続けます。
管理者パスワードの設定
ADMIN ユーザー用に、強力なパスワード(12〜30文字、大文字、小文字、数字、特殊文字を含む)を作成します。
ネットワーク・アクセス
開発用: 「セキュアなアクセスをどこからでも許可」を選択します
データベースの作成
「Autonomous Databaseの作成」をクリックします。プロビジョニングには 2〜5 分かかります。ステータスが「使用可能」になるまで待ちます。
接続ウォレットの取得
データベースの詳細ページに移動します
「データベース接続」 → 「ウォレットのダウンロード」をクリックします
ウォレットのパスワードを設定します
ウォレットの ZIP ファイルを安全に保存します
アプリケーションで ORACLE_DB_WALLET_PATH を使用します
これで、Twelve Labs Embed API と統合するデータベースの準備が整いました。次に、必要な環境変数を設定します。
3 - 事前準備と環境変数の設定
TwelveLabs Embed API と Oracle Database 23ai を統合する前に、必要なツールと資格情報がセットアップされていることを確認してください。このセクションでは、必要なソフトウェアのインストールと環境構成について説明します。
必要なソフトウェアのインストール
このチュートリアルを正常に完了するには、以下が必要になります。
AI Vector Search 機能を備えた Oracle Database 23.4 以降
開発マシンにインストールされた Python 3.8 以降
データベース接続用の Oracle Client ライブラリ
Embed API にアクセスするための TwelveLabs API キー
必要な Python パッケージをインストールします。
oracledb パッケージは Python から Oracle Database への接続を提供し、twelvelabs パッケージは Twelve Labs の API サービスへの便利なインターフェースを提供します。
環境構成
接続資格情報を安全に保存するために、以下の環境変数を設定します。
export ORACLE_DB_USERNAME=your_username export ORACLE_DB_PASSWORD=your_password export ORACLE_DB_CONNECT_STRING=your_connect_string export ORACLE_DB_WALLET_PATH=/path/to/wallet export TWELVE_LABS_API_KEY
プレースホルダーの値を実際の資格情報に置き換えてください。
your_username: データベースのユーザー名(通常、新しい Autonomous Database の場合は ADMIN)
your_password: データベースのプロビジョニング中に作成したパスワード
your_connect_string: ウォレット内の tnsnames.ora ファイルに記載されているサービス名
/path/to/wallet: Oracle ウォレットファイルを展開したディレクトリのパス
your_api_key: 開発者ポータルから取得した TwelveLabs の API キー
4 - データベース・スキーマのセットアップ
このセクションでは、TwelveLabs から取得した動画の埋め込みを保存し、クエリを実行するために必要なデータベース・スキーマを作成します。Python スクリプトを使用して接続を確立し、適切なベクトル・インデックスを持つテーブル構造を作成します。
Oracle Database への接続
create_schema_video_embeddings.py スクリプトは、前のセクションで設定した環境変数を使用して、Oracle Database インスタンスへの接続を処理します。このスクリプトの主要なコンポーネントを見てみましょう。
import oracledb # Connect to Oracle Database 23.7 with oracledb.connect( user=db_username, password=db_password, dsn=db_connect_string, config_dir=db_wallet_path, wallet_location=db_wallet_path, wallet_password=db_password ) as connection: # Script operations will go here
動画埋め込み用テーブルの作成
このスクリプトは、以下の構造を持つ video_embeddings テーブルを作成します。
CREATE TABLE video_embeddings ( id VARCHAR2(100) PRIMARY KEY, video_file VARCHAR2(1000), start_time NUMBER, end_time NUMBER, embedding_vector VECTOR(1024, float64) )
このテーブルには以下が含まれます。
id: 各埋め込みの一意の識別子video_file: ソース動画のファイル名またはパスstart_timeおよびend_time: 動画セグメントのタイムスタンプマーカーembedding_vector: Twelve Labs の埋め込みを保存するための、float64 精度を使用した 1024 次元のベクトル
ベクトル・インデックスのセットアップ
テーブルの作成が完了したら、create_vector_index を呼び出して類似性検索用のベクトル・インデックスを作成します。ターゲット精度 95% のコサイン類似度(DISTANCE COSINE)を使用します。
def create_vector_index(cursor): cursor.execute(""" CREATE VECTOR INDEX video_embeddings_idx ON video_embeddings(embedding_vector) ORGANIZATION NEIGHBOR PARTITIONS DISTANCE COSINE WITH TARGET ACCURACY 95 """)
スキーマ作成スクリプトの実行
スキーマ作成スクリプトを実行します。
このスクリプトは以下の処理を行います。
Oracle データベースに接続します
既存のテーブルがある場合は削除します
新しい
video_embeddingsテーブルを作成します指定されたベクトル・インデックスを作成します
コンソール出力で作成成功を確認します
スキーマのセットアップが完了すると、Oracle Database 23ai インスタンスに TwelveLabs の動画埋め込みを保存し、クエリを実行するための基盤が整います。
5 - 動画埋め込みの保存
データベース・スキーマをセットアップした後の次のステップは、TwelveLabs Embed API を使用して動画を処理し、結果の埋め込みを Oracle Database に保存することです。store_video_embeddings.py スクリプトがこのプロセス全体を処理し、埋め込みの生成とデータベースへの保存の両方を管理します。
スクリプト・ワークフローの理解
このスクリプトは、いくつかの重要な操作を実行します。
環境変数を使用して Oracle Database に接続します
API キーを使用して TwelveLabs クライアントを初期化します
TwelveLabs の Marengo モデル を使用して動画の埋め込みを作成します
埋め込みをデータベースのテーブルに保存します
重複処理を避けるため、処理済みの動画の記録を保持します
主な関数
埋め込みの作成
def create_video_embeddings(client, video_file): """Create embeddings for a video file using Twelve Labs Marengo""" task = client.embed.task.create( model_name=EMBEDDING_MODEL, video_file=video_file, video_clip_length=SEGMENT_DURATION ) print(f"Created task: id={task.id} model_name={EMBEDDING_MODEL} status={task.status}") status = task.wait_for_done( sleep_interval=2, callback=on_task_update ) print(f"Embedding done: {status}") return task.id
この関数は動画を TwelveLabs に送信し、Marengo 2.7 モデルを使用して動画を処理します。動画は 6 秒のクリップ(SEGMENT_DURATION 定数で構成可能)に分割され、各セグメントがそれぞれ独自の埋め込みベクトルを受け取ります。関数は、処理が完了した後に埋め込みを取得するために使用されるタスク ID を返します。
埋め込みの保存
def store_embeddings_in_db(connection, task_id, video_file): """Store video embeddings in Oracle DB""" # Get embeddings from the task task = twelvelabs_client.embed.task.retrieve(task_id) # Get embeddings from the task if not task.video_embedding or not task.video_embedding.segments: print("No embeddings found") return insert_sql = """ INSERT INTO video_embeddings ( id, video_file, start_time, end_time, embedding_vector ) VALUES ( :1, :2, :3, :4, :5 )""" BATCH_SIZE = 1000 data_batch = [] # Process in batches of 1000 for efficiency with connection.cursor() as cursor: for idx, segment in enumerate(task.video_embedding.segments): id = f"{task_id}_{idx}" vector = array.array("f", segment.embeddings_float) data_batch.append([ id, video_file, segment.start_offset_sec, segment.end_offset_sec, vector ]) # Execute and commit every BATCH_SIZE rows if len(data_batch) >= BATCH_SIZE: print("insert data") cursor.executemany(insert_sql, data_batch) connection.commit() data_batch = [] # Insert any remaining rows if data_batch: print("insert data final") cursor.executemany(insert_sql, data_batch) connection.commit() print(f"Stored {len(task.video_embedding.segments)} embeddings in database")
この関数は、TwelveLabs から完了した埋め込みを取得し、それを Oracle に保存します。各埋め込みは、以下を含むメタデータとともに保存されます。
タスク ID とセグメント・インデックスを組み合わせた一意の ID
ソース動画のファイル名
動画セグメントの開始および終了タイムスタンプ
埋め込みベクトル自体(1024 次元)
この関数は、最適なデータベース・パフォーマンスを実現するために、埋め込みを 1000 件ずつのバッチで処理します。
タスク ID の管理
def load_task_ids(): """Load existing task IDs from JSON file""" try: with open('video_task_ids.json', 'r') as f: return json.load(f) except FileNotFoundError: return {}
スクリプトは、動画パスを TwelveLabs のタスク ID にマッピングする video_task_ids.json ファイルを維持します。これにより、スクリプトはすでに埋め込み済みの動画の再処理をスキップでき、時間と API コストの両方を削減できます。動画を再埋め込みする必要がある場合は、このファイルから該当するエントリを削除するか、ファイル自体を削除してください。
スクリプトの実行
スクリプトは 2 つの方法で使用できます。
単一の動画ファイルの場合:
動画ディレクトリの場合:
ディレクトリを処理する場合、スクリプトは一般的な動画ファイルの拡張子(.mp4、.avi、.mov、.mkv、.webm)を自動的にフィルタリングし、一致する各ファイルを処理します。
進捗状況のモニタリング
スクリプトは、以下に関するリアルタイムの更新情報を提供します。
Oracle Database への接続ステータス
TwelveLabs からのタスク作成およびステータス更新
バッチ挿入の確認を含む、埋め込み保存の進捗状況
保存された埋め込みの数を示す完了サマリー
スクリプトが完了すると、動画埋め込みは video_embeddings テーブルに保存され、類似性検索を実行する準備が整います。これについては次のセクションで説明します。
6 - 動画埋め込みへのクエリ実行
動画埋め込みを Oracle Database に保存した後の最大の強みは、自然言語を使用して動画コンテンツを検索できることです。query_video_embeddings.py スクリプトを使用すると、動画リポジトリ全体にわたってセマンティック検索を実行し、単なるキーワードではなく、クエリの意味に一致する瞬間を見つけることができます。
基本的な類似性検索
検索機能の核心は、スクリプト内の以下の SQL クエリに依存しています。
SELECT video_file, start_time, end_time FROM video_embeddings ORDER BY vector_distance(embedding_vector, :1, COSINE) FETCH FIRST :2 ROWS ONLY
このクエリは、Oracle ネイティブの vector_distance 関数を COSINE 類似度メトリックとともに使用して、クエリの埋め込みと保存されているすべての動画埋め込みを比較します。結果は類似度順にソートされ、上位 2 つの一致に制限されます。
主要な関数の説明
このスクリプトには、効率的な動画検索を提供するために連携して動作するいくつかの重要な関数が含まれています。
テキストから埋め込みへの変換
def similarity_search(connection, query_text): # Create embedding for query embedding = twelvelabs_client.embed.create( model_name=EMBEDDING_MODEL, text=query_text, text_truncate="start", ) if len(embedding.text_embedding.segments) > 1: print(f"Warning: Query generated {len(embedding.text_embedding.segments)} segments. Using only the first segment.") query_vector = array.array("d", embedding.text_embedding.segments[0].embeddings_float) # Search query search_sql = """ SELECT video_file, start_time, end_time FROM video_embeddings ORDER BY vector_distance(embedding_vector, :1, COSINE) FETCH FIRST :2 ROWS ONLY """ results = [] cursor = connection.cursor() cursor.execute(search_sql, [query_vector, TOP_K]) for row in cursor: results.append({ 'video_file': row[0], 'start_time': row[1], 'end_time': row[2] }) cursor.close() return results
この関数は、テキストクエリを Twelve Labs の API に送信し、テキストのセマンティック(意味的な)内容を捉えた埋め込みベクトルを返します。スクリプトは、text_truncate="start" を使用してテキストの先頭部分を維持することにより、長いクエリの切り捨てを自動的に処理します。
複数クエリの同時処理
def similarity_search_multiple(connection, query_texts, batch_size=1000): """Perform multiple similarity searches using a list of query texts in batches""" results_by_query = {} # Process queries in batches for i in range(0, len(query_texts), batch_size): batch_queries = query_texts[i:i + batch_size] print(f"\nProcessing batch {i//batch_size + 1} ({len(batch_queries)} queries)") # Create embeddings for batch queries embeddings = [] for query_text in batch_queries: embedding = twelvelabs_client.embed.create( model_name=EMBEDDING_MODEL, text=query_text, text_truncate="start", ) if len(embedding.text_embedding.segments) > 1: print(f"Warning: Query '{query_text}' generated {len(embedding.text_embedding.segments)} segments. Using only the first segment.") query_vector = array.array("d", embedding.text_embedding.segments[0].embeddings_float) embeddings.append(query_vector) # Search query search_sql = """ SELECT video_file, start_time, end_time FROM video_embeddings ORDER BY vector_distance(embedding_vector, :1, COSINE) FETCH FIRST :2 ROWS ONLY """ with connection.cursor() as cursor: for query_text, query_vector in zip(batch_queries, embeddings): results = [] for row in cursor.execute(search_sql, [query_vector, TOP_K]): results.append({ 'video_file': row[0], 'start_time': row[1], 'end_time': row[2] }) results_by_query[query_text] = results return results_by_query
複数のクエリで検索する際の効率向上のために、この関数はクエリをバッチ処理し、データベース接続と API コール数。簡単に結果を取得して表示できるように、各クエリをその結果にマッピングする辞書を保持します。
データベース接続の管理
def query_video_embeddings(query_text): connection = oracledb.connect( user=db_username, password=db_password, dsn=db_connect_string, config_dir=db_wallet_path, wallet_location=db_wallet_path, wallet_password=db_password ) # Verify DB version db_version = tuple(int(s) for s in connection.version.split("."))[:2] if db_version < (23, 7): sys.exit("This example requires Oracle Database 23.7 or later") print("Connected to Oracle Database") print("\nSearching for relevant video segments...") results = similarity_search(connection, query_text) print("\nResults:") print("========") for r in results: print(f"Video: {r['video_file']}") print(f"Segment: {r['start_time']:.1f}s to {r['end_time']:.1f}s\n")
このスクリプトは、環境変数を使用してすべてのデータベース接続詳細を処理し、Oracle Database インスタンスへの安全で効率的なアクセスを保証します。
スクリプトの実行
クエリに一致する動画セグメントを検索するには、1つ以上のテキストクエリを引数としてスクリプトを実行します。
python3 query_video_embeddings.py "people dancing at a party" "someone explaining AI concepts"
スクリプトは任意の数のクエリを受け入れ、それらを効率的に処理します。各クエリは:
Twelve Labs の Marengo-2.7 モデルを使用して、埋め込みベクトルに変換されます
コサイン類似度を使用して、すべての動画セグメント埋め込みと比較されます
意味的に最も類似している上位2つの動画セグメントと一致させます
結果の理解
スクリプトは、読みやすい形式で結果を出力します:
Connected to Oracle Database Searching for relevant video segments... Results: ======== Query: 'people dancing at a party' ---------------------------------- Video: birthday_celebration.mp4 Segment: 15.0s to 21.0s Video: summer_festival.mp4 Segment: 45.5s to 51.5s Query: 'someone explaining AI concepts' -------------------------------------- Video: tech_lecture.mp4 Segment: 120.0s to 126.0s Video: developer_conference.mp4 Segment: 75.5s to 81
各クエリについて、最も関連性の高い動画セグメントがファイル名と正確なタイムスタンプとともにリストされます。これにより、検索基準に一致する動画の特定の部分をすばやく見つけて視聴することができます。
コサイン類似度メトリックにより、結果は完全なキーワードの一致ではなく、セマンティックな意味に基づいていることが保証されます。つまり、クエリの正確な単語が動画の画像フレーム、音声、または字幕に表示されない場合でも、関連するコンテンツを見つけることができます。
7 - まとめ
当社の Embed API と Oracle Database 23ai とのインテグレーションは、動画の理解と検索機能における重要なマイルストーンとなります。当社の高度なマルチモーダル埋め込みと Oracle の堅牢なベクトル検索機能を組み合わせることで、開発者は人間のような知覚で動画コンテンツを処理および理解する、洗練された動画アプリケーションを構築できます。
ビジネス価値
当社のソリューションは、企業にいくつかの重要なメリットをもたらします:
強化された動画検索:当社の セマンティック動画検索 機能により、ユーザーはキーワードではなく意味に基づいて関連する動画セグメントを見つけることができ、ユーザーエンゲージメントとコンテンツ発見が向上します。
統合されたインフラストラクチャ:Oracle のコンバージドデータベース戦略と連動することで、個別の専用データベースの必要性を排除し、スケーラビリティとセキュリティを強化しながら、複雑さとコストを削減します。
イノベーションとリーダーシップ:当社の最先端の AI テクノロジーを通じて、組織は市場での差別化を図り、動画コンテンツ管理および分析におけるリーダーシップを確立できます。
技術的な利点
当社のインテグレーションは開発者に以下を提供します:
合理化された開発:リレーショナルデータとベクトルデータの両方に対応する統合プラットフォームを通じて、高度な動画理解機能にアクセスし、開発ワークフローを簡素化します。
高性能検索:当社の最先端の 埋め込み(Embeddings) 技術と Oracle のベクトルインデックスを組み合わせることで、大規模な動画ライブラリにわたり、高速かつ正確な類似性検索を可能にします。
スケーラビリティと信頼性:Oracle Cloud Infrastructure (OCI) 上でトレーニングされた当社の 動画基礎モデル(Video Foundation Models) は、エンタープライズグレードの信頼性とスケーラビリティを保証します。
「Better Together(共創)」のストーリー
Oracle と当社の関係は深く、私たちは Oracle Cloud Infrastructure を活用して動画基礎モデルをトレーニングしており、人間とそれ以上に動画を理解するモデルの開発を可能にしています。Embed API を Oracle Database 23ai と統合することで、私たちの補完的なテクノロジーがお客様に強力なソリューションを提供できることを実証しています。
結論として、当社の Embed API と Oracle Database 23ai のインテグレーションは、動画コンテンツの可能性を最大限に引き出したい企業や開発者にとって画期的な進歩を意味します。このパートナーシップは、当社の高度な動画理解テクノロジーが Oracle のエンタープライズグレードのインフラストラクチャと組み合わさることで、どのように産業を変革できるかを示す一例です。
リソース一覧
チュートリアルのコードを格納した GitHub リポジトリ: https://github.com/twelvelabs-io/twelvelabs-developer-experience/tree/main/integrations/Oracle
TwelveLabs Embed API ドキュメント: https://docs.twelvelabs.io/v1.3/docs/guides/create-embeddings/video
Oracle AI Vector Search ユーザーズ・ガイド: https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/overview-node.html




