TwelveLabsがわずか数回のAPI呼び出しで、何時間もの手動ビデオ注釈作業を削減する方法

はじめに

ビデオデータのラベリングは、機械学習における最もコストのかかるボトルの1つです。わずか1時間の映像を処理するのに4時間の人間によるアノテーション時間が必要であり、専門家（放射線科医、安全監査人、スポーツアナリストなど）への1時間あたり100ドルのコストを考えると、バックログに達するはるか前に採算が合わなくなります。

映像自体は存在しています。ドライブレコーダー、店舗の監視カメラ、倉庫のフィード、手術の録画、スポーツ中継など、企業は何千時間ものビデオを保有しており、そこにはまさにモデルが必要としているトレーニングシグナルが含まれています。しかし、未加工の映像から構造化されたラベルを作成するまでのプロセスは、今でもレビュー担当者がフレームごとに確認するラベリングプラットフォームに依存しています。

このチュートリアルでは、異なるパイプラインを構築します。ビデオをアノテーターに送る代わりに、TwelveLabsのマルチモーダル基盤モデルに送ります。Marengoは各ビデオを、視覚、音声、コンテキスト情報を512次元でキャプチャする高密度な時系列エンベディングへとエンコードします。その後、Pegasusがそれらのエンベディングを推論し、構造化され、タイムスタンプが付与されたアノテーション（シーン分類、オブジェクト検出、確信度スコアを網羅）を、厳密なJSONスキーマに準拠した形で返します。

このウォークスルーを終える頃には、ビデオのインデックス作成、カスタムタクソノミー（分類体系）に沿ったトレーニングラベルの自動生成、2次元エンベディング空間でのデータセットの可視化、そしてPyTorchや標準的な機械学習パイプラインに直接取り込めるCOCO、JSON、またはCSV形式でのエクスポートが可能な、実際に動作するNext.jsアプリケーションが完成します。

完成したアプリケーションの動作は以下の通りです：

アーキテクチャの概要

コードを書く前に、全体のパイプラインを示します。各レイヤーは、本番環境におけるビデオアノテーションの特定の制約を解決するために選定されています。

Next.js 16 + React 19 は、フロントエンドのダッシュボードとバックエンドのAPIルートの両方を処理します。サーバーレス機能を使用することで、常時稼働するサーバーなしでアノテーションパイプライン全体をオーケストレーションできます。これは、ISVパートナーや社内チームが vercel deploy コマンド1つでこれをデプロイできるようにしたい場合に重要となります。

Vercel Blob は、一時的なビデオストレージを提供します。サーバーレス環境では厳密なペイロード制限（Vercelでは4.5 MB）が課されるため、クライアントはビデオファイルをBlobストレージに直接アップロードし、生成された公開URLのみをAPIルートに渡します。これにより、アップロードサイズが関数の制約から切り離されます。

TwelveLabs Marengo は、各ビデオから512次元のベクトルエンベディングを抽出します。これらはフレームレベルの特徴量ではありません。Marengoはビデオを、視覚、音声、時間的次元にわたる連続的なマルチモーダルシグナルとして処理し、ピクセルデータではなくセマンティック（意味的）な意味を捉えるセグメントレベルのエンベディングのシーケンスを生成します。これにより、手作業での特徴量エンジニアリングを一切行うことなく、下流でのクラスタリングや可視化が可能になります。

TwelveLabs Pegasus (Analyze API) は推論エンジンとして機能します。エンベディングとユーザーが定義したラベルタクソノミーを受け取り、Pegasusはタイムスタンプ、シーン分類、検出されたオブジェクトを含む、機械が読み取り可能な構造化されたアノテーションを生成します。これらはすべて、MLトレーニングフォーマットに直接マッピングできるJSONとして返されます。

データフローの詳細については、LucidChartで公開されている完全なアーキテクチャ図をご覧ください：[TwelveLabs] - 自動ビデオデータラベリングソリューション

ステップ 1: 前提条件とセットアップ

このプロジェクトをローカルで実行するには、次の3つのものが必要です。

• Node.js 18+ (20+ 推奨)

• TwelveLabs ダッシュボードから取得したTwelveLabs API キー

• 一時的なビデオアップロードを処理するためのVercel Blob トークン

リポジトリをクローンし、依存関係をインストールします：

>> git clone https://github.com/nathanchess/tl-automated-video-data-labeler.git
>> cd tl-automated-video-data-labeler
>> npm

