# 完整的嵌入请求和响应架构
<a name="embeddings-schema"></a>

## 完整的同步架构
<a name="embeddings-schema-sync"></a>



```
{
    "schemaVersion": "nova-multimodal-embed-v1",
    "taskType": "SINGLE_EMBEDDING",
    "singleEmbeddingParams": {
        "embeddingPurpose": "GENERIC_INDEX" | "GENERIC_RETRIEVAL" | "TEXT_RETRIEVAL" | "IMAGE_RETRIEVAL" | "VIDEO_RETRIEVAL" | "DOCUMENT_RETRIEVAL" | "AUDIO_RETRIEVAL" | "CLASSIFICATION" | "CLUSTERING",
        "embeddingDimension": 256 | 384 | 1024 | 3072,
        "text": {
            "truncationMode": "START" | "END" | "NONE",
            "value": string,
            "source": SourceObject,
        },
        "image": {
            "detailLevel": "STANDARD_IMAGE" | "DOCUMENT_IMAGE",
            "format": "png" | "jpeg" | "gif" | "webp",
            "source": SourceObject
        },
        "audio": {
            "format": "mp3" | "wav" | "ogg",
            "source": SourceObject
        },
        "video": {
            "format": "mp4" | "mov" | "mkv" | "webm" | "flv" | "mpeg" | "mpg" | "wmv" | "3gp",
            "source": SourceObject,
            "embeddingMode": "AUDIO_VIDEO_COMBINED" | "AUDIO_VIDEO_SEPARATE"
        }
    }
}
```

以下列表包含了该请求的所有参数：
+ `schemaVersion`（可选）：多模态嵌入模型请求的架构版本
  + 类型：字符串
  + 允许值："nova-multimodal-embed-v1"
  + 默认值："nova-multimodal-embed-v1"
+ `taskType`（必填）：指定要对输入内容执行的嵌入操作类型。`single_embedding` 指为每个模型输入生成一个嵌入。`segmented_embedding` 指首先根据用户规格对模型输入进行分段，然后为每个分段生成一个嵌入。
  + 类型：字符串
  + 允许值：对于同步调用，必须为 "SINGLE\$1EMBEDDING"。
