使用 Converse API

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

主題

請求
回應

請求

您可以透過設定 modelId 欄位來指定要使用的模型。如需 IDs Amazon Bedrock 支援的模型清單，請參閱 Amazon Bedrock 中支援的基礎模型。

對話是使用者與模型之間的一系列訊息。您可以透過以使用者 (使用者角色) 身分傳送訊息至模型來開始對話。模型做為助理 (輔助角色)，然後產生回應，並在訊息中傳回。如有需要，您可以傳送進一步的使用者角色訊息至模型，以繼續對話。若要維持對話內容，請務必在後續請求中包含從模型接收的任何助理角色訊息。

您可以在 messages 欄位中提供您要傳遞給模型的訊息，該模型會映射到訊息物件陣列。每個訊息都包含訊息的內容，以及訊息在對話中扮演的角色。

注意

Amazon Bedrock 不會儲存您作為內容提供的任何文字、影像或文件。資料僅用於產生回應。使用時 Converse API，您必須使用大小小於 4.5 MB 的未壓縮和解碼文件。

您可以在 content 欄位中新增訊息的內容，該欄位會映射到ContentBlock物件陣列。在每個中ContentBlock，您可以指定下列其中一個欄位（若要查看哪些模型支援哪些模態，請參閱支援的模型和模型功能)：

text

text 欄位會映射至指定提示的字串。text 欄位會與其他在相同中指定的欄位一起解譯ContentBlock。

（選用）對於某些模型，您可以使用cachePoint欄位來新增快取檢查點，以利用提示快取。提示快取是一項功能，可讓您開始快取對話內容，以節省成本和延遲。如需詳細資訊，請參閱提示快取可加快模型推論。

注意

Amazon Bedrock 提示快取目前僅適用於特定數量的客戶。若要進一步了解參與預覽，請參閱 Amazon Bedrock 提示快取。

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


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

以下顯示訊息物件，其中包含包含文字ContentBlock和選用cachePoint欄位的content陣列。因此，文字中的內容ContentBlock會新增至快取。