.env.local ファイルを設定します：

TL_API_KEY=your_twelvelabs_api_key_here
TL_INDEX_NAME=your_default_index_name_here
BLOB_READ_WRITE_TOKEN

npm run dev を実行して開発サーバーを起動します。ダッシュボードは http://localhost:3000/indexes でアクセス可能になります。

ステップ 2: ビデオの取り込みとインデックス作成

取り込みフローは、ユーザーがダッシュボードのUIにビデオファイルをドロップしたときに始まります。クライアントは各ファイルをVercel Blobにアップロードし、生成された公開URLをNext.jsのAPIルートに送信してTwelveLabsのインデックス作成をトリガーします。

以下は、src/app/api/videos/route.js におけるサーバー側のロジックです：

import { TwelveLabs } from 'twelvelabs-js';
import { NextResponse } from 'next/server';

const tl_client = new TwelveLabs({ apiKey: process.env.TL_API_KEY });

export async function POST(request) {
  const { videoURLs, metadata } = await request.json();

  // 1. Locate the target index
  const indexPager = await tl_client.indexes.list();
  let indexId = null;
  for await (const index of indexPager) {
    if (index.indexName === process.env.TL_INDEX_NAME) indexId = index.id;
  }

  if (!indexId) return NextResponse.json({ error: 'Index not found' }, { status: 404 });

  // 2. Create tasks and wait for completion
  for (const videoURL of videoURLs) {
    const task = await tl_client.tasks.create({
      indexId,
      videoUrl: videoURL,
      userMetadata: JSON.stringify(metadata),
    });

    const completedTask = await tl_client.tasks.waitForDone(task.id, {
      sleepInterval: 5,
    });

    if (completedTask.status !== 'ready') {
      throw new Error(`Task ${completedTask.id} failed`);
    }
  }

  return new Response('ok');
}

本番環境での注意点: ビデオ処理は基本的に非同期処理です。ここでの waitForDone 呼び出しは、インデックス作成が完了するまでHTTPリクエストをブロックします。これは数個のクリップを処理するリファレンスアプリケーション用の動作です。何時間もの映像を処理する本番環境のパイプラインでは、インデックス作成をバックグラウンドキュー（Inngest、Upstashなど）にオフロードし、TwelveLabsのWebフックを使用して処理完了をアプリケーションに通知するようにしてください。SDKはこのパターンを完全にサポートしています。

ステップ 3: エンベディングの抽出とプーリング

ビデオのインデックスが作成されたら、ビデオとそれに対応するMarengoエンベディングを取得します。これらのベクトルは、セマンティックなグループ分けや、後ほど構築する2次元の視覚化を可能にする原動力となります。

const videoPager = await tl_client.indexes.videos.list(indexId);
  const videos = [];

  for await (const video of videoPager) {
    let embeddings = [];
    try {
      const videoData = await tl_client.indexes.videos.retrieve(indexId, video.id, {
        embeddingOption: ['visual'],
      });

      const segments = videoData.embedding?.videoEmbedding?.segments || [];
      if (segments.length > 0) {
        const dim = segments[0].float?.length;
        if (dim) {
          const sum = new Array(dim).fill(0);
          let count = 0;

          // Average the embeddings across all temporal segments
          for (const seg of segments) {
            if (seg.float && seg.float.length === dim) {
              for (let i = 0; i < dim; i++) sum[i] += seg.float[i];
              count++;
            }
          }
          if (count > 0) embeddings = sum.map((val) => val / count);
        }
      }
    } catch (embErr) {
      console.warn(`Failed to get embeddings for ${video.id}`);
    }
    videos.push({ ...video, embeddings });
  }

なぜミーンプーリング（平均値プーリング）を行うのか？ Marengoは、時系列セグメント（例えば0〜5秒、5〜10秒など）にマッピングされたエンベディングのシーケンスを出力します。その時間的な粒度は、検索（フォークリフトが制限エリアに進入した正確な瞬間を見つけるなど）には非常に便利ですが、ビデオ全体を2D散布図上の1つの点としてプロットして可視化するためには、ビデオごとに1つのベクトルが必要になります。

ミーンプーリング（すべてのセグメントにわたる浮動小数点値の平均を求めること）は、ビデオ全体のセマンティックなコンテンツを代表する複合ベクトルを生成します。映像が主に倉庫内で稼働するフォークリフトである場合、どの特定の5秒間のセグメントを抽出するかに関わらず、平均化されたベクトルはエンベディング空間における「フォークリフト作業」の領域に着地します。

