View a markdown version of this page

TwelveLabs Marengo Embed 3.0 - Amazon Bedrock
TwelveLabs Marengo Embed 2.7 から TwelveLabs Marengo Embed 3.0 に移行するTwelveLabs Marengo Embed 3.0 リクエストパラメータTwelveLabs Marengo Embed 3.0レスポンスTwelveLabs Marengo Embed 3.0 コードの例

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

TwelveLabs Marengo Embed 3.0

このTwelveLabs Marengo Embed 3.0モデルは、動画、テキスト、オーディオ、画像、またはマルチ入力 (複数の画像を含むテキスト) 入力から拡張埋め込みを生成します。この最新バージョンでは、類似度検索、クラスタリング、その他の機械学習タスクのパフォーマンスと精度が向上します。

  • プロバイダー — TwelveLabs

  • モデル ID — twelvelabs.marengo-embed-3-0-v1:0

Marengo Embed 3.0 は、いくつかの主要な機能強化を提供します。

  • 拡張ビデオ処理容量 – 最大 4 時間のビデオおよびオーディオコンテンツを処理します。ファイルは最大 6 GB で、以前のバージョンの容量の 2 倍になります。これにより、完全なスポーツイベント、拡張トレーニングビデオ、完全な映画制作の分析に最適です。

  • スポーツ分析の強化 – このモデルは大幅に改善されています。ゲームプレイのダイナミクス、プレイヤーの動き、イベント検出をよりよく理解できます。

  • グローバル多言語サポート – 言語機能を 12 から 36 の言語に拡張しました。これにより、グローバル組織は、さまざまなリージョンや市場にわたってシームレスに機能する統合検索および検索システムを構築できます。

  • マルチモーダル検索の精度 – 画像と説明テキストを単一の埋め込みリクエストに結合します。これにより、視覚的な類似性とセマンティックな理解がマージされ、より正確でコンテキストに関連する検索結果が得られます。

  • 埋め込みディメンションの削減 – 1024 から 512 に削減され、ストレージコストを削減できます。

TwelveLabs Marengo Embed 3.0 モデルは、次の表の Amazon Bedrock ランタイムオペレーションをサポートしています。

API オペレーション: サポートされているモデルタイプ 入力モダリティ 出力モダリティ

InvokeModel

米国東部 (バージニア北部) – ベースモデルと推論プロファイル

欧州 (アイルランド) – 推論プロファイル

アジアパシフィック (ソウル) - ベースモデル

テキスト

イメージ

マルチ入力 (複数のイメージを含むテキスト)

注: インターリーブされたテキストとイメージもサポートされています。

埋め込み
StartAsyncInvoke

米国東部 (バージニア北部) – ベースモデル

欧州 (アイルランド) – ベースモデル

アジアパシフィック (ソウル) - ベースモデル

動画

音声

画像

テキスト

マルチ入力 (複数のイメージを含むテキスト)

注: インターリーブされたテキストとイメージもサポートされています。

埋め込み
注記

検索クエリの埋め込みを生成するには、InvokeModel を使用します。アセットの埋め込みを大規模に生成するには、StartAsyncInvoke を使用します。

次のクォータが入力に適用されます。

入力モダリティ 最大値
テキスト 500 トークン
画像 イメージあたり 5 MB
動画 (S3) 6 GB、4 時間の長さ
音声 (S3) 6 GB、4 時間の長さ
注記

base64 エンコーディングを使用して音声または動画をインラインで定義する場合は、リクエスト本文のペイロードが Amazon Bedrock 25 MB のモデル呼び出しクォータを超えないようにしてください。

TwelveLabs Marengo Embed 2.7 から TwelveLabs Marengo Embed 3.0 に移行する

重要

TwelveLabs Marengo Embed 2.7 は廃止されます。で作成した埋め込みTwelveLabs Marengo Embed 2.7は、 と互換性がありませんTwelveLabs Marengo Embed 3.0。ですべての埋め込みを再生成する必要がありますTwelveLabs Marengo Embed 3.0。

