使用 Converse API

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

主題

請求
回應

請求

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

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

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

注意

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

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

text

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

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


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

image

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

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

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


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

document

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

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

以下顯示訊息物件，其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"
                }
            }
        }
    ]
}

中的其他欄位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. "
    }
]

推論參數

Converse API支援一組您在 inferenceConfig 欄位（InferenceConfiguration）中設定的推論參數。推論參數的基本集為：

maxTokens – 在產生的回應中允許的最大字符數量。
stopSequences – 停止序列的清單。停止序列是導致模型停止產生回應的字元序列。
溫度 – 在產生回應時，模型選擇較高機率選項的可能性。
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欄位中。

metrics 欄位（ConverseMetrics）包含呼叫的指標。若要判斷模型停止產生內容的原因，請檢查 stopReason 欄位。您可以透過檢查 usage 欄位（），取得傳遞給請求中模型的權杖，以及在回應中產生的權杖的相關資訊TokenUsage。如果您在請求中指定了其他回應欄位，會如 JSON additionalModelResponseFields 欄位一樣API傳回它們。

下列範例顯示當您傳遞中討論的提示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 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

支援的模型和模型功能

對話API範例