本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 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 方法使用案例的詳細資訊，請參閱 [提出推論請求](inference.md)。 + 如需關於模型類型的詳細資訊，請參閱 [提出推論請求](inference.md)。 + 如需模型 IDs 的清單，以及查看 中TwelveLabs Marengo Embed 3.0支援的模型和 AWS 區域，請在 的 資料表中搜尋模型[Amazon Bedrock 中支援的基礎模型](models-supported.md)。 + 如需推論設定檔 ID 的完整清單，請參閱 [推論設定檔支援的區域和模型](inference-profiles-support.md)。推論設定檔 ID 是以 AWS 區域為基礎。 **** | API 操作 | 支援的模型類型 | 輸入模態 | 輸出模態 | | --- | --- | --- | --- | | InvokeModel | 美國東部 （維吉尼亞北部） – [基礎模型](models-supported.md)和[推論設定檔](inference-profiles-support.md)
歐洲 （愛爾蘭） – [推論設定檔](inference-profiles-support.md)
亞太區域 （首爾） - [基礎模型](models-supported.md) | 文字
影像
多輸入 （具有多個影像的文字）
**注意：**也支援文字和映像交錯。 | 嵌入項目 | | StartAsyncInvoke | 美國東部 （維吉尼亞北部） – [基礎模型](models-supported.md)
歐洲 （愛爾蘭） – [基礎模型](models-supported.md)
亞太區域 （首爾） - [基礎模型](models-supported.md) | 影片
音訊
影像
文字
多輸入 （具有多個影像的文字）
**注意：**也支援文字和映像交錯。 | 嵌入項目 | **注意** 使用 `InvokeModel` 產生搜尋查詢的嵌入。使用 `StartAsyncInvoke` 大規模產生資產的嵌入。 輸入有下列配額： **** | 輸入模式 | 上限 | | --- | --- | | 文字 | 500 個字符 | | 影像 | 每個映像 5 MB | | 影片 (S3) | 6 GB，長度為 4 小時 | | 音訊 (S3) | 6 GB，長度為 4 小時 | **注意** 如果您使用 base64 編碼定義音訊或視訊內嵌，請確定請求內文承載不超過 Amazon Bedrock 25 MB 模型調用配額。 **Topics** + [TwelveLabs Marengo Embed 3.0 請求參數](#model-parameters-marengo-3-async-request) + [TwelveLabs Marengo Embed 3.0 回應](#model-parameters-marengo-3-response) + [TwelveLabs Marengo Embed 3.0 程式碼範例](#model-parameters-marengo-3-examples) ## TwelveLabs Marengo Embed 3.0 請求參數 當您提出請求時，指定模型特定輸入所在的欄位取決於 API 操作： + [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) – 在請求 `body` 中。 + [StartAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_StartAsyncInvoke.html) – 在請求內文的 `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}}" } } ] } } ``` ------ 如需輸入參數的詳細資訊，請展開下列各節： ### inputType 嵌入的模式。 + **類型：**字串 + **必要**：是 + **有效值**︰`text` \| `image` \| `text_image` \| `audio` \| `video` \| `multi_input` ### inputText 要嵌入的文字。 + **類型：**字串 + **必要：**是 (適用於相容輸入類型) + **相容輸入類型：**文字 ### mediaSource 包含媒體來源的相關資訊。 + **類型：**物件 + **必要：**是 (如果相容類型) + **相容輸入類型：**影像、影片、音訊 請求內文中 `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。 ### embeddingOption 指定要擷取的嵌入類型。 + **類型：**清單 + **必要**：否 + **清單成員的有效值：** + `visual` – 影片中的視覺化內嵌。 + `audio` – 影片中音訊的嵌入。 + `transcription` – 轉錄文字的內嵌。 + **預設值：** + 影片：【「視覺」、「音訊」、「轉錄」】 + 音訊：【「音訊」、「轉錄」】 + **相容輸入類型：**影片、音訊 ### embeddingScope 指定要擷取的內嵌範圍。 + **類型：**清單 + **必要**：否 + **清單成員的有效值：** + `clip` – 傳回每個剪輯的內嵌。 + `asset` – 傳回整個資產的內嵌。 + **相容輸入類型：**影片、音訊 ### startSec 剪輯中處理應開始的時間點，以秒為單位。 + **類型**：Double + **必要**：否 + **最小值**：0 + **預設值：**0 + **相容輸入類型：**影片、音訊 ### endSec 處理應結束的時間點，以秒為單位。 + **類型**：Double + **必要**：否 + **最小值：**startSec \+ 區段長度 + **最大值：**媒體持續時間 + **預設值：**媒體持續時間 + **相容輸入類型：**影片、音訊 ### 分段 定義如何將媒體分成區段以產生內嵌。 + **類型：**物件 + **必要**：否 + **相容輸入類型：**影片、音訊 分段物件包含`method`欄位和方法特定的參數： + `method` – 要使用的分段方法。有效值：`dynamic` \| `fixed` + `dynamic` – 對於影片， 使用鏡頭邊界偵測來動態分割內容。包含： + `minDurationSec` – 每個區段的最短持續時間，以秒為單位。類型：整數。範圍：1-5。預設：4. + `fixed` – 將內容分割為相同持續時間的區段。包含： + `durationSec` – 每個區段的持續時間，以秒為單位。類型：整數。範圍：1-10。預設：6。 **預設行為：** + 影片：使用動態分割搭配鏡頭邊界偵測。 + 音訊：使用固定分段。內容會盡可能平均分割，區段接近 10 秒。 ### multi\_input 包含用於在單一內嵌請求中結合文字與多個影像的多輸入組態。當您想要建立內嵌以擷取文字和多個影像之間的關係時，請使用此輸入類型。 + **類型：**物件 + **必要：**是 （當 `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`。 ### embeddingType 控制內嵌如何跨模態彙總。 + **類型：**清單 + **必要**：否 + **清單成員的有效值：** + `separate_embedding` – 分別傳回每個模態的內嵌 （視覺、音訊、轉錄）。 + `fused_embedding` – 傳回多個內嵌模態的加權融合。 + **預設值：**【"separate\_embedding"】 + **相容輸入類型：**影片、音訊 **限制條件**： + 對於視訊： 在 中至少`fused_embedding`需要 2 種內嵌類型`embeddingOption`。 + 對於音訊： 在 `transcription`中`fused_embedding`需要 `audio`和 `embeddingOption`。 ### inferenceId 推論請求的唯一識別符。 + **類型：**字串 + **必要**：否 ## 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 位置。 如需回應參數的詳細資訊，請展開下列各節： ### 嵌入項目 輸入的嵌入向量表示法。 + **類型**：雙精度浮點數清單 ### embeddingOption 嵌入的類型。 + **類型：**字串 + **可能的值：** + 視覺化 – 影片中的視覺化內嵌。 + 音訊 – 視訊中音訊的內嵌。 + 轉錄 – 轉錄文字的內嵌。 + fused – 多個內嵌類型的加權融合。只有在請求`"fused_embedding"`中`embeddingType`包含 時才傳回。 + **相容輸入類型：**影片、音訊 **注意** 不適用於文字、影像、text\_image 和 multi\_input 輸入類型。這些會傳回不含 `embeddingOption` 欄位的單一內嵌。 ### embeddingScope 指定要擷取的內嵌範圍。 + **類型：**字串 您可以包含下列一或多個值： + 剪輯：傳回每個剪輯的內嵌。 + asset：傳回整個資產的內嵌。 ### startSec 剪輯的開始位移。 + **類型**：Double + **相容輸入類型：**影片、音訊 ### endSec 剪輯的結束位移。不適用於文字、影像、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. 使用模型輸入執行模型調用** 然後，新增對應至所選模型調用方法的程式碼片段。 ------ #### [ 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}") ``` ------