から TwelveLabs Marengo Embed 2.7 に移行するにはTwelveLabs Marengo Embed 3.0、次の手順を実行します。

  1. 次のセクションで説明する新しいネストされた入力構造とパラメータの変更を使用するようにコードを更新します。

  2. モデル ID を に更新しますtwelvelabs.marengo-embed-3-0-v1:0。

  3. 新しいバージョンとの統合をテストします。

以下は、 TwelveLabs Marengo Embed 2.7と の主な変更点ですTwelveLabs Marengo Embed 3.0。

  • ネストされた入力構造 – 値に基づいて入力パラメータがオブジェクト内に整理されるようになりましたinputType。たとえば、 inputTypeが の場合text、 text オブジェクトinputText内にネストします。

  • テキスト入力とイメージ入力の組み合わせ – 新しいtext_image入力タイプを使用すると、テキストとイメージを 1 つのリクエストに結合できます。この入力タイプは ではサポートされていませんTwelveLabs Marengo Embed 2.7。

  • パラメータの変更 – embeddingOption変更されたパラメータ値:

    • TwelveLabs Marengo Embed 2.7: visual-text, visual-image, audio

    • TwelveLabs Marengo Embed 3.0: visual, audio, transcription

次の例は、テキスト入力の構造変更を示しています。

TwelveLabs Marengo Embed 2.7 (フラット構造)

{
    "inputType": "text",
    "inputText": "your-text",
    "embeddingOption": "visual-text"
}

TwelveLabs Marengo Embed 3.0 (ネストされた構造)

{
    "inputType": "text",
    "text": {
        "inputText": "your-text"
    },
    "embeddingOption": "visual"
}

次の例は、メディア入力 (画像、動画、オーディオ) の構造変更を示しています。

TwelveLabs Marengo Embed 2.7 (フラット構造)

{
    "inputType": "image|video|audio",
    "mediaSource": {
        "s3Location": {
            "bucketName": "your-bucket",
            "objectKey": "your-key"
        }
    },
    "embeddingOption": "visual-image|audio"
}

TwelveLabs Marengo Embed 3.0 (ネストされた構造)

{
    "inputType": "image|video|audio",
    "image|video|audio": {
        "mediaSource": {
            "s3Location": {
                "bucketName": "your-bucket",
                "objectKey": "your-key"
            }
        }
    },
    "embeddingOption": "visual|audio|transcription"
}

TwelveLabs Marengo Embed 3.0 リクエストパラメータ

リクエストを行う際に、モデル固有の入力が指定されるフィールドは、API オペレーションによって異なります。

モデル入力の形式は、入力モダリティによって異なります。

