使用 Converse API 進行推論

Converse API 僅適用於bedrock-runtime端點。

您可以使用 Amazon Bedrock Converse API 來建立對話式應用程式，以將訊息傳送 Amazon Bedrock 模型和接收來自 Amazon Bedrock 模型的訊息。例如，您可以建立聊天機器人，以維持多回合對話，並使用符合您需求的獨特角色或語氣自訂，例如實用的技術支援助理。

若要使用 Converse API，您可以使用 Converse 或 ConverseStream (用於串流回應) 操作將訊息傳送到模型。您可以將現有的基礎推論操作 (InvokeModel 或 InvokeModelWithResponseStream) 用於對話應用程式。不過，ConverseAPI 提供一致的 API，可與支援訊息的所有 Amazon Bedrock 模型搭配使用。這表示您可以編寫程式碼一次，並搭配不同的模型使用。如果模型具有唯一的推論參數，Converse API 也可讓您在模型特定結構中傳遞那些唯一參數。

您可以使用 Converse API 在應用程式中實作工具使用和防護機制。

注意

透過 Mistral AI 和 Meta 模型，Converse API 會將輸入內嵌在可啟用對話的模型特定提示範本。
限制適用於下列操作：InvokeModel、Converse、 InvokeModelWithResponseStream和 ConverseStream。如需詳細資訊，請參閱 API 限制。

如需程式碼範例，請參閱下方：

本主題的 Python 範例：Converse API 範例
各種語言和模型：使用 AWS SDKs的 Amazon Bedrock 執行期程式碼範例
Java 教學課程：Bedrock 新 Converse API 的 Java 開發人員指南
JavaScript 教學課程：Bedrock 新 Converse API 的開發人員指南

使用 Converse API

若要使用 Converse API，您可以呼叫 Converse 或 ConverseStream 操作，將訊息傳送到模型。若要呼叫 Converse，您需要 bedrock:InvokeModel 操作的許可。若要呼叫 ConverseStream，您需要 bedrock:InvokeModelWithResponseStream 操作的許可。

請求

使用 Amazon Bedrock 執行時期端點提出 Converse 請求時，您可以包含下列欄位：

modelId：標頭中的必要參數，可讓您指定用於推論的資源。
下列欄位可讓您自訂提示：
- 訊息：用來指定提示的內容和角色。
- 系統：用來指定系統提示，以定義模型的指示或內容。
- inferenceConfig：用來指定所有模型通用的推論參數。影響回應產生的推論參數。
- additionalModelRequestFields：用來指定與您執行推論所用之模型所特有的推論參數。
- promptVariables：(如果您使用提示管理中的提示) 使用此欄位來定義提示中要填入的變數，以及要填入這些變數的值。
下列欄位可讓您自訂回應的傳回方式：
- guardrailConfig：使用此欄位來包含要套用至整個提示的防護機制。
- toolConfig：使用此欄位來包含工具，以協助模型產生回應。
- additionalModelResponseFieldPaths：使用此欄位指定要作為 JSON 指標物件傳回的欄位。
- serviceTier – 使用此欄位來指定特定請求的服務層
requestMetadata：使用此欄位來包含可在使用調用日誌時篩選的中繼資料。

注意

當您搭配 Converse 或 ConverseStream 使用提示管理提示時，適用下列限制：

您無法包含 additionalModelRequestFields、inferenceConfig、system 或 toolConfig 欄位。
如果您包含 messages 欄位，會將訊息附加在提示中定義的訊息之後。
如果您包含 guardrailConfig 欄位，則防護機制會套用至整個提示。如果您在 ContentBlock 欄位中包含 guardContent 區塊，防護機制只會套用至那些區塊。

展開區段以進一步了解 Converse 請求內文中的欄位：

messages

messages 欄位是 Message 物件的陣列，每個項目都會定義使用者與模型之間的訊息。Message 物件包含下列欄位：

角色：定義訊息是來自 user (傳送至模型的提示) 還是 assistant (模型回應)。
內容：在提示中定義內容。

注意
Amazon Bedrock 不會存放您作為內容提供的任何文字、影像或文件。資料僅用於產生回應。

您可以在後續 Converse 請求中包含對話中的所有訊息，並使用 role 欄位來指定訊息是來自使用者或模型，以維護對話內容。

content 欄位會對應至 ContentBlock 物件的陣列。在每個 ContentBlock 中，您可以指定下列其中一個欄位（若要查看哪些模型支援哪些區塊，請參閱模型一目了然)：

text

text 欄位會對應至指定提示的字串。系統會將 text 欄位與其他在相同 ContentBlock 中指定的欄位一起解譯。

以下顯示 Message 物件，其 content 陣列僅包含文字 ContentBlock：


{
    "role": "user",
    "content": [
        {
            "text": "string"
        }
    ]
}

image

image 欄位會對應至 ImageBlock。傳遞 bytes 欄位中影像的原始位元組 (以 base64 編碼)。如果您使用 AWS SDK，則不需要對 base64 中的位元組進行編碼。

如果您排除 text 欄位，則模型會描述影像。

以下顯示範例 Message 物件，其 content 陣列僅包含影像 ContentBlock：


{
    "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。如果您包含 DocumentBlock，請檢查請求是否符合下列限制：

在 Message 物件的 content 欄位中，您還必須包含 text 欄位，其中包含與文件相關的提示。
傳遞 bytes 欄位中文件的原始位元組 (以 base64 編碼)。如果您使用 AWS SDK，則不需要對 base64 中的文件位元組進行編碼。
該 name 欄位可以包含以下任何字元：
- 英數字元
- 空格字元 (一列中不可超過一個)
- 連字號
- 括號
- 方括號
注意
name 欄位容易受到提示注入的影響，因為模型可能會不小心將其解譯為指示。因此，我們建議您指定中性名稱。

使用文件時，您可以啟用 citations 標籤，這會在 API 呼叫的回應中提供文件特定的引文。如需詳細資訊，請參閱 DocumentBlock API。

以下顯示範例 Message 物件，其 content 陣列僅包含文件 ContentBlock 和必要的隨附文字 ContentBlock。


{
    "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 物件。傳遞 bytes 欄位中的原始位元組 (以 base64 編碼)。如果您使用 AWS SDK，則不需要對 base64 中的位元組進行編碼。

如果您未包含 text 欄位，模型會描述影片。

以下顯示範例 Message 物件，其 content 陣列僅包含影片 ContentBlock。


{
    "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 儲存貯體的存取權。

cachePoint

您可以使用 cachePoint 欄位來使用提示快取，將快取檢查點新增為訊息中的區塊，以及隨附的提示。提示快取是一項功能，可讓您開始快取對話的內容，以節省成本和減少延遲。如需詳細資訊，請參閱提示快取可加快模型推論速度。

以下顯示範例 Message 物件，其 content 陣列包含文件 ContentBlock 和必要的隨附文字 ContentBlock，以及同時將文件和文字內容新增至快取的 cachePoint。


{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

guardContent

guardContent 欄位會對應至 GuardrailConverseContentBlock 物件。您可以使用此欄位，將要由 guardrailConfig 欄位中定義的防護機制評估的輸入設為目標。如果您未指定此欄位，防護機制會評估請求內文中的所有訊息。您可以在 GuardBlock 中傳遞下列類型的內容：

文字：以下顯示範例 Message 物件，其 content 陣列僅包含文字 GuardrailConverseContentBlock：


{
    "role": "user",
    "content": [
        {
            "text": "Tell me what stocks to buy.",
            "qualifiers": [
                "guard_content"
            ]
        }
    ]
}

您可以定義要評估的文字，並包含要用於