{
    "role": "user | assistant",
    "content": [
        {
            "text": "string"
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

image

image 欄位會映射到 ImageBlock。傳遞bytes欄位中影像的原始位元組，以 base64 編碼。如果您使用 AWS SDK，則不需要編碼 base64 中的位元組。

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

注意

Amazon Bedrock 提示快取目前僅適用於特定數量的客戶。若要進一步了解參與預覽，請參閱 Amazon Bedrock 提示快取。

以下顯示訊息物件，其content陣列僅包含映像 ContentBlock：


{
    "role": "user",
    "content": [
        {
            "image": {
                "format": "png | jpeg | gif | webp",
                "source": {
                    "bytes": "image in bytes"
                }
            }
        }
    ]
}

以下顯示訊息物件，其中包含包含映像ContentBlock和選用cachePoint欄位的content陣列。因此，映像內容會新增至快取。


{
    "role": "user",
    "content": [
        {
            "image": {
                "format": "png | jpeg | gif | webp",
                "source": {
                    "bytes": "image in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

document

document 欄位會映射到 DocumentBlock。如果您包含 DocumentBlock，請檢查您的請求是否符合下列限制：

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

注意

Amazon Bedrock 提示快取目前僅適用於特定數量的客戶。若要進一步了解參與預覽，請參閱 Amazon Bedrock 提示快取。

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


{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf | csv | doc | docx | xls | xlsx | html | txt | md",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        }
    ]
}

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


{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf | csv | doc | docx | xls | xlsx | html | txt | md",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

video

video 欄位會映射至 VideoBlock。傳遞 bytes 欄位中的原始位元組，以 base64 編碼。如果您使用 AWS SDK，則不需要對 base64 中的位元組進行編碼。

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

以下顯示訊息物件，其content陣列僅包含影片 ContentBlock。


{
    "role": "user",
    "content": [
        {
            "video": {
                "format": "mov | mkv | mp4 | webm | flv | mpeg | mpg | wmv | three_gp",
                "source": {
                    "bytes": "video in bytes"
                }
            }
        }
    ]
}

請注意，對於具有.3gp副檔名的檔案，格式必須指定為 three_gp。

您也可以透過 Amazon S3 傳遞影片，URI而不是直接在請求內文中傳遞位元組。以下顯示具有內容陣列的Message物件，僅包含視訊來源透過 Amazon S3 傳遞的ContentBlock視訊URI。


{
    "role": "user",
    "content": [
        {
            "video": {
                "format": "mov | mkv | mp4 | webm | flv | mpeg | mpg | wmv | three_gp",
                "source": {
                    "s3Location": {
                        "uri": "s3 uri",
                        "bucketOwner": "s3 uri bucket owner"
                    }
                }
            }
        }
    ]
}

s3Location 參數僅支援美國東部（維吉尼亞北部）區域。

注意

擔任的角色必須具有 Amazon S3 的s3:GetObject許可URI。bucketOwner 欄位是選用的，但如果提出請求的帳戶沒有 Amazon S3 URI所在的儲存貯體，則必須指定。

中的其他欄位ContentBlock僅供工具使用。

您可以在 role 欄位中指定角色。角色可以是下列其中一項：

user — 正在傳送訊息至模型的人。
助理 — 將訊息傳回給人工使用者的模型。

注意

下列限制與 content 欄位相關：

您最多可以包含 20 個影像。每個影像的大小、高度和寬度分別不得超過 3.75 MB、8，000 px 和 8，000 px。
您最多可以包含五個文件。每個文件的大小不得超過 4.5 MB。
如果 role是，您只能包含映像和文件user。

在下列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(SystemContentBlock) 欄位中指定請求的系統提示清單，如下列範例所示。


[
    {
        "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. "
    }
]

您也可以選擇將快取檢查點新增至 system或 tools 欄位，以使用提示快取，具體取決於您使用的模型。如需詳細資訊，請參閱提示快取可加快模型推論。

注意

Amazon Bedrock 提示快取目前僅適用於特定數量的客戶。若要進一步了解參與預覽，請參閱 Amazon Bedrock 提示快取。

推論參數

所以此 Converse API 支援您在 inferenceConfig 欄位 () 中設定的一組基本推論參數InferenceConfiguration。推論參數的基本集為：

maxTokens – 在產生的回應中允許的最大字符數量。
stopSequences – 停止序列的清單。停止序列是導致模型停止產生回應的字元序列。
temperature – 在產生回應時，模型選擇較高機率選項的可能性。
topP – 模型考慮用於下一個字符的最可能候選者的百分比。

如需詳細資訊，請參閱利用推論參數影響回應產生。

下列範例會JSON設定temperature推論參數。


{"temperature": 0.5}

如果您使用的模型有額外的推論參數，您可以透過JSON在 additionalModelRequestFields 欄位中指定這些參數來設定這些參數。下列範例JSON示範如何設定 top_k，其可在中使用 Anthropic Claude 模型，但不是訊息中的基本推論參數API。


{"top_k": 200}

您可以在 additionalModelResponseFieldPaths 欄位中指定其他模型參數的路徑，如下列範例所示。


[ "/stop_sequence" ]

會API傳回您在欄位中請求的其他additionalModelResponseFields欄位。

回應

您從取得的回應 Converse API 取決於您呼叫的操作，Converse或 ConverseStream。

對話回應

在來自的回應中Converse， output 欄位 (ConverseOutput) 包含模型產生的訊息 (訊息)。訊息內容位於 content(ContentBlock) 欄位中，而訊息對應的角色 (user 或 assistant) 位於 role欄位中。

如果您使用提示快取，請在使用欄位中cacheWriteInputTokensCount，cacheReadInputTokensCount告訴您分別從快取讀取並寫入快取的字符總數。

metrics 欄位 (ConverseMetrics) 包含呼叫的指標。若要判斷模型停止產生內容的原因，請檢查 stopReason 欄位。您可以檢查 usage 欄位 ()，取得在請求中傳遞給模型的字符，以及在回應中產生的字符的相關資訊TokenUsage。如果您在請求中指定了其他回應欄位，則會將其API傳回為 JSON 欄位中的 additionalModelResponseFields。

下列範例顯示當您傳遞中討論的提示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回應欄位中傳回串流。串流會依下列順序發出下列事件。

messageStart (MessageStartEvent)。訊息的啟動事件。包含訊息的角色。
contentBlockStart (ContentBlockStartEvent)。內容區塊啟動事件。僅限工具使用。
contentBlockDelta (ContentBlockDeltaEvent)。內容區塊差異事件。包括模型產生的部分文字或用於工具的部分輸入 json。
contentBlockStop (ContentBlockStopEvent)。內容區塊停止事件。
messageStop (MessageStopEvent)。訊息的停止事件。包括模型停止產生輸出的原因。
metadata (ConverseStreamMetadataEvent)。請求的中繼資料。中繼資料包含 usage(TokenUsage) 中的字符用量和 metrics() 中呼叫的指標ConverseStreamMetadataEvent。

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}}}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

支援的模型和模型功能

Converse API 範例