Text
{
    "inputType": "text",
    "text": {
        "inputText": "string"
    }
}
Image
{
  "inputType": "image",
  "image": {
    "mediaSource": {
      "base64String": "base64-encoded string", // base64String OR s3Location, exactly one
      "s3Location": {
        "uri": "s3://amzn-s3-demo-bucket/folder/dog.jpg",
        "bucketOwner": "123456789012"
      }
    }
  }
}
Text & image
{
  "inputType": "text_image",
  "text_image": {
    "inputText": "man walking a dog",
    "mediaSource": {
      "base64String": "base64-encoded string", // base64String OR s3Location, exactly one
      "s3Location": {
        "uri": "s3://amzn-s3-demo-bucket/folder/dog.jpg",
        "bucketOwner": "123456789012"
      }
    }
  }
}
Audio
{
  "inputType": "audio",
  "audio": {
    "mediaSource": {
      "base64String": "base64-encoded string", // base64String OR s3Location, exactly one
      "s3Location": {
        "uri": "s3://amzn-s3-demo-bucket/audio/a.wav",
        "bucketOwner": "123456789012"
      }
    },
    "startSec": 0,
    "endSec": 6,
    "segmentation": {
      "method": "fixed", 
      "fixed": {
        "durationSec": 6
      }
    },
    "embeddingOption": [
      "audio",
      "transcription"
    ], // optional, default=both
    "embeddingType": [
      "separate_embedding"
    ], // optional, default=["separate_embedding"]
    "embeddingScope": [
      "clip",
      "asset"
    ] // optional, one or both
  }
}
Video
{
  "inputType": "video",
  "video": {
    "mediaSource": {
      "base64String": "base64-encoded string", // base64String OR s3Location, exactly one
      "s3Location": {
        "uri": "s3://amzn-s3-demo-bucket/video/clip.mp4",
        "bucketOwner": "123456789012"
      }
    },
    "startSec": 0,
    "endSec": 6,
    "segmentation": {
      "method": "dynamic", // dynamic OR fixed, exactly one
      "dynamic": {
        "minDurationSec": 4
      }
      "method": "fixed",
      "fixed": {
        "durationSec": 6
      }
    },
    "embeddingOption": [
      "visual",
      "audio", 
      "transcription"
    ], // optional, default=all
    "embeddingType": [
      "separate_embedding"
    ], // optional, default=["separate_embedding"]
    "embeddingScope": [
      "clip",
      "asset"
    ] // optional, one or both
  }
}
Multi-input
{
  "inputType": "multi_input",
  "multi_input": {
    "inputText": "<@img1> walking a dog with <@img2>", // optional
    "mediaSources": [
      {
        "name": "img1", // required if inputText uses <@name> placeholders
        "mediaType": "image",
        "base64String": "base64-encoded string", // base64String OR s3Location, exactly one
        "s3Location": {
          "uri": "s3://amzn-s3-demo-bucket/images/person.jpg",
          "bucketOwner": "123456789012"
        }
      },
      {
        "name": "img2",
        "mediaType": "image",
        "base64String": "base64-encoded string", // base64String OR s3Location, exactly one
        "s3Location": {
          "uri": "s3://amzn-s3-demo-bucket/images/dog.jpg",
          "bucketOwner": "123456789012"
        }
      }
    ]
  }
}

入力パラメータの詳細については、次のセクションを展開してください。

埋め込み用のモダリティ。

  • タイプ: 文字列

  • 必須: はい

  • 有効な値: text | image | text_image | audio | video | multi_input

埋め込むテキスト。

  • タイプ: 文字列

  • 必須: はい (互換性のある入力タイプの場合)

  • 互換性のある入力タイプ: テキスト

メディアソースに関する情報が含まれます。

  • タイプ: オブジェクト

  • 必須: はい (互換性のあるタイプの場合)

  • 互換性のある入力タイプ: 画像、動画、音声

リクエスト本文内の mediaSource オブジェクトの形式は、メディアが Base64 でエンコードされた文字列として定義されているか、S3 の場所として定義されているかによって異なります。

  • Base64-encoded文字列

    {
    "mediaSource": {
        "base64String": "base64-encoded string"
    }
}

    • base64String – メディアに対して Base64 でエンコードされた文字列。

  • S3 の場所 – S3 URI とバケット所有者を指定します。

    {
    "s3Location": {
        "uri": "string",
        "bucketOwner": "string"
    }
}

    • uri – メディアを含む S3 URI。

    • bucketOwner – S3 バケット所有者の AWS アカウント ID。

取得する埋め込みのタイプを指定します。

  • タイプ: リスト

  • 必須: いいえ

  • リストメンバーの有効な値:

    • visual – 動画からのビジュアル埋め込み。

    • audio – 動画内の音声の埋め込み。

    • transcription – 文字起こしされたテキストの埋め込み。

  • デフォルト値:

    • 動画: ["visual"、"audio"、"transcription"]

    • 音声: ["audio", "transcription"]

  • 互換性のある入力タイプ: 動画、音声

取得する埋め込みの範囲を指定します。

  • タイプ: リスト

  • 必須: いいえ

  • リストメンバーの有効な値:

    • clip – 各クリップの埋め込みを返します。

    • asset – アセット全体の埋め込みを返します。

  • 互換性のある入力タイプ: 動画、音声

処理が開始されるクリップの時点 (秒単位)。

  • 型: 倍精度

  • 必須: いいえ

  • 最小値: 0

  • デフォルト値: 0

  • 互換性のある入力タイプ: 動画、音声

処理が終了する秒単位の時間ポイント。

  • 型: 倍精度

  • 必須: いいえ

  • 最小値: startSec + セグメント長

  • 最大値: メディアの期間

  • デフォルト値: メディアの時間

  • 互換性のある入力タイプ: 動画、音声

