從遷移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，這是先前版本的兩倍容量。這使得它非常適合分析完整的體育賽事、延伸訓練影片和完整的電影製作。
增強型運動分析 – 模型可提供顯著的改善。它可讓您更了解遊戲動態、玩家動作和事件偵測。
全球多語言支援 – 將語言功能從 12 種擴展到 36 種語言。這可讓全球組織建置統一的搜尋和擷取系統，在不同的區域和市場無縫運作。
多模態搜尋精確度 – 在單一內嵌請求中結合影像和描述性文字。這將視覺相似性與語意理解合併，以提供更準確和情境相關的搜尋結果。
降低內嵌維度 – 從 1024 縮減至 512，這有助於降低儲存成本。

此 TwelveLabs Marengo Embed 3.0 模型支援下表中的 Amazon Bedrock 執行時期操作。

如需不同 API 方法使用案例的詳細資訊，請參閱提出推論請求。
如需關於模型類型的詳細資訊，請參閱提出推論請求。
- 如需模型 IDs 的清單，以及查看中TwelveLabs Marengo Embed 3.0支援的模型和 AWS 區域，請在的資料表中搜尋模型Amazon Bedrock 中支援的基礎模型。
- 如需推論設定檔 ID 的完整清單，請參閱推論設定檔支援的區域和模型。推論設定檔 ID 是以 AWS 區域為基礎。

API 操作	支援的模型類型	輸入模態	輸出模態
InvokeModel	美國東部（維吉尼亞北部） – 基礎模型和推論設定檔歐洲（愛爾蘭） – 推論設定檔亞太區域（首爾） - 基礎模型	文字影像多輸入（具有多個影像的文字）注意：也支援文字和映像交錯。	嵌入項目
StartAsyncInvoke	美國東部（維吉尼亞北部） – 基礎模型歐洲（愛爾蘭） – 基礎模型亞太區域（首爾） - 基礎模型	影片音訊影像文字多輸入（具有多個影像的文字）注意：也支援文字和映像交錯。	嵌入項目

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，請完成下列步驟。

更新您的程式碼，以使用下一節所述的新巢狀輸入結構和參數變更。
將模型 ID 更新為 twelvelabs.marengo-embed-3-0-v1:0。
測試您與新版本的整合。

以下是 TwelveLabs Marengo Embed 2.7和之間的金鑰變更TwelveLabs Marengo Embed 3.0。

巢狀輸入結構 – 現在會根據 inputType值在物件內組織輸入參數。例如，如果 inputType是 text，請在text物件inputText中巢狀化。
合併文字和影像輸入 – 新的text_image輸入類型可讓您在單一請求中合併文字和影像。不支援此輸入類型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 操作：

InvokeModel – 在請求 body 中。
StartAsyncInvoke – 在請求內文的 modelInput 欄位中。

模型輸入的格式取決於輸入模式：

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-encoded 字串還是 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 – 轉錄文字的內嵌。
預設值：
- 影片：【「視覺」、「音訊」、「轉錄」】
- 音訊：【「音訊」、「轉錄」】
相容輸入類型：影片、音訊

指定要擷取的內嵌範圍。

類型：清單
必要：否
清單成員的有效值：
- clip – 傳回每個剪輯的內嵌。
- asset – 傳回整個資產的內嵌。
相容輸入類型：影片、音訊

剪輯中處理應開始的時間點，以秒為單位。

類型：Double
必要：否
最小值：0
預設值：0
相容輸入類型：影片、音訊

處理應結束的時間點，以秒為單位。

類型：Double
必要：否
最小值：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 – （必要）媒體來源物件的陣列。每個媒體來源都包含影像資料。陣列必須至少包含一個項目。
- name – （條件式）此媒體來源的唯一識別符。只有在 inputText使用<@name>預留位置時才需要。提供時，必須與中的預留位置相符 inputText（不含 <@和 > 字元）。
- mediaType – （必要）媒體類型。目前僅支援 "image"。
- base64String – Base64-encoded的影像承載。上限：每個映像 5 MB。提供 base64String或的確切其中之一s3Location。
- s3Location – S3包含 uri(S3 URI) 和 bucketOwner(12 位數 AWS 帳戶 ID) 的 S3 位置物件。上限：每個映像 5 MB。提供 base64String或的確切其中之一s3Location。

媒體排序：

如果 inputText包含<@name>預留位置，則順序取決於中的預留位置順序inputText。
如果省略或inputText為空，則順序預設為陣列順序 mediaSources。

控制內嵌如何跨模態彙總。

類型：清單
必要：否
清單成員的有效值：
- separate_embedding – 分別傳回每個模態的內嵌（視覺、音訊、轉錄）。
- fused_embedding – 傳回多個內嵌模態的加權融合。
預設值：【"separate_embedding"】
相容輸入類型：影片、音訊

限制條件：

對於影片：在中至少fused_embedding需要 2 種內嵌類型embeddingOption。
對於音訊：在 transcription中fused_embedding需要 audio和 embeddingOption。

推論請求的唯一識別符。

類型：字串
必要：否

TwelveLabs Marengo Embed 3.0 回應

輸出嵌入和相關聯中繼資料的位置取決於調用方法：

InvokeModel – 在回應內文中。
StartAsyncInvoke – 在中定義的 S3 儲存貯體中s3OutputDataConfig，非同步調用任務完成後。

如果有多個嵌入向量，則輸出會是物件清單，每個物件皆包含向量及其相關聯的中繼資料。

輸出嵌入向量的格式如下：


{
  "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 位置。

如需回應參數的詳細資訊，請展開下列各節：

輸入的嵌入向量表示法。

類型：雙精度浮點數清單

嵌入的類型。

類型：字串
可能的值：
- 視覺化 – 影片中的視覺化內嵌。
- 音訊 – 視訊中音訊的內嵌。
- 轉錄 – 轉錄文字的內嵌。
- fused – 多個內嵌類型的加權融合。只有在請求"fused_embedding"中embeddingType包含時才傳回。
相容輸入類型：影片、音訊

注意

不適用於文字、影像、text_image 和 multi_input 輸入類型。這些會傳回不含 embeddingOption 欄位的單一內嵌。

指定要擷取的內嵌範圍。

類型：字串

您可以包含下列一或多個值：

剪輯：傳回每個剪輯的內嵌。
資產：傳回整個資產的內嵌。

剪輯的開始位移。

類型：Double
相容輸入類型：影片、音訊

剪輯的結束位移。不適用於文字、影像、text_image 和 multi_input 內嵌。

類型：Double
相容輸入類型：影片、音訊

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. 使用模型輸入執行模型調用

然後，新增對應至所選模型調用方法的程式碼片段。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

TwelveLabs Marengo Embed 2.7

Writer AI Palmyra 模型