本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 完成請求結構描述
<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`、`video`、 `image`或 `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` – （必要） 影片資料。對於調用 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` – （必要） 音訊資料。對於調用 API，這必須是 Base64 編碼的音訊字串。對於 Converse API，這必須是位元組陣列。
+ `inferenceConfig:` 這些是可在推論中傳遞的推論組態值。
  + `maxTokens` – (選用) 停止之前要產生的詞元數目上限。

    請注意，Amazon Nova 模型可能會在達到 `maxTokens` 的值之前停止產生詞元。允許的新詞元上限值為 5K。
  + `temperature` – (選用) 注入回應的隨機性數量。有效值介於 0.00001 到 1 (含) 之間。預設值為 0.7。
  + `topP` – (選用) 使用核取樣。

    Amazon Nova 會以遞減的機率順序計算每個後續詞元的所有選項的累積分佈，並在達到 `topP` 指定的特定機率時將其截斷。您應該更改 `temperature` 或 `topP`，但不能同時更改兩者。有效值介於 0 到 1 (含) 之間。預設值為 0.9。
  + `topK` – (選用) 每個後續詞元僅從頂端 K 選項中抽樣。

    使用 `topK` 參數移除長尾低機率回應。有效值介於 0 到 128 之間。預設值為不使用此參數。
**注意**  
搭配 `topK` 參數使用 Converse API 時，`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_tw/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` – 模型必須使用以名稱識別的特定工具。

# 回應結構重點
<a name="complete-request-schema-response"></a>

以下顯示非串流 `Converse`和 `InvokeModel`函數傳回之回應結構的關鍵元素。如需完整回應結構以及串流函數的請求和回應結構的詳細資訊，請參閱 API 文件。

```
{
    "ResponseMetadata": {
        "RequestId": string,
        "HTTPStatusCode": int,
        "HTTPHeaders": {
            "date": string,
            "content-type": "application/json",
            "content-length": string,
            "connection": "keep-alive",
            "x-amzn-requestid": string
        },
        "RetryAttempts": 0
    },
    "output": {
        "message": {
            "role": "assistant",
            "content": [
                { // Optional
                    "reasoningContent": {
                        "reasoningText": {
                            "text": string
                        }
                    }
                },
                { // Optional
                    "toolUse": {
                        "toolUseId": string,
                        "name": string,
                        "input": object
                    }
                },
                { // Optional
                    "text": string
                },
                { // Optional
                    "image": {
                        "format": "png",
                        "source": {
                            "bytes": {
                                "bytes": image // Binary array (Converse API) or Base64-encoded string (Invoke API)
                            }
                        }
                    }
                }
            ]
        }
    },
    "stopReason": string, // "end_turn" | "content_filtered" | "max_tokens" | "malformed_model_output" | "malformed_tool_use" | etc.
    "usage": {
        "inputTokens": int,
        "outputTokens": int,
        "totalTokens": int
    },
    "metrics": {
        "latencyMs": int
    }
}
```

以下是關鍵回應元素：
+ `output` – （必要） 包含模型的回應訊息。
  + `message` – （必要） 助理的回應訊息。
    + `content` – （必要） 一或多個內容區塊的陣列，可包含：
      + `reasoningContent` – （選用） 如果已啟用推理，則傳回。包含推理文字，一律會在回應`[REDACTED]`中。
      + `toolUse` – （選用） 如果呼叫工具，則傳回。包含工具使用 ID、名稱和輸入引數。
      + `text` – （選用） 如果模型以文字內容回應，則傳回。
      + `image` – （選用，僅限） 如果模型產生映像，則傳回。對於 產生的映像，格式一律為 PNG。
+ `stopReason` – （必要） 列舉值，指出模型停止產生輸出的原因。支援的值包括：
  + `end_turn` – 已達到轉彎的邏輯結尾。
  + `max_tokens` – 輸出達到使用者設定`maxTokens`的限制，或模型自己的最大輸出字符限制。
  + `content_filtered` – 模型的輸出違反了 AWS 負責任的 AI 政策。
  + `malformed_model_output` – 模型產生無效的輸出。
  + `malformed_tool_use` – 模型產生無效的`toolUse`輸出。
  + `service_unavailable` – 無法連線其中一個內建工具服務。
  + `invalid_query` – 模型傳送至內建 Web Grounding 工具的查詢無效。
  + `max_tool_invocations` – 表示已呼叫內建工具，但即使多次重試也未產生有效的結果。
+ `usage` – （必要） 字符使用資訊，包括輸入字符、輸出字符和總字符。
+ `metrics` – （必要） 效能指標，包括以毫秒為單位的總推論延遲。