埋め込み生成のためにメディアをセグメントに分割する方法を定義します。

  • タイプ: オブジェクト

  • 必須: いいえ

  • 互換性のある入力タイプ: 動画、音声

セグメンテーションオブジェクトには、methodフィールドとメソッド固有のパラメータが含まれます。

  • method – 使用するセグメンテーション方法。有効な値: dynamic | fixed

  • dynamic – 動画の場合、 はショット境界検出を使用してコンテンツを動的に分割します。次を含みます。

    • minDurationSec – 各セグメントの最小時間を秒単位で表します。タイプ: 整数。範囲: 1～5。デフォルト: 4。

  • fixed – コンテンツを同じ期間のセグメントに分割します。次を含みます。

    • durationSec – 各セグメントの秒単位の所要時間。タイプ: 整数。範囲: 1～10。デフォルト: 6。

デフォルトの動作

  • 動画: ショット境界検出で動的セグメンテーションを使用します。

  • オーディオ: 固定セグメンテーションを使用します。コンテンツは、10 秒に近いセグメントでできるだけ均等に分割されます。

単一の埋め込みリクエストでテキストを複数のイメージと組み合わせるためのマルチ入力設定が含まれています。この入力タイプは、テキストと複数のイメージの関係をキャプチャする埋め込みを作成する場合に使用します。

  • タイプ: オブジェクト

  • 必須: はい ( inputTypeが の場合multi_input)

multi_input オブジェクトには、以下のフィールドが含まれています。

  • inputText – (オプション) プレースホルダー構文を使用したテキストクエリ。を使用してメディアソースを参照<@name>します (例: "<@img1> walking with <@img2>")。プレースホルダーとともに提供される場合、それぞれが と一致する<@name>必要がありますmediaSources[].name。最大: プレースホルダーを含む 500 トークン。

  • mediaSources – (必須) メディアソースオブジェクトの配列。各メディアソースにはイメージデータが含まれています。配列には少なくとも 1 つの項目が含まれている必要があります。

    • name – (条件付き) このメディアソースの一意の識別子。<@name> がプレースホルダーinputTextを使用する場合にのみ必要です。指定すると、 は ( <@ および >文字inputTextなし) のプレースホルダーと一致する必要があります。

    • mediaType – (必須) メディアのタイプ。現在は、"image" のみがサポートされます。

    • base64String – Base64-encodedイメージペイロード。最大: イメージあたり 5 MB。base64String または のいずれかを正確に指定しますs3Location。

    • s3Location – uri (S3 URI) と bucketOwner (12 桁の AWS アカウント ID) を含む S3 ロケーションオブジェクト。最大: イメージあたり 5 MB。base64String または のいずれかを正確に指定しますs3Location。

メディアの順序:

  • <@name> にプレースホルダーinputTextが含まれている場合、順序は のプレースホルダー順序によって決まりますinputText。

  • inputText が省略されるか空の場合、順序はデフォルトで の配列順序になりますmediaSources。

埋め込みをモダリティ間で集約する方法を制御します。

  • タイプ: リスト

  • 必須: いいえ

  • リストメンバーの有効な値:

    • separate_embedding – 各モダリティ (ビジュアル、オーディオ、文字起こし) の埋め込みを個別に返します。

    • fused_embedding – 複数の埋め込みモダリティの加重フュージョンを返します。

  • デフォルト値: ["separate_embedding"]

  • 互換性のある入力タイプ: 動画、音声

制約:

  • 動画の場合: には少なくとも 2 つの埋め込みタイプfused_embeddingが必要ですembeddingOption。

  • オーディオの場合: では audioと transcription の両方fused_embeddingが必要ですembeddingOption。

推論リクエストの一意の識別子。

  • タイプ: 文字列

  • 必須: いいえ

TwelveLabs Marengo Embed 3.0レスポンス

出力埋め込みおよび関連するメタデータの場所は、呼び出しメソッドによって異なります。

  • InvokeModel – レスポンス本文内。

  • StartAsyncInvoke – 非同期呼び出しジョブが完了した後s3OutputDataConfig、 で定義された S3 バケット。