ステップ 4: Pegasusによるゼロショット自動ラベリング

アノテーションに汎用的なLLM（大規模言語モデル）を使用する際の核心的な問題は、出力構造にあります。言語モデルはフリートークンのテキストを返すため、開発者は長文の段落からタイムスタンプやラベル、確信度スコアを抽出するために脆弱な正規表現を書くことになります。予想外のフォーマット変更が1つあるだけで、パーサーが壊れてしまいます。

TwelveLabsのAnalyze APIは、Pegasusの出力に厳格なJSONスキーマを適用することで、この問題を排除します。機械学習パイプラインが期待する正確な構造を定義し、ユーザー固有のカスタムラベルタクソノミー（例：shoplifting (万引き)、forklift_violation (フォークリフト違反)、surgical_clamp (止血鉗子) など）を直接プロンプトに挿入するだけで、後処理なしで機械が解析可能なアノテーションデータを受け取ることができます。

const response_format = {
    type: 'json_schema',
    json_schema: {
      type: 'object',
      properties: {
        annotations: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              start_timestamp: { type: 'string' },
              end_timestamp: { type: 'string' },
              description: { type: 'string' },
              scene_classification: { type: 'string' },
              detected_objects: {
                type: 'array',
                items: {
                  type: 'object',
                  properties: {
                    label: { type: 'string' },
                    confidence_score: { type: 'number' },
                    start_timestamp: { type: 'string' },
                    end_timestamp: { type: 'string' },
                  },
                },
              },
            },
            required: ['start_timestamp', 'end_timestamp', 'description', 'scene_classification', 'detected_objects'],
          },
        },
      },
    },
  };

このスキーマにより、すべてのアノテーションが開始・終了タイムスタンプ、自然言語による説明、シーン分類ラベル、および検出されたオブジェクトの配列（それぞれに確信度スコアとタイムスタンプ範囲）を確実に含むようになります。Pegasusはゼロショット生成モデルであるため、ファインチューニングは不要です。タクソノミーを定義し、スキーマを渡すだけで、ものの数秒で構造化されたトレーニングデータを取得できます。

ステップ 5: PCAを用いたインタラクティブなエンベディングビジュアライゼーション

機械学習のパイプラインには数値やラベルが必要ですが、データを整理・キュレーションする作業においては、データセットを視覚的に確認することも大切です。このアプリケーションには、主成分分析（PCA）を利用してMarengoの512次元エンベディングを2次元に投影する、ブラウザ上で動くインタラクティブな2D散布図が含まれています。

ブラウザビジュアライゼーション向けのPCAの最適化

高次元データに対するPCAの計算は非常に高コストです。標準的なアプローチ（512 × 512の共分散行列を構築し、特異値分解によってその固有値を求める方法）は、ブラウザのプロセスをフリーズさせてしまいます。ユーザーが50本のビデオからなるデータセットを整理している際には、読み込み中のスピナーではなく、即座の視覚的フィードバックが求められます。

その解決策がグラム行列アプローチです。完全な D × D（D = 512）の共分散行列を計算する代わりに、ビデオ間の内積からなる N × N の行列（N = データセット内のビデオ数）を計算します。50ビデオのデータセットであれば、50 × 50の行列の固有ベクトルを求める方が512次元を扱うより桁違いに高速になり、計算量を O(D³) から O(N³) へと削減し、ブラウザのメインスレッドを止めずに滑らかな描画を維持することができます。

可視化によって明らかになるアノテーション品質： 点が綺麗にグループ化され、空間的に分離している場合、分類したカテゴリがセマンティックに明確に区別されていることを意味します。外れ値（どのグループからも遠く離れた位置にある点）は、別個のアノテーションの注意が必要な珍しいイベント（日常的な倉庫の映像の中で発生した安全関連のアクシデントなど）か、誤分類されたノイズデータのいずれかを示しています。これにより、データのプロジェクトマネージャーやアノテーターは、多大なコストをかけてモデルの教育を開始する前に、データセットの健康状態に関する具体的なアクションにつながるフィードバックを即座に得ることができます。

ステップ 6: MLパイプライン向けへのエクスポート

いくら整理されたデータセットであっても、後続の学習用ツールとの互換性がなければ価値は半減します。このアプリケーションは、ネイティブで3つのエクスポート形式に対応しています。