+ `singleEmbeddingParams`（必填）
  + `embeddingPurpose`（必填）：Nova Multimodal Embeddings 使您能够根据预期应用优化嵌入。示例包括 MM-RAG、用于图像和视频搜索的数字资产管理、多模态内容的相似度比较或用于智能文档处理的文档分类。您可以通过 `embeddingPurpose` 来指定嵌入使用案例。根据以下使用案例选择正确的值。
    + **搜索和检索：**诸如 RAG 和搜索之类的嵌入使用案例涉及两个主要步骤：第一，通过为内容生成嵌入来创建索引；第二，在搜索期间从索引中检索最相关的内容。对于搜索和检索使用案例，请使用以下值：
      + 创建索引：
        + "GENERIC\$1INDEX"：创建经优化的嵌入，用于在向量数据存储中作为索引使用。无论您要为哪种模态创建索引，都应使用此值。
      + 搜索/检索：根据要检索的内容类型优化嵌入：
        + "TEXT\$1RETREIVEAL"：创建经优化的嵌入，用于搜索仅含文本嵌入的存储库。
        + "IMAGE\$1RETEIVEL"：创建经优化的嵌入，用于搜索仅含使用 "STANDARD\$1IMAGE" detailLevel 创建的图像嵌入的存储库。
        + "VIDEO\$1RETEIVEO\$1COMBINED"：创建经优化的嵌入，用于搜索仅含视频嵌入的存储库，或使用 "AUDIO\$1VIDEO\$1COMBINED" 嵌入模式创建的嵌入的存储库。
        + "DOCUMENT\$1RETREIVEL"：创建经优化的嵌入，用于搜索仅含使用 "DOCUMENT\$1IMAGE" DetailLevel 创建的文档图像嵌入的存储库。
        + "AUDIO\$1RETREIVEAL"：创建经优化的嵌入，用于搜索仅含音频嵌入的存储库。
        + "GENERIC\$1RETREIVEAL"：创建经优化的嵌入，用于搜索包含混合模态嵌入的存储库。
      + 示例：在用户使用文本查询来检索图像的图像搜索应用程序中，在基于图像创建嵌入索引时使用 `embeddingPurpose = generic_index`，而在创建用于检索图像的查询的嵌入时使用 `embeddingPurpose = image_retrieval`。
    + "CLASSIFICATION"：创建为执行分类而优化的嵌入。
    + "CLUSTERING"：创建针对聚类进行优化的嵌入。
  + `embeddingDimension`（可选）：要生成的向量的大小。
    + 类型：int
    + 允许值：256 \$1 384 \$1 1024 \$1 3072
    + 默认值：3072
  + `text`（可选）：表示文本内容。必须存在文本、图像、视频和音频之一。
    + `truncationMode`（必填）：指定当文本的令牌化版本超过模型支持的最大值时，将从文本中截断的部分。
      + 类型：字符串
      + 允许的值：
        + "START"：必要时省略文本开头的字符。
        + "END"：必要时省略文本末尾的字符。
        + "NONE"：文本长度超过模型的最大令牌限制时操作将会失败。
    + `value`（可选；必须提供值或来源）：要为其创建嵌入的文本值。
      + 类型：字符串
      + 长度上限：8192 个字符。
    + `source`（可选；必须提供值或来源）：对存储在 S3 中的文本文件的引用。请注意，SourceObject 的字节选项不适用于文本输入。要以内联方式在请求中传递文本，请改用 value 参数。
      + 类型：SourceObject（请参阅“常用对象”部分）
  + `image`（可选）：表示图像内容。必须存在文本、图像、视频和音频之一。
    + `detailLevel`（可选）：指定处理图像的分辨率，"STANDARD\$1IMAGE" 使用较低的图像分辨率，"DOCUMENT\$1IMAGE" 使用更高分辨率的图像来更好地解释文本。
      + 类型：字符串
      + 允许值："STANDARD\$1IMAGE" \$1 "DOCUMENT\$1IMAGE"
      + 默认值："STANDARD\$1IMAGE"
    + `format`（必填）
      + 类型：字符串
      + 允许值："png" \$1 "jpeg" \$1 "gif" \$1 "webp"
    + `source`（必填）：图像内容来源。
      + 类型：SourceObject（请参阅“常用对象”部分）
  + `audio`（可选）：表示音频内容。必须存在文本、图像、视频和音频之一。
    + `format`（必填）
      + 类型：字符串
      + 允许值："mp3" \$1 "wav" \$1 "ogg"
    + `source`（必填）：音频内容来源。
      + 类型：SourceObject（请参阅“常用对象”部分）
      + 最大音频长度：30 秒
  + `video`（可选）：表示视频内容。必须存在文本、图像、视频和音频之一。
    + `format`（必填）
      + 类型：字符串
      + 允许值："mp4" \$1 "mov" \$1 "mkv" \$1 "webm" \$1 "flv" \$1 "mpeg" \$1 "mpg" \$1 "wmv" \$1 "3gp"
    + `source`（必填）：视频内容来源。
      + 类型：SourceObject（请参阅“常用对象”部分）
      + 最大视频长度：30 秒
    + `embeddingMode`（必填）
      + 类型：字符串
      + 值："AUDIO\$1VIDEO\$1COMBINED" \$1 "AUDIO\$1VIDEO\$1SEPARATE"
        + "AUDIO\$1VIDEO\$1COMBINED"：将生成一个组合听觉和视觉内容的嵌入。
        + "AUDIO\$1VIDEO\$1SEPARATE"：将生成两个嵌入，一个用于听觉内容，另一个用于视觉内容。

**InvokeModel 响应正文**  
当 [invokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_InvokeModel.html) 返回“成功”结果时，响应正文将具有以下结构：

```
{
   "embeddings": [
      {
          "embeddingType": "TEXT" | "IMAGE" | "VIDEO" | "AUDIO" | "AUDIO_VIDEO_COMBINED",
          "embedding": number[],
          "truncatedCharLength": int // Only included if text input was truncated
      }
    ]                       
}
```

