使用匡威 API

要使用 ConverseAPI，您可以调用Converse或ConverseStream操作向模型发送消息。要拨打电话Converse，您需要获得bedrock:InvokeModel操作许可。要拨打电话ConverseStream，您需要获得bedrock:InvokeModelWithResponseStream操作许可。

主题

请求
响应

请求

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

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

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

注意

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

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

text

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

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


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

image

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

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

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


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

document

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

在 Mess ag e 对象的content字段中，还必须包括一个带有与文档相关的提示的text字段。
为字段中的文档传递以 base64 编码的原始字节。bytes如果您使用 AWS SDK，则无需以 base64 对文档字节进行编码。
该name字段只能包含以下字符：
- 字母数字字符
- 空格字符（连续不超过一个）
- 连字符
- 圆括号
- 方括号
注意
该name字段容易受到即时注入的影响，因为模型可能会无意中将其解释为指令。因此，我们建议您指定一个中性名称。

下面显示了一个 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"
                }
            }
        }
    ]
}

中的其他字段ContentBlock仅供工具使用。

您可以在role字段中指定角色。该角色可以是以下角色之一：

user-向模型发送消息的人。
助手 — 向人类用户发送消息的模型。

注意

以下限制与该content领域有关：

您最多可以包含 20 张图片。每张图片的大小、高度和宽度必须分别不超过 3.75 MB、8,000 像素和 8,000 像素。
您最多可以包括五个文档。每个文档的大小不得超过 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}

如果您使用的模型具有其他推理参数，则可以通过在additionalModelRequestFields字段JSON中指定这些参数来设置这些参数。以下示例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)，您可以获取有关在请求中传递给模型的令牌以及响应中生成的令牌的信息。如果您在请求中指定了其他响应字段，则会像在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响应字段中返回该流。直播按以下顺序发出以下事件。

messageStart(MessageStartEvent)。消息的开始事件。包括消息的角色。
contentBlockStart(ContentBlockStartEvent)。内容区块启动事件。仅限工具使用。
contentBlockDelta(ContentBlockDeltaEvent)。内容区块增量事件。包括模型生成的部分文本或用于工具的部分输入 json。
contentBlockStop(ContentBlockStopEvent)。内容屏蔽停止事件。
messageStop(MessageStopEvent)。消息的停止事件。包括模型停止生成输出的原因。
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}}}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

支持的型号和型号功能

匡威示例 API