埋め込みベクトルが複数ある場合、出力はオブジェクトのリストとなり、各オブジェクトにはベクトルとそれに関連付けられたメタデータが含まれます。

出力埋め込みベクトルの形式は次のとおりです。

{
  "data": {
    "embedding": [
    0.111, 0.234, ...
    ],
    "embeddingOption": ["visual", "audio", "transcription", "fused" (for video input) | "audio", "transcription", "fused" (for audio input)],
    "embeddingScope": ["asset" | "clip"],
    "startSec": 0,
    "endSec": 4.2
  }
}

埋め込みは浮動小数点の配列として返されます。

このレスポンスが表示される場所は、使用した API メソッドによって異なります。

  • InvokeModel – レスポンス本文に表示されます。

  • StartAsyncInvoke – リクエストで指定した S3 の場所に表示されます。レスポンスは を返しますinvocationArn。これを使用して、非同期呼び出しに関するメタデータを取得できます。これには、ステータスと結果が書き込まれる S3 の場所が含まれます。

レスポンスパラメータの詳細については、次のセクションを展開してください。

入力のベクトル表現を埋め込みます。

  • タイプ: double のリスト

埋め込みのタイプ。

  • タイプ: 文字列

  • 指定できる値:

    • ビジュアル – 動画からのビジュアル埋め込み。

    • audio – ビデオ内のオーディオの埋め込み。

    • 文字起こし – 文字起こしされたテキストの埋め込み。

    • fused – 複数の埋め込みタイプの加重フュージョン。リクエスト"fused_embedding"に embeddingTypeが含まれている場合にのみ返されます。

  • 互換性のある入力タイプ: 動画、音声

注記

text、image、text_image、multi_input 入力タイプには適用されません。これらは、 embeddingOptionフィールドなしで 1 つの埋め込みを返します。

取得する埋め込みの範囲を指定します。

  • タイプ: 文字列

次の値のうち 1 つ以上を含めることができます。

  • clip: 各クリップの埋め込みを返します。

  • asset: アセット全体の埋め込みを返します。

クリップの開始オフセット。

  • 型: 倍精度

  • 互換性のある入力タイプ: 動画、音声

クリップの終了オフセット。テキスト、イメージ、text_image、および multi_input 埋め込みには適用されません。

  • 型: 倍精度

  • 互換性のある入力タイプ: 動画、音声

TwelveLabs Marengo Embed 3.0 コードの例

このセクションでは、Python を使用して異なる入力タイプを備えた TwelveLabs Marengo Embed 3.0 モデルを使用する方法を示します。この例では、モデル固有の入力を定義し、モデル呼び出しを実行する方法を示します。

注記

InvokeModel は、テキスト、イメージ、マルチ入力、およびイメージインターリーブ入力を持つテキストをサポートします。ビデオおよびオーディオ入力の場合は、StartAsyncInvoke を使用します。

次の手順でコードを組み立てます。

1. モデル固有の入力を定義する

入力タイプに応じてモデル固有の入力を定義します。

Text
# Create the model-specific input
model_id = "twelvelabs.marengo-embed-3-0-v1:0"
# Replace the us prefix depending on your region
inference_profile_id = "us.twelvelabs.marengo-embed-3-0-v1:0"

model_input = {
    "inputType": "text",
    "text": {
        "inputText": "man walking a dog"
    }
}
Image
# Create the model-specific input
model_id = "twelvelabs.marengo-embed-3-0-v1:0"
# Replace the us prefix depending on your region
inference_profile_id = "us.twelvelabs.marengo-embed-3-0-v1:0"

model_input = {
    "inputType": "image",
    "image": {
        "mediaSource": {
            "s3Location": {
                "uri": "s3://amzn-s3-demo-bucket/my_image.png",
                "bucketOwner": "123456789012"
            }
        }
    }
}
Text & image
# Create the model-specific input
model_id = "twelvelabs.marengo-embed-3-0-v1:0"
# Replace the us prefix depending on your region
inference_profile_id = "us.twelvelabs.marengo-embed-3-0-v1:0"

