使用 Converse API - Amazon Bedrock
请求响应

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 Converse API

要再次使用 Converse API，您可以调用Converse或ConverseStream操作向模型发送消息。要调用 Converse，需具有 bedrock:InvokeModel 操作的权限。要调用 ConverseStream，需具有 bedrock:InvokeModelWithResponseStream 操作的权限。

请求

您可以通过设置 modelId 字段来指定要使用的模型。有关 Amazon Bedrock 支持的型号IDs列表，请参阅Amazon Bedrock 中支持的根基模型。

对话是用户与模型之间的一系列消息。您可以通过以用户（user 角色）的身份向模型发送消息来开始对话。然后，模型充当助理（assistant 角色），生成一个响应，并在消息中返回该响应。如果需要，您可以通过向模特发送更多用户角色消息来继续对话。要维护对话上下文，请务必在后续请求中包含您从模型收到的所有助理角色消息。

您在 messages 字段中提供要传递给模型的消息，该字段会映射到一个 Message 对象数组。每个 Message 都包含消息的内容以及该消息在对话中扮演的角色。

注意

Amazon Bedrock 不会存储您作为内容提供的任何文本、图像或文档。数据仅用于生成响应。使用时 Converse API，则必须使用大小小于 4.5 MB 的未压缩和解码文档。

您可以在字段中添加消息的内容，该content字段映射到ContentBlock对象数组。在每个字段ContentBlock中，您可以指定以下字段之一（要查看哪些模型支持哪些模式，请参阅支持的模型和模型功能）：

text

text 字段会映射到指定提示的字符串。该text字段与同一字段中指定的其他字段一起解释ContentBlock。

（可选）对于某些型号，您可以使用cachePoint字段添加缓存检查点以利用提示缓存。提示缓存功能使您能够开始缓存对话上下文，从而节省成本和延迟。有关更多信息，请参阅 提示缓存以加快模型推断速度。

注意

Amazon Bedrock 提示缓存目前仅适用于特定数量的客户。要了解有关参与预览版的更多信息，请参阅 Amazon Bedrock 提示缓存。

下面显示了一个 M essag e 对象，其content数组仅包含文本 ContentBlock：

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

下面显示了一个 M essag e 对象，其content数组包含一个文本ContentBlock和一个可选cachePoint字段。因此，文本中的内容ContentBlock被添加到缓存中。

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

该image字段映射到 ImageBlock. 为 bytes 字段中的图像传递以 base64 编码的原始字节。如果您使用 AWS SDK，则无需在 base64 中对字节进行编码。

如果您排除该text字段，则模型将描述图像。

（可选）对于某些型号，您可以使用cachePoint字段添加缓存检查点以利用提示缓存。提示缓存功能使您能够开始缓存对话上下文，从而节省成本和延迟。有关更多信息，请参阅 提示缓存以加快模型推断速度。

注意

Amazon Bedrock 提示缓存目前仅适用于特定数量的客户。要了解有关参与预览版的更多信息，请参阅 Amazon Bedrock 提示缓存。

下面显示了一个 M essag e 对象，其content数组仅包含图像 ContentBlock：

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

下面显示了一个 M essag e 对象，其content数组包含图像ContentBlock和可选cachePoint字段。因此，图像内容被添加到缓存中。

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

该document字段映射到 DocumentBlock. 如果包含 DocumentBlock，请检查您的请求是否符合以下限制：

  • 在 Message 对象的 content 字段中，还必须包括一个带有与文档相关的提示的 text 字段。

  • 为 bytes 字段中的文档传递以 base64 编码的原始字节。如果您使用 AWS SDK，则无需以 base64 对文档字节进行编码。

  • name 字段只能包含以下字符：

    • 字母数字字符

    • 空格字符（连续不得超过一个）

    • 连字符

    • 圆括号

    • 方括号

    注意

    name 字段容易受到提示注入的影响，因为模型可能会意外将其解释为指令。因此，我们建议您指定一个中性名称。