1. JSON は、カスタムデータローダーを介してプログラムでパースするためのプログラムフレンドリーな生の構造化出力を提供します。確信度スコア付きのネストされた検出オブジェクトを含む、Pegasusのアノテーションスキーマからすべてのフィールドが保持されます。

2. CSV は、タイムスタンプ、ラベル、説明を含むスプレッドシート対応の行にアノテーションをフラット化します。手作業での簡単な監査や、pandas（Python）ベースの前処理スクリプトへの読み込みに便利です。

3. COCO (Common Objects in Context) は、主要なトレーニングフレームワークが想定する videos、annotations、categories のアレイにアノテーションを配置します。これはPyTorchのDataLoaderがネイティブに使用する形式であり、人間による最終チェックのため、Label StudioやCVATといった外部のラベリングプラットフォームにも直接インポートできます。

COCO形式へのエクスポートは非常に重要です。なぜなら、アノテーションとトレーニングの間に通常発生する、フォーマットの変換作業を省くことができるからです。未加工の動画からインデックス化されたエンベディング、構造化されたラベル、そしてトレーニング可能なデータセットまで、すべて単一のパイプラインで完結します。

ビジネスへの影響：何が変わるのか

MLおよびコンピュータビジョンチーム向け

このパイプラインを導入することで、アノテーションのボトルネックによるコストを、人的な労働力から計算リソースへとシフトできます：

• 従来の手動ワークフロー： 専門知識を持つ人材が1時間の動画に対して2〜4時間作業し、コストは1時間あたり50〜100ドル。500時間の動画ライブラリを処理するには1,000〜2,000時間のアノテーション作業が必要となり、フルタイム労働で約6〜12ヶ月相当になります。

• TwelveLabs自動化ワークフロー： 1つの動画のインデックス作成と構造化アノテーションの処理時間は約1分の計算コスト。自動生成されたラベルの最終確認作業のみを人が行います。同じ500時間の動画ライブラリを数ヶ月ではなく、数日で処理完了へと導きます。

人間は品質管理（QA）の観点からプロセスに関わり続けますが、コストがかかる最初のステップ（2時間のビデオから関係する4秒のアクションを見つけ出す作業）はモデルが処理します。これにより、これまで費用対効果が見合わず放置されていた過去のアーカイブ映像にも、ラベリングを施すことが商業的に可能になります。

データラベリングプラットフォームのISV向け

このアプリケーションは、製品の設計図でもあります。プラットフォームにAIベースのビデオアノテーションを組み込むことで、プロジェクト単位のアノテーション作業の手間を80〜90％削減できます（数時間の手動作業を数分間の機械処理に置き換える実証結果に基づきます）。これにより、純粋な「人作業の作業時間」を切り売りするビジネスモデルから、スケーラブルな「高単価、高付加価値なインテリジェンスの提供」へとシフトできます。ラベリングがますますコモディティ化するなかで、これは極めて強力な差別化要因になります。

まとめ

このリファレンスアプリケーションは、TwelveLabsのビデオ理解APIを使用し、未加工のビデオを構造化され教育可能なデータセットに変換する一連のパイプラインを明示しています。Marengoは映像を時系列の高密度エンベディングにエンコードします。Pegasusは、それらのエンベディングをタイムスタンプが付与され、指定されたスキーマに適合した形でトレーニング用ラベルに変換します。そして、ブラウザベースのダッシュボードが、データの取り込み、可視化、エクスポートのすべてを処理します（常時オンのバックエンドサーバーを必要としません）。

このチュートリアルを実行して得られるもの：独自の映像を用意し、カスタムタクソノミーを設定すれば、ビデオのインデックスを作成する時間だけで、機械学習にそのまま使えるアノテーションデータを即座に生成するアプリケーションを得ることができます。

完全なソースコードはGitHubで公開されています。ぜひクローンし、TwelveLabsのインデックスを設定して開発を始めてください。

ソースコードを入手する →

ライブデモを体験する →

TwelveLabsのビデオ理解APIで他に何ができるか探求するには、ドキュメントをご参照いただくか、当社チームまでお問い合わせください。

リソース

• TwelveLabs ドキュメント

• GitHub リポジトリ (ソースコード)

• ウォークスルー チュートリアル動画 (YouTube)

• アーキテクチャダイアグラム (LucidChart)