不透明な動画から収益可能な瞬間へ：TwelveLabsを使用した文脈連動型広告エンジンの構築

TLDR

ほとんどのCTV/FASTプラットフォームは、実際に画面で何が起きているかを確認せずに広告配信を決定しています。このチュートリアルでは、構造化されたシーンインテリジェンスにTwelveLabs Pegasus 1.5を、マルチモーダルエンベディングにMarengo 3.0を、エンタープライズ分析にDatabricks Delta Lakeを使用する、本番規模のコンテキスト広告エンジンの構築プロセスを解説します。結果として、古いメタデータではなく、実際のビデオ理解に基づいた広告掲載が可能になり、IAB 3.1分類への完全準拠とFreeWheel互換のペイロードを実現できます。

構築するもの：動画コンテンツをクエリ可能なコンテキストに変換し、セマンティックな類似性とブランドセーフティルールに基づいて広告をシーンにマッチングし、最適なブレイクポイントを特定し、下流の分析のために意思決定データをDatabricksにエクスポートする完全なパイプラインです。

はじめに

ほとんどの広告配信決定の仕組みは、動画を中身の見えない黒い箱のように扱っており、広告掲載を決定するためにメタデータやコンテンツラベル、または過去のオーディエンスセグメントに依存しています。動画そのもの以外のすべてに頼っている状態です。

このアプローチは、大まかなターゲティングには有効です。キーワードマッチングを使用すれば、おおよそ的外れでない場所に配置できます。しかし、以下の3つの要素を考慮できないため、重大な収益機会を逃しています。

1. タイミング：シーンの切り替わりを意識せずに挿入された広告は、視聴体験を妨げ、動画からの離脱を引き起こします。

2. コンテキスト：システムが画面で実際に何が起きているかを把握できない場合、ブランドセーフティの違反が発生します。例えば、依存症からの回復を描いたシーンの最中にアルコールの広告を流すべきではありません。

3. 深さ：表面的なデモグラフィックターゲティングは、世帯収入、視聴デバイス、リアルタイムのエンゲージメントシグナルなどの細かなニュアンスを見落とします。

このチュートリアルでは、動画を中身の見えないブラックボックスとしてではなく、クエリ可能な構造化データとして扱うコンテキスト広告エンジンを構築することで、これら3つの課題をすべて解決します。このエンジンは以下の技術を組み合わせています：

• 感情、トーン、キャスト、環境、GARMに準拠したセーフティシグナルなど、微細なシーン理解のためのTwelveLabs Pegasus 1.5

• シーンと広告クリエイティブのセマンティック（意味的）類似性スコアリングを可能にするマルチモーダルなセマンティックエンベディングを実現するTwelveLabs Marengo 3.0

• エンタープライズ規模のストレージと検索に対応したDatabricks Delta Lake + Mosaic AI Vector Search

• 既存の広告サーバーと直接統合するための、FreeWheel/OpenRTB互換のペイロード生成

図1: ビデオインベントリにおけるインテリジェントなシーン抽出

目標は、実際のビデオコンテンツに基づいたデータを使用して、「この視聴者、この特定のシーン、ブランドセーフティとキャンペーンの制約を考慮した上で、この広告枠ではどの広告を掲載すべきか？」という問いに答えることです。

完成したアプリケーションのウォークスルーは以下からご覧いただけます：

前提条件

開始する前に、以下が必要になります：

1. Node.js 18+ および npm/yarn/pnpm

2. 2つのインデックスを持つTwelveLabs APIキー：

   • コンテンツ動画用のTL_INDEX_ID

   • 広告クリエイティブ用のTL_AD_INDEX_ID

3. TwelveLabsへの大容量ビデオファイル転送を処理するためのVercel Blobトークン (BLOB_READ_WRITE_TOKEN)

4. IAB 3.1分類へのマッピング中の低レイテンシなテキストエンベディング用のOpenAI APIキー（任意）

5. DATABRICKS_TOKEN、DATABRICKS_HOST、DATABRICKS_HTTP_PATH、およびオプションでDATABRICKS_CATALOGとDATABRICKS_SCHEMAを設定したDatabricksワークスペース（任意）

複製して実行：

>> git clone https://github.com/nathanchess/twelvelabs-context-ad-engine.git
>> cd contextual-ad-engine
>> npm install
>> cp .env.example .env.local
>> npm

アーキテクチャの概要