model_input = {
    "inputType": "text_image",
    "text_image": {
        "inputText": "man walking a dog",
        "mediaSource": {
            "s3Location": {
                "uri": "s3://amzn-s3-demo-bucket/my_image.jpg",
                "bucketOwner": "123456789012"
            }
        }
    }
}
Audio
# Create the model-specific input
model_id = "twelvelabs.marengo-embed-3-0-v1:0"
# Replace the us prefix depending on your region
inference_profile_id = "us.twelvelabs.marengo-embed-3-0-v1:0"
 
model_input = {
    "inputType": "audio",
    "audio": {
        "mediaSource": {  
            "s3Location": { 
                "uri": "s3://amzn-s3-demo-bucket/my-audio.wav", 
                "bucketOwner": "123456789012" 
            }
        },
        "startSec": 0,
        "endSec": 5,
        "segmentation": {
            "method": "fixed",
            "fixed": {
                "durationSec": 5
            }
        },
        "embeddingScope": ["clip", "asset"],
        "embeddingOption": ["audio", "transcription"],
        "embeddingType": ["separate_embedding", "fused_embedding"]
    }
}
Video
# Create the model-specific input
model_id = "twelvelabs.marengo-embed-3-0-v1:0"
# Replace the us prefix depending on your region
inference_profile_id = "us.twelvelabs.marengo-embed-3-0-v1:0"
 
model_input = {
    "inputType": "video",
    "video": {
        "mediaSource": {
            "s3Location": {
                "uri": "s3://amzn-s3-demo-bucket/my-video.mp4",
                "bucketOwner": "123456789012"
            }
        },
        "startSec": 10,
        "endSec": 20,
        "segmentation": {
            "method": "fixed",
            "fixed": {
                "durationSec": 5
            }
        },
        "embeddingOption": [
            "visual", 
            "audio"
        ],
        "embeddingType": ["separate_embedding", "fused_embedding"],
        "embeddingScope": [
            "clip",
            "asset"
        ]
    }
}
Multi-input
# Create the model-specific input
model_id = "twelvelabs.marengo-embed-3-0-v1:0"
# Replace the us prefix depending on your region
inference_profile_id = "us.twelvelabs.marengo-embed-3-0-v1:0"

model_input = {
    "inputType": "multi_input",
    "multi_input": {
        "inputText": "<@img1> walking a dog with <@img2>",
        "mediaSources": [
            {
                "name": "img1",
                "mediaType": "image",
                "s3Location": {
                    "uri": "s3://amzn-s3-demo-bucket/images/person.jpg",
                    "bucketOwner": "123456789012"
                }
            },
            {
                "name": "img2",
                "mediaType": "image",
                "s3Location": {
                    "uri": "s3://amzn-s3-demo-bucket/images/dog.jpg",
                    "bucketOwner": "123456789012"
                }
            }
        ]
    }
}
2. モデル入力を使用してモデル呼び出しを実行する

次に、選択したモデル呼び出しメソッドに対応するコードスニペットを追加します。

InvokeModel
# Run model invocation with InvokeModel
import boto3
import json

# Initialize the Bedrock Runtime client
client = boto3.client('bedrock-runtime')

# Make the request
response = client.invoke_model(
    modelId=inference_profile_id,
    body=json.dumps(model_input)
)

# Print the response body
response_body = json.loads(response['body'].read().decode('utf-8'))

print(response_body)
StartAsyncInvoke
# Run model invocation asynchronously
import boto3
import json

# Initalize the Bedrock Runtime client.
client = boto3.client("bedrock-runtime")

try:
    # Start the asynchronous job
    invocation = client.start_async_invoke(
        modelId=model_id,
        modelInput=model_input,
        outputDataConfig={
            "s3OutputDataConfig": {
                "s3Uri": "s3://amzn-s3-demo-bucket"
            }
        }
    )

    # Print the response JSON
    print("Response:")
    print(json.dumps(invocation, indent=2, default=str))

except Exception as e:
    # Implement error handling here.
    message = e.response["Error"]["Message"]
    print(f"Error: {message}")