以下列表包含了该响应的所有参数：
+ `embeddings`（必填）：对于大多数请求，此数组将包含单个嵌入。对于选择了 "AUDIO\$1VIDEO\$1SEPARATE" embeddingMode 模式的视频请求，此数组将包含两个嵌入，一个用于视频内容，另一个用于音频内容。
  + 类型：具有下列属性的嵌入数组
    + `embeddingType`（必填）：报告创建的嵌入类型。
      + 类型：字符串
      + 允许值："TEXT" \$1 "IMAGE" \$1 "VIDEO" \$1 "AUDIO" \$1 "AUDIO\$1VIDEO\$1COMBINED"
    + `embedding`（必填）：嵌入向量。
      + 类型：数值[]
    + `truncatedCharLength`（可选）：仅适用于文本嵌入请求。输入文本的令牌化版本超出模型的限制时将会返回此响应。该值表示在生成嵌入之前会将其之后的文本截断的字符。
      + 类型：int

## 完整的异步架构
<a name="embeddings-schema-async"></a>

您可以使用 Amazon Bedrock 运行时 API 函数 [StartAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_StartAsyncInvoke.html), [GetAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_GetAsyncInvoke.html) 和 [ListAsyncInvokes](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_ListAsyncInvokes.html) 异步生成嵌入。如果要使用 Nova Embeddings 对长内容（例如长篇文本或长度超过 30 秒的视频和音频）进行分段，则必须使用异步 API。

调用 [StartAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_StartAsyncInvoke.html) 时，必须提供 `modelId`、`outputDataConfig` 和 `modelInput` 参数。

```
response = bedrock_runtime.start_async_invoke(
    modelId="amazon.nova-2-multimodal-embeddings-v1:0",
    outputDataConfig=Data Config,
    modelInput=Model Input
)
```

`outputDataConfig` 指定要将生成的输出保存到的 S3 存储桶。它具有以下结构：

```
{
    "s3OutputDataConfig": {
        "s3Uri": "s3://your-s3-bucket"
    }
}
```

`s3Uri` 是目标存储桶的 S3 URI。有关其他可选参数，请参阅 StartAsyncInvoke 文档。

`modelInput` 参数使用以下结构。

```
{
    "schemaVersion": "nova-multimodal-embed-v1",
    "taskType": "SEGMENTED_EMBEDDING",
    "segmentedEmbeddingParams": {
        "embeddingPurpose": "GENERIC_INDEX" | "GENERIC_RETRIEVAL" | "TEXT_RETRIEVAL" | "IMAGE_RETRIEVAL" | "VIDEO_RETRIEVAL" | "DOCUMENT_RETRIEVAL" | "AUDIO_RETRIEVAL" | "CLASSIFICATION" | "CLUSTERING",
        "embeddingDimension": 256 | 384 | 1024 | 3072,
        "text": {
            "truncationMode": "START" | "END" | "NONE",
            "value": string,
            "source": {
                "s3Location": {
                    "uri": "s3://Your S3 Object"
                }
            },
            "segmentationConfig": {
                "maxLengthChars": int
            }
        },
        "image": {
            "format": "png" | "jpeg" | "gif" | "webp",
            "source": SourceObject,
            "detailLevel": "STANDARD_IMAGE" | "DOCUMENT_IMAGE"
        },
        "audio": {
            "format": "mp3" | "wav" | "ogg",
            "source": SourceObject,
            "segmentationConfig": {
                "durationSeconds": int
            }
        },
        "video": {
            "format": "mp4" | "mov" | "mkv" | "webm" | "flv" | "mpeg" | "mpg" | "wmv" | "3gp",
            "source": SourceObject,
            "embeddingMode": "AUDIO_VIDEO_COMBINED" | "AUDIO_VIDEO_SEPARATE",
            "segmentationConfig": {
                "durationSeconds": int
            }
        }
    }
}
```

以下列表包含了该请求的所有参数：
+ `schemaVersion`（可选）：多模态嵌入模型请求的架构版本
  + 类型：字符串
  + 允许值："nova-multimodal-embed-v1"
  + 默认值："nova-multimodal-embed-v1"