図2: コンテキスト広告エンジン バックエンドアーキテクチャ（LucidChart）

このアーキテクチャは、補完的な役割を果たす2つのTwelveLabsモデルを活用しています：

Marengo 3.0はエンコーダーです。ビデオを検索可能な512次元のベクトルエンベディングに変換し、製品、感情、環境、瞬間をクエリ可能にします。これにより、広告クリエイティブとコンテンツシーン間のセマンティック（意味的）マッチングが可能になります。

Pegasus 1.5は推論モデルです。デモグラフィック、ブランドセーフティフラグ、感情、ターゲティングの推奨事項など、各シーンに関する構造化メタデータを生成します。構造化出力をサポートしており、下流システムが決定論的に解析できる一貫したJSONを生成します。

技術アーキテクチャ図の右側に示されているように、これら独自の機能と生成されたメタデータを「(ユーザーと広告のマッチスコア) × (シーンと広告のマッチスコア)」という単一の決定論的な計算に活用することで、事前に作成されたテキストメタデータに依存せず、実際のビデオ理解に基づいたシーンレベルの決定による広告の推奨が可能になります。

これにより、広告エンジンは各セグメントを活きたコンテキストシグナルとして扱い、以下を考慮することができます：

• トーン

• 感情

• 環境

• ブランドセーフティ

このアプローチは、数週間前にラベル付けされたコンテンツのメタデータではなく、ビデオ内で実際に何が起きているかに基づいて広告を決定します。基礎となる技術のより詳細な背景については、TwelveLabsプラットフォームの概要およびTwelveLabsの調査を参照してください。

中核となる広告決定 | 配信ロジック

中核となる決定ロジックは、両方のシグナルを単一のスコアに結合します：

totalScore = adAffinity * sceneFit

ここで、adAffinityは視聴者のプロフィール（デモグラフィック、興味・関心、ポリシー制約）への広告の適合度を測定し、sceneFitは現在のシーンへの広告クリエイティブの適合度（セマンティック類似度 ＋ 安全性 ＋ トーン ＋ 環境）を測定します。

スコアリングパイプラインは、4つの重み付けされたシグナルを結合してsceneFitを計算します：

sceneFit =
  suitableMatch  * 0.15 +   // Pegasus suitable_categories overlap
  environmentFit * 0.15 +   // environment-category affinity
  toneCompat     * 0.10 +   // emotional tone compatibility
  contextMatch   * 0.60     // Marengo semantic cosine similarity

この重み付けは意図的なものです。CTV/OTTによる収益化では、通常、セマンティックコンテキストの品質から最も大きなCPMの上昇が得られるため、Marengo 3.0がスコアの大半を占めています。残りのシグナルは、決定論的なガードレールを必要とするポリシーチームやコンテンツセーフティチーム向けに、ルールベースの制御性を担保します。

ステップ1：構造化広告メタデータの生成（Pegasus + IAB + FreeWheel）

このステップでは、Pegasus 1.5を使用してビデオコンテンツから構造化シーンインテリジェンスを抽出し、それをIAB 3.1分類に正規化し、広告サーバー統合のためのFreeWheel互換のキー・値ペアを生成します。

1.1 - 構造化出力を有効にしてPegasus 1.5を実行する

/api/analyzeエンドポイントは3つのタスクを処理します：

1. フロントエンドからプロンプト（/videosまたは/adsページから）を受け取る

2. 冗長な処理を避けるため、Vercel Blobキャッシュを確認する

3. 構造化出力を指定してPegasus 1.5を呼び出し、結果を保存する

const tl_client = new TwelveLabs({ apiKey: process.env.TL_API_KEY });
const result = await tl_client.analyze({
  videoId,
  prompt,
  temperature: 0.2,
  response_format
}, { timeoutInSeconds: 90 });

出力は、下流システムが論理思考できる時間に合致したメタデータ（シーンの境界、感情、環境、出演者、セーフティフラグ）です。これにより、脆弱なキーワードベースのターゲティングは、信頼性の高い動画理解に置き換えられます。

1.2 - エンベディングKNN IDマッチングを介してモデル出力をIAB 3.1に正規化する

Pegasusからの分析出力は、広告サーバーの互換性を担保するために、IABコンテンツ分類3.1にマッピングされる必要があります。パイプラインは、テキストエンベディングと、標準的なIAB IDに対するk近傍法（K-NN）マッチングを使用します。

