View a markdown version of this page

TwelveLabs Marengo 嵌入 3.0 - Amazon Bedrock
迁移自 TwelveLabs Marengo 嵌入 2.7 修改为 TwelveLabs Marengo 嵌入 3.0TwelveLabs Marengo 嵌入 3.0 请求参数TwelveLabs Marengo 嵌入 3.0 响应TwelveLabs Marengo 嵌入 3.0 代码示例

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

TwelveLabs Marengo 嵌入 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 操作 受支持的模型类型 输入模式 输出模态

InvokeModel

美国东部（弗吉尼亚北部）-基础模型和推理配置文件

欧洲（爱尔兰）-推理概况

亚太地区（首尔）-基本模型

文本

Image

Multi-input （包含多张图片的文本）

注意：还支持文本和图像交错。

嵌入
StartAsyncInvoke

美国东部（弗吉尼亚北部）— 基本型号

欧洲（爱尔兰）-基本模型

亚太地区（首尔）-基本模型

视频

音频

Image

文本

Multi-input （包含多张图片的文本）

注意：还支持文本和图像交错。

嵌入
注意

使用 InvokeModel 可为搜索查询生成嵌入。使用 StartAsyncInvoke 可为大规模资源生成嵌入。

以下配额适用于输入：

输入模态 最大值
文本 500 个代币
Image 每张图片 5 MB
视频（S3） 6 GB，时长 4 小时
音频（S3） 6 GB，时长 4 小时
注意

如果您使用 base64 编码以内嵌方式定义音频或视频，请确保请求正文有效载荷不超过 Amazon Bedrock 的 25 MB 模型调用配额。

迁移自 TwelveLabs Marengo 嵌入 2.7 修改为 TwelveLabs Marengo 嵌入 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，则嵌套inputText在text对象中。

  • 组合文本和图像输入-新的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 嵌入 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-encoded 字符串还是 S3 位置。

  • Base64-encoded string

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

    • base64String— 媒体 Base64-encoded 字符串。

  • S3 位置-指定 S3 URI 和存储桶所有者。

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

    • uri - 包含媒体的 S3 URI。

    • bucketOwner— S3 存储桶所有者的 AWS 账户 ID。

指定要检索的嵌入的类型。

  • 类型：列表

  • 必需：否

  • 列表成员的有效值：

    • visual— 视频中的视觉嵌入内容。

    • audio – 视频中的音频嵌入。

    • transcription— 转录文本的嵌入。

  • 默认值：

    • 视频：[“视觉”、“音频”、“转录”]

    • 音频：[“音频”，“转录”]

  • 兼容的输入类型：视频、音频

指定要检索的嵌入的范围。

  • 类型：列表

  • 必需：否

  • 列表成员的有效值：

    • clip— 返回每个片段的嵌入内容。

    • asset— 返回整个资源的嵌入内容。

  • 兼容的输入类型：视频、音频

剪辑中应开始处理的时间点（以秒为单位）。

  • 类型：双精度

  • 必需：否

  • 最小值：0

  • 默认值：0

  • 兼容的输入类型：视频、音频

处理应结束的时间点（以秒为单位）。

  • 类型：双精度

  • 必需：否

  • 最小值：起始秒 + 分段长度

  • 最大值：媒体持续时间

  • 默认值：媒体时长

  • 兼容的输入类型：视频、音频

定义如何将媒体划分为片段以进行嵌入生成。

  • 类型：对象

  • 必需：否

  • 兼容的输入类型：视频、音频

分割对象包含一个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>必须与 a 匹配。mediaSources[].name最大：500 个代币，包括占位符。

  • mediaSources—（必需）媒体源对象数组。每个媒体源都包含图像数据。数组必须至少包含一个项目。

    • name—（视情况而定）此媒体源的唯一标识符。仅在inputText使用<@name>占位符时才需要。如果提供，则必须与中的占位符匹配inputText（不带<@和>字符）。

    • mediaType—（必填）媒体类型。目前仅支持 "image"。

    • base64String— Base64-encoded 图像有效载荷。最大值：每张图片 5 MB。请恰好提供base64String或中的一个s3Location。

    • s3Location— 包含 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。

  • 对于音频：fused_embedding需要同时输入audio和输transcription入embeddingOption。

推理请求的唯一标识符。

  • 类型：字符串

  • 必需：否

TwelveLabs Marengo 嵌入 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 位置。

展开以下各个部分，查看有关响应参数的详细信息：

输入的嵌入向量表示。

  • 类型：双精度数列表

嵌入的类型。

  • 类型：字符串

  • 可能的值：

    • visual — 视频中的视觉嵌入内容。

    • 音频-在视频中嵌入音频。

    • 转录-转录文本的嵌入。

    • fused — 多种嵌入类型的加权融合。仅在请求"fused_embedding"中embeddingType包含时才返回。

  • 兼容的输入类型：视频、音频

注意

不适用于文本、图像、文本图像和多输入输入类型。它们返回一个不带embeddingOption字段的嵌入。

指定要检索的嵌入的范围。

  • 类型：字符串

您可以包含以下一个或多个值：

  • clip：返回每个片段的嵌入内容。

  • asset：返回整个资产的嵌入内容。

剪辑的起始偏移量。

  • 类型：双精度

  • 兼容的输入类型：视频、音频

片段的末端偏移量。不适用于文本、图像、text_image 和 multi_input 嵌入式。

  • 类型：双精度

  • 兼容的输入类型：视频、音频

TwelveLabs Marengo 嵌入 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}")