+ `taskType`（必填）：指定要对输入内容执行的嵌入操作类型。`single_embedding` 指为每个模型输入生成一个嵌入。`segmented_embedding` 指首先根据用户规格对模型输入进行分段，然后为每个分段生成一个嵌入。
  + 类型：字符串
  + 允许值：对于异步调用必须为 "SEGMENTED\$1EMBEDDING"。
+ `segmentedEmbeddingParams`（必填）
  + `embeddingPurpose`（必填）：Nova Multimodal Embeddings 使您能够根据预期应用优化嵌入。示例包括 MM-RAG、用于图像和视频搜索的数字资产管理、多模态内容的相似度比较或用于智能文档处理的文档分类。您可以通过 `embeddingPurpose` 来指定嵌入使用案例。根据以下使用案例选择正确的值。
    + **搜索和检索：**诸如 RAG 和搜索之类的嵌入使用案例涉及两个主要步骤：第一，通过为内容生成嵌入来创建索引；第二，在搜索期间从索引中检索最相关的内容。对于搜索和检索使用案例，请使用以下值：
      + 创建索引：
        + "GENERIC\$1INDEX"：创建经优化的嵌入，用于在向量数据存储中作为索引使用。无论您要为哪种模态创建索引，都应使用此值。
      + 搜索/检索：根据要检索的内容类型优化嵌入：
        + "TEXT\$1RETREIVEAL"：创建经优化的嵌入，用于搜索仅含文本嵌入的存储库。
        + "IMAGE\$1RETEIVEL"：创建经优化的嵌入，用于搜索仅含使用 "STANDARD\$1IMAGE" detailLevel 创建的图像嵌入的存储库。
        + "VIDEO\$1RETEIVEO\$1COMBINED"：创建经优化的嵌入，用于搜索仅含视频嵌入的存储库，或使用 "AUDIO\$1VIDEO\$1COMBINED" 嵌入模式创建的嵌入的存储库。
        + "DOCUMENT\$1RETREIVEL"：创建经优化的嵌入，用于搜索仅含使用 "DOCUMENT\$1IMAGE" DetailLevel 创建的文档图像嵌入的存储库。
        + "AUDIO\$1RETREIVEAL"：创建经优化的嵌入，用于搜索仅含音频嵌入的存储库。
        + "GENERIC\$1RETREIVEAL"：创建经优化的嵌入，用于搜索包含混合模态嵌入的存储库。
      + 示例：在用户使用文本查询来检索图像的图像搜索应用程序中，在基于图像创建嵌入索引时使用 `embeddingPurpose = generic_index`，而在创建用于检索图像的查询的嵌入时使用 `embeddingPurpose = image_retrieval`。
    + "CLASSIFICATION"：创建为执行分类而优化的嵌入。
    + "CLUSTERING"：创建针对聚类进行优化的嵌入。
  + `embeddingDimension`（可选）：要生成的向量的大小。
    + 类型：int
    + 允许值：256 \$1 384 \$1 1024 \$1 3072
    + 默认值：3072
  + `text`（可选）：表示文本内容。必须存在文本、图像、视频和音频之一。
    + `truncationMode`（必填）：指定当文本的令牌化版本超过模型支持的最大值时，将从文本中截断的部分。
      + 类型：字符串
      + 允许的值：
        + "START"：必要时省略文本开头的字符。
        + "END"：必要时省略文本末尾的字符。
        + "NONE"：文本长度超过模型的最大令牌限制时操作将会失败。
    + `value`（可选；必须提供值或来源）：要为其创建嵌入的文本值。
      + 类型：字符串
      + 长度上限：8192 个字符。
    + `source`（可选；必须提供值或来源）：对存储在 S3 中的文本文件的引用。请注意，SourceObject 的字节选项不适用于文本输入。要以内联方式在请求中传递文本，请改用 value 参数。
    + `segmentationConfig`（必填）：控制如何将文本内容分段为多个嵌入。
      + `maxLengthChars`（可选）：每个分段允许的最大长度。模型将尝试仅在单词边界处进行分段。
        + 类型：int
        + 有效范围：800-50,000
        + 默认值：32000
  + `image`（可选）：表示图像内容。必须存在文本、图像、视频和音频之一。
    + `format`（必填）
      + 类型：字符串
      + 允许值："png" \$1 "jpeg" \$1 "gif" \$1 "webp"
    + `source`（必填）：图像内容来源。
      + 类型：SourceObject（请参阅“常用对象”部分）
    + `detailLevel`（可选）：指定处理图像的分辨率，"STANDARD\$1IMAGE" 使用较低的图像分辨率，"DOCUMENT\$1IMAGE" 使用更高分辨率的图像来更好地解释文本。
      + 类型：字符串
      + 允许值："STANDARD\$1IMAGE" \$1 "DOCUMENT\$1IMAGE"
      + 默认值："STANDARD\$1IMAGE"
  + `audio`（可选）：表示音频内容。必须存在文本、图像、视频和音频之一。
    + `format`（必填）
      + 类型：字符串
      + 允许值："mp3" \$1 "wav" \$1 "ogg"
    + `source`（必填）：音频内容来源。
      + 类型：SourceObject（请参阅“常用对象”部分）
    + `segmentationConfig`（必填）：控制如何将音频内容分段为多个嵌入。
      + `durationSeconds`（可选）：用于每个分段的最大音频时长（以秒为单位）。
        + 类型：int
        + 有效范围：1-30
        + 默认：5
  + `video`（可选）：表示视频内容。必须存在文本、图像、视频和音频之一。
    + `format`（必填）
      + 类型：字符串
      + 允许值："mp4" \$1 "mov" \$1 "mkv" \$1 "webm" \$1 "flv" \$1 "mpeg" \$1 "mpg" \$1 "wmv" \$1 "3gp"
    + `source`（必填）：视频内容来源。
      + 类型：SourceObject（请参阅“常用对象”部分）
    + `embeddingMode`（必填）
      + 类型：字符串
      + 值："AUDIO\$1VIDEO\$1COMBINED" \$1 "AUDIO\$1VIDEO\$1SEPARATE"
        + "AUDIO\$1VIDEO\$1COMBINED"：将为每个分段生成一个组合听觉和视觉内容的嵌入。
        + "AUDIO\$1VIDEO\$1SEPARATE"：将为每个分段生成两个嵌入，一个用于音频内容，另一个用于视频内容。
    + `segmentationConfig`（必填）：控制如何将视频内容分段为多个嵌入。
      + `durationSeconds`（可选）：用于每个分段的最大视频时长（以秒为单位）。
        + 类型：int
        + 有效范围：1-30
        + 默认：5

