# 完整的请求架构
<a name="complete-request-schema"></a>

Invoke API（流式传输和非流式传输）和 Converse API 之间的请求架构几乎相同。在图像和视频有效载荷编码方面存在细微差别。Amazon Nova Micro 不支持将图像或视频作为输入，因此请求架构的这些部分不适用于 Amazon Nova Micro。否则，所有 Amazon Nova 理解模型的请求架构都相同。

**重要**  
对 Amazon Nova 进行推理调用的超时时间为 60 分钟。默认情况下，AWS SDK 客户端在 1 分钟后超时。建议将 AWS SDK 客户端的读取超时时间延长至至少 60 分钟。例如，在 AWS Python botocore SDK 中，请将 [botocore.config](https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#) 中的 `read_timeout` 字段值更改为至少 3600。  

```
client = boto3.client(
    "bedrock-runtime",
    region_name="us-east-1",
    config=Config(
        connect_timeout=3600,  # 60 minutes
        read_timeout=3600,     # 60 minutes
        retries={'max_attempts': 1}
    )
)
```

```
{
  "system": [
    {
      "text": "string"
    }
  ],
  "messages": [
    {
      "role": "user", //first turn should always be the user turn
      "content": [
        {
          "text": "string"
        },
        {
          "image": {
            "format": "jpeg" | "png" | "gif" | "webp",
            "source": {
              "bytes": image // Binary array (Converse API) or Base64-encoded string (Invoke API)
            }
          }
        },
        {
          "video": {
            "format": "mkv" | "mov" | "mp4" | "webm" | "three_gp" | "flv" | "mpeg" | "mpg" | "wmv",
            "source": {
              // Option 1: Sending a S3 location 
              "s3Location": {
                "uri": "string", // example: s3://my-bucket/object-key
                "bucketOwner": "string" // (Optional) example: "123456789012"
              },
              // Option 2: Sending file bytes 
              "bytes": video // Binary array (Converse API) or Base64-encoded string (Invoke API)
            }
          }
        },
        {
            "audio": {
                "format": "mp3" | "opus" | "wav" | "aac" | "flac" | "mp4" | "ogg" | "mkv",
                "source": {
                    // Option 1: Sending a S3 location 
                    "s3Location": {
                        "uri": "string", // example: s3://my-bucket/object-key
                        "bucketOwner": "string" // (Optional) example: "123456789012"
                    },
                    // Option 2: Sending file bytes 
                    "bytes": audio // Binary array (Converse API) or Base64-encoded string (Invoke API)
                }
            }
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "text": "string" //prefilling assistant turn
        }
      ]
    }
  ],
 "inferenceConfig":{ // all Optional, Invoke parameter names used in this example
    "maxTokens": int, // greater than 0, equal or less than 5k (default: dynamic*)
    "temperature": float, // greater than 0 and less than 1.0 (default: 0.7)
    "topP": float, // greater than 0, equal or less than 1.0 (default: 0.9)
    "topK": int, // 0 or greater (default: 50)
    "stopSequences": ["string"],
    "reasoningConfig": {
        "type": "string", //"enabled"/"disabled" (default: "disabled")
        "maxReasoningEffort": "string" // "low", "medium", "high"
    }
  },
  "toolConfig": { // all Optional
        "tools": [
            {
                "toolSpec": {
                    "name": "string", //meaningful tool name (Max char: 64)
                    "description": "string", //meaningful description of the tool
                    "inputSchema": {
                        "json": { // The JSON schema for the tool. For more information, see JSON Schema Reference
                            "type": "object",
                            "properties": {
                                "arg1": { //arguments 
                                    "type": "string", //argument data type
                                    "description": "string" //meaningful description
                                }
                            },
                            "required": [
                                "string" //args
                            ]
                        }
                    }
                }
            }
        ],
    },
    "toolChoice": { //can select one of three options
      "auto": {},
      "any": {},
      "tool": {
        "name": "string" //name of tool
      }
    }
}
```

以下是必要参数：
+ `system` –（可选）请求的系统提示。

  系统提示是一种可以为 Amazon Nova 提供上下文和说明的方式，例如指定特定的目标或角色。
+ `messages` –（必要）输入消息。
  + `role` – 对话回合的角色。有效值为 `user` 和 `assistant`。
  + `content`-（必要）一个包含对话内容的 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 对象列表。每个对象都包含一个指定内容类型（`text`、`image`、`video` 或 `audio`）的键。对象的值取决于键类型。以下是支持的键类型：
    + `text`— 映射到包含单个字段 `text` 的对象，字段值为对话回合的文本提示。如果对话回合还包含 `image` 或 `video` 对象，则 `text` 对象将被解释为伴随图像或视频的文本提示。
    + `image`—（Amazon Nova Micro 不支持）映射到一个表示图像内容且含有以下字段的对象：
      + `format` –（必要）图像格式。您可以指定以下图像格式：
        + `jpeg`
        + `png`
        + `webp`
        + `gif`
      + `source` –（必要）图像数据。对于 Invoke API，该数据必须是 Base64 编码图像字符串。对于 Converse API，该数据必须是字节数组。
      + `bytes` –（必要）图像数据。对于 Invoke API，该数据必须是 Base64 编码图像字符串。对于 Converse API，该数据必须是字节数组。
    + `video`—（Amazon Nova Micro 不支持）映射到一个表示视频内容且含有以下字段的对象：
      + `format` –（必要）视频格式。可以指定以下值：
        + `mkv`
        + `mov`
        + `mp4`
        + `webm`
        + `three_gp`
        + `flv`
        + `mpeg`
        + `mpg`
        + `wmv`
      + `source` –（必要）视频数据的来源。您可以在请求中指定 Amazon S3 URI 或视频文件字节。
        + `uri`：（必要）视频文件的 Amazon S3 URI。例如，`“s3://my-bucket/object-key”`
        + `bucketOwner` –（可选）拥有存储桶的账户 ID。如果您要从单独的账户调用模型，请使用此选项。
        + `bytes`：（必需）视频数据。对于 Invoke API，该数据必须是 Base64 编码视频字符串。对于 Converse API，该数据必须是字节数组。
    + `audio`：（仅限）映射至一个代表音频内容的对象，包含以下字段：
      + `format`：（必需）音频格式。可以指定以下值：
        + `aac`
        + `flac`
        + `mkv`
        + `mp3`
        + `mp4`
        + `ogg`
        + `opus`
        + `wav`
      + `source`：（必需）音频数据的来源。您可以在请求中指定 Amazon S3 URI 或音频文件字节。
        + `uri`：（必需）音频文件的 Amazon S3 URI。例如，`"s3://my-bucket/object-key"`
        + `bucketOwner` –（可选）拥有存储桶的账户 ID。如果您要从单独的账户调用模型，请使用此选项。
        + `bytes`：（必需）音频数据。对于 Invoke API，该数据必须是 Base64 编码音频字符串。对于 Converse API，该数据必须是字节数组。
+ `inferenceConfig:` 这些是推理配置值，可以在推理中传递。
  + `maxTokens` –（可选）停止前要生成的最大词元数量。

    请注意，Amazon Nova 模型可能会在达到 `maxTokens` 值之前停止生成词元。允许的最大新词元值为 5K。
  + `temperature` –（可选）注入回复的随机性数量。有效值介于 0.00001 到 1 之间（含两端值）。默认值为 0.7。
  + `topP` –（可选）使用 nucleus 采样。

    Amazon Nova 按概率递减顺序计算每个后续词元的所有选项的累积分布，并在达到 `topP` 指定的特定概率后将其切断。您应该更改 `temperature` 或 `topP`，但不能同时更改这两个。有效值介于 0 到 1 之间（含两端值）。默认值为 0.9。
  + `topK` –（可选）仅从每个后续词元的前 K 个选项中取样。

    使用 `topK` 参数移除长尾低概率回复。有效值在 0 到 128 之间。如果未使用此参数，则默认值为：
**注意**  
将 Converse API 与 `topK` 参数一起使用时，`additionalModelRequestFields` 字段中必须包含其他 `inferenceConfig` 参数。有关如何传递这些参数的示例，请参阅 [使用 Converse API](using-converse-api.md)。
  + `stopSequences` –（可选）包含停止序列的字符串数组。如果模型生成其中任何一个字符串，则生成将停止并返回回复，直到该点为止。
  + `reasoningConfig`：（仅限 Amazon Nova Pro 和 Amazon Nova Lite）可在推理中传递的推理配置值。
    + `type`：（可选）是否启用或禁用推理。有效选项是 `enabled` 或 `disabled`。默认值为 `disabled`。
    + `maxReasoningEffort`：推理过程中使用的计算工作量。有效的选项为 `low`、`medium` 或 `high`。在流式传输中，当使用 `low` 和 `medium` 设置时，推理内容将在使用 `ConverseStream` 生成每个词元时进行流式传输。但是，`high` 的工作原理有所不同，它采用不同的方法来提高质量，所有推理内容都输出到一个最终的块中。
**注意**  
将 Converse API 与 `reasoningConfig` 参数结合使用时，应将该参数置于 `additionalModelRequestFields` 字段中。有关如何传递这些参数的示例，请参阅 [使用 Converse API](using-converse-api.md)。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/nova/latest/userguide/complete-request-schema.html)
+ `toolConfig` –（可选）遵循 [ToolConfig 架构](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolConfiguration.html)的 JSON 对象，包含工具规格和工具选择。此架构与 [Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html) 遵循的架构相同
  + `toolChoice`：（可选）指定模型可使用的工具。您可以从三个选项中选择一项：
    + `auto`：模型会自动决定是否使用工具以及使用何种工具。
    + `any`：模型必须至少使用所提供的一种工具。
    + `tool`：模型必须使用按名称标识的特定工具。