このアプローチは、承認されたIAB 3.1行のクローズドな参照テーブルを維持します：

export const IAB_ALLOWED_ROWS = [
  { tier1: "Alcohol", tier2: "Spirits", code: "1005" },
  { tier1: "Alcohol", tier2: "Beer", code: "1003" },
  { tier1: "Consumer Packaged Goods", tier2: "General Food", tier3: "Snacks", code: "1169" },
  { tier1: "Finance and Insurance", tier2: "Stocks and Investments", code: "1338" },
  { tier1: "Vehicles", tier2: "Automotive Ownership", tier3: "New Vehicle Ownership", code: "1536" },
  // ...
] as const;

各行は、インデックス作成時に一度だけエンベディングされます。実行時に、モデルから出力された候補ラベルがエンベディングされ、KNN経由で最も近い標準的IAB行にマッチングされた後、しきい値が適用されて重複排除が行われます：

export function normalizeIabWithKnnPolicy(
  rawInput: unknown,
  categoryKey?: string
): IabPolicyResult {
  const rawItems = Array.isArray(rawInput) ? rawInput : [];
  // 1) Embed candidate text from model output
  const embeddedCandidates = embedCandidateLabels(rawItems);
  // 2) KNN against canonical IAB 3.1 embedding index
  const knnMatches = queryIabKnnIndex(embeddedCandidates, { k: 5 });
  // 3) Keep only policy-compliant matches above similarity threshold
  const normalizedItems = dedupeAndSort(
    applyIabMatchPolicy(knnMatches).filter(
      (item): item is IabTaxonomyItem => Boolean(item)
    )
  );
  const high = normalizedItems.filter((item) => item.confidence >= IAB_HIGH_CONFIDENCE);
  const medium = normalizedItems.filter((item) => item.confidence >= IAB_MEDIUM_CONFIDENCE);
  let effectiveItems: IabTaxonomyItem[] = [];
  let fallbackApplied = false;
  let fallbackReason: string | null = null;
  if (high.length > 0) {
    effectiveItems = high;
  } else if (medium.length > 0) {
    effectiveItems = medium;
    fallbackReason = "No high-confidence Tier-2/3 matches; using medium-confidence Tier-1 band.";
  } else {
    const fallback = (categoryKey && FALLBACK_BY_CATEGORY_KEY[categoryKey]) || [];
    effectiveItems = fallback;
    fallbackApplied = true;
    fallbackReason = fallback.length
      ? "No medium-confidence KNN matches; applied deterministic vertical fallback."
      : "No medium-confidence KNN matches and no category fallback mapping found.";
  }
  const effectiveTier1 = [...new Set(effectiveItems.map((item) => item.tier1))];
  const effectiveTier2 = high.length > 0
    ? [...new Set(effectiveItems.map((item) => item.tier2))]
    : [];
  const effectiveTier3 = high.length > 0
    ? [...new Set(effectiveItems.map((item) => item.tier3).filter((tier3): tier3 is string => Boolean(tier3)))]
    : [];
  const effectiveIabIds = high.length > 0
    ? [...new Set(effectiveItems.map((item) => item.iabId).filter(Boolean))]
    : [];
  const averageConfidence = normalizedItems.length > 0
    ? normalizedItems.reduce((sum, item) => sum + item.confidence, 0) / normalizedItems.length
    : 0;
  return {
    normalizedItems,
    effectiveTier1,
    effectiveTier2,
    effectiveTier3,
    effectiveIabIds,
    averageConfidence,
    fallbackApplied,
    fallbackReason,
  };
}

このパイプラインはおおまかに以下の流れで処理されます：

• モデルが生成したカテゴリ表現のエンベディング化

• 標準的なIAB 3.1行のエンベディングに対するKNN類似度検索の実行

• 候補を有効なIAB分類行/IDのみに整列

• 重複排除、および信頼度（confidence）別の候補一致のランク付け

• 信頼度の高い行をアクティブなターゲティングフィールドとして採用

• 信頼度があまりに低い場合、決定論的な縦列型フォールバックを適用

これは、本番環境の広告技術にとって不可欠な要素です。分類の捏造（ハルシネーション）を防ぎ、有効なIAB 3.1 IDを強制しつつも、エンベディングベースのマッチングを通じて文脈的な細かい違いを捉えることができます。

1.3 - 正規化されたメタデータからFreeWheel KVPペイロードを構築する