**StartAsyncInvoke 响应**  
调用 [StartAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_StartAsyncInvoke.html) 时的响应将具有以下结构。`invocationArn` 可用于通过 [GetAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_GetAsyncInvoke.html) 函数查询异步作业的状态。

```
{
    "invocationArn": "arn:aws:bedrock:us-east-1:xxxxxxxxxxxx:async-invoke/lvmxrnjf5mo3",
}
```

### 异步输出
<a name="w2aac25c20b5c27"></a>

异步嵌入生成完成后，输出构件将会写入您指定为输出目标的 S3 存储桶。文件的结构如下：

```
   amzn-s3-demo-bucket/
    job-id/
        segmented-embedding-result.json
        embedding-audio.jsonl
        embedding-image.json
        embedding-text.jsonl
        embedding-video.jsonl
        manifest.json
```

`segmented-embedding-result.json` 将包含总体作业结果以及对相应 jsonl 文件的引用，后者包含每种模态的实际嵌入。以下是对文件进行截断对示例：

```
{
    "sourceFileUri": string, 
    "embeddingDimension": 256 | 384 | 1024 | 3072,
    "embeddingResults": [
        {
            "embeddingType": "TEXT" | "IMAGE" | "VIDEO" | "AUDIO" | "AUDIO_VIDEO_COMBINED",
            "status": "SUCCESS" | "FAILURE" | "PARTIAL_SUCCESS",
            "failureReason": string, // Granular error codes
            "message": string, // Human-readbale failure message
            "outputFileUri": string // S3 URI to a "embedding-modality.jsonl" file
        }
        ...
    ]
}
```

