本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Converse API 進行推論 Converse API 僅適用於`bedrock-runtime`端點。 您可以使用 Amazon Bedrock Converse API 來建立對話式應用程式，以將訊息傳送 Amazon Bedrock 模型和接收來自 Amazon Bedrock 模型的訊息。例如，您可以建立聊天機器人，以維持多回合對話，並使用符合您需求的獨特角色或語氣自訂，例如實用的技術支援助理。 若要使用 Converse API，您可以使用 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 或 [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html) (用於串流回應) 操作將訊息傳送到模型。您可以將現有的基礎推論操作 ([InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 或 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)) 用於對話應用程式。不過，我們建議您使用 Converse API，因為其提供一致的 API，可用於支援訊息的所有 Amazon Bedrock 模型。這表示您可以編寫程式碼一次，並搭配不同的模型使用。如果模型具有唯一的推論參數，Converse API 也可讓您在模型特定結構中傳遞那些唯一參數。 您可以使用 Converse API 在應用程式中實作[工具使用](tool-use.md)和[防護機制](guardrails-use-converse-api.md)。 **注意** 透過 Mistral AI 和 Meta 模型，Converse API 會將輸入內嵌在可啟用對話的模型特定提示範本。 限制適用於下列操作：`InvokeModel`、`Converse`、 `InvokeModelWithResponseStream`和 `ConverseStream`。如需詳細資訊，請參閱 [API 限制](inference-api-restrictions.md)。 如需程式碼範例，請參閱下方： + 本主題的 Python 範例：[Converse API 範例Converse API 範例 （已移動）](conversation-inference-examples.md) + 各種語言和模型：[使用 AWS SDKs的 Amazon Bedrock 執行期程式碼範例](service_code_examples_bedrock-runtime.md) + Java 教學課程：[Bedrock 新 Converse API 的 Java 開發人員指南](https://community.aws/content/2hUiEkO83hpoGF5nm3FWrdfYvPt/amazon-bedrock-converse-api-java-developer-guide) + JavaScript 教學課程：[Bedrock 新 Converse API 的開發人員指南](https://community.aws/content/2dtauBCeDa703x7fDS9Q30MJoBA/amazon-bedrock-converse-api-developer-guide) ## 使用 Converse API 若要使用 Converse API，您可以呼叫 `Converse` 或 `ConverseStream` 操作，將訊息傳送到模型。若要呼叫 `Converse`，您需要 `bedrock:InvokeModel` 操作的許可。若要呼叫 `ConverseStream`，您需要 `bedrock:InvokeModelWithResponseStream` 操作的許可。 ### 請求 使用 [Amazon Bedrock 執行時期端點](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt)提出 [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) 請求時，您可以包含下列欄位： + **modelId**：標頭中的必要參數，可讓您指定用於推論的資源。 + 下列欄位可讓您自訂提示： + **訊息**：用來指定提示的內容和角色。 + **系統**：用來指定系統提示，以定義模型的指示或內容。 + **inferenceConfig**：用來指定所有模型通用的推論參數。影響回應產生的推論參數。 + **additionalModelRequestFields**：用來指定與您執行推論所用之模型所特有的推論參數。 + **promptVariables**：(如果您使用提示管理中的提示) 使用此欄位來定義提示中要填入的變數，以及要填入這些變數的值。 + 下列欄位可讓您自訂回應的傳回方式： + **guardrailConfig**：使用此欄位來包含要套用至整個提示的防護機制。 + **toolConfig**：使用此欄位來包含工具，以協助模型產生回應。 + **additionalModelResponseFieldPaths**：使用此欄位指定要作為 JSON 指標物件傳回的欄位。 + **serviceTier** – 使用此欄位來指定特定請求的服務層 + **requestMetadata**：使用此欄位來包含可在使用調用日誌時篩選的中繼資料。 **注意** 當您搭配 `Converse` 或 `ConverseStream` 使用提示管理提示時，適用下列限制： 您無法包含 `additionalModelRequestFields`、`inferenceConfig`、`system` 或 `toolConfig` 欄位。 如果您包含 `messages` 欄位，會將訊息附加在提示中定義的訊息之後。 如果您包含 `guardrailConfig` 欄位，則防護機制會套用至整個提示。如果您在 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 欄位中包含 `guardContent` 區塊，防護機制只會套用至那些區塊。 展開區段以進一步了解 `Converse` 請求內文中的欄位： #### messages `messages` 欄位是 [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 物件的陣列，每個項目都會定義使用者與模型之間的訊息。`Message` 物件包含下列欄位： + **角色**：定義訊息是來自 `user` (傳送至模型的提示) 還是 `assistant` (模型回應)。 + **內容**：在提示中定義內容。 **注意** Amazon Bedrock 不會存放您作為內容提供的任何文字、影像或文件。資料僅用於產生回應。 您可以在後續 `Converse` 請求中包含對話中的所有訊息，並使用 `role` 欄位來指定訊息是來自使用者或模型，以維護對話內容。 `content` 欄位會對應至 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 物件的陣列。在每個 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 中，您可以指定下列其中一個欄位 （若要查看哪些模型支援哪些區塊，請參閱[模型一目了然](model-cards.md))： ------ #### [ text ] `text` 欄位會對應至指定提示的字串。系統會將 `text` 欄位與其他在相同 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 中指定的欄位一起解譯。 以下顯示 [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 物件，其 `content` 陣列僅包含文字 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)： ``` { "role": "user", "content": [ { "text": "{{string}}" } ] } ``` ------ #### [ image ] `image` 欄位會對應至 [ImageBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ImageBlock.html)。傳遞 `bytes` 欄位中影像的原始位元組 (以 base64 編碼)。如果您使用 AWS SDK，則不需要對 base64 中的位元組進行編碼。 如果您排除 `text` 欄位，則模型會描述影像。 以下顯示範例 [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 物件，其 `content` 陣列僅包含影像 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)： ``` { "role": "user", "content": [ { "image": { "format": "png", "source": { "bytes": "{{image in bytes}}" } } } ] } ``` 您也可以指定 Amazon S3 URI (而不是直接在請求內文中傳遞位元組)。以下顯示具有內容陣列的範例 `Message` 物件，其中包含透過 Amazon S3 URI 傳遞的來源。 ``` { "role": "user", "content": [ { "image": { "format": "png", "source": { "s3Location": { "uri": "s3://amzn-s3-demo-bucket/myImage", "bucketOwner": "111122223333" } } } } ] } ``` ------ #### [ document ] `document` 欄位對應至 [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html)。如果您包含 `DocumentBlock`，請檢查請求是否符合下列限制： + 在 [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 物件的 `content` 欄位中，您還必須包含 `text` 欄位，其中包含與文件相關的提示。 + 傳遞 `bytes` 欄位中文件的原始位元組 (以 base64 編碼)。如果您使用 AWS SDK，則不需要對 base64 中的文件位元組進行編碼。 + 該 `name` 欄位可以包含以下任何字元： + 英數字元 + 空格字元 (一列中不可超過一個) + 連字號 + 括號 + 方括號 **注意** `name` 欄位容易受到提示注入的影響，因為模型可能會不小心將其解譯為指示。因此，我們建議您指定中性名稱。 使用文件時，您可以啟用 `citations` 標籤，這會在 API 呼叫的回應中提供文件特定的引文。如需詳細資訊，請參閱 [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html) API。 以下顯示範例 [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 物件，其 `content` 陣列僅包含文件 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 和必要的隨附文字 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)。 ``` { "role": "user", "content": [ { "text": "{{string}}" }, { "document": { "format": "pdf", "name": "MyDocument", "source": { "bytes": "{{document in bytes}}" } } } ] } ``` 您也可以指定 Amazon S3 URI (而不是直接在請求內文中傳遞位元組)。以下顯示具有內容陣列的範例 `Message` 物件，其中包含透過 Amazon S3 URI 傳遞的來源。 ``` { "role": "user", "content": [ { "text": "{{string}}" }, { "document": { "format": "pdf", "name": "MyDocument", "source": { "s3Location": { "uri": "s3://amzn-s3-demo-bucket/myDocument", "bucketOwner": "111122223333" } } } } ] } ``` ------ #### [ video ] `video` 欄位會對應至 [VideoBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_VideoBlock.html) 物件。傳遞 `bytes` 欄位中的原始位元組 (以 base64 編碼)。如果您使用 AWS SDK，則不需要對 base64 中的位元組進行編碼。 如果您未包含 `text` 欄位，模型會描述影片。 以下顯示範例 [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 物件，其 `content` 陣列僅包含影片 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)。 ``` { "role": "user", "content": [ { "video": { "format": "mp4", "source": { "bytes": "{{video in bytes}}" } } } ] } ``` 您也可以指定 Amazon S3 URI (而不是直接在請求內文中傳遞位元組)。以下顯示具有內容陣列的範例 `Message` 物件，其中包含透過 Amazon S3 URI 傳遞的來源。 ``` { "role": "user", "content": [ { "video": { "format": "mp4", "source": { "s3Location": { "uri": "s3://amzn-s3-demo-bucket/myVideo", "bucketOwner": "111122223333" } } } } ] } ``` **注意** 擔任的角色必須具有 Amazon S3 URI 的 `s3:GetObject` 許可。`bucketOwner` 是選用欄位，但如果提出請求的帳戶未擁有在其中找到 Amazon S3 URI 的儲存貯體，則必須加以指定。如需詳細資訊，請參閱[設定對 Amazon S3 儲存貯體的存取權](s3-bucket-access.md)。 ------ #### [ cachePoint ] 您可以使用 `cachePoint` 欄位來使用提示快取，將快取檢查點新增為訊息中的區塊，以及隨附的提示。提示快取是一項功能，可讓您開始快取對話的內容，以節省成本和減少延遲。如需詳細資訊，請參閱[提示快取可加快模型推論速度](prompt-caching.md)。 以下顯示範例 [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 物件，其 `content` 陣列包含文件 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html) 和必要的隨附文字 [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)，以及同時將文件和文字內容新增至快取的 **cachePoint**。 ``` { "role": "user", "content": [ { "text": "{{string}}" }, { "document": { "format": "pdf", "name": "string", "source": { "bytes": "{{document in bytes}}" } } }, { "cachePoint": { "type": "default" } } ] } ``` ------ #### [ guardContent ] `guardContent` 欄位會對應至 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) 物件。您可以使用此欄位，將要由 `guardrailConfig` 欄位中定義的防護機制評估的輸入設為目標。如果您未指定此欄位，防護機制會評估請求內文中的所有訊息。您可以在 `GuardBlock` 中傳遞下列類型的內容： + **文字**：以下顯示範例 [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 物件，其 `content` 陣列僅包含文字 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)： ``` { "role": "user", "content": [ { "text": "Tell me what stocks to buy.", "qualifiers": [ "guard_content" ] } ] } ``` 您可以定義要評估的文字，並包含要用於[內容關聯依據](guardrails-contextual-grounding-check.md)的任何限定詞。 + **影像**：以下顯示具有僅包含影像 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) `content` 陣列的 [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) 物件： ``` { "role": "user", "content": [ { "format": "png", "source": { "bytes": "{{image in bytes}}" } } ] } ``` 您可以指定影像的格式，並以位元組為單位定義影像。 如需防護機制的使用詳細資訊，請參閱[使用 Amazon Bedrock 防護機制偵測和篩選有害內容](guardrails.md)。 ------ #### [ reasoningContent ] `reasoningContent` 欄位會對應至 [ReasoningContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ReasoningContentBlock.html)。此區塊包含有關模型在隨附 `ContentBlock` 中產生回應所執行之推理的內容。 以下顯示 `Message` 物件，其 `content` 陣列僅包含 `ReasoningContentBlock` 和隨附的文字 `ContentBlock`。 ``` { "role": "user", "content": [ { "text": "{{string}}" }, { "reasoningContent": { "reasoningText": { "text": "{{string}}", "signature": "{{string}}" } "redactedContent": "{{base64-encoded binary data object}}" } } ] } ``` `ReasoningContentBlock` 包含用於在 `reasoningText` 欄位中產生隨附內容的推理，以及模型提供者在 `redactedContent` 欄位中基於信任和安全性原因加密之推理中的任何內容。 在 `reasoningText` 欄位中，`text` 欄位會描述推理。`signature` 欄位是對話中所有訊息的雜湊，可防止模型使用的推理遭到竄改。您必須在後續 `Converse` 請求中包含簽章和所有先前的訊息。如果變更任何訊息，回應會擲回錯誤。 ------ #### [ toolUse ] 包含模型要使用之工具的相關資訊。如需詳細資訊，請參閱[使用工具完成 Amazon Bedrock 模型回應](tool-use.md)。 ------ #### [ toolResult ] 包含使用工具之模型結果相關資訊。如需詳細資訊，請參閱[使用工具完成 Amazon Bedrock 模型回應](tool-use.md)。 ------ 在下列 `messages` 範例中，使用者要求三首流行歌曲的清單，而模型會產生歌曲清單。 ``` [ { "role": "user", "content": [ { "text": "Create a list of 3 pop songs." } ] }, { "role": "assistant", "content": [ { "text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"As It Was\" by Harry Styles\n2. \"Easy On Me\" by Adele\n3. \"Unholy\" by Sam Smith and Kim Petras" } ] } ] ``` #### system 系統提示是一種提示類型，可為模型提供有關應執行任務或對話過程中應擔任角色的指示或情境。您可以如下列範例所示，在 `system` ([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)) 欄位中指定請求的系統提示清單。 ``` [ { "text": "You are an app that creates play lists for a radio station that plays rock and pop music. Only return song names and the artist. " } ] ``` #### inferenceConfig Converse API 支援一組您在 `inferenceConfig` 欄位 ([InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InferenceConfiguration.html)) 中設定的推論參數。推論參數的基本集合為： + **maxTokens** – 產生的回應中允許的字符數目上限。 + **stopSequences** – 停止序列的清單。停止序列是使模型停止產生回應的字元序列。 + **temperature** – 模型產生回應時，選取較高機率選項的可能性。 + **topP** – 模型考慮下一個字符時，最可能的候選項目百分比。 如需詳細資訊，請參閱[使用推論參數影響回應生成](inference-parameters.md)。 下列範例 JSON 會設定 `temperature` 推論參數。 ``` {"temperature": 0.5} ``` #### additionalModelRequestFields 如果您使用的模型有其他推論參數，您可以在 `additionalModelRequestFields` 欄位中將那些參數指定為 JSON，以設定參數。下列範例 JSON 說明如何設定可在 Anthropic Claude 模型中使用的 `top_k` (但其不是訊息 API 中的基本推論參數)。 ``` {"top_k": 200} ``` #### promptVariables 如果您從 `modelId` 中的[提示管理](prompt-management.md)將提示指定為要在其中執行推論的資源，請使用此欄位將實際值填入提示變數。`promptVariables` 欄位會對應至具有對應至提示中定義變數之索引鍵的 JSON 物件，以及用來取代變數的值。 例如，假設您有提示，該提示寫著 **Make me a {{{{genre}}}} playlist consisting of the following number of songs: {{{{number}}}}.**。提示的 ID 是 `PROMPT12345`，其版本是 `1`。您可以傳送下列 `Converse` 請求來取代變數： ``` POST /model/arn:aws:bedrock:us-east-1:111122223333:prompt/PROMPT12345:1/converse HTTP/1.1 Content-type: application/json { "promptVariables": { "genre": { "text": "pop" }, "number": { "text": "3" } } } ``` #### guardrailConfig 您可以包含此欄位，套用使用 [Amazon Bedrock 防護機制](guardrails.md)建立的防護機制。若要將防護機制套用至對話中的特定訊息，請在 [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) 中包含訊息。如果您在請求內文中未包含任何 `GuardrailConverseContentBlock`，則會將防護機制套用至 `messages` 欄位中的所有訊息。如需範例，請參閱 [包含防護機制與 Converse API](guardrails-use-converse-api.md)。 #### toolConfig 此欄位可讓您為模型定義工具，以用於協助產生回應。如需詳細資訊，請參閱[使用工具完成 Amazon Bedrock 模型回應](tool-use.md)。 #### additionalModelResponseFieldPaths 您可以如下列範例所示，在 `additionalModelResponseFieldPaths` 欄位中指定其他模型參數的路徑。 ``` [ "/stop_sequence" ] ``` API 會傳回您在 `additionalModelResponseFields` 欄位中請求的其他欄位。 #### requestMetadata `requestMetadata` 欄位會映射至金鑰值標籤的 JSON 物件，該標籤會與您的模型調用日誌中的請求一起記錄。您可以使用請求中繼資料，依團隊、應用程式、環境或任何其他因呼叫而異的維度來篩選和彙總日誌。 相同的功能可透過 `X-Amzn-Bedrock-Request-Metadata` HTTP 標頭在 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) 和 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) 上使用。如需支援的 APIs、限制以及請求中繼資料在調用日誌中顯示方式的詳細資訊，請參閱 [每個請求中繼資料標記](cost-mgmt-request-metadata.md)。 #### serviceTier 此欄位會對應至 JSON 物件。您可以為特定請求指定服務方案。 下列範例顯示 `serviceTier`結構： ``` "serviceTier": { "type": "reserved" | "priority" | "default" | "flex" } ``` 如需服務方案的詳細資訊，包括定價和效能特性，請參閱 [最佳化效能和成本的服務層](service-tiers-inference.md)。 視使用的模型而定，您也可以選擇將快取檢查點新增至 `system` 或 `tools` 欄位，以使用提示快取。如需詳細資訊，請參閱[提示快取可加快模型推論速度](prompt-caching.md)。 ### 回應 您從 Converse API 取得的回應取決於您呼叫的操作 (`Converse` 或 `ConverseStream`)。 #### Converse 回應 在來自 `Converse` 的回應中，`output` 欄位 ([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)) 包含模型產生的訊息 ([訊息](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html))。訊息內容位於 `content` ([ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)) 欄位中，而訊息對應的角色 (`user` 或 `assistant`) 位於 `role` 欄位中。 如果您使用[提示快取](prompt-caching.md)，請在用量欄位中，`cacheReadInputTokens` 和 `cacheWriteInputTokens` 會個別告訴您從快取讀取並寫入快取的字符總數。 如果您使用[服務層](#inference-service-tiers)，則在回應欄位中， `service tier`會告訴您用於請求的服務層。 `metrics` 欄位 ([ConverseMetrics](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseMetrics.html)) 包含呼叫的指標。若要判斷模型停止產生內容的原因，請檢查 `stopReason` 欄位。您可以檢查 `usage` 欄位 ([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html))，以取得在請求中傳遞給模型的字符，以及在回應中產生之字符的相關資訊。如果您在請求中指定了其他回應欄位，API 會在 `additionalModelResponseFields` 欄位中將其傳回為 JSON。 下列範例顯示當您傳遞在 [請求](#conversation-inference-call-request) 中討論的提示時，來自 `Converse` 的回應。 ``` { "output": { "message": { "role": "assistant", "content": [ { "text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"Wannabe\" by Spice Girls\n2. \"Bitter Sweet Symphony\" by The Verve \n3. \"Don't Look Back in Anger\" by Oasis" } ] } }, "stopReason": "end_turn", "usage": { "inputTokens": 125, "outputTokens": 60, "totalTokens": 185 }, "metrics": { "latencyMs": 1175 } } ``` #### ConverseStream 回應 如果您呼叫 `ConverseStream` 以從模型串流回應，則會在 `stream` 回應欄位中傳回串流。串流會依下列順序發出下列事件。 1. `messageStart` ([MessageStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStartEvent.html))。訊息的開始事件。包含訊息的角色。 1. `contentBlockStart` ([ContentBlockStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStartEvent.html))。內容區塊開始事件。僅限工具使用。 1. `contentBlockDelta` ([ContentBlockDeltaEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockDeltaEvent.html))。內容區塊差異事件。包括下列其中一項： + `text`：模型產生的部分文字。 + `reasoningContent`：模型執行的部分推理，以產生回應。除了後續 `Converse` 請求中的所有先前訊息之外，您還必須提交傳回的 `signature`。如果變更任何訊息，回應會擲回錯誤。 + `toolUse`：用於工具使用的部分輸入 JSON 物件。 1. `contentBlockStop` ([ContentBlockStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStopEvent.html))。內容區塊停止事件。 1. `messageStop` ([MessageStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStopEvent.html))。訊息的停止事件。包括模型停止產生輸出的原因。 1. `metadata` ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html))。請求的中繼資料。中繼資料包含 `usage` ([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html)) 中的字符用量和 `metrics` ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)) 中呼叫的指標。 ConverseStream 會將完整的內容區塊串流為 `ContentBlockStartEvent` 事件、一或多個 `ContentBlockDeltaEvent` 事件和 `ContentBlockStopEvent` 事件。使用 `contentBlockIndex` 欄位作為索引，以將組成內容區塊的事件建立關聯。 下列範例是 `ConverseStream` 的部分回應。 ``` {'messageStart': {'role': 'assistant'}} {'contentBlockDelta': {'delta': {'text': ''}, 'contentBlockIndex': 0}} {'contentBlockDelta': {'delta': {'text': ' Title'}, 'contentBlockIndex': 0}} {'contentBlockDelta': {'delta': {'text': ':'}, 'contentBlockIndex': 0}} . . . {'contentBlockDelta': {'delta': {'text': ' The'}, 'contentBlockIndex': 0}} {'messageStop': {'stopReason': 'max_tokens'}} {'metadata': {'usage': {'inputTokens': 47, 'outputTokens': 20, 'totalTokens': 67}, 'metrics': {'latencyMs': 100.0}}} ``` ## Converse API 範例 下表顯示如何將 `Converse` 和 `ConverseStream` 操作搭配使用的範例。 ------ #### [ Text ] 此範例示範如何使用 *Anthropic Claude 3 Sonnet* 模型呼叫 `Converse` 操作。此範例示範如何傳送輸入文字、推論參數，以及模型特有的其他參數。程式碼會要求模型建立歌曲清單，以展開對話。然後，其會繼續對話，詢問歌曲是否來自英國的藝術家。 ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ Shows how to use the Converse API with Anthropic Claude 3 Sonnet (on demand). """ import logging import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) logging.basicConfig(level=logging.INFO) def generate_conversation(bedrock_client, model_id, system_prompts, messages): """ Sends messages to a model. Args: bedrock_client: The Boto3 Bedrock runtime client. model_id (str): The model ID to use. system_prompts (JSON) : The system prompts for the model to use. messages (JSON) : The messages to send to the model. Returns: response (JSON): The conversation that the model generated. """ logger.info("Generating message with model %s", model_id) # Inference parameters to use. temperature = 0.5 top_k = 200 # Base inference parameters to use. inference_config = {"temperature": temperature} # Additional inference parameters to use. additional_model_fields = {"top_k": top_k} # Send the message. response = bedrock_client.converse( modelId=model_id, messages=messages, system=system_prompts, inferenceConfig=inference_config, additionalModelRequestFields=additional_model_fields ) # Log token usage. token_usage = response['usage'] logger.info("Input tokens: %s", token_usage['inputTokens']) logger.info("Output tokens: %s", token_usage['outputTokens']) logger.info("Total tokens: %s", token_usage['totalTokens']) logger.info("Stop reason: %s", response['stopReason']) return response def main(): """ Entrypoint for Anthropic Claude 3 Sonnet example. """ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") model_id = "anthropic.claude-3-sonnet-20240229-v1:0" # Setup the system prompts and messages to send to the model. system_prompts = [{"text": "You are an app that creates playlists for a radio station that plays rock and pop music. Only return song names and the artist."}] message_1 = { "role": "user", "content": [{"text": "Create a list of 3 pop songs."}] } message_2 = { "role": "user", "content": [{"text": "Make sure the songs are by artists from the United Kingdom."}] } messages = [] try: bedrock_client = boto3.client(service_name='bedrock-runtime') # Start the conversation with the 1st message. messages.append(message_1) response = generate_conversation( bedrock_client, model_id, system_prompts, messages) # Add the response message to the conversation. output_message = response['output']['message'] messages.append(output_message) # Continue the conversation with the 2nd message. messages.append(message_2) response = generate_conversation( bedrock_client, model_id, system_prompts, messages) output_message = response['output']['message'] messages.append(output_message) # Show the complete conversation. for message in messages: print(f"Role: {message['role']}") for content in message['content']: print(f"Text: {content['text']}") print() except ClientError as err: message = err.response['Error']['Message'] logger.error("A client error occurred: %s", message) print(f"A client error occured: {message}") else: print( f"Finished generating text with model {model_id}.") if __name__ == "__main__": main() ``` ------ #### [ Image ] 此範例示範如何在訊息中傳送影像，以及請求模型描述影像。此範例使用 `Converse` 操作和 *Anthropic Claude 3 Sonnet* 模型。 ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ Shows how to send an image with the Converse API with an accompanying text prompt to Anthropic Claude 3 Sonnet (on demand). """ import logging import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) logging.basicConfig(level=logging.INFO) def generate_conversation(bedrock_client, model_id, input_text, input_image): """ Sends a message to a model. Args: bedrock_client: The Boto3 Bedrock runtime client. model_id (str): The model ID to use. input text : The text prompt accompanying the image. input_image : The path to the input image. Returns: response (JSON): The conversation that the model generated. """ logger.info("Generating message with model %s", model_id) # Get image extension and read in image as bytes image_ext = input_image.split(".")[-1] with open(input_image, "rb") as f: image = f.read() message = { "role": "user", "content": [ { "text": input_text }, { "image": { "format": image_ext, "source": { "bytes": image } } } ] } messages = [message] # Send the message. response = bedrock_client.converse( modelId=model_id, messages=messages ) return response def main(): """ Entrypoint for Anthropic Claude 3 Sonnet example. """ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") model_id = "anthropic.claude-3-sonnet-20240229-v1:0" input_text = "What's in this image?" input_image = "path/to/image" try: bedrock_client = boto3.client(service_name="bedrock-runtime") response = generate_conversation( bedrock_client, model_id, input_text, input_image) output_message = response['output']['message'] print(f"Role: {output_message['role']}") for content in output_message['content']: print(f"Text: {content['text']}") token_usage = response['usage'] print(f"Input tokens: {token_usage['inputTokens']}") print(f"Output tokens: {token_usage['outputTokens']}") print(f"Total tokens: {token_usage['totalTokens']}") print(f"Stop reason: {response['stopReason']}") except ClientError as err: message = err.response['Error']['Message'] logger.error("A client error occurred: %s", message) print(f"A client error occured: {message}") else: print( f"Finished generating text with model {model_id}.") if __name__ == "__main__": main() ``` ------ #### [ Document ] 此範例示範如何在訊息中傳送文件，以及請求模型描述文件的內容。此範例使用 `Converse` 操作和 *Anthropic Claude 3 Sonnet* 模型。 ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ Shows how to send an document as part of a message to Anthropic Claude 3 Sonnet (on demand). """ import logging import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) logging.basicConfig(level=logging.INFO) def generate_message(bedrock_client, model_id, input_text, input_document_path): """ Sends a message to a model. Args: bedrock_client: The Boto3 Bedrock runtime client. model_id (str): The model ID to use. input text : The input message. input_document_path : The path to the input document. Returns: response (JSON): The conversation that the model generated. """ logger.info("Generating message with model %s", model_id) # Get format from path and read the path input_document_format = input_document_path.split(".")[-1] with open(input_document_path, 'rb') as input_document_file: input_document = input_document_file.read() # Message to send. message = { "role": "user", "content": [ { "text": input_text }, { "document": { "name": "MyDocument", "format": input_document_format, "source": { "bytes": input_document } } } ] } messages = [message] # Send the message. response = bedrock_client.converse( modelId=model_id, messages=messages ) return response def main(): """ Entrypoint for Anthropic Claude 3 Sonnet example. """ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") model_id = "anthropic.claude-3-sonnet-20240229-v1:0" input_text = "What's in this document?" input_document_path = "path/to/document" try: bedrock_client = boto3.client(service_name="bedrock-runtime") response = generate_message( bedrock_client, model_id, input_text, input_document_path) output_message = response['output']['message'] print(f"Role: {output_message['role']}") for content in output_message['content']: print(f"Text: {content['text']}") token_usage = response['usage'] print(f"Input tokens: {token_usage['inputTokens']}") print(f"Output tokens: {token_usage['outputTokens']}") print(f"Total tokens: {token_usage['totalTokens']}") print(f"Stop reason: {response['stopReason']}") except ClientError as err: message = err.response['Error']['Message'] logger.error("A client error occurred: %s", message) print(f"A client error occured: {message}") else: print( f"Finished generating text with model {model_id}.") if __name__ == "__main__": main() ``` ------ #### [ Streaming ] 此範例示範如何使用 *Anthropic Claude 3 Sonnet* 模型呼叫 `ConverseStream` 操作。此範例示範如何傳送輸入文字、推論參數，以及模型特有的其他參數。 ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ Shows how to use the Converse API to stream a response from Anthropic Claude 3 Sonnet (on demand). """ import logging import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) logging.basicConfig(level=logging.INFO) def stream_conversation(bedrock_client, model_id, messages, system_prompts, inference_config, additional_model_fields): """ Sends messages to a model and streams the response. Args: bedrock_client: The Boto3 Bedrock runtime client. model_id (str): The model ID to use. messages (JSON) : The messages to send. system_prompts (JSON) : The system prompts to send. inference_config (JSON) : The inference configuration to use. additional_model_fields (JSON) : Additional model fields to use. Returns: Nothing. """ logger.info("Streaming messages with model %s", model_id) response = bedrock_client.converse_stream( modelId=model_id, messages=messages, system=system_prompts, inferenceConfig=inference_config, additionalModelRequestFields=additional_model_fields ) stream = response.get('stream') if stream: for event in stream: if 'messageStart' in event: print(f"\nRole: {event['messageStart']['role']}") if 'contentBlockDelta' in event: print(event['contentBlockDelta']['delta']['text'], end="") if 'messageStop' in event: print(f"\nStop reason: {event['messageStop']['stopReason']}") if 'metadata' in event: metadata = event['metadata'] if 'usage' in metadata: print("\nToken usage") print(f"Input tokens: {metadata['usage']['inputTokens']}") print( f":Output tokens: {metadata['usage']['outputTokens']}") print(f":Total tokens: {metadata['usage']['totalTokens']}") if 'metrics' in event['metadata']: print( f"Latency: {metadata['metrics']['latencyMs']} milliseconds") def main(): """ Entrypoint for streaming message API response example. """ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") model_id = "anthropic.claude-3-sonnet-20240229-v1:0" system_prompt = """You are an app that creates playlists for a radio station that plays rock and pop music. Only return song names and the artist.""" # Message to send to the model. input_text = "Create a list of 3 pop songs." message = { "role": "user", "content": [{"text": input_text}] } messages = [message] # System prompts. system_prompts = [{"text" : system_prompt}] # inference parameters to use. temperature = 0.5 top_k = 200 # Base inference parameters. inference_config = { "temperature": temperature } # Additional model inference parameters. additional_model_fields = {"top_k": top_k} try: bedrock_client = boto3.client(service_name='bedrock-runtime') stream_conversation(bedrock_client, model_id, messages, system_prompts, inference_config, additional_model_fields) except ClientError as err: message = err.response['Error']['Message'] logger.error("A client error occurred: %s", message) print("A client error occured: " + format(message)) else: print( f"Finished streaming messages with model {model_id}.") if __name__ == "__main__": main() ``` ------ #### [ Video ] 此範例示範如何在訊息中傳送影片，以及請求模型描述影片。此範例使用 `Converse` 操作和 Amazon Nova Pro 模型。 ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ Shows how to send a video with the Converse API to Amazon Nova Pro (on demand). """ import logging import boto3 from botocore.exceptions import ClientError logger = logging.getLogger(__name__) logging.basicConfig(level=logging.INFO) def generate_conversation(bedrock_client, model_id, input_text, input_video): """ Sends a message to a model. Args: bedrock_client: The Boto3 Bedrock runtime client. model_id (str): The model ID to use. input text : The input message. input_video : The input video. Returns: response (JSON): The conversation that the model generated. """ logger.info("Generating message with model %s", model_id) # Message to send. with open(input_video, "rb") as f: video = f.read() message = { "role": "user", "content": [ { "text": input_text }, { "video": { "format": 'mp4', "source": { "bytes": video } } } ] } messages = [message] # Send the message. response = bedrock_client.converse( modelId=model_id, messages=messages ) return response def main(): """ Entrypoint for Amazon Nova Pro example. """ logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s") model_id = "amazon.nova-pro-v1:0" input_text = "What's in this video?" input_video = "path/to/video" try: bedrock_client = boto3.client(service_name="bedrock-runtime") response = generate_conversation( bedrock_client, model_id, input_text, input_video) output_message = response['output']['message'] print(f"Role: {output_message['role']}") for content in output_message['content']: print(f"Text: {content['text']}") token_usage = response['usage'] print(f"Input tokens: {token_usage['inputTokens']}") print(f"Output tokens: {token_usage['outputTokens']}") print(f"Total tokens: {token_usage['totalTokens']}") print(f"Stop reason: {response['stopReason']}") except ClientError as err: message = err.response['Error']['Message'] logger.error("A client error occurred: %s", message) print(f"A client error occured: {message}") else: print( f"Finished generating text with model {model_id}.") if __name__ == "__main__": main() ``` ------