IABとコンテキストシグナルが正規化されると、エンジンは下流の広告配信用のFreeWheelキー・値ペア（KVP）を生成します：

const freewheelPayload = {
  ad_server: "Freewheel",
  endpoint: "https://ads.freewheel.tv/ad/p/1",
  generated_kvps: {
    vw_brand: toBrand(parsed.company),
    vw_ctx_inc: includeContexts.join(","),
    vw_ctx_exc: excludeContexts.join(","),
    vw_garm_floor: "strict",
    vw_duration: String(duration),
    vw_ad_title: parsed.proposedTitle || "untitled",
    vw_iab_t1: policy.effectiveTier1.join(","),
    vw_iab_t2: policy.effectiveTier2.join(","),
    vw_iab_t3: policy.effectiveTier3.join(","),
    vw_iab_codes: policy.effectiveCodes.join(","),
    vw_iab_conf: policy.averageConfidence.toFixed(3),
  },
};

主なフィールドは以下の通りです：

• vw_ctx_inc：指定したコンテキストとPegasusが推奨するコンテキストを結合します

• vw_ctx_exc：キャンペーンから除外されたパラメータ、Pegasusによる不要表現、GARMフラグを結合します

• vw_iab_*：正規化され、実際に適用されたクラスのみが入力されます

このステップこそが、AIによって生成された理解を既存の運用ワークフローに結びつけます。TwelveLabsはセマンティックな理解力を提供し、ポリシーに則った正規化により確実、かつ監査可能な分類動作を保証します。FreeWheel/OpenRTBマッピングにより、これらの結果を実稼働環境の広告サーバーに適用できるようにします。

ステップ2：Marengoによるマルチモーダルエンベディングの構築

Marengo 3.0を使用することで、コンテンツシーンと広告クリエイティブの双方が同一の512次元エンベディング空間にベクトル化されます。これにより、単なるキーワードの一致に留まらず、シーンと広告の真の意味的な（セマンティックな）マッチングが可能となります。

export function cosineSimilarity(vecA: number[], vecB: number[]): number {
  let dot = 0, normA = 0, normB = 0;
  const len = Math.min(vecA.length, vecB.length);
  for (let i = 0; i < len; i++) {
    dot += vecA[i] * vecB[i];
    normA += vecA[i] * vecA[i];
    normB += vecB[i] * vecB[i];
  }
  if (normA === 0 || normB === 0) return 0;
  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
}

デプロイされたアプリケーションの「メタデータビュー（Metadata View）」から、これらエンベディングの視覚化データを確認できます。セマンティックに類似したシーンがどのようにクラスタリング（集約）されているかが分かります。

ランキングのばらつきを改善するために、エンジンは期待されるコサイン値を正規化し、非線形ブースト（べき乗変換）を適用します。これにより、上位候補に並ぶ高品質な一致がより明確に切り分けられ、広告選択において類似度スコアが0.7の場合と0.8の場合の差が、より意義深いものとなります。

ステップ3：最適な広告ブレイクの特定

広告を推奨する前に、エンジンはコンテンツ内の最適な広告挿入（収益化）ポイントを特定します。Pegasus 1.5は、各シーンについて以下の要素を分析します：

• セグメント直後の区切りのクオリティ

• 割り込みが発生することによる不快さのリスク

• 不快なシーン（ネガティブなトーンなど）の検知

• シーンが切り替わるタイプに応じた追加評価点（トランジションタイプボーナス）

• モード（厳格、バランス重視、収益最優先）を考慮したセーフティ評価係数

その後、エンジンは間隔の制約を適用し、時系列順にスコアの高いブレイクポイントを貪欲法（グリーディーアプローチ）で選び出します。

実環境において、広告の関連性は、挿入タイミングが視聴者の不快感を防ぎ、UXに配慮して判定された場合のみ真に意味を持つため、この処理が極めて重要です。どれだけコンテンツと合致した高精度の広告であっても、発言の途中や最も感情の高まるクライマックスシーンで表示されれば、離脱を引き起こしてしまいます。

ステップ4：セーフティフィルタ ＋ 広告重複制限による広告のランク付け

最適なブレイクポイントが特定され、エンベディングが算出され、メタデータが抽出されたことで、エンジンは広告の順位付けを行えるようになります。しかし、単純なスコアリングだけでは本番環境で不十分です。商用の広告配信においては、以下の2つの層の追加チェックが必要になります：

1. ブランドセーフティに基づく厳格なフィルタリング