`embedding-modality.json` 将是包含每种模态的嵌入输出的 jsonl 文件。该 jsonl 文件中的每一行都将遵循以下架构：

```
{
    "embedding": number[], // The generated embedding vector
    "segmentMetadata": {
        "segmentIndex": number,
        "segmentStartCharPosition": number, // Included for text only
        "segmentEndCharPosition": number, // Included for text only
        "truncatedCharLength": number, // Included only when text gets truncated
        "segmentStartSeconds": number, // Included for audio/video only
        "segmentEndSeconds": number // Included for audio/video only
    },
    "status": "SUCCESS" | "FAILURE",
    "failureReason": string, // Granular error codes
    "message": string // Human-readable failure message
}
```

以下列表包含了该响应的所有参数。对于文本字符或音频/视频时间，所有开始和结束时间均从零开始计算。此外，所有结束文本位置或音频/视频时间值都包括本数。
+ `embedding`（必填）：嵌入向量。
  + 类型：数字
+ `segmentMetadata`：分段的元数据。
  + `segmentIndex`：请求中所提供数组中分段的索引。
  + `segmentStartCharPosition`：仅限文本。分段中嵌入内容的起始字符位置（含本数）。
  + `segmentEndCharPosition`：仅限文本。分段中嵌入内容的结束字符位置（不含本数）。
  + `truncatedCharLength`（可选）：输入文本的令牌化版本超出模型的限制时将会返回此响应。该值表示在生成嵌入之前会将其之后的文本截断的字符。
    + 类型：整数
  + `segmentStartSeconds`：仅限音频/视频。分段中嵌入内容的开始时间位置。
  + `segmentEndSeconds`：仅限音频/视频。分段中嵌入内容的结束时间位置。
+ `status`：分段的状态。
+ `failureReason`：分段失败的详细原因。
  + `RAI_VIOLATION_INPUT_TEXT_DEFLECTION`：输入文本违反了 RAI 政策。
  + `RAI_VIOLATION_INPUT_IMAGE_DEFLECTION`：输入图像违反了 RAI 政策。
  + `INVALID_CONTENT`：输入无效。
  + `RATE_LIMIT_EXCEEDED`：由于服务不可用，嵌入请求被节流。
  + `INTERNAL_SERVER_EXCEPTION`：出现问题。
+ `message`：相关失败消息。

## Nova Embeddings 的文件限制
<a name="w2aac25c20b7"></a>

同步操作既可以接受 S3 输入，也可以接受内联块。异步操作只能接受 S3 输入。

异步生成嵌入时，您需要确保将文件分成适当数量的分段。对于文本嵌入，分段不能超过 1900 个。对于音频和视频嵌入，分段不能超过 1434 个。


**同步输入大小限制**  

|  文件类型  |  大小限制  | 
| --- | --- | 
|  （内联）所有文件类型  |  25MB  | 
|  （S3）文本  |  1 MB；50000 个字符  | 
|  （S3）图像  |  50 MB  | 
|  （S3）视频  |  30 秒；100 MB  | 
|  （S3）音频  |  30 秒；100 MB  | 

**注意**  
25 MB 的内联文件限制在嵌入 Base64 **之后**适用。这导致文件大小膨胀了大约 33%


**异步输入大小限制**  

|  文件类型  |  大小限制  | 
| --- | --- | 
|  （S3）文本  |  634MB  | 
|  （S3）图像  |  50 MB  | 
|  （S3）视频  |  2 GB；2 小时  | 
|  （S3）音频  |  1 GB；2 小时  | 


**输入文件格式**  

|  模式  |  文件类型  | 
| --- | --- | 
|  映像格式  |  PNG、JPEG、WEBP、GIF  | 
|  音频格式  |  MP3、WAV、OGG  | 
|  视频格式  |  MP4、MOV、MKV、WEBM、FLV、MPEG、MPG、WMV、3GP  |