（可选）对于某些型号，您可以使用cachePoint字段添加缓存检查点以利用提示缓存。提示缓存功能使您能够开始缓存对话上下文，从而节省成本和延迟。有关更多信息，请参阅 提示缓存以加快模型推断速度。

注意

Amazon Bedrock 提示缓存目前仅适用于特定数量的客户。要了解有关参与预览版的更多信息，请参阅 Amazon Bedrock 提示缓存。

下面显示了一个 M essag e 对象，其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"
                }
            }
        }
    ]
}

下面显示了一个 Mess ag e 对象，该对象包含一个包含文档ContentBlock和必需的随附文本的content数组 ContentBlockcachePoint，以及一个将文档和文本内容都添加到缓存中的数组。

{
    "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字段映射到 aVideoBlock. 在bytes字段中传递以 base64 编码的原始字节。如果您使用 AWS SDK，则无需在 base64 中对字节进行编码。

如果您不包括该text字段，则模型将描述视频。

下面显示了一个 M essag e 对象，其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对象，其内容数组仅包含视频，其视频ContentBlock源通过 Amazon S3 传输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 – 向模型发送消息的人。

  • assistant – 向人工用户发送消息的模型。

注意

以下限制适用于 content 字段：

  • 您最多可以包含 20 个图像。每个图像的大小、高度和宽度必须分别不超过 3.75 MB、8000 像素和 8000 像素。

  • 您最多可以包含五个文档。每个文档的大小不得超过 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}

如果您使用的模型具有其他推理参数，则可以通过在additionalModelRequestFields字段JSON中指定这些参数来设置这些参数。以下示例JSON显示了如何设置top_k，可在中找到 Anthropic Claude 模型，但不是消息API中的基本推理参数。

{"top_k": 200}

您可以在 additionalModelResponseFieldPaths 字段中指定其他模型参数的路径，如以下示例所示。

[ "/stop_sequence" ]

API返回您在该字段中请求的其他字additionalModelResponseFields段。

响应

你从中得到的回应 Converse API取决于您调用的操作，Converse或ConverseStream。

Converse 响应

在来自的响应中Converse，output字段 (ConverseOutput) 包含模型生成的消息（消息）。消息内容位于 content (ContentBlock) 字段中，消息对应的角色（user或assistant）位于该role字段中。

如果您使用了提示缓存，则在 usage 字段中，cacheReadInputTokensCount分别cacheWriteInputTokensCount告诉您从缓存中读取和写入缓存的令牌总数。

字metrics段 (ConverseMetrics) 包含呼叫的指标。要确定模型停止生成内容的原因，请检查 stopReason 字段。通过选中usage字段 (TokenUsage)，您可以获取有关在请求中传递给模型的令牌以及响应中生成的令牌的信息。如果您在请求中指定了其他响应字段，则会像在additionalModelResponseFields字段JSON中一样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 响应字段中返回该流。流按以下顺序发出以下事件。

  1. messageStart(MessageStartEvent)。 消息的开始事件。包括消息的角色。

  2. contentBlockStart(ContentBlockStartEvent)。 内容区块启动事件。仅用于实现工具使用。

  3. contentBlockDelta(ContentBlockDeltaEvent)。 内容区块增量事件。包括模型生成的部分文本或用于实现工具使用的部分输入 JSON。

  4. contentBlockStop(ContentBlockStopEvent)。 内容屏蔽停止事件。

  5. messageStop(MessageStopEvent)。 消息的停止事件。包括模型停止生成输出的原因。

  6. metadata(ConverseStreamMetadataEvent)。 请求的元数据。元数据包括 usage (TokenUsage) 中的令牌使用情况和 metrics (ConverseStreamMetadataEvent) 中调用的指标。

ConverseStream 将完整的内容块作为ContentBlockStartEvent事件、一个或多个事件和一个ContentBlockDeltaEventContentBlockStopEvent事件进行流式传输。使用 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}}}