スコアリングの実行前に、広告は以下を介してフィルタリングされます：

• ユーザー・対象カテゴリの適合検証

• 不要なキャンペーンコンテキスト（状況設定）の重複検知

• GARMに規定されるリスク対象（アルコール、ギャンブル、暴力表現など）の除外

• セーフティモード適用ルール

2. ブレイク間を跨いでの表示多様性

車がどれほど好きな視聴者であっても、すべての広告箇所で車の広告ばかり見たいとは思いません。このエンジンでは以下のような重複制限を適用します：

• 同一の広告映像についての挿入箇所全般における再生上限を設定

• 同一カテゴリーの表示頻度の制限

• 表示多様性のルールにより上位候補が除外された場合の、適切な代替動作の設定

結果として、視聴者やその瞬間（シーン）、および確保できている広告枠に合わせて最適化された、スコアが高くかつテレビ放送のように自然な流れの広告プランが生成されます。

ステップ5：エンタープライズな検索と分析のためのDatabricksへのエクスポート

このエンジンが生成したメタデータ、エンベディング、および広告判定用データは、社内の既存システムと連携して初めて真の価値を生み出します。システムはすべてのシグナルをDatabricks Delta Tableに蓄積し、そこから先のアナリティクスや機械学習パイプラインで利用できるようにします。

ユーザー個別のDatabricks環境（ワークスペース）に応じて、自動的にクエリが組み立てられます：

CREATE OR REPLACE VIEW ad_metadata_premium_spirits_vec AS
SELECT
  creative_id,
  campaign_name,
  from_json(marengo_embedding_json, 'array<double>') AS embedding
FROM main.default.ad_metadata_premium_spirits
WHERE vector_sync_status = 'embedded_marengo_clip_avg'

Databricksにこれらの価値あるデータをインポートすることで、以下が実現します：

1. 大規模検索に最適化されたMosaic AI Vector Search Indexingによる類似判定

2. すべての掲載決定に対する完全な監査記録を伴うキャンペーンQA（品質保証）

3. 動画演出の企画（クリエイティブ運用等）や競合分析に活かせる類似素材の検索

4. BIや機械学習（ML）のフローで利用できる、モデルに支援された分析設計

全社展開を検討しているシステム管理者にとっても、TwelveLabsとDatabricksのこの連携は非常に魅力的な選択肢です。なぜならAIモデルならではの動画インテリジェンスと、強固な企業のデータガバナンスおよび効率的な検索インフラが完全に機能統合されるからです。

なぜコンテキストターゲティング広告にTwelveLabsなのか

ここまでで、古びたメタデータから離れ、実際の動画の再生内容に基づいて配信判定を行える広告エンジンの仕組みが理解できた（または一通り作成してみた）はずです。このように、複雑なタイミング判定、シーン情感、セマンティック（意味構造）、および業務要件を実用的な構成で一貫してサポートできる仕組みは、動画に特化した優れたAIを設計・搭載しない限りはほぼ不可能です。

TwelveLabsは以下の基礎技術を提供しています：

• 詳細で構造化されたシーンインテリジェンスのためのPegasus 1.5

• マルチモーダルなセマンティック検索およびマッチングを実現するMarengo 3.0

• 既存の広告配信システム（アドテクスタック）へスムーズに組み込めるAPI主導の構造設計

これらの強力な連携により、これまで「単なる中身の見えない高負荷な保存動画データの一種」であったファイルが、クエリ可能で直接収益を生み出す生きた企業資産へと変わります。

開発をスタートする

• 動作確認環境：ホーム | TwelveLabs

• API仕様解説：はじめに | TwelveLabs

• 製品概要：Video AI Platform: Search, Analyze & Embed - TwelveLabs

• 法人・お問い合わせ：TwelveLabsへのお問い合わせ: 営業部門へ

• 構成設計イメージ図：https://lucid.app/lucidchart/ef8d11e1-3f00-4bf0-b411-ab8e3bb3606b/edit?viewport_loc=515%2C-1146%2C5419%2C2654%2C0_0&invitationId=inv_09de1972-142b-4369-9df4-f91eb3f5a949 

• ソースコード：nathanchess/twelvelabs-context-ad-engine: TwelveLabsマルチモーダル機能とDatabricks連携を備えた、動画の内容に基づくコンテキスト広告挿入エンジン

• 本番デプロイプログラム：動画コンテキスト広告エンジン — TwelveLabs