As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Inferência usando a API Converse
A API Converse está disponível somente no `bedrock-runtime` endpoint.
É possível usar a API Converse do Amazon Bedrock para criar aplicações conversacionais que enviam e recebem mensagens de e para um modelo do Amazon Bedrock. Por exemplo, é possível criar um chatbot que mantenha uma conversa por muitos turnos e use uma persona ou uma personalização de tom exclusiva de acordo com suas necessidades, como um útil assistente de suporte técnico.
Para usar a Converse API, você usa as operações [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) ou [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)(para streaming de respostas) para enviar mensagens para um modelo. É possível usar as operações de inferência de base existentes ([InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)ou [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)) para aplicativos de conversação. No entanto, é recomendável usar a API Converse, pois ela é uma API consistente, que funciona com todos os modelos do Amazon Bedrock que permitem mensagens. Isso significa que é possível escrever código uma vez e usá-lo com modelos diferentes. Caso um modelo tenha parâmetros de inferência exclusivos, a API Converse também permite que você transmita esses parâmetros exclusivos em uma estrutura específica do modelo.
É possível usar a API Converse para implementar o [uso de ferramentas](tool-use.md) e [barreiras de proteção](guardrails-use-converse-api.md) em suas aplicações.
**nota**
Com os modelos da Mistral AI e da Meta, a API Converse incorpora a entrada em um prompt específico do modelo que permite conversas.
As restrições se aplicam às seguintes operações: `InvokeModel` `InvokeModelWithResponseStream``Converse`,, `ConverseStream` e. Consulte as [restrições da API](inference-api-restrictions.md) para obter detalhes.
Para obter exemplos de código, consulte os seguintes tópicos:
+ Exemplos do Python para este tópico: [Converse Exemplos de APIExemplos da API Converse (movidos)](conversation-inference-examples.md)
+ Várias linguagens e modelos: [Exemplos de código para o Amazon Bedrock Runtime usando AWS SDKs](service_code_examples_bedrock-runtime.md)
+ Tutorial de Java: [A Java developer's guide to Bedrock's new Converse API](https://community.aws/content/2hUiEkO83hpoGF5nm3FWrdfYvPt/amazon-bedrock-converse-api-java-developer-guide)
+ JavaScript tutorial — [Um guia para desenvolvedores da nova Converse API da Bedrock](https://community.aws/content/2dtauBCeDa703x7fDS9Q30MJoBA/amazon-bedrock-converse-api-developer-guide)
## Usar o Converse solicitações de
Para usar a API Converse, você chama as operações `ConverseStream` ou `Converse` para enviar mensagens a um modelo. Para chamar `Converse`, é necessário ter a permissão para a operação `bedrock:InvokeModel`. Para chamar `ConverseStream`, é necessário ter a permissão para a operação `bedrock:InvokeModelWithResponseStream`.
### Solicitação
Ao fazer uma solicitação [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) com um [endpoint de runtime do Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt), você pode incluir os seguintes campos:
+ **modelId**: um parâmetro obrigatório no cabeçalho que permite especificar o recurso a ser usado para inferência.
+ Os seguintes campos permitem que você personalize o prompt:
+ **messages**: use para especificar o conteúdo e a função dos prompts.
+ **system**: use para especificar prompts do sistema, que definem instruções ou contexto para o modelo.
+ **inferenceConfig**: use para especificar parâmetros de inferência que são comuns a todos os modelos. Os parâmetro de inferência influenciam a geração da resposta.
+ **adicional ModelRequestFields** — Use para especificar parâmetros de inferência específicos do modelo com o qual você executa a inferência.
+ **promptVariables**: (se você usar um prompt do Gerenciamento de Prompts) use esse campo para definir as variáveis no prompt a serem preenchidas e os valores com os quais preenchê-las.
+ Os campos a seguir permitem que você personalize como a resposta é exibida:
+ **guardrailConfig**: use esse campo para incluir uma barreira de proteção a ser aplicada a todo o prompt.
+ **toolConfig**: use esse campo para incluir uma ferramenta para ajudar um modelo a gerar respostas.
+ **adicional ModelResponseFieldPaths** — Use esse campo para especificar campos a serem retornados como um objeto ponteiro JSON.
+ **ServiceTier** — Use esse campo para especificar o nível de serviço para uma solicitação específica.
+ **requestMetadata**: use esse campo para incluir metadados que podem ser filtrados ao usar logs de invocação.
**nota**
As seguintes restrições se aplicam quando você usa um prompt do Gerenciamento de Prompts com `Converse` ou `ConverseStream`:
Não é possível incluir os campos `additionalModelRequestFields`, `inferenceConfig`, `system` ou `toolConfig`.
Se você incluir o campo `messages`, as mensagens serão anexadas após as mensagens definidas no prompt.
Se você incluir o campo `guardrailConfig`, a barreira de proteção será aplicada a todo o prompt. Se você incluir `guardContent` blocos no [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)campo, a grade de proteção só será aplicada a esses blocos.
Expanda uma seção para saber mais sobre um campo no corpo da solicitação `Converse`:
#### mensagens
O campo `messages` é uma matriz de objetos [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) em que cada um define uma mensagem entre o usuário e o modelo. Um objeto `Message` contém os seguintes campos:
+ **role**: define se a mensagem é de `user` (o prompt enviado ao modelo) ou de `assistant` (a resposta do modelo).
+ **content**: define o conteúdo no prompt.
**nota**
O Amazon Bedrock não armazena nenhum texto, imagem ou documento que você forneça como conteúdo. Os dados são usados somente para gerar a resposta.
É possível manter o contexto da conversa incluindo todas as mensagens na conversa em solicitações `Converse` subsequentes e usando o campo `role` para especificar se a mensagem é do usuário ou do modelo.
O `content` campo é mapeado para uma matriz de [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)objetos. Em cada um [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html), você pode especificar um dos seguintes campos (para ver quais modelos suportam quais blocos, consulte [os modelos em um piscar](model-cards.md) de olhos):
------
#### [ text ]
O campo `text` é associado a uma string que especifica o prompt. O `text` campo é interpretado junto com outros campos especificados no mesmo [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html).
O seguinte mostra um objeto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) com uma `content` matriz contendo somente um texto [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html):
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
}
]
}
```
------
#### [ image ]
O `image` campo é mapeado para um [ImageBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ImageBlock.html). Passe os bytes brutos, codificados em base64, para uma imagem no campo `bytes`. Se você usa um AWS SDK, não precisa codificar os bytes em base64.
Se você excluir o campo `text`, o modelo descreverá a imagem.
Veja a seguir um exemplo de objeto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) com uma `content` matriz contendo somente uma imagem [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html):
```
{
"role": "user",
"content": [
{
"image": {
"format": "png",
"source": {
"bytes": "{{image in bytes}}"
}
}
}
]
}
```
Também é possível especificar um URI do Amazon S3 em vez de transmitir os bytes diretamente no corpo da solicitação. O exemplo a seguir mostra um objeto `Message` de amostra com uma matriz de conteúdo contendo a fonte transmitida por meio de um URI do Amazon S3.
```
{
"role": "user",
"content": [
{
"image": {
"format": "png",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myImage",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
------
#### [ document ]
O `document` campo é mapeado para um [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html). Se você incluir um `DocumentBlock`, verifique se a solicitação está em conformidade com as seguintes restrições:
+ No campo `content` do objeto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html), inclua também um campo `text` com um prompt relacionado ao documento.
+ Passe os bytes brutos, codificados em base64, para o documento no campo `bytes`. Se usar um SDK da AWS , não será necessário codificar os bytes do documento em base64.
+ O campo `name` pode conter somente os seguintes caracteres:
+ Caracteres alfanuméricos
+ Caracteres de espaço em branco (não mais do que um em uma linha)
+ Hifens
+ Parênteses
+ Colchetes
**nota**
O campo `name` é vulnerável a injeções de prompt, porque o modelo pode interpretá-lo como instruções de forma inadvertida. Por isso, é recomendável especificar um nome neutro.
Ao usar um documento, você pode habilitar a tag `citations`, que fornecerá citações específicas do documento na resposta da chamada de API. Consulte a [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html)API para obter mais detalhes.
Veja a seguir um exemplo de objeto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) com uma `content` matriz contendo somente um documento [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)e um texto [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)de acompanhamento obrigatório.
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"document": {
"format": "pdf",
"name": "MyDocument",
"source": {
"bytes": "{{document in bytes}}"
}
}
}
]
}
```
Também é possível especificar um URI do Amazon S3 em vez de transmitir os bytes diretamente no corpo da solicitação. O exemplo a seguir mostra um objeto `Message` de amostra com uma matriz de conteúdo contendo a fonte transmitida por meio de um URI do Amazon S3.
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"document": {
"format": "pdf",
"name": "MyDocument",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myDocument",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
------
#### [ video ]
O `video` campo é mapeado para um [VideoBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_VideoBlock.html)objeto. Transmita os bytes brutos, codificados em base64, no campo `bytes`. Se você usa o AWS SDK, não precisa codificar os bytes em base64.
Se não incluir o campo `text`, o modelo descreverá o vídeo.
Veja a seguir um exemplo de objeto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) com uma `content` matriz contendo somente um vídeo [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html).
```
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"bytes": "{{video in bytes}}"
}
}
}
]
}
```
Também é possível especificar um URI do Amazon S3 em vez de transmitir os bytes diretamente no corpo da solicitação. O exemplo a seguir mostra um objeto `Message` de amostra com uma matriz de conteúdo contendo a fonte transmitida por meio de um URI do Amazon S3.
```
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myVideo",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
**nota**
O perfil assumido deve ter a permissão `s3:GetObject` para o URI do Amazon S3. O campo `bucketOwner` é opcional, mas deve ser especificado se a conta que faz a solicitação não for proprietária do bucket em que o URI do Amazon S3 foi encontrado. Para obter mais informações, consulte [Configurar acesso para buckets do Amazon S3](s3-bucket-access.md).
------
#### [ cachePoint ]
Você pode adicionar pontos de verificação de cache como um bloco em uma mensagem junto com uma solicitação anexa usando `cachePoint` campos para usar o cache de solicitações. O armazenamento em cache de prompts é um recurso que permite que você comece a armazenar em cache o contexto das conversas para reduzir os custos e a latência. Para obter mais informações, consulte [Armazenamento em cache de prompts para agilizar a inferência do modelo](prompt-caching.md).
Veja a seguir um exemplo de objeto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) com uma `content` matriz contendo um documento [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)e um texto de acompanhamento obrigatório [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html), bem como um **CachePoint** que adiciona o conteúdo do documento e do texto ao cache.
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"document": {
"format": "pdf",
"name": "string",
"source": {
"bytes": "{{document in bytes}}"
}
}
},
{
"cachePoint": {
"type": "default"
}
}
]
}
```
------
#### [ guardContent ]
O `guardContent` campo é mapeado para um [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)objeto. Você pode usar esse campo para direcionar uma entrada a ser avaliada pela barreira de proteção definida no campo `guardrailConfig`. Se você não especificar esse campo, a barreira de proteção avaliará todas as mensagens no corpo da solicitação. É possível transmitir os seguintes tipos de conteúdo em um `GuardBlock`:
+ **texto** — O seguinte mostra um exemplo de objeto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) com uma `content` matriz contendo somente um texto [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html):
```
{
"role": "user",
"content": [
{
"text": "Tell me what stocks to buy.",
"qualifiers": [
"guard_content"
]
}
]
}
```
Você define o texto a ser avaliado e inclui quaisquer qualificadores a serem usados como [base contextual](guardrails-contextual-grounding-check.md).
+ **imagem** — O seguinte mostra um objeto [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) com uma `content` matriz contendo somente uma imagem [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html):
```
{
"role": "user",
"content": [
{
"format": "png",
"source": {
"bytes": "{{image in bytes}}"
}
}
]
}
```
Você especifica o formato da imagem e define a imagem em bytes.
Para ter mais informações sobre como usar barreiras de proteção, consulte [Detectar e filtrar conteúdo nocivo usando as Barreiras de Proteção do Amazon Bedrock](guardrails.md).
------
#### [ reasoningContent ]
O `reasoningContent` campo mapeia para um [ReasoningContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ReasoningContentBlock.html). Esse bloco contém conteúdo sobre o raciocínio que foi realizado pelo modelo para gerar a resposta no anexo `ContentBlock`.
O exemplo a seguir mostra um objeto `Message` com uma matriz `content` que contém somente um `ReasoningContentBlock` e um texto `ContentBlock` que o acompanha.
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"reasoningContent": {
"reasoningText": {
"text": "{{string}}",
"signature": "{{string}}"
}
"redactedContent": "{{base64-encoded binary data object}}"
}
}
]
}
```
O `ReasoningContentBlock` contém o raciocínio usado para gerar o conteúdo anexo no campo `reasoningText`, além de qualquer conteúdo no raciocínio que tenha sido criptografado pelo fornecedor do modelo por motivos de confiança e segurança no campo `redactedContent`.
No campo `reasoningText`, os campos `text` descrevem o raciocínio. O campo `signature`, que é um hash de todas as mensagens da conversa, é uma proteção contra adulteração do raciocínio usado pelo modelo. Você deve incluir a assinatura e todas as mensagens anteriores nas solicitações `Converse` subsequentes. Se alguma das mensagens for alterada, a resposta gerará um erro.
------
#### [ toolUse ]
Contém informações sobre uma ferramenta para o modelo usar. Para obter mais informações, consulte [Use uma ferramenta para concluir uma resposta do modelo do Amazon Bedrock](tool-use.md).
------
#### [ toolResult ]
Contém informações sobre o resultado do modelo usando uma ferramenta. Para obter mais informações, consulte [Use uma ferramenta para concluir uma resposta do modelo do Amazon Bedrock](tool-use.md).
------
No exemplo de `messages` a seguir, o usuário solicita uma lista de três músicas pop e o modelo gera uma lista de músicas.
```
[
{
"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"
}
]
}
]
```
#### operacional
Um prompt do sistema é um tipo de prompt que fornece instruções ou contexto ao modelo sobre a tarefa que ele deve executar ou a personalidade que ele deve adotar durante a conversa. Você pode especificar uma lista de solicitações do sistema para a solicitação no campo `system` ([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)), conforme mostrado no exemplo a seguir.
```
[
{
"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. "
}
]
```
#### inferenceConfig
A Converse API é compatível com um conjunto básico de parâmetros de inferência que você define no `inferenceConfig` campo ([InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InferenceConfiguration.html)). O conjunto básico de parâmetros de inferência é:
+ **maxTokens**: o número máximo de tokens a serem permitidos na resposta gerada.
+ **stopSequences**: uma lista de sequências de parada. Uma sequência de parada é uma sequência de caracteres que faz com que o modelo interrompa a geração da resposta.
+ **temperature**: a probabilidade do modelo selecionar opções de maior probabilidade ao gerar uma resposta.
+ **topP**: a porcentagem de candidatos mais prováveis que o modelo considera para o próximo token.
Para obter mais informações, consulte [Geração de resposta de influência com parâmetros de inferência](inference-parameters.md).
O exemplo de JSON a seguir define o parâmetro de inferência `temperature`.
```
{"temperature": 0.5}
```
#### adicional ModelRequestFields
Se o modelo que você está usando tiver parâmetros de inferência adicionais, será possível definir esses parâmetros especificando-os como JSON no campo `additionalModelRequestFields`. O exemplo de JSON a seguir mostra como definir `top_k`, que está disponível em modelos Claude da Anthropic, mas não é um parâmetro básico de inferência na API de mensagens.
```
{"top_k": 200}
```
#### promptVariables
Se você especificar um prompt do [Gerenciamento de Prompts](prompt-management.md) no `modelId` como recurso para executar a inferência, use esse campo para preencher as variáveis do prompt com valores reais. O campo `promptVariables` está associado a um objeto JSON com chaves que correspondem às variáveis definidas nos prompts e aos valores pelos quais substituir as variáveis.
Por exemplo, vamos supor que você tenha um prompt que diz **Make me a {{{{genre}}}} playlist consisting of the following number of songs: {{{{number}}}}.** O ID do prompt é `PROMPT12345` e a versão é `1`. Você pode enviar a seguinte solicitação `Converse` para substituir as variáveis:
```
POST /model/arn:aws:bedrock:us-east-1:111122223333:prompt/PROMPT12345:1/converse HTTP/1.1
Content-type: application/json
{
"promptVariables": {
"genre": {
"text": "pop"
},
"number": {
"text": "3"
}
}
}
```
#### guardrailConfig
É possível aplicar uma barreira de proteção criada com as [Barreiras de Proteção do Amazon Bedrock](guardrails.md) incluindo esse campo. Para aplicar a grade de proteção a uma mensagem específica na conversa, inclua a mensagem em um. [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) Se você não incluir nenhum `GuardrailConverseContentBlock` no corpo da solicitação, a barreira de proteção será aplicada a todas as mensagens no campo `messages`. Para ver um exemplo, consulte [Inclua uma grade de proteção com o Converse solicitações de](guardrails-use-converse-api.md).
#### toolConfig
Esse campo permite definir uma ferramenta para o modelo usar para ajudar a gerar uma resposta. Para obter mais informações, consulte [Use uma ferramenta para concluir uma resposta do modelo do Amazon Bedrock](tool-use.md).
#### adicional ModelResponseFieldPaths
É possível especificar os caminhos para os parâmetros adicionais do modelo no campo `additionalModelResponseFieldPaths`, conforme mostrado no exemplo a seguir.
```
[ "/stop_sequence" ]
```
A API mostra os campos adicionais que você solicita no campo `additionalModelResponseFields`.
#### requestMetadata
O `requestMetadata` campo mapeia para um objeto JSON de tags de valor-chave que são registradas com a solicitação nos registros de invocação do modelo. Você pode usar metadados de solicitação para filtrar e agregar registros por equipe, aplicativo, ambiente ou qualquer outra dimensão que varie por chamada.
O mesmo recurso está disponível no cabeçalho `X-Amzn-Bedrock-Request-Metadata` HTTP [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)e [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)por meio dele. Para obter detalhes sobre APIs compatíveis, limites e como os metadados da solicitação aparecem nos registros de invocação, consulte. [Per-request marcação de metadados](cost-mgmt-request-metadata.md)
#### Nível de serviço
Esse campo está associado a um objeto JSON. Você pode especificar o nível de serviço para uma solicitação específica.
O exemplo a seguir mostra a `serviceTier` estrutura:
```
"serviceTier": {
"type": "reserved" | "priority" | "default" | "flex"
}
```
Para obter informações detalhadas sobre níveis de serviço, incluindo características de preço e desempenho, consulte[Níveis de serviço para otimizar o desempenho e o custo](service-tiers-inference.md).
Opcionalmente, também é possível adicionar pontos de verificação de cache aos campos `system` ou `tools` para usar o armazenamento em cache de prompts, dependendo do modelo usado. Para obter mais informações, consulte [Armazenamento em cache de prompts para agilizar a inferência do modelo](prompt-caching.md).
### Resposta
A resposta que você recebe da API Converse depende de qual operação você chama, `Converse` ou `ConverseStream`.
#### Resposta de Converse
Na resposta de`Converse`, o `output` campo ([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)) contém a mensagem ([Mensagem](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html)) que o modelo gera. O conteúdo da mensagem está no campo `content` ([ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)) e a função (`user`ou`assistant`) à qual a mensagem corresponde está no `role` campo.
Se você usou o [armazenamento em cache de prompts](prompt-caching.md), no campo de uso, `cacheReadInputTokens` e `cacheWriteInputTokens` informam o total de tokens lidos do cache e gravados no cache, respectivamente.
Se você usou [camadas de serviço](#inference-service-tiers), no campo de resposta, `service tier` informaria qual camada de serviço foi usada para a solicitação.
O `metrics` campo ([ConverseMetrics](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseMetrics.html)) inclui métricas para a chamada. Para determinar porque o modelo parou de gerar conteúdo, verifique o campo `stopReason`. Você pode obter informações sobre os tokens passados para o modelo na solicitação e os tokens gerados na resposta, verificando o `usage` campo ([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html)). Se você tiver especificado campos de resposta adicionais na solicitação, a API os retornará como JSON no campo `additionalModelResponseFields`.
O exemplo a seguir mostra a resposta de `Converse` quando você passa o prompt discutido em [Solicitação](#conversation-inference-call-request).
```
{
"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 resposta
Se você chamar `ConverseStream` para transmitir a resposta de um modelo, o fluxo será retornado no campo de resposta `stream`. O fluxo emite os eventos abaixo na seguinte ordem:
1. `messageStart`([MessageStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStartEvent.html)). O evento inicial de uma mensagem. Inclui a função da mensagem.
1. `contentBlockStart`([ContentBlockStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStartEvent.html)). Um evento de início do bloco de conteúdo. Somente para uso de ferramentas.
1. `contentBlockDelta`([ContentBlockDeltaEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockDeltaEvent.html)). Um evento delta do bloco de conteúdo. Inclui um destes itens:
+ `text`: o texto parcial que o modelo gera.
+ `reasoningContent`: o raciocínio parcial realizado pelo modelo para gerar a resposta. Você deve enviar a `signature` exibida, além de todas as mensagens anteriores nas solicitações `Converse` subsequentes. Se alguma das mensagens for alterada, a resposta gerará um erro.
+ `toolUse`: o objeto JSON de entrada parcial para uso da ferramenta.
1. `contentBlockStop`([ContentBlockStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStopEvent.html)). Um evento de interrupção do bloqueio de conteúdo.
1. `messageStop`([MessageStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStopEvent.html)). O evento de parada da mensagem. Inclui o motivo pelo qual o modelo parou de gerar saída.
1. `metadata`([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)). Metadados da solicitação. Os metadados incluem o uso do token em `usage` ([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html)) e métricas para a chamada em `metrics` ([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)).
ConverseStream transmite um bloco de conteúdo completo como um `ContentBlockStartEvent` evento, um ou mais `ContentBlockDeltaEvent` eventos e um `ContentBlockStopEvent` evento. Use o campo `contentBlockIndex` como um índice para correlacionar os eventos que compõem um bloco de conteúdo.
O exemplo a seguir é a resposta parcial de `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}}}
```
## Converse Exemplos de API
Os exemplos a seguir mostram como usar as operações `Converse` e `ConverseStream`.
------
#### [ Text ]
Este exemplo mostra como chamar a operação `Converse` com o modelo *Claude 3 Sonnet da Anthropic*. O exemplo mostra como enviar o texto de entrada, os parâmetros de inferência e os parâmetros adicionais exclusivos do modelo. O código inicia uma conversa solicitando que o modelo crie uma lista de músicas. E continua a conversa solicitando que as músicas sejam de artistas do Reino Unido.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use the Converse API with Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
system_prompts,
messages):
"""
Sends messages to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
system_prompts (JSON) : The system prompts for the model to use.
messages (JSON) : The messages to send to the model.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Inference parameters to use.
temperature = 0.5
top_k = 200
# Base inference parameters to use.
inference_config = {"temperature": temperature}
# Additional inference parameters to use.
additional_model_fields = {"top_k": top_k}
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages,
system=system_prompts,
inferenceConfig=inference_config,
additionalModelRequestFields=additional_model_fields
)
# Log token usage.
token_usage = response['usage']
logger.info("Input tokens: %s", token_usage['inputTokens'])
logger.info("Output tokens: %s", token_usage['outputTokens'])
logger.info("Total tokens: %s", token_usage['totalTokens'])
logger.info("Stop reason: %s", response['stopReason'])
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
# Setup the system prompts and messages to send to the model.
system_prompts = [{"text": "You are an app that creates playlists for a radio station that plays rock and pop music. Only return song names and the artist."}]
message_1 = {
"role": "user",
"content": [{"text": "Create a list of 3 pop songs."}]
}
message_2 = {
"role": "user",
"content": [{"text": "Make sure the songs are by artists from the United Kingdom."}]
}
messages = []
try:
bedrock_client = boto3.client(service_name='bedrock-runtime')
# Start the conversation with the 1st message.
messages.append(message_1)
response = generate_conversation(
bedrock_client, model_id, system_prompts, messages)
# Add the response message to the conversation.
output_message = response['output']['message']
messages.append(output_message)
# Continue the conversation with the 2nd message.
messages.append(message_2)
response = generate_conversation(
bedrock_client, model_id, system_prompts, messages)
output_message = response['output']['message']
messages.append(output_message)
# Show the complete conversation.
for message in messages:
print(f"Role: {message['role']}")
for content in message['content']:
print(f"Text: {content['text']}")
print()
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Image ]
Este exemplo mostra como enviar uma imagem como parte de uma mensagem e solicita que o modelo descreva a imagem. O exemplo usa a operação `Converse` e o modelo *Claude 3 Sonnet da Anthropic*.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send an image with the Converse API with an accompanying text prompt to Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
input_text,
input_image):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The text prompt accompanying the image.
input_image : The path to the input image.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Get image extension and read in image as bytes
image_ext = input_image.split(".")[-1]
with open(input_image, "rb") as f:
image = f.read()
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"image": {
"format": image_ext,
"source": {
"bytes": image
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
input_text = "What's in this image?"
input_image = "path/to/image"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_conversation(
bedrock_client, model_id, input_text, input_image)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Document ]
Este exemplo mostra como enviar um documento como parte de uma mensagem e solicita que o modelo descreva o documento. O exemplo usa a operação `Converse` e o modelo *Claude 3 Sonnet da Anthropic*.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send an document as part of a message to Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_message(bedrock_client,
model_id,
input_text,
input_document_path):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The input message.
input_document_path : The path to the input document.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Get format from path and read the path
input_document_format = input_document_path.split(".")[-1]
with open(input_document_path, 'rb') as input_document_file:
input_document = input_document_file.read()
# Message to send.
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"document": {
"name": "MyDocument",
"format": input_document_format,
"source": {
"bytes": input_document
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
input_text = "What's in this document?"
input_document_path = "path/to/document"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_message(
bedrock_client, model_id, input_text, input_document_path)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Streaming ]
Este exemplo mostra como chamar a operação `ConverseStream` com o modelo *Claude 3 Sonnet da Anthropic*. O exemplo mostra como enviar o texto de entrada, os parâmetros de inferência e os parâmetros adicionais exclusivos do modelo.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use the Converse API to stream a response from Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def stream_conversation(bedrock_client,
model_id,
messages,
system_prompts,
inference_config,
additional_model_fields):
"""
Sends messages to a model and streams the response.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send.
system_prompts (JSON) : The system prompts to send.
inference_config (JSON) : The inference configuration to use.
additional_model_fields (JSON) : Additional model fields to use.
Returns:
Nothing.
"""
logger.info("Streaming messages with model %s", model_id)
response = bedrock_client.converse_stream(
modelId=model_id,
messages=messages,
system=system_prompts,
inferenceConfig=inference_config,
additionalModelRequestFields=additional_model_fields
)
stream = response.get('stream')
if stream:
for event in stream:
if 'messageStart' in event:
print(f"\nRole: {event['messageStart']['role']}")
if 'contentBlockDelta' in event:
print(event['contentBlockDelta']['delta']['text'], end="")
if 'messageStop' in event:
print(f"\nStop reason: {event['messageStop']['stopReason']}")
if 'metadata' in event:
metadata = event['metadata']
if 'usage' in metadata:
print("\nToken usage")
print(f"Input tokens: {metadata['usage']['inputTokens']}")
print(
f":Output tokens: {metadata['usage']['outputTokens']}")
print(f":Total tokens: {metadata['usage']['totalTokens']}")
if 'metrics' in event['metadata']:
print(
f"Latency: {metadata['metrics']['latencyMs']} milliseconds")
def main():
"""
Entrypoint for streaming message API response example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
system_prompt = """You are an app that creates playlists for a radio station
that plays rock and pop music. Only return song names and the artist."""
# Message to send to the model.
input_text = "Create a list of 3 pop songs."
message = {
"role": "user",
"content": [{"text": input_text}]
}
messages = [message]
# System prompts.
system_prompts = [{"text" : system_prompt}]
# inference parameters to use.
temperature = 0.5
top_k = 200
# Base inference parameters.
inference_config = {
"temperature": temperature
}
# Additional model inference parameters.
additional_model_fields = {"top_k": top_k}
try:
bedrock_client = boto3.client(service_name='bedrock-runtime')
stream_conversation(bedrock_client, model_id, messages,
system_prompts, inference_config, additional_model_fields)
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
else:
print(
f"Finished streaming messages with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Video ]
Este exemplo mostra como enviar um vídeo como parte de uma mensagem e solicita que o modelo descreva o vídeo. O exemplo usa a operação `Converse` e o modelo Amazon Nova Pro.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send a video with the Converse API to Amazon Nova Pro (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
input_text,
input_video):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The input message.
input_video : The input video.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Message to send.
with open(input_video, "rb") as f:
video = f.read()
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"video": {
"format": 'mp4',
"source": {
"bytes": video
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Amazon Nova Pro example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "amazon.nova-pro-v1:0"
input_text = "What's in this video?"
input_video = "path/to/video"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_conversation(
bedrock_client, model_id, input_text, input_video)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
```
------