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á.
# Envie prompts e gere respostas com a inferência de modelo
Inferência se refere ao processo de gerar uma saída com base em uma entrada fornecida a um modelo.
O Amazon Bedrock oferece um conjunto de modelos de base que é possível usar para gerar resultados das modalidades a seguir. Para obter a compatibilidade com a modalidade por modelo de base, consulte [Modelos de base compatíveis no Amazon Bedrock](models-supported.md).
****
| Modalidade de saída | Description | Exemplo de casos de uso |
| --- | --- | --- |
| Texto | Fornecer entrada de texto e gerar vários tipos de texto | Bate-papo question-and-answering, brainstorming, resumo, geração de código, criação de tabelas, formatação de dados, reescrita |
| Imagem | Fornecer texto ou imagens de entrada e gerar ou modificar imagens | Geração de imagens, edição de imagens, variação de imagens |
| Vídeo | Fornecer textos ou imagens de referência e gerar um vídeo | Geração de vídeo, conversão de imagem em vídeo |
| Incorporações | Forneça texto, imagens ou texto e imagens e gere um vetor de valores numéricos que representem a entrada. O vetor de saída pode ser comparado a outros vetores de incorporação para determinar a similaridade semântica (para texto) ou visual (para imagens). | Pesquisa de texto e imagem, consulta, categorização, recomendações, personalização, [criação de base de conhecimento](knowledge-base.md) |
**Topics**
+ [Saiba mais sobre os casos de uso para diferentes métodos de inferência do modelo.](inference-methods.md)
+ [Como a inferência funciona no Amazon Bedrock](inference-how.md)
+ [Geração de resposta de influência com parâmetros de inferência](inference-parameters.md)
+ [Regiões e modelos compatíveis com execução de inferência do modelo](inference-supported.md)
+ [Pré-requisitos para executar a inferência do modelo](inference-prereq.md)
+ [Gerar respostas no console usando playgrounds](playgrounds.md)
+ [Melhorar as respostas do modelo com o raciocínio de modelo](inference-reasoning.md)
+ [Otimizar a inferência do modelo para latência](latency-optimized-inference.md)
+ [Gere respostas usando OpenAI APIs](bedrock-mantle.md)
+ [Enviar prompts e gerar respostas usando a API](inference-api.md)
+ [Obtenha resultados JSON validados de modelos](structured-output.md)
+ [Use uma ferramenta Computer Use para concluir uma resposta do modelo do Amazon Bedrock](computer-use.md)
# Saiba mais sobre os casos de uso para diferentes métodos de inferência do modelo.
É possível executar a inferência de modelos diretamente das seguintes maneiras:
****
| Método | Caso de uso |
| --- | --- |
| [Playgrounds do console do Amazon Bedrock](playgrounds.md) | Execute inferências em uma interface gráfica fácil de usar. Conveniente para exploração. |
| [Converse ou [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) | Implemente aplicações conversacionais com uma API unificada para entrada de modelo. |
| [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) | Envie um único prompt e gere uma resposta de forma síncrona. Útil para gerar respostas em tempo real ou para consultas de pesquisa. |
| [StartAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_StartAsyncInvoke.html) | Envie um único prompt e gere uma resposta de forma assíncrona. Útil para gerar respostas em grande escala. |
| [CreateModelInvocationJob](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_CreateModelInvocationJob.html) | Prepare um conjunto de dados de prompts e gere respostas em lote. |
| [API de respostas](https://platform.openai.com/docs/api-reference/responses) | Use a API de respostas para aplicativos modernos e agentes que exigem o uso de ferramentas integradas (pesquisa, interpretador de código), entradas multimodais e conversas com estado. |
| [Conclusões de bate-papo](https://platform.openai.com/docs/api-reference/chat) | Use a API Chat Completions para tarefas leves, sem estado e focadas em texto, nas quais você precisa de controle total sobre o gerenciamento do histórico de bate-papo e menor latência. |
Os seguintes recursos do Amazon Bedrock também usam a inferência de modelos como uma etapa em um fluxo de trabalho maior:
+ A [avaliação do modelo](evaluation.md) usa o processo de invocação do modelo para avaliar o desempenho de diferentes modelos após o envio de uma [CreateEvaluationJob](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_CreateEvaluationJob.html)solicitação.
+ As [bases de conhecimento](knowledge-base.md) usam a invocação do modelo ao usar a API [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html) para gerar uma resposta com base nos resultados recuperados de uma base de conhecimento.
+ Os [agentes](agents.md) usam a invocação do modelo para gerar respostas em vários estágios durante uma solicitação [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html).
+ Os [fluxos](flows.md) incluem recursos do Amazon Bedrock, como prompts, bases de conhecimento e agentes, que usam a invocação de modelo.
Depois de testar diferentes modelos básicos com diferentes prompts e parâmetros de inferência, você pode configurar seu aplicativo para chamá-los APIs com as especificações desejadas.
# Como a inferência funciona no Amazon Bedrock
Ao enviar uma entrada a um modelo, o modelo prediz uma provável sequência de tokens que se segue e exibe essa sequência como saída. O Amazon Bedrock oferece a capacidade de executar inferência com o modelo de base de sua escolha. Ao executar a inferência, você fornece as seguintes entradas:
+ **Prompt**: uma entrada fornecida ao modelo para que ele gere uma resposta. Para obter informações sobre como escrever prompts, consulte [Conceitos de engenharia de prompts](prompt-engineering-guidelines.md). Para obter informações sobre a proteção contra ataques de injeção de prompt, consulte [Segurança de injeção de prompt](prompt-injection.md).
+ **Modelo**: você faz solicitações a um modelo para executar a inferência em um prompt. O modelo escolhido também especifica um nível de throughput, que define o número e a taxa de tokens de entrada e saída que é possível processar. É possível fazer solicitações aos tipos de modelo a seguir:
+ **Modelo básico**: um modelo de base com o qual executar a inferência. As solicitações são enviadas a uma única região da AWS. Para obter IDs de modelo, consulte [Modelos de base compatíveis no Amazon Bedrock](models-supported.md). Para obter mais informações sobre os modelos de base que estão disponíveis no Amazon Bedrock, consulte [Informações sobre modelos de base do Amazon Bedrock](foundation-models-reference.md).
+ **Perfil de inferência**: um modelo de base com o qual executar a inferência. As solicitações são feitas ao modelo em várias regiões da AWS. Para obter IDs de perfil de inferência, consulte [Regiões e modelos que compatíveis com perfis de inferência](inference-profiles-support.md).
**nota**
Os modelos diferem com em disponibilidade de modelo de base e perfil de inferência por região e por método de API. Para ter mais informações, consulte [Modelos de base compatíveis no Amazon Bedrock](models-supported.md) e as páginas dos modelos individuais em [Informações sobre modelos de base](foundation-models-reference.md).
+ **Throughput provisionado**: um modelo de base para o qual você comprou throughput dedicado. Para obter mais informações, consulte [Aumentar a capacidade de invocação do modelo com throughput provisionado no Amazon Bedrock](prov-throughput.md).
+ **Modelo personalizado**: um modelo de base cujos pesos foram modificados por meio da personalização do modelo. Para obter mais informações, consulte [Personalizar o modelo para melhorar a performance para o caso de uso](custom-models.md).
+ **Parâmetros de inferência**: um conjunto de valores que podem ser ajustados para limitar ou influenciar a resposta do modelo. Para obter informações sobre os parâmetros de inferência, consulte [Geração de resposta de influência com parâmetros de inferência](inference-parameters.md) e [Parâmetros de solicitação de inferência e campos de resposta para modelos de base](model-parameters.md).
## Invocar modelos em diferentes regiões da AWS
Ao invocar um modelo, você escolhe a Região da AWS na qual invocá-lo. As cotas referentes à frequência e ao tamanho das solicitações que você pode fazer dependem da região. Você pode encontrar essas cotas pesquisando as seguintes cotas em [Cotas de serviço do Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#limits_bedrock):
+ Solicitações de inferência do modelo sob demanda por minuto para *\$1\$1Model\$1*
+ Tokens InvokeModel sob demanda por minuto para *\$1\$1Model\$1*
Também é possível invocar um perfil de inferência em vez do próprio modelo de base. Um perfil de inferência define um modelo e uma ou mais regiões para as quais ele pode encaminhar solicitações de invocação de modelo. Ao invocar um perfil de inferência que inclui várias regiões, é possível aumentar o throughput. Para obter mais informações, consulte [Aumentar o throughput com inferência entre regiões](cross-region-inference.md). Para ver as cotas de frequência e tamanho das solicitações que você pode fazer com um perfil de inferência, pesquise as seguintes cotas em [Cotas de serviço do Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#limits_bedrock):
+ Solicitações InvokeModel entre regiões por minuto para *\$1\$1Model\$1*
+ Tokens InvokeModel entre regiões por minuto para *\$1\$1Model\$1*
+ Solicitações InvokeModel entre regiões por minuto para *\$1\$1Model\$1*
+ Tokens InvokeModel entre regiões por minuto para *\$1\$1Model\$1*
As solicitações feitas a uma região podem ser atendidas fora de zonas locais que compartilhem a mesma região principal. Por exemplo, solicitações feitas à região Leste dos EUA (Norte da Virgínia) (us-east-1) podem ser atendidas em qualquer zona local associada a ela, como Atlanta, EUA (us-east-1-atl-2a).
O mesmo princípio se aplica ao usar a inferência entre regiões. Por exemplo, solicitações feitas ao perfil de inferência do Claude 3 Haiku da Anthropic nos EUA podem ser atendidas fora de qualquer zona local cuja região principal esteja nos EUA, como Seattle, EUA (us-west-2-sea-1a). Quando novas zonas locais forem adicionadas à AWS. Elas também serão adicionadas ao endpoint de inferência entre regiões correspondente.
Para ver uma lista dos endpoints locais e das regiões principais às quais eles estão associados, consulte [Localizações de zonas locais da AWS](https://aws.amazon.com/about-aws/global-infrastructure/localzones/locations/).
Quando você invoca um perfil de inferência entre regiões no Amazon Bedrock, sua solicitação se origina de uma região de origem e é automaticamente encaminhada a uma das regiões de destino definidas nesse perfil, otimizando o desempenho. As regiões de destino para o perfil de inferência global entre regiões incluem todas as regiões comerciais.
O perfil de inferência global entre regiões para um modelo específico pode mudar com o tempo, à medida que a AWS adiciona mais regiões comerciais nas quais suas solicitações podem ser processadas. No entanto, se um perfil de inferência estiver vinculado a uma área geográfica (como EUA, UE ou APAC), a respectiva lista de regiões de destino nunca será alterada. A AWS pode criar perfis de inferência que incorporem novas regiões. É possível atualizar seus sistemas para usar esses perfis de inferência alterando os IDs em sua configuração para os novos.
**nota**
As regiões de destino em um perfil de inferência entre regiões podem incluir **regiões de aceitação**, que são regiões que você deve habilitar explicitamente na Conta da AWS ou no nível da organização. Para saber mais, consulte [Habilitar ou desabilitar Regiões da AWS em sua conta](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html). Ao usar um perfil de inferência entre regiões, sua solicitação de inferência pode ser encaminhada a qualquer uma das regiões de destino no perfil, mesmo que você não tenha optado por essas regiões em sua conta.
As políticas de controle de serviços (SCPs) e as políticas do AWS Identity and Access Management (IAM) funcionam juntas para controlar onde a inferência entre regiões é permitida. Usando SCPs, você pode controlar quais regiões o Amazon Bedrock pode usar para inferência e, usando políticas do IAM, você pode definir quais usuários ou perfis têm permissão para executar inferências. Se alguma região de destino em um perfil de inferência entre regiões estiver bloqueada em suas SCPs, a solicitação falhará mesmo que a permissão de outras regiões se mantenha. Para garantir uma operação eficiente com a inferência entre regiões, você pode atualizar suas SCPs e as políticas do IAM para permitir todas as ações de inferência necessárias do Amazon Bedrock (por exemplo, `bedrock:InvokeModel*` ou `bedrock:CreateModelInvocationJob`) em todas as regiões de destino incluídas no perfil de inferência escolhido. Para saber mais, consulte [https://aws.amazon.com/blogs/machine-learning/enable-amazon-bedrock-cross-region-inference-in-multi-account-environments/](https://aws.amazon.com/blogs/machine-learning/enable-amazon-bedrock-cross-region-inference-in-multi-account-environments/)Enabling Amazon Bedrock cross-Region inference in multi-account environments.
# Geração de resposta de influência com parâmetros de inferência
Ao executar a inferência do modelo, é possível ajustar os parâmetros de inferência para influenciar a resposta do modelo. Os parâmetros de inferência podem alterar o conjunto de possíveis saídas que o modelo considera durante a geração ou podem limitar a resposta final.
Os valores e intervalos padrão dos parâmetros de inferência dependem do modelo. Para saber sobre os parâmetros de inferência para diversos modelos, consulte [Parâmetros de solicitação de inferência e campos de resposta para modelos de base](model-parameters.md).
As seguintes categorias de parâmetros são comumente encontradas em diferentes modelos:
**Topics**
+ [Randomização e diversidade](#inference-randomness)
+ [Tamanho](#inference-length)
## Randomização e diversidade
Para qualquer sequência, um modelo determina uma distribuição de probabilidade das opções para o próximo token na sequência. Para gerar cada token em uma saída, o modelo obtém amostras dessa distribuição. A randomização e a diversidade se referem à quantidade de variação na resposta de um modelo. É possível controlar esses fatores limitando ou ajustando a distribuição. Os modelos de base geralmente são compatíveis com os parâmetros a seguir para controlar a randomização e a diversidade na resposta.
+ **Temperatura**: afeta a forma da distribuição de probabilidade da saída prevista e influencia a probabilidade de o modelo selecionar saídas de menor probabilidade.
+ Escolha um valor mais baixo para influenciar o modelo a selecionar saídas de maior probabilidade.
+ Escolha um valor mais alto para influenciar o modelo a selecionar saídas de menor probabilidade.
Em termos técnicos, a temperatura modula a função massa de probabilidade para o próximo token. Uma temperatura mais baixa aumenta a função e ocasiona respostas mais determinísticas, enquanto uma temperatura mais alta achata a função e ocasiona respostas mais aleatórias.
+ **Top K**: o número de candidatos mais prováveis que o modelo considera para o próximo token.
+ Escolha um valor mais baixo para diminuir o tamanho do grupo e limitar as opções às saídas mais prováveis.
+ Escolha um valor mais alto para aumentar o tamanho do grupo e permitir que o modelo considere saídas menos prováveis.
Por exemplo, se você escolher um valor de 50 para o parâmetro Top K, o modelo selecionará entre os 50 tokens com maior probabilidade de serem os próximos na sequência.
+ **Top P**: a porcentagem de candidatos mais prováveis que o modelo considera para o próximo token.
+ Escolha um valor mais baixo para diminuir o tamanho do grupo e limitar as opções às saídas mais prováveis.
+ Escolha um valor mais alto para aumentar o tamanho do grupo e permitir que o modelo considere saídas menos prováveis.
Em termos técnicos, o modelo calcula a distribuição de probabilidade cumulativa para o conjunto de respostas e considera somente os melhores P% da distribuição.
Por exemplo, se você escolher um valor de 0,8 para o parâmetro Top P, o modelo selecionará entre os melhores 80% da distribuição de probabilidade de tokens que podem ser os próximos na sequência.
A tabela a seguir resume os efeitos desses parâmetros.
****
| Parâmetro | Efeito de um valor mais baixo | Efeito de um valor mais alto |
| --- | --- | --- |
| Temperatura | Aumenta a chance de tokens de maior probabilidade Diminui a chance de tokens de menor probabilidade | Aumenta a chance de tokens de menor probabilidadeDiminui a chance de tokens de maior probabilidade |
| Top K | Remove os tokens de menor probabilidade | Permite os tokens de menor probabilidade |
| Top P | Remove os tokens de menor probabilidade | Permite os tokens de menor probabilidade |
Para entender esses parâmetros, considere o exemplo de prompt **I hear the hoof beats of "**. Digamos que o modelo determine as três palavras a seguir como candidatas ao próximo token. O modelo também atribui uma probabilidade a cada palavra.
```
{
"horses": 0.7,
"zebras": 0.2,
"unicorns": 0.1
}
```
+ Se você definir uma **temperatura** alta, a distribuição de probabilidades será nivelada e as probabilidades se tornarão menos diferentes, o que aumentará a probabilidade de escolher “unicórnios” e diminuirá a probabilidade de escolher “cavalos”.
+ Se você definir **Top K** como 2, o modelo considerará apenas os dois candidatos mais prováveis: “cavalos” e “zebras”.
+ Se você definir **Top P** como 0,7, o modelo considerará apenas “cavalos”, porque é o único candidato que está entre os 70% superiores da distribuição de probabilidades. Se você definir **Top P** como 0,9, o modelo considerará “cavalos” e “zebras”, pois eles estão nos 90% superiores da distribuição de probabilidades.
## Tamanho
Os modelos de base geralmente oferecem suporte a parâmetros que limitam o comprimento da resposta. Exemplos desses parâmetros são fornecidos abaixo.
+ **Comprimento da resposta**: um valor exato para especificar o número mínimo ou máximo de tokens a serem retornados na resposta gerada.
+ **Penalidades**: especifique o grau com que deseja penalizar as saídas em uma resposta. Os exemplos incluem o seguinte.
+ O comprimento da resposta.
+ Tokens repetidos em uma resposta.
+ Frequência de tokens em uma resposta.
+ Tipos de tokens em uma resposta.
+ **Sequências de interrupção**: especifique sequências de caracteres que impedem o modelo de gerar mais tokens. Se o modelo gerar uma sequência de interrupção especificada por você, a geração será interrompida após essa sequência.
# Regiões e modelos compatíveis com execução de inferência do modelo
É possível executar inferência do modelo usando modelos de base em todas as regiões e em todos os modelos compatíveis com o Amazon Bedrock. Para ver as regiões e os modelos compatíveis com o Amazon Bedrock, consulte [Modelos de base compatíveis no Amazon Bedrock](models-supported.md).
Também é possível executar inferência do modelo com recursos do Amazon Bedrock que não sejam modelos de base. Consulte as seguintes páginas para ver a disponibilidade de regiões e modelos para diferentes recursos:
+ [Regiões e modelos que compatíveis com perfis de inferência](inference-profiles-support.md)
+ [Regiões e modelos compatíveis com o Gerenciamento de Prompts](prompt-management-supported.md)
**nota**
[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) só funcionam em prompts do Gerenciamento de Prompts cuja configuração especifica um modelo Claude da Anthropic ou Llama da Meta.
+ [Modelos e regiões compatíveis para ajuste fino](custom-model-fine-tuning.md#custom-model-supported)
+ [Usar a importação de modelo personalizado para importar um modelo de código aberto personalizado para o Amazon Bedrock](model-customization-import-model.md)
+ [Regiões e modelos em que é possível usar as Barreiras de Proteção do Amazon Bedrock](guardrails-supported.md)
# Pré-requisitos para executar a inferência do modelo
Para que um perfil execute a inferência do modelo, é necessário permitir que ele execute as ações de API de invocação do modelo. Se sua função tiver a política [AmazonBedrockFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonBedrockFullAccess)AWSgerenciada anexada, você poderá pular esta seção. Caso contrário, anexe as seguintes permissões à função para permitir que ela use o [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html), [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html), [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) e [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)as ações com todos os recursos suportados no Amazon Bedrock:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ModelInvocationPermissions",
"Effect": "Allow",
"Action": [
"bedrock:InvokeModel",
"bedrock:InvokeModelWithResponseStream",
"bedrock:GetInferenceProfile",
"bedrock:ListInferenceProfiles",
"bedrock:RenderPrompt",
"bedrock:GetCustomModel",
"bedrock:ListCustomModels",
"bedrock:GetImportedModel",
"bedrock:ListImportedModels",
"bedrock:GetProvisionedModelThroughput",
"bedrock:ListProvisionedModelThroughputs",
"bedrock:GetGuardrail",
"bedrock:ListGuardrails",
"bedrock:ApplyGuardrail"
],
"Resource": "*"
}
]
}
```
------
Para restringir ainda mais as permissões, você pode omitir ações ou especificar chaves de recurso e de condição que devem ser usadas para filtrar permissões. Para ter mais informações sobre ações, recursos e chaves de condição, consulte os tópicos a seguir na *Referência de autorização do serviço*.
+ [Ações definidas pelo Amazon Bedrock](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrock.html#amazonbedrock-actions-as-permissions): saiba mais sobre as ações, os tipos de recurso para os quais é possível definir um escopo de ação no campo `Resource` e as chaves de condição nas quais você pode filtrar as permissões no campo `Condition`.
+ [Tipos de recursos definidos pelo Amazon Bedrock](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrock.html#amazonbedrock-resources-for-iam-policies): saiba mais sobre os tipos de recurso no Amazon Bedrock.
+ [Chaves de condição para o Amazon Bedrock](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonbedrock.html#amazonbedrock-policy-keys): saiba mais sobre as chaves de condição no Amazon Bedrock.
A seguinte lista resume se você precisa de uma ação dependendo do seu caso de uso:
+ `bedrock:InvokeModel`: necessária para realizar a invocação do modelo. Permite que a função chame as operações da API [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)e da [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html).
+ `bedrock:InvokeModelWithResponseStream`: necessária para realizar a invocação do modelo e exibir respostas de streaming. Permite que a função chame as operações da API [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)e do [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) Stream.
+ As seguintes ações permitem que um perfil execute inferência com recursos do Amazon Bedrock que não sejam modelos de base:
+ `bedrock:GetInferenceProfile`: necessária para executar inferência com um [perfil de inferência](inference-profiles.md).
+ `bedrock:RenderPrompt`: necessária para invocar um prompt no [Gerenciamento de Prompts](prompt-management.md).
+ `bedrock:GetCustomModel`: necessária para executar inferência com um [modelo personalizado](custom-models.md).
+ `bedrock:GetImportedModel`: necessária para executar inferência com um [modelo importado](model-customization-import-model.md).
+ `bedrock:GetProvisionedModelThroughput`: necessária para executar inferência com [throughput provisionado](prov-throughput.md).
+ As seguintes ações permitem que um perfil veja recursos do Amazon Bedrock que não sejam modelos de base no console do Amazon Bedrock e os selecione:
+ `bedrock:ListInferenceProfiles`: necessária para escolher um [perfil de inferência](custom-models.md) no console do Amazon Bedrock.
+ `bedrock:ListCustomModels`: necessária para escolher um [modelo personalizado](custom-models.md) no console do Amazon Bedrock.
+ `bedrock:ListImportedModels`: necessária para escolher um [modelo importado](model-customization-import-model.md) no console do Amazon Bedrock.
+ `bedrock:ListProvisionedModelThroughputs`: necessária para escolher [throughput provisionado](prov-throughput.md) no console do Amazon Bedrock.
+ As seguintes ações permitem que um perfil acesse e aplique barreiras de proteção das [Barreiras de Proteção do Amazon Bedrock](guardrails.md) durante a invocação do modelo:
+ `bedrock:GetGuardrail`: necessária para usar uma barreira de proteção durante a invocação do modelo.
+ `bedrock:ApplyGuardrail`: necessária para aplicar uma barreira de proteção durante a invocação do modelo.
+ `bedrock:ListGuardrails`: necessária para escolher uma barreira de proteção no console do Amazon Bedrock.
# Gerar respostas no console usando playgrounds
Os playgrounds Amazon Bedrock são uma ferramenta Console de gerenciamento da AWS que fornece uma interface visual para experimentar a execução de inferência em diferentes modelos e o uso de configurações diferentes. Você pode usar os playgrounds para testar modelos e valores diferentes antes de integrá-los à aplicação.
Executar um prompt em um playground equivale a fazer uma [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)solicitação [InvokeModel[InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html),, [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) ou na API.
O Amazon Bedrock oferece os seguintes playgrounds para você experimentar:
+ **Chat/texto**: envie prompts de texto e gere respostas ou interaja usando a fala. Você pode selecionar um dos seguintes modos:
+ **Chat**: envie um prompt de texto ou interaja usando a fala. Para prompts de texto, você também pode incluir imagens ou documentos para complementar o prompt. Os prompts subsequentes enviados incluirão os prompts anteriores como contexto, de maneira que a sequência de prompts e respostas se assemelhe a uma conversa.
+ **Prompt único**: envie um prompt de texto único e gere uma resposta para ele.
**nota**
Speech-to-speech modelos como o Amazon Nova Sonic só estão disponíveis no modo chat. O modo de comparação não é compatível com speech-to-speech modelos.
+ **Imagem**: envie um prompt de texto para gerar uma imagem. Você também pode enviar um prompt de imagem e especificar se deseja editá-lo ou gerar variações dele.
+ **Multimodal (pré-visualização)** — Envie solicitações de texto e gere conteúdo multimodal. Ele também suporta os modos de bate-papo e prompt único.
O procedimento a seguir descreve como enviar um prompt no playground, as opções que você pode ajustar e as ações que você poderá realizar depois que o modelo gerar uma resposta.
**Como usar um playground**
1. Caso ainda não tenha feito isso, solicite acesso aos modelos que deseja usar. Para obter mais informações, consulte [Acessar modelos de base do Amazon Bedrock](model-access.md).
1. Faça login no Console de gerenciamento da AWS com uma identidade do IAM que tenha permissões para usar o console Amazon Bedrock. Em seguida, abra o console Amazon Bedrock em [https://console.aws.amazon.com/bedrock.](https://console.aws.amazon.com/bedrock)
1. No painel de navegação, em Teste, escolha **Playground**.
1. Se você estiver no playground **Chat/texto**, selecione um **Modo**.
1. Escolha **Selecionar modelo** e selecione um provedor, um modelo e um throughput a serem usados. Para ter mais informações sobe aumentar o throughput, consulte [Aumentar o throughput com inferência entre regiões](cross-region-inference.md) e [Aumentar a capacidade de invocação do modelo com throughput provisionado no Amazon Bedrock](prov-throughput.md).
1. Envie as seguintes informações para gerar uma resposta:
+ Prompt: uma ou mais frases de texto que configuram um cenário, uma pergunta ou uma tarefa para um modelo. Para obter informações sobre como criar prompts, consulte [Conceitos de engenharia de prompts](prompt-engineering-guidelines.md).
Alguns modelos (consulte[Modelos compatíveis e recursos do modelo](conversation-inference-supported-models-features.md)) permitem que você inclua um arquivo das seguintes formas:
+ Selecione o ícone de anexo e escolha um arquivo para fazer upload.
+ Selecione o ícone de anexo e escolha um objeto do Amazon S3 para fazer upload.
+ Arraste um arquivo até o prompt.
Inclua arquivos para complementar o prompt. Você pode consultar o arquivo no texto do prompt. Por exemplo, você pode escrever **Summarize this document for me** ou **Tell me what's in this image**. Você pode incluir os seguintes tipos de arquivo:
+ **Documentos**: adicione documentos para complementar o prompt. Para obter uma lista dos tipos de arquivo compatíveis, consulte o `format` campo em [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html).
**Atenção**
Os nomes de documento são vulneráveis a injeções de prompt, porque o modelo pode interpretá-los inadvertidamente como instruções. Por isso, é recomendável especificar um nome neutro.
+ **Imagens**: adicione imagens para complementar o prompt, se o modelo permitir entradas multimodais de imagem e texto. Para obter uma lista dos tipos de arquivo compatíveis, consulte o `format` campo no [ImageBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ImageBlock.html).
+ **Imagens**: adicione vídeos para complementar o prompt, se o modelo permitir entradas multimodais de vídeo e texto. Para obter uma lista dos tipos de arquivo compatíveis, consulte o `format` campo no [VideoBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_VideoBlock.html).
**nota**
As restrições de conteúdo variam de acordo com a operação e o modelo subjacentes da API. Para obter mais informações, consulte [Restrições de API](inference-api-restrictions.md).
+ Configurações: configurações ajustadas por você para modificar a resposta do modelo. Entre as configurações estão:
+ Parâmetros de inferência: valores que afetam ou limitam a maneira como o modelo gera a resposta. Para obter mais informações, consulte [Geração de resposta de influência com parâmetros de inferência](inference-parameters.md). Para examinar parâmetros de inferência para modelos específicos, consulte [Parâmetros de solicitação de inferência e campos de resposta para modelos de base](model-parameters.md).
+ Prompts de sistema: prompts que dão instruções ou contextualizam para o modelo a tarefa que ele deve realizar ou a persona que ele deve adotar. Para obter mais informações e uma lista de modelos compatíveis com prompts do sistema, consulte [Realizar uma conversa com as operações de API Converse](conversation-inference.md).
+ Barreiras de proteção: filtra conteúdo perigoso ou indesejado em prompts e respostas de modelo. Para obter mais informações, consulte [Detectar e filtrar conteúdo nocivo usando as Barreiras de Proteção do Amazon Bedrock](guardrails.md).
1. (Opcional) Se um modelo oferecer suporte a streaming, o comportamento padrão é transmitir as respostas. Você pode desativar o streaming escolhendo o ícone de opções (![\[Vertical ellipsis icon representing a menu or more options.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/vertical-ellipsis.png)) e modificando a opção **Preferência de streaming**.
1. (Opcional) Alguns modelos de geração de texto oferecem suporte à avaliação comparativa. Você pode comparar respostas de modelos diferentes fazendo o seguinte:
1. Ative o **Modo de comparação**.
1. Escolha **Selecionar modelo** e selecione um provedor, um modelo e um throughput a serem usados.
1. Escolha o ícone de configurações (![\[Three horizontal sliders with adjustable circular controls for settings or parameters.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/configurations.png)) para modificar as configurações a serem usadas.
1. Para adicionar mais modelos a serem comparados, escolha o ícone \$1 à direita, selecione um modelo e modifique as configurações conforme necessário.
1. (Opcional) Se um modelo permitir armazenamento em cache de prompts, você poderá abrir o painel **Configurações** e ativar o **Armazenamento em cache de prompts** para permitir o armazenamento em cache de suas entradas e das respostas do modelo e reduzir o custo 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).
1. Para executar o prompt, escolha **Executar**. O Amazon Bedrock não armazena nenhum texto, imagem ou documento que você forneça. Os dados são usados somente para gerar a resposta.
**nota**
Se a resposta violar a política de moderação de conteúdo, o Amazon Bedrock não a exibirá. Se você ativou o streaming, o Amazon Bedrock limpa toda a resposta caso ela gere conteúdo que viole a política. Para obter mais detalhes, acesse o console Amazon Bedrock, selecione **Provedores** e leia o texto na seção **Limitações de conteúdo**.
1. O modelo exibe a resposta. Se você estiver usando o modo de bate-papo do playground, poderá enviar uma solicitação para responder à resposta e gerar outra resposta.
1. Depois de gerar uma resposta, você terá as seguintes opções:
+ Para exportar a resposta como um arquivo JSON, escolha o ícone de opções (![\[Vertical ellipsis icon representing a menu or more options.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/vertical-ellipsis.png)) e selecione **Exportar como JSON**.
+ Para exibir a solicitação de API feita por você, escolha o ícone de opções (![\[Vertical ellipsis icon representing a menu or more options.\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/images/icons/vertical-ellipsis.png)) e selecione **Visualizar solicitação de API**.
+ No modo de bate-papo do playground, você pode ver as métricas na seção **Métricas do modelo**. As seguintes métricas de modelo estão disponíveis:
+ **Latência**: o tempo que leva entre o recebimento da solicitação pelo Amazon Bedrock e o momento em que a resposta é exibida (para respostas sem streaming) ou o momento em que o fluxo de respostas é concluído (para respostas de streaming).
+ **Contagem de tokens de entrada**: o número de tokens que são inseridos no modelo como entrada durante a inferência.
+ **Contagem de tokens de saída**: o número de tokens gerados em resposta a um prompt. Respostas mais longas e mais coloquiais exigem mais tokens.
+ **Custo**: o custo de processar a entrada e gerar tokens de saída.
Para definir critérios de métricas aos quais você deseja que a resposta corresponda, escolha **Definir critérios de métricas** e defina condições para que o modelo corresponda. Depois que você aplica os critérios, a seção **Métricas do modelo** mostra quantos e quais critérios foram atendidos pela resposta.
Se os critérios não forem atendidos, você poderá escolher um modelo diferente, reescrever o prompt ou modificar as configurações e reexecutar o prompt.
# Melhorar as respostas do modelo com o raciocínio de modelo
Alguns modelos de base conseguem aplicar o raciocínio de modelo, caso em que são capazes de assumir uma tarefa maior e complexa e dividi-la em etapas menores e mais simples. Esse processo é frequentemente chamado de raciocínio em cadeia de pensamento (CoT). O raciocínio em cadeia de pensamento pode melhorar a precisão do modelo dando a ele a chance de pensar antes de responder. O raciocínio do modelo é mais útil para tarefas como análise em várias etapas, problemas matemáticos e tarefas de raciocínio complexo.
Por exemplo, ao lidar com um problema matemático em forma de texto, o modelo pode primeiro identificar as variáveis relevantes, depois construir equações com base nas informações fornecidas e, finalmente, resolver essas equações para chegar à solução. Essa estratégia não apenas minimiza os erros, mas também torna o processo de raciocínio mais transparente e fácil de seguir, melhorando assim a qualidade da saída do modelo de base.
O raciocínio de modelo não é necessário para todas as tarefas e envolve despesas indiretas, bem como maior latência e mais tokens de saída. Tarefas simples que não precisam de explicações adicionais não são boas candidatas ao raciocínio em CoT.
Observe que nem todos os modelos permitem que você configure o número de tokens de saída que são alocados ao raciocínio de modelo.
O raciocínio de modelo está disponível para os modelos a seguir.
| Modelo de base | ID do modelo | Número de tokens | Configuração de raciocínio |
| --- | --- | --- | --- |
| Anthropic Claude Opus 4 | anthropic.claude-opus-4-20250514-v1:0 | Esse modelo terá 32.768 tokens, que incluem tokens de saída e de raciocínio. | O raciocínio pode ser habilitado ou desabilitado para esse modelo usando um orçamento de token configurável. Por padrão, o raciocínio está desabilitado. |
| Anthropic Claude Sonnet 4 | anthropic.claude-sonnet-4-20250514-v1:0 | Esse modelo terá 65.536 tokens, que incluem tokens de saída e de raciocínio. | O raciocínio pode ser habilitado ou desabilitado para esse modelo usando um orçamento de token configurável. Por padrão, o raciocínio está desabilitado. |
| Anthropic Claude 3.7 Sonnet | anthropic.claude-3-7-sonnet-20250219-v 1:0 | Esse modelo terá 65.536 tokens, que incluem tokens de saída e de raciocínio. | O raciocínio pode ser habilitado ou desabilitado para esse modelo usando um orçamento de token configurável. Por padrão, o raciocínio está desabilitado. |
| DeepSeek DeepSeek-R1 | deepseek.r1-v1:0 | Esse modelo terá 8.192 tokens, que incluem tokens de saída e de raciocínio. O número de tokens de raciocínio não pode ser configurado e o número máximo de tokens de saída não deve ser maior que 8.192. | O raciocínio está sempre habilitado para esse modelo. O modelo não permite ativar e desativar o recurso de raciocínio. |
# Otimizar a inferência do modelo para latência
**nota**
O recurso de inferência otimizada para latência está em versão prévia Amazon Bedrock e está sujeito a alterações.
A inferência otimizada para latência para modelos básicos Amazon Bedrock oferece tempos de resposta mais rápidos e melhor capacidade de resposta para aplicativos de IA. As versões otimizadas dos modelos [https://docs.aws.amazon.com/nova/latest/userguide/what-is-nova.html](https://docs.aws.amazon.com/nova/latest/userguide/what-is-nova.html), [Claude 3.5 Haiku da Anthropic](https://aws.amazon.com/bedrock/claude/) e [Llama 3.1 405B e 70B da Meta](https://aws.amazon.com/bedrock/llama/) oferecem latência significativamente reduzida sem comprometer a precisão.
O acesso ao recurso de otimização de latência não requer configuração adicional nem ajuste fino do modelo, permitindo o aprimoramento imediato das aplicações existentes com tempos de resposta mais rápidos. Você pode definir o parâmetro “latency” como “optimized” ao chamar a API de runtime do Amazon Bedrock. Se você selecionar “standard” como opção de invocação, suas solicitações serão atendidas pela inferência padrão. Por padrão, todas as solicitações são encaminhadas com “standard”.
```
"performanceConfig" : {
"latency" : "standard | optimized"
}
```
Quando você atingir a cota de uso para otimização de latência de um modelo, tentaremos atender à solicitação com latência padrão. Nesses casos, a solicitação será cobrada de acordo com as taxas de latência padrão. A configuração de latência de uma solicitação atendida é visível na resposta e nos AWS CloudTrail registros da API. Você também pode visualizar métricas para solicitações otimizadas para latência nos Amazon CloudWatch registros em “model-id\$1latency-optimization”.
A inferência otimizada para latência está disponível no Llama 3.1 70B e 405B da Meta, bem como no Claude 3.5 Haiku da Anthropic nas regiões Leste dos EUA (Ohio) e Oeste dos EUA (Oregon) por meio da [inferência entre regiões](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html).
A inferência otimizada para latência está disponível no Amazon Nova Pro nas regiões Leste dos EUA (Norte da Virgínia), Leste dos EUA (Ohio) e Oeste dos EUA (Oregon) por meio da [inferência entre regiões](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html).
Para ter mais informações sobre preços, consulte a [página de preços](https://aws.amazon.com/bedrock/pricing/).
**nota**
No momento, a inferência otimizada para latência no Llama 3.1 405B permite solicitações com contagem total de tokens de entrada e saída de até 11 mil. Para solicitações com um número maior de tokens, voltaremos para o modo padrão.
A tabela a seguir mostra os perfis de inferência que oferecem suporte à otimização da latência:
| Fornecedor | Modelo | ID do modelo | Suporte ao perfil de inferência entre regiões |
| --- | --- | --- | --- |
| Amazon | Nova Pro | amazônia. nova-pro-v1:0 | us-east-1 us-east-2 |
| Anthropic | Claude 3.5 Haiku | anthropic.claude-3-5-haiku-20241022-v1:0 | us-east-2 us-west-2 |
| Meta | Llama 3.1 405B Instruct | meta.llama3-1-405 1:0 b-instruct-v | us-east-2 |
| Meta | Llama 3.1 70B Instruct | meta.llama3-1-70 1:0 b-instruct-v | us-east-2 us-west-2 |
Para obter mais informações sobre perfis de inferência, consulte [Regiões e modelos que compatíveis com perfis de inferência](inference-profiles-support.md).
# Gere respostas usando OpenAI APIs
O Amazon Bedrock fornece endpoints de API OpenAI compatíveis para inferência de modelos, com tecnologia do Mantle, um mecanismo de inferência distribuído para fornecimento de modelos de aprendizado de máquina em grande escala. Esses endpoints permitem que você use ferramentas familiares OpenAI SDKs e ferramentas com os modelos Amazon Bedrock, permitindo que você migre aplicativos existentes com o mínimo de alterações de código — basta atualizar sua URL base e chave de API.
Os benefícios importantes incluem:
+ Inferência **assíncrona — Support para cargas de trabalho de inferência** de longa duração por meio da API de respostas
+ **Gerenciamento de conversas com estado** — reconstrua automaticamente o contexto sem passar manualmente o histórico de conversas com cada solicitação
+ **Uso simplificado de ferramentas** — integração simplificada para fluxos de trabalho agentes
+ **Modos de resposta flexíveis** — Support para respostas de streaming e não streaming
+ **Fácil migração** — Compatível com as bases de código OpenAI SDK existentes
## Regiões e endpoints compatíveis
O Amazon Bedrock está disponível nas seguintes AWS regiões:
| Nome da região | Região | Endpoint |
| --- | --- | --- |
| Leste dos EUA (Ohio) | us-east-2 | bedrock-mantle.us-east-2.api.aws |
| Leste dos EUA (Norte da Virgínia) | us-east-1 | bedrock-mantle.us-east-1.api.aws |
| Oeste dos EUA (Oregon) | us-west-2 | bedrock-mantle.us-west-2.api.aws |
| Ásia-Pacífico (Jacarta) | ap-southeast-3 | bedrock-mantle.ap-southeast-3.api.aws |
| Ásia-Pacífico (Mumbai) | ap-south-1 | bedrock-mantle.ap-south-1.api.aws |
| Ásia-Pacífico (Tóquio) | ap-northeast-1 | bedrock-mantle.ap-northeast-1.api.aws |
| Europa (Frankfurt) | eu-central-1 | bedrock-mantle.eu-central-1.api.aws |
| Europa (Irlanda) | eu-west-1 | bedrock-mantle.eu-west-1.api.aws |
| Europa (Londres) | eu-west-2 | bedrock-mantle.eu-west-2.api.aws |
| Europa (Milão) | eu-south-1 | bedrock-mantle.eu-south-1.api.aws |
| Europa (Estocolmo) | eu-north-1 | bedrock-mantle.eu-north-1.api.aws |
| América do Sul (São Paulo) | sa-east-1 | bedrock-mantle.sa-east-1.api.aws |
## Pré-requisitos
Antes de usar OpenAI APIs, verifique se você tem o seguinte:
+ **Autenticação** — Você pode se autenticar usando:
+ Chave de API Amazon Bedrock (necessária para o OpenAI SDK)
+ AWS credenciais (com suporte para solicitações HTTP)
+ **OpenAISDK** (opcional) — Instale o SDK do OpenAI Python se estiver usando solicitações baseadas em SDK.
+ **Variáveis de ambiente** — Defina as seguintes variáveis de ambiente:
+ `OPENAI_API_KEY`— Defina sua chave de API Amazon Bedrock
+ `OPENAI_BASE_URL`— Defina como o endpoint Amazon Bedrock da sua região (por exemplo,) ` https://bedrock-mantle.us-east-1.api.aws/v1`
## API de modelos
A API de modelos permite que você descubra modelos disponíveis no Amazon Bedrock com tecnologia Mantle. Use essa API para recuperar uma lista de modelos que você pode usar com a API de respostas e a API de conclusão de bate-papo. Para obter detalhes completos da API, consulte a [documentação dos OpenAI modelos](https://platform.openai.com/docs/api-reference/models).
### Listar modelos disponíveis
Para listar os modelos disponíveis, escolha a guia do seu método preferido e siga as etapas:
------
#### [ OpenAI SDK (Python) ]
```
# List all available models using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
from openai import OpenAI
client = OpenAI()
models = client.models.list()
for model in models.data:
print(model.id)
```
------
#### [ HTTP request ]
Faça uma solicitação GET para`/v1/models`:
```
# List all available models
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
curl -X GET $OPENAI_BASE_URL/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
------
## API de respostas
A API de respostas fornece gerenciamento de conversas com estado, com suporte para streaming, processamento em segundo plano e interações em vários turnos. Para obter detalhes completos da API, consulte a [documentação de OpenAI respostas](https://platform.openai.com/docs/api-reference/responses).
### Solicitação básica
Para criar uma resposta, escolha a guia do seu método preferido e siga as etapas:
------
#### [ OpenAI SDK (Python) ]
```
# Create a basic response using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="openai.gpt-oss-120b",
input=[
{"role": "user", "content": "Hello! How can you help me today?"}
]
)
print(response)
```
------
#### [ HTTP request ]
Faça uma solicitação POST para`/v1/responses`:
```
# Create a basic response
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
curl -X POST $OPENAI_BASE_URL/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "openai.gpt-oss-120b",
"input": [
{"role": "user", "content": "Hello! How can you help me today?"}
]
}'
```
------
### Transmita respostas
Para receber eventos de resposta incrementalmente, escolha a guia do seu método preferido e siga as etapas:
------
#### [ OpenAI SDK (Python) ]
```
# Stream response events incrementally using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
from openai import OpenAI
client = OpenAI()
stream = client.responses.create(
model="openai.gpt-oss-120b",
input=[{"role": "user", "content": "Tell me a story"}],
stream=True
)
for event in stream:
print(event)
```
------
#### [ HTTP request ]
Faça uma solicitação POST para `/v1/responses` com `stream` definido como`true`:
```
# Stream response events incrementally
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
curl -X POST $OPENAI_BASE_URL/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "openai.gpt-oss-120b",
"input": [
{"role": "user", "content": "Tell me a story"}
],
"stream": true
}'
```
------
## API de conclusão de bate-papo
A API Chat Completions gera respostas conversacionais. Para obter detalhes completos da API, consulte a [documentação de conclusão de OpenAI bate-papo](https://platform.openai.com/docs/api-reference/chat/create).
### Criar um preenchimento de chat
Para criar uma conclusão de bate-papo, escolha a guia do seu método preferido e siga as etapas:
------
#### [ OpenAI SDK (Python) ]
Configure o OpenAI cliente usando variáveis de ambiente:
```
# Create a chat completion using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
from openai import OpenAI
client = OpenAI()
completion = client.chat.completions.create(
model="openai.gpt-oss-120b",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
)
print(completion.choices[0].message)
```
------
#### [ HTTP request ]
Faça uma solicitação POST para`/v1/chat/completions`:
```
# Create a chat completion
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
curl -X POST $OPENAI_BASE_URL/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "openai.gpt-oss-120b",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
}'
```
------
### Ativar streaming
Para receber respostas incrementalmente, escolha a guia do seu método preferido e siga as etapas:
------
#### [ OpenAI SDK (Python) ]
```
# Stream chat completion responses incrementally using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
from openai import OpenAI
client = OpenAI()
stream = client.chat.completions.create(
model="openai.gpt-oss-120b",
messages=[{"role": "user", "content": "Tell me a story"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content is not None:
print(chunk.choices[0].delta.content, end="")
```
------
#### [ HTTP request ]
Faça uma solicitação POST para `/v1/chat/completions` com ` stream` definido como`true`:
```
# Stream chat completion responses incrementally
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables
curl -X POST $OPENAI_BASE_URL/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "openai.gpt-oss-120b",
"messages": [
{"role": "user", "content": "Tell me a story"}
],
"stream": true
}'
```
------
# Enviar prompts e gerar respostas usando a API
O Amazon Bedrock oferece as seguintes operações de API para realizar inferência do modelo:
+ [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)— Envie uma solicitação e gere uma resposta. O corpo da solicitação é específico ao modelo. Para gerar respostas de streaming, use [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html).
+ [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html): envie um prompt e gere respostas com uma estrutura unificada em todos os modelos. Os campos de solicitação específicos ao modelo podem ser indicados no campo `additionalModelRequestFields`. Também é possível incluir prompts do sistema e conversas anteriores para contextualizar. Para gerar respostas de streaming, use [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html).
+ [StartAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_StartAsyncInvoke.html)— Envie uma solicitação e gere uma resposta de forma assíncrona que possa ser recuperada posteriormente. Usado para gerar vídeos.
+ [InvokeModelWithBidirectionalStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithBidirectionalStream.html) –
+ API Chat Completions da OpenAI: use a [API Chat Completions da OpenAI](https://platform.openai.com/docs/api-reference/chat/create) com modelos compatíveis com o Amazon Bedrock para gerar uma resposta.
**nota**
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 inferência do modelo, determine os seguintes parâmetros:
+ ID do modelo: o ID ou nome do recurso da Amazon (ARN) do modelo ou do perfil de inferência a ser usado no campo `modelId` para inferência. A tabela a seguir descreve como encontrar IDs diferentes tipos de recursos:
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/bedrock/latest/userguide/inference-api.html)
+ Corpo da solicitação: contém os parâmetros de inferência para um modelo e outras configurações. Cada modelo de base tem seus próprios de parâmetros de inferência. Os parâmetros de inferência para um modelo personalizado ou provisionado dependem do modelo de base do qual ele foi criado. Para obter mais informações, consulte [Parâmetros de solicitação de inferência e campos de resposta para modelos de base](model-parameters.md).
Selecione um tópico para aprender a usar a APIs invocação do modelo.
**Topics**
+ [Envie uma única solicitação com InvokeModel](inference-invoke.md)
+ [Invocar um modelo com a API Chat Completions da OpenAI](inference-chat-completions.md)
+ [Realizar uma conversa com as operações de API Converse](conversation-inference.md)
+ [Restrições de API](inference-api-restrictions.md)
# Envie uma única solicitação com InvokeModel
Você executa a inferência em um único prompt usando as operações [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)e da [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)API e especificando um modelo. Há diferenças nos modelos do Amazon Bedrock com relação a se aceitam entradas de texto, imagem ou vídeo e se podem produzir saídas de texto, imagem ou incorporações. Alguns modelos podem exibir a resposta em um fluxo. Para verificar se o modelo permite entrada, saída e streaming, execute um destes procedimentos:
+ Verifique o valor nas colunas **Modalidades de entrada**, **Modalidades de saída** ou **Suporte a streaming** referentes a um modelo em [Modelos de base compatíveis no Amazon Bedrock](models-supported.md).
+ Envie uma [GetFoundationModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_GetFoundationModel.html)solicitação com o ID do modelo e verifique os valores no `responseStreamingSupported` campo `inputModalities``outputModalities`, e.
Execute a inferência do modelo em um prompt enviando uma [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)solicitação [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)or com um endpoint de tempo de [execução do Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt).
**nota**
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.
Os seguintes campos são obrigatórios:
****
| Campo | Caso de uso |
| --- | --- |
| modelId | Para especificar o modelo, o perfil de inferência ou o prompt no Gerenciamento de Prompts a ser usado. Para saber como encontrar esse valor, consulte [Enviar prompts e gerar respostas usando a API](inference-api.md). |
| body | Especificar os parâmetros de inferência para um modelo. Para consultar os parâmetros de inferência para diversos modelos, consulte[Parâmetros de solicitação de inferência e campos de resposta para modelos de base](model-parameters.md). Se você especificar uma solicitação no Gerenciamento de Prompts no campo modelId, omita esse campo (se você incluí-lo, ele será ignorado). |
Os seguintes campos são opcionais:
****
| Campo | Caso de uso |
| --- | --- |
| aceitar | Especificar o tipo de mídia para o corpo da solicitação. Para obter mais informações, consulte Media Types no [site do Swagger](https://swagger.io/specification/). |
| contentType | Especificar o tipo de mídia para o corpo da resposta. Para obter mais informações, consulte Media Types no [site do Swagger](https://swagger.io/specification/). |
| performanceConfigLatency | Para especificar se um modelo deve ser otimizado para latência. Para obter mais informações, consulte [Otimizar a inferência do modelo para latência](latency-optimized-inference.md). |
| guardrailIdentifier | Especificar uma barreira de proteção a ser aplicada ao prompt e à resposta. Para obter mais informações, consulte [Testar uma barreira de proteção](guardrails-test.md). |
| guardrailVersion | Especificar uma barreira de proteção a ser aplicada ao prompt e à resposta. Para obter mais informações, consulte [Testar uma barreira de proteção](guardrails-test.md). |
| trace | Especificar se o rastreamento da barreira de proteção especificada deve ser retornado. Para obter mais informações, consulte [Testar uma barreira de proteção](guardrails-test.md). |
| Nível de serviço | Para especificar o nível de serviço para uma solicitação. Para obter mais informações, consulte [Níveis de serviço para otimizar o desempenho e o custo](service-tiers-inference.md). |
## Exemplos de código de invocação de modelos
Este tópico fornece alguns exemplos básicos para executar inferência usando um único prompt com a [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)API. Para ver mais exemplos com modelos diferentes, acesse os seguintes recursos:
+ Escolha um exemplo abaixo do tópico [Exemplos de código para o Amazon Bedrock Runtime usando AWS SDKs](service_code_examples_bedrock-runtime.md).
+ Acesse a referência de parâmetros de inferência do modelo desejado em [Parâmetros de solicitação de inferência e campos de resposta para modelos de base](model-parameters.md).
Os exemplos a seguir pressupõem que você configurou o acesso programático para se autenticar automaticamente no AWS CLI e no SDK for Python (Boto3) em um padrão ao executar esses exemplos. Região da AWS Para ter informações sobre como configurar o acesso de programação, consulte [Começar a usar a API](getting-started-api.md).
**nota**
Analise os seguintes pontos antes de experimentar os exemplos:
Teste esses exemplos no Leste dos EUA (Norte da Virgínia) (us-east-1), que aceita todos os modelos usados nos exemplos.
O parâmetro `body` pode ser grande, então, para alguns exemplos da CLI, você deverá criar um arquivo JSON e fornecer esse arquivo no argumento `--body` em vez de especificá-lo na linha de comandos.
Nos exemplos de imagens e vídeos, você deverá usar sua própria imagem e vídeo. Os exemplos pressupõem que seu arquivo de imagem tenha um nome *image.png* e que seu arquivo de vídeo tenha um nome*video.mp4*.
Talvez seja necessário converter imagens ou vídeos em uma string codificada em base64 ou enviá-los a um local do Amazon S3. Nos exemplos, você precisará substituir os espaços reservados pela string real codificada em base64 ou pela localização do S3.
Expanda uma seção para experimentar alguns exemplos básicos de código.
### Gerar texto com um prompt de texto
Os exemplos a seguir geram uma resposta de texto a um prompt de texto usando o modelo Amazon Titan Text Premier. Escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ CLI ]
Execute o comando a seguir em um terminal e encontre a resposta gerada em um arquivo chamado*invoke-model-output.txt*.
```
aws bedrock-runtime invoke-model \
--model-id amazon.titan-text-premier-v1:0 \
--body '{
"inputText": "Describe the purpose of a 'hello world' program in one line.",
"textGenerationConfig": {
"maxTokenCount": 512,
"temperature": 0.5
}
}' \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
------
#### [ Python ]
Execute o seguinte exemplo de código Python para gerar uma resposta textual:
```
# Use the native inference API to send a text message to Amazon Titan Text.
import boto3
import json
from botocore.exceptions import ClientError
# Create a Bedrock Runtime client in the AWS Region of your choice.
client = boto3.client("bedrock-runtime", region_name="us-east-1")
# Set the model ID, e.g., Titan Text Premier.
model_id = "amazon.titan-text-premier-v1:0"
# Define the prompt for the model.
prompt = "Describe the purpose of a 'hello world' program in one line."
# Format the request payload using the model's native structure.
native_request = {
"inputText": prompt,
"textGenerationConfig": {
"maxTokenCount": 512,
"temperature": 0.5,
},
}
# Convert the native request to JSON.
request = json.dumps(native_request)
try:
# Invoke the model with the request.
response = client.invoke_model(modelId=model_id, body=request)
except (ClientError, Exception) as e:
print(f"ERROR: Can't invoke '{model_id}'. Reason: {e}")
exit(1)
# Decode the response body.
model_response = json.loads(response["body"].read())
# Extract and print the response text.
response_text = model_response["results"][0]["outputText"]
print(response_text)
```
------
### Gere texto com um prompt de texto usando o nível de serviço
Os exemplos a seguir geram uma resposta de texto para uma solicitação de texto usando o modelo OpenAI GPT com uma camada de serviço para priorizar a solicitação. Escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ CLI ]
Execute o comando a seguir em um terminal e valide o nível de serviço na resposta.
```
aws bedrock-runtime invoke-model \
--model-id openai.gpt-oss-120b-1:0 \
--body '{
"messages": [
{
"role": "user",
"content": "Describe the purpose of a '\''hello world'\'' program in one line."
}
],
"max_tokens": 512,
"temperature": 0.7
}' \
--content-type application/json \
--accept application/json \
--service-tier priority \
--cli-binary-format raw-in-base64-out
```
------
#### [ Python ]
Execute o exemplo de código Python a seguir para gerar uma resposta de texto com nível de serviço:
```
import boto3
import json
# Create a Bedrock Runtime client
bedrock_runtime = boto3.client(
service_name="bedrock-runtime",
region_name="us-east-1"
)
# Define the model ID and request body
model_id = "openai.gpt-oss-120b-1:0"
body = json.dumps({
"messages": [
{
"role": "user",
"content": "Describe the purpose of a 'hello world' program in one line."
}
],
"max_tokens": 512,
"temperature": 0.7
})
# Make the request with service tier
response = bedrock_runtime.invoke_model(
modelId=model_id,
body=body,
contentType="application/json",
accept="application/json",
serviceTier="priority"
)
# Parse and print the response
response_body = json.loads(response["body"])
print(response_body)
```
------
### Gere uma imagem com um prompt de texto.
Os exemplos de código a seguir geram uma imagem usando um prompt de texto com o modelo Stable Diffusion XL 1.0. Escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ CLI ]
Execute o comando a seguir em um terminal e encontre a resposta gerada em um arquivo chamado*invoke-model-output.txt*. Os bytes que representam a imagem podem ser encontrados no campo `base64` da resposta:
```
aws bedrock-runtime invoke-model \
--model-id stability.stable-diffusion-xl-v1 \
--body '{
"text_prompts": [{"text": "A stylized picture of a cute old steampunk robot."}],
"style_preset": "photographic",
"seed": 0,
"cfg_scale": 10,
"steps": 30
}' \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
------
#### [ Python ]
Execute o exemplo de código Python a seguir para gerar uma imagem e encontrar o arquivo de *stability\$11.png* imagem resultante em uma pasta chamada. *output*
```
# Use the native inference API to create an image with Amazon Titan Image Generator
import base64
import boto3
import json
import os
import random
# Create a Bedrock Runtime client in the AWS Region of your choice.
client = boto3.client("bedrock-runtime", region_name="us-east-1")
# Set the model ID, e.g., Titan Image Generator G1.
model_id = "amazon.titan-image-generator-v2:0"
# Define the image generation prompt for the model.
prompt = "A stylized picture of a cute old steampunk robot."
# Generate a random seed.
seed = random.randint(0, 2147483647)
# Format the request payload using the model's native structure.
native_request = {
"taskType": "TEXT_IMAGE",
"textToImageParams": {"text": prompt},
"imageGenerationConfig": {
"numberOfImages": 1,
"quality": "standard",
"cfgScale": 8.0,
"height": 512,
"width": 512,
"seed": seed,
},
}
# Convert the native request to JSON.
request = json.dumps(native_request)
# Invoke the model with the request.
response = client.invoke_model(modelId=model_id, body=request)
# Decode the response body.
model_response = json.loads(response["body"].read())
# Extract the image data.
base64_image_data = model_response["images"][0]
# Save the generated image to a local folder.
i, output_dir = 1, "output"
if not os.path.exists(output_dir):
os.makedirs(output_dir)
while os.path.exists(os.path.join(output_dir, f"titan_{i}.png")):
i += 1
image_data = base64.b64decode(base64_image_data)
image_path = os.path.join(output_dir, f"titan_{i}.png")
with open(image_path, "wb") as file:
file.write(image_data)
print(f"The generated image has been saved to {image_path}")
```
------
### Gerar incorporações com base no texto
Os exemplos a seguir usam o modelo Amazon Titan Text Embeddings V2 para gerar incorporações binárias para uma entrada de texto. Escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ CLI ]
Execute o comando a seguir em um terminal e encontre a resposta gerada em um arquivo chamado*invoke-model-output.txt*. As incorporações resultantes estão no campo `binary`.
```
aws bedrock-runtime invoke-model \
--model-id amazon.titan-embed-text-v2:0 \
--body '{
"inputText": "What are the different services that you offer?",
"embeddingTypes": ["binary"]
}' \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
------
#### [ Python ]
Execute o seguinte exemplo de código Python para gerar incorporações para o texto fornecido:
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to generate an embedding with the Amazon Titan Text Embeddings V2 Model
"""
import json
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_embedding(model_id, body):
"""
Generate an embedding with the vector representation of a text input using Amazon Titan Text Embeddings G1 on demand.
Args:
model_id (str): The model ID to use.
body (str) : The request body to use.
Returns:
response (JSON): The embedding created by the model and the number of input tokens.
"""
logger.info("Generating an embedding with Amazon Titan Text Embeddings V2 model %s", model_id)
bedrock = boto3.client(service_name='bedrock-runtime')
accept = "application/json"
content_type = "application/json"
response = bedrock.invoke_model(
body=body, modelId=model_id, accept=accept, contentType=content_type
)
response_body = json.loads(response.get('body').read())
return response_body
def main():
"""
Entrypoint for Amazon Titan Embeddings V2 - Text example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "amazon.titan-embed-text-v2:0"
input_text = "What are the different services that you offer?"
# Create request body.
body = json.dumps({
"inputText": input_text,
"embeddingTypes": ["binary"]
})
try:
response = generate_embedding(model_id, body)
print(f"Generated an embedding: {response['embeddingsByType']['binary']}") # returns binary embedding
print(f"Input text: {input_text}")
print(f"Input Token count: {response['inputTextTokenCount']}")
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 generating an embedding with Amazon Titan Text Embeddings V2 model {model_id}.")
if __name__ == "__main__":
main()
```
------
### Gerar incorporações com base em uma imagem
Os exemplos a seguir usam o modelo Amazon Titan Multimodal Embeddings G1 para gerar incorporações para uma entrada de imagem. Escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ CLI ]
Abra um novo terminal e faça o seguinte:
1. Converta uma imagem intitulada *image.png* em sua pasta atual em uma string codificada em base64 e grave-a em um arquivo intitulado *image.txt* executando o seguinte comando:
```
base64 -i image.png -o image.txt
```
1. Crie um arquivo JSON chamado *image-input-embeddings-output.json* e cole o seguinte JSON, *\$1\$1image-base64\$1* substituindo-o pelo conteúdo do *image.txt* arquivo (certifique-se de que não haja uma nova linha no final da string):
```
{
"inputImage": "${image-base64}",
"embeddingConfig": {
"outputEmbeddingLength": 256
}
}
```
1. Execute o comando a seguir, especificando o *image-input-embeddings-output.json* arquivo como corpo.
```
aws bedrock-runtime invoke-model \
--model-id amazon.titan-embed-image-v1 \
--body file://image-input-embeddings-output.json \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
1. Encontre as incorporações resultantes no *invoke-model-output.txt* arquivo.
------
#### [ Python ]
No script Python a seguir, */path/to/image* substitua pelo caminho para uma imagem real. Em seguida, execute o script para gerar incorporações:
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to generate embeddings from an image with the Amazon Titan Multimodal Embeddings G1 model (on demand).
"""
import base64
import json
import logging
import boto3
from botocore.exceptions import ClientError
class EmbedError(Exception):
"Custom exception for errors returned by Amazon Titan Multimodal Embeddings G1"
def __init__(self, message):
self.message = message
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_embeddings(model_id, body):
"""
Generate a vector of embeddings for an image input using Amazon Titan Multimodal Embeddings G1 on demand.
Args:
model_id (str): The model ID to use.
body (str) : The request body to use.
Returns:
response (JSON): The embeddings that the model generated, token information, and the
reason the model stopped generating embeddings.
"""
logger.info("Generating embeddings with Amazon Titan Multimodal Embeddings G1 model %s", model_id)
bedrock = boto3.client(service_name='bedrock-runtime')
accept = "application/json"
content_type = "application/json"
response = bedrock.invoke_model(
body=body, modelId=model_id, accept=accept, contentType=content_type
)
response_body = json.loads(response.get('body').read())
finish_reason = response_body.get("message")
if finish_reason is not None:
raise EmbedError(f"Embeddings generation error: {finish_reason}")
return response_body
def main():
"""
Entrypoint for Amazon Titan Multimodal Embeddings G1 example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
# Read image from file and encode it as base64 string.
with open("/path/to/image", "rb") as image_file:
input_image = base64.b64encode(image_file.read()).decode('utf8')
model_id = 'amazon.titan-embed-image-v1'
output_embedding_length = 256
# Create request body.
body = json.dumps({
"inputImage": input_image,
"embeddingConfig": {
"outputEmbeddingLength": output_embedding_length
}
})
try:
response = generate_embeddings(model_id, body)
print(f"Generated image embeddings of length {output_embedding_length}: {response['embedding']}")
except ClientError as err:
message = err.response["Error"]["Message"]
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
except EmbedError as err:
logger.error(err.message)
print(err.message)
else:
print(f"Finished generating image embeddings with Amazon Titan Multimodal Embeddings G1 model {model_id}.")
if __name__ == "__main__":
main()
```
------
### Gerar uma resposta de texto para uma imagem com um prompt de texto anexado
Escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ CLI ]
O exemplo a seguir usa o modelo Claude 3 Haiku da Anthropic para gerar uma resposta, com uma imagem e um prompt de texto que pergunta qual é o conteúdo da imagem. Abra um novo terminal e faça o seguinte:
1. Converta uma imagem intitulada *image.png* em sua pasta atual em uma string codificada em base64 e grave-a em um arquivo intitulado *image.txt* executando o seguinte comando:
```
base64 -i image.png -o image.txt
```
1. Crie um arquivo JSON chamado *image-text-input.json* e cole o seguinte JSON, *\$1\$1image-base64\$1* substituindo-o pelo conteúdo do *image.txt* arquivo (certifique-se de que não haja uma nova linha no final da string):
```
{
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": "${image-base64}"
}
},
{
"type": "text",
"text": "What's in this image?"
}
]
}
]
}
```
1. Execute o comando a seguir para gerar uma saída de texto, com base na imagem e no prompt de texto que a acompanha, para um arquivo chamado*invoke-model-output.txt*:
```
aws bedrock-runtime invoke-model \
--model-id anthropic.claude-3-haiku-20240307-v1:0 \
--body file://image-text-input.json \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
1. Encontre a saída no *invoke-model-output.txt* arquivo na pasta atual.
------
#### [ Python ]
No script python a seguir, */path/to/image.png* substitua pelo caminho real da imagem antes de executar o script:
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to run a multimodal prompt with Anthropic Claude (on demand) and InvokeModel.
"""
import json
import logging
import base64
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def run_multi_modal_prompt(bedrock_runtime, model_id, messages, max_tokens):
"""
Invokes a model with a multimodal prompt.
Args:
bedrock_runtime: The Amazon Bedrock boto3 client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send to the model.
max_tokens (int) : The maximum number of tokens to generate.
Returns:
None.
"""
body = json.dumps(
{
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": max_tokens,
"messages": messages
}
)
response = bedrock_runtime.invoke_model(
body=body, modelId=model_id)
response_body = json.loads(response.get('body').read())
return response_body
def main():
"""
Entrypoint for Anthropic Claude multimodal prompt example.
"""
try:
bedrock_runtime = boto3.client(service_name='bedrock-runtime')
model_id = 'anthropic.claude-3-sonnet-20240229-v1:0'
max_tokens = 1000
input_text = "What's in this image?"
input_image = "/path/to/image" # Replace with actual path to image file
# Read reference image from file and encode as base64 strings.
image_ext = input_image.split(".")[-1]
with open(input_image, "rb") as image_file:
content_image = base64.b64encode(image_file.read()).decode('utf8')
message = {
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": f"image/{image_ext}",
"data": content_image
}
},
{
"type": "text",
"text": input_text
}
]
}
messages = [message]
response = run_multi_modal_prompt(
bedrock_runtime, model_id, messages, max_tokens)
print(json.dumps(response, indent=4))
except ClientError as err:
message = err.response["Error"]["Message"]
logger.error("A client error occurred: %s", message)
print("A client error occurred: " +
format(message))
if __name__ == "__main__":
main()
```
------
### Gerar uma resposta de texto para um vídeo enviado ao Amazon S3 com um prompt de texto que o acompanha
Os exemplos a seguir mostram como gerar uma resposta com o modelo Amazon Nova Lite, considerando um vídeo que você carrega em um bucket do S3 e um prompt de texto que o acompanha.
**Pré-requisito:** faça upload de um vídeo intitulado *video.mp4* para um bucket do Amazon S3 em sua conta seguindo as etapas em [Carregar objetos no](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html#upload-objects-procedure) Guia do usuário do Amazon Simple Storage Service. Anote o URI do S3 do vídeo.
Escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ CLI ]
Abra um terminal e execute o seguinte comando, *s3://amzn-s3-demo-bucket/video.mp4* substituindo-o pela localização real do seu vídeo no S3:
```
aws bedrock-runtime invoke-model \
--model-id amazon.nova-lite-v1:0 \
--body '{
"messages": [
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/video.mp4"
}
}
}
},
{
"text": "What happens in this video?"
}
]
}
]
}' \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
Encontre a saída no *invoke-model-output.txt* arquivo na pasta atual.
------
#### [ Python ]
No script Python a seguir, *s3://amzn-s3-demo-bucket/video.mp4* substitua pela localização real do seu vídeo no S3. Em seguida, execute o script:
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to run a multimodal prompt with Nova Lite (on demand) and InvokeModel.
"""
import json
import logging
import base64
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def run_multi_modal_prompt(bedrock_runtime, model_id, messages, max_tokens):
"""
Invokes a model with a multimodal prompt.
Args:
bedrock_runtime: The Amazon Bedrock boto3 client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send to the model.
max_tokens (int) : The maximum number of tokens to generate.
Returns:
None.
"""
body = json.dumps(
{
"messages": messages,
"inferenceConfig": {
"maxTokens": max_tokens
}
}
)
response = bedrock_runtime.invoke_model(
body=body, modelId=model_id)
response_body = json.loads(response.get('body').read())
return response_body
def main():
"""
Entrypoint for Nova Lite video prompt example.
"""
try:
bedrock_runtime = boto3.client(service_name='bedrock-runtime')
model_id = "amazon.nova-lite-v1:0"
max_tokens = 1000
input_video_s3_uri = "s3://amzn-s3-demo-bucket/video.mp4" # Replace with real S3 URI
video_ext = input_video_s3_uri.split(".")[-1]
input_text = "What happens in this video?"
message = {
"role": "user",
"content": [
{
"video": {
"format": video_ext,
"source": {
"s3Location": {
"uri": input_video_s3_uri
}
}
}
},
{
"text": input_text
}
]
}
messages = [message]
response = run_multi_modal_prompt(
bedrock_runtime, model_id, messages, max_tokens)
print(json.dumps(response, indent=4))
except ClientError as err:
message = err.response["Error"]["Message"]
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
if __name__ == "__main__":
main()
```
------
### Gerar uma resposta de texto para um vídeo convertido em uma string codificada em base64 com um prompt de texto que o acompanha
Os exemplos a seguir mostram como gerar uma resposta com o modelo Amazon Nova Lite, considerando um vídeo convertido em uma string codificada em base64 e um prompt de texto que o acompanha. Escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ CLI ]
Faça o seguinte:
1. Converta um vídeo intitulado *video.mp4* em sua pasta atual em base64 executando o seguinte comando:
```
base64 -i video.mp4 -o video.txt
```
1. Crie um arquivo JSON chamado *video-text-input.json* e cole o seguinte JSON, *\$1\$1video-base64\$1* substituindo-o pelo conteúdo do `video.txt` arquivo (certifique-se de que não haja uma nova linha no final):
```
{
"messages": [
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"bytes": ${video-base64}
}
}
},
{
"text": "What happens in this video?"
}
]
}
]
}
```
1. Execute o comando a seguir para gerar uma saída de texto com base no vídeo e no prompt de texto que o acompanha para um arquivo chamado*invoke-model-output.txt*:
```
aws bedrock-runtime invoke-model \
--model-id amazon.nova-lite-v1:0 \
--body file://video-text-input.json \
--cli-binary-format raw-in-base64-out \
invoke-model-output.txt
```
1. Encontre a saída no *invoke-model-output.txt* arquivo na pasta atual.
------
#### [ Python ]
No script Python a seguir, */path/to/video.mp4* substitua pelo caminho real do vídeo. Em seguida, execute o script:
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to run a multimodal prompt with Nova Lite (on demand) and InvokeModel.
"""
import json
import logging
import base64
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def run_multi_modal_prompt(bedrock_runtime, model_id, messages, max_tokens):
"""
Invokes a model with a multimodal prompt.
Args:
bedrock_runtime: The Amazon Bedrock boto3 client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send to the model.
max_tokens (int) : The maximum number of tokens to generate.
Returns:
None.
"""
body = json.dumps(
{
"messages": messages,
"inferenceConfig": {
"maxTokens": max_tokens
}
}
)
response = bedrock_runtime.invoke_model(
body=body, modelId=model_id)
response_body = json.loads(response.get('body').read())
return response_body
def main():
"""
Entrypoint for Nova Lite video prompt example.
"""
try:
bedrock_runtime = boto3.client(service_name='bedrock-runtime')
model_id = "amazon.nova-lite-v1:0"
max_tokens = 1000
input_video = "/path/to/video.mp4" # Replace with real path to video
video_ext = input_video.split(".")[-1]
input_text = "What happens in this video?"
# Read reference video from file and encode as base64 string.
with open(input_video, "rb") as video_file:
content_video = base64.b64encode(video_file.read()).decode('utf8')\
message = {
"role": "user",
"content": [
{
"video": {
"format": video_ext,
"source": {
"bytes": content_video
}
}
},
{
"text": input_text
}
]
}
messages = [message]
response = run_multi_modal_prompt(
bedrock_runtime, model_id, messages, max_tokens)
print(json.dumps(response, indent=4))
except ClientError as err:
message = err.response["Error"]["Message"]
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
if __name__ == "__main__":
main()
```
------
## Exemplo de código de invocação de modelos com streaming
**nota**
O AWS CLI não suporta streaming.
O exemplo a seguir mostra como usar a [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)API para gerar streaming de texto com Python usando o prompt. *write an essay for living on mars in 1000 words*
```
import boto3
import json
brt = boto3.client(service_name='bedrock-runtime')
body = json.dumps({
'prompt': '\n\nHuman: write an essay for living on mars in 1000 words\n\nAssistant:',
'max_tokens_to_sample': 4000
})
response = brt.invoke_model_with_response_stream(
modelId='anthropic.claude-v2',
body=body
)
stream = response.get('body')
if stream:
for event in stream:
chunk = event.get('chunk')
if chunk:
print(json.loads(chunk.get('bytes').decode()))
```
# Invocar um modelo com a API Chat Completions da OpenAI
Você pode executar a inferência de modelos usando a [API Create chat completion da OpenAI](https://platform.openai.com/docs/api-reference/chat/create) com modelos do Amazon Bedrock.
Você pode chamar a API Create chat completion das seguintes maneiras:
+ Faça uma solicitação HTTP com um endpoint do Amazon Bedrock Runtime.
+ Use uma solicitação de SDK da OpenAI com um endpoint do Amazon Bedrock Runtime.
Escolha um tópico para saber mais:
**Topics**
+ [Modelos e regiões compatíveis para a API Chat Completions da OpenAI](#inference-chat-completions-supported)
+ [Pré-requisitos para usar a API Chat Completions](#inference-chat-completions-prereq)
+ [Criar um preenchimento de chat](#inference-chat-completions-create)
+ [Incluir uma barreira de proteção em um preenchimento de chat](#inference-chat-completions-guardrails)
## Modelos e regiões compatíveis para a API Chat Completions da OpenAI
Você pode usar a API de conclusão de chat Create com todos os OpenAI modelos compatíveis com o Amazon Bedrock e nas AWS regiões que oferecem suporte a esses modelos. Para ter mais informações sobre modelos e regiões compatíveis, consulte [Modelos de base compatíveis no Amazon Bedrock](models-supported.md).
## Pré-requisitos para usar a API Chat Completions
Para ver os pré-requisitos para usar a API Chat Completions, escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ OpenAI SDK ]
+ **Autenticação**: o SDK da OpenAI só permite autenticação com uma chave de API do Amazon Bedrock. Gere uma chave de API do Amazon Bedrock para autenticar sua solicitação. Para saber mais sobre as chaves de API do Amazon Bedrock e como gerá-las, consulte a seção Chaves de API no capítulo Build.
+ **Endpoint** — Encontre o endpoint que corresponde à AWS região a ser usada nos [endpoints e cotas do Amazon Bedrock Runtime](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt). Se você usa um AWS SDK, talvez precise especificar apenas o código da região e não o endpoint inteiro ao configurar o cliente.
+ **Instalar um SDK da OpenAI**: para ter mais informações, consulte [Libraries](https://platform.openai.com/docs/libraries) na documentação da OpenAI.
------
#### [ HTTP request ]
+ **Autenticação** — Você pode se autenticar com suas AWS credenciais ou com uma chave de API Amazon Bedrock.
Configure suas AWS credenciais ou gere uma chave de API Amazon Bedrock para autenticar sua solicitação.
+ Para saber mais sobre como configurar suas AWS credenciais, consulte [Acesso programático com credenciais de AWS segurança](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds-programmatic-access.html).
+ Para saber mais sobre as chaves de API do Amazon Bedrock e como gerá-las, consulte a seção Chaves de API no capítulo Build.
+ **Endpoint** — Encontre o endpoint que corresponde à AWS região a ser usada nos [endpoints e cotas do Amazon Bedrock Runtime](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt). Se você usa um AWS SDK, talvez precise especificar apenas o código da região e não o endpoint inteiro ao configurar o cliente.
------
## Criar um preenchimento de chat
Consulte os seguintes recursos na documentação da OpenAI para obter detalhes sobre a API Create chat completion:
+ [Parâmetros do corpo da solicitação](https://platform.openai.com/docs/api-reference/chat/create)
+ [Parâmetros corporais de resposta](https://platform.openai.com/docs/api-reference/chat/object)
**nota**
No momento, o Amazon Bedrock não permite outras operações da API Chat Completions da OpenAI.
Para saber como usar a API Create chat completion da OpenAI, escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ OpenAI SDK (Python) ]
Para criar um preenchimento de chat com o SDK da OpenAI, faça o seguinte:
1. Importe o SDK da OpenAI e configure o cliente com os seguintes campos:
+ `base_url`: prefixe o endpoint do Amazon Bedrock Runtime como `/openai/v1`, conforme o seguinte formato:
```
https://${bedrock-runtime-endpoint}/openai/v1
```
+ `api_key`: especifique uma chave de API do Amazon Bedrock.
+ `default_headers`: se precisar incluir algum cabeçalho, você pode incluí-lo como pares de chave-valor nesse objeto. Ou você pode especificar cabeçalhos em `extra_headers` ao fazer uma chamada de API específica.
1. Use o método `chat.completions.create()` com o cliente e especifique no mínimo `model` e `messages` no corpo da solicitação.
O exemplo a seguir chama a API Create chat completion na `us-west-2`. *\$1AWS\$1BEARER\$1TOKEN\$1BEDROCK*Substitua pela sua chave de API real.
```
from openai import OpenAI
client = OpenAI(
base_url="https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1",
api_key="$AWS_BEARER_TOKEN_BEDROCK" # Replace with actual API key
)
completion = client.chat.completions.create(
model="openai.gpt-oss-20b-1:0",
messages=[
{
"role": "developer",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
]
)
print(completion.choices[0].message)
```
------
#### [ HTTP request ]
Para criar um preenchimento de chat com uma solicitação HTTP, faça o seguinte:
1. Especifique o URL prefixando o endpoint do Amazon Bedrock Runtime com `/openai/v1/chat/completions`, conforme o seguinte formato:
```
https://${bedrock-runtime-endpoint}/openai/v1/chat/completions
```
1. Especifique suas AWS credenciais ou uma chave de API do Amazon Bedrock no cabeçalho. `Authorization`
1. No corpo da solicitação, especifique pelo menos `model` e `messages` no corpo da solicitação.
O exemplo a seguir usa curl para chamar a API Create chat completion na `us-west-2`. *\$1AWS\$1BEARER\$1TOKEN\$1BEDROCK*Substitua pela sua chave de API real:
```
curl -X POST https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK" \
-d '{
"model": "openai.gpt-oss-20b-1:0",
"messages": [
{
"role": "developer",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
]
}'
```
------
## Incluir uma barreira de proteção em um preenchimento de chat
Para incluir proteções na entrada e nas respostas do modelo, aplique uma [barreira de proteção](guardrails.md) ao executar a invocação do modelo incluindo os seguintes [parâmetros extras](https://github.com/openai/openai-python#undocumented-request-params) como campos no corpo da solicitação:
+ `extra_headers`: está associado a um objeto que conte´m os seguintes campos, que especificam cabeçalhos extras na solicitação:
+ `X-Amzn-Bedrock-GuardrailIdentifier`: (obrigatório) o ID da barreira de proteção.
+ `X-Amzn-Bedrock-GuardrailVersion`: (obrigatório) a versão da barreira de proteção.
+ `X-Amzn-Bedrock-Trace`: (opcional) se é necessário ou não habilitar o rastreamento da barreira de proteção.
+ `extra_body`: está associado a um objeto. Nesse objeto, você pode incluir o campo `amazon-bedrock-guardrailConfig`, que está associado a um objeto que contém os seguintes campos:
+ `tagSuffix`: (opcional) inclua esse campo para [marcação de entrada](guardrails-tagging.md).
Para ter mais informações sobre esses parâmetros nas Barreiras de Proteção do Amazon Bedrock, consulte [Testar uma barreira de proteção](guardrails-test.md).
Para ver exemplos de uso de barreiras de proteção com preenchimentos de chat da OpenAI, escolha a guia correspondente ao método de sua preferência e siga as etapas:
------
#### [ OpenAI SDK (Python) ]
```
import openai
from openai import OpenAIError
# Endpoint for Amazon Bedrock Runtime
bedrock_endpoint = "https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1"
# Model ID
model_id = "openai.gpt-oss-20b-1:0"
# Replace with actual values
bedrock_api_key = "$AWS_BEARER_TOKEN_BEDROCK"
guardrail_id = "GR12345"
guardrail_version = "DRAFT"
client = openai.OpenAI(
api_key=bedrock_api_key,
base_url=bedrock_endpoint,
)
try:
response = client.chat.completions.create(
model=model_id,
# Specify guardrail information in the header
extra_headers={
"X-Amzn-Bedrock-GuardrailIdentifier": guardrail_id,
"X-Amzn-Bedrock-GuardrailVersion": guardrail_version,
"X-Amzn-Bedrock-Trace": "ENABLED",
},
# Additional guardrail information can be specified in the body
extra_body={
"amazon-bedrock-guardrailConfig": {
"tagSuffix": "xyz" # Used for input tagging
}
},
messages=[
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "assistant",
"content": "Hello! How can I help you today?"
},
{
"role": "user",
"content": "What is the weather like today?"
}
]
)
request_id = response._request_id
print(f"Request ID: {request_id}")
print(response)
except OpenAIError as e:
print(f"An error occurred: {e}")
if hasattr(e, 'response') and e.response is not None:
request_id = e.response.headers.get("x-request-id")
print(f"Request ID: {request_id}")
```
------
#### [ OpenAI SDK (Java) ]
```
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpResponseFor;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
// Endpoint for Amazon Bedrock Runtime
String bedrockEndpoint = "http://bedrock-runtime.us-west-2.amazonaws.com/openai/v1"
// Model ID
String modelId = "openai.gpt-oss-20b-1:0"
// Replace with actual values
String bedrockApiKey = "$AWS_BEARER_TOKEN_BEDROCK"
String guardrailId = "GR12345"
String guardrailVersion = "DRAFT"
OpenAIClient client = OpenAIOkHttpClient.builder()
.apiKey(bedrockApiKey)
.baseUrl(bedrockEndpoint)
.build()
ChatCompletionCreateParams request = ChatCompletionCreateParams.builder()
.addUserMessage("What is the temperature in Seattle?")
.model(modelId)
// Specify additional headers for the guardrail
.putAdditionalHeader("X-Amzn-Bedrock-GuardrailIdentifier", guardrailId)
.putAdditionalHeader("X-Amzn-Bedrock-GuardrailVersion", guardrailVersion)
// Specify additional body parameters for the guardrail
.putAdditionalBodyProperty(
"amazon-bedrock-guardrailConfig",
JsonValue.from(Map.of("tagSuffix", JsonValue.of("xyz"))) // Allows input tagging
)
.build();
HttpResponseFor rawChatCompletionResponse =
client.chat().completions().withRawResponse().create(request);
final ChatCompletion chatCompletion = rawChatCompletionResponse.parse();
System.out.println(chatCompletion);
```
------
# Realizar uma conversa com as operações de API Converse
É 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: [Exemplos de API Converse](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)
**Topics**
+ [Modelos compatíveis e recursos do modelo](conversation-inference-supported-models-features.md)
+ [Usar a API Converse](conversation-inference-call.md)
+ [Exemplos de API Converse](conversation-inference-examples.md)
# Modelos compatíveis e recursos do modelo
A API Converse pode ser usada com os modelos e recursos de modelo a seguir do Amazon Bedrock. Não é possível usar a API Converse em nenhum modelo de incorporação ou geração de imagens.
| Modelo | Converse | ConverseStream | Prompts do sistema | Chat de documentos | Visão | Uso de ferramentas | Uso de ferramentas de streaming | Barreiras de proteção | Links do Amazon S3 para multimídia |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| AI21 Jamba-Instruct | Sim | Sim | Sim | Não | Não | Não | Não | Não | Não |
| Jurassic-2 (Text) da AI21 Labs | Limitado. Incompatível com chat. | Não | Não | Não | Não | Não | Não | Sim | Não |
| AI21 Labs Jamba 1.5 Large | Sim | Sim | Sim | Sim | Não | Sim | Sim | Sim | Não |
| AI21 Labs Jamba 1.5 Mini | Sim | Sim | Sim | Sim | Não | Sim | Sim | Sim | Não |
| Amazon Nova Premier | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim |
| Amazon Nova Pro | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim |
| Amazon Nova Lite | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim |
| Amazon Nova Micro | Sim | Sim | Sim | Não | Não | Sim | Sim | Sim | Não |
| Modelos do Amazon Titan | Sim | Sim | Não | Sim (exceto Titan Text Premier) | Não | Não | Não | Sim | Não |
| Modelos Claude 2.x e anteriores da Anthropic | Sim | Sim | Sim | Sim | Não | Não | Não | Sim | Não |
| Modelos Claude 3 da Anthropic | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Não |
| Anthropic Claude 3.5 Sonnet | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Não |
| Claude 3.5 Sonnet v2 da Anthropic | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Não |
| Anthropic Claude 3.7 Sonnet | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Não |
| Anthropic Claude 3.5 Haiku | Sim | Sim | Sim | Sim | Não | Sim | Sim | Não | Não |
| Anthropic Claude Sonnet 4 | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Não | Não |
| AnthropicClaude Opus4 | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Não | Não |
| Anthropic Claude Sonnet 4.5 | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Não | Não |
| Anthropic Claude Haiku 4.5 | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Não | Não |
| AnthropicClaude Opus4.1 | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Não | Não |
| Claude Opus4.5 | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Não | Não |
| Cohere Command | Limitado. Incompatível com chat. | Limitado. Incompatível com chat. | Não | Sim | Não | Não | Não | Sim | Não |
| Cohere Command Light | Limitado. Incompatível com chat. | Limitado. Incompatível com chat. | Não | Não | Não | Não | Não | Sim | Não |
| Command R e Command R\$1 da Cohere | Sim | Sim | Sim | Sim | Não | Sim | Sim | Não | Não |
| DeepSeek-R1 | Sim | Sim | Sim | Sim | Não | Não | Não | Sim | Não |
| Llama 2 e Llama 3 da Meta | Sim | Sim | Sim | Sim | Não | Não | Não | Sim | Não |
| Meta Llama 3.1 | Sim | Sim | Sim | Sim | Não | Sim | Não | Sim | Não |
| Meta Llama 3.2 1b and Llama 3.2 3b | Sim | Sim | Sim | Sim | Não | Não | Não | Sim | Não |
| Meta Llama 3.2 11b and Llama 3.2 90b | Sim | Sim | Sim | Sim | Sim | Sim | Não | Sim | Não |
| Meta Llama 4 Maverick 17B and Llama 4.0 Scout 17B | Sim | Sim | Sim | Sim | Sim | Sim | Não | Sim | Não |
| Mistral AI Instruct | Sim | Sim | Não | Sim | Não | Não | Não | Sim | Não |
| Mistral Large | Sim | Sim | Sim | Sim | Não | Sim | Não | Sim | Não |
| Mistral Large 2 (24.07) | Sim | Sim | Sim | Sim | Não | Sim | Não | Sim | Não |
| Mistral Small | Sim | Sim | Sim | Não | Não | Sim | Não | Sim | Não |
| Pixtral Large (25.02) | Sim | Sim | Sim | Sim | Não | Sim | Não | Sim | Não |
| Writer Palmyra X4 | Sim | Sim | Sim | Sim | Não | Sim | Não | Sim | Não |
| Writer Palmyra X5 | Sim | Sim | Sim | Sim | Não | Sim | Não | Sim | Não |
Para ver uma tabela das regiões nas quais é possível usar cada modelo, consulte [Suporte de modelos Região da AWS no Amazon Bedrock](models-regions.md).
**nota**
Não é possível usar chat no Command (Text) da Cohere e no Jurassic-2 (Text) da AI21 Labs com a API Converse. Os modelos só podem lidar com uma mensagem de usuário por vez e não podem manter o histórico de uma conversa. Você receberá um erro se tentar passar mais de uma mensagem.
# Usar a API Converse
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`.
**Topics**
+ [Solicitação](#conversation-inference-call-request)
+ [Resposta](#conversation-inference-call-response)
**nota**
As restrições se aplicam às seguintes operações: InvokeModel InvokeModelWithResponseStream,, Converse e. ConverseStream Consulte as [restrições da API](inference-api-restrictions.md) para obter detalhes.
## 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.
+ **additionalModelRequestCampos** — 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.
+ **additionalModelResponseFieldPaths**— 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[Modelos compatíveis e recursos do modelo](conversation-inference-supported-models-features.md)):
------
#### [ 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 ]
É possível adicionar pontos de verificação de cache como um bloco em uma mensagem ao lado de um prompt anexado usando campos `cachePoint` para utilizar o armazenamento em cache de prompts. 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 é mapeado 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}
```
### additionalModelRequestCampos
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 *\$1\$1genre\$1\$1* playlist consisting of the following number of songs: *\$1\$1number\$1\$1*.** 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" : "pop",
"number": 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 [Incluir uma barreira de proteção com a API Converse](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).
### additionalModelResponseFieldPaths
É 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
Esse campo está associado a um objeto JSON. É possível especificar as chaves e os valores de metadados com os quais ele está associado dentro desse objeto. Você pode usar metadados de solicitação para ajudar a filtrar os logs de invocação do modelo.
### 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`.
**Topics**
+ [Resposta de Converse](#conversation-inference-call-response-converse)
+ [ConverseStream resposta](#conversation-inference-call-response-converse-stream)
### 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, `cacheReadInputTokensCount` e `cacheWriteInputTokensCount` 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 para a 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}}}
```
# Exemplos de API Converse
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()
```
------
# Restrições de API
As restrições a seguir se aplicam às `ConverseStream` operações `InvokeModel` `InvokeModelWithResponseStream``Converse`,, e. Algumas restrições variam de acordo com a operação ou o modelo, conforme indicado abaixo:
+ Ao usar essas operações, você só pode incluir imagens e documentos se `role` houver`user`.
+ **Geração de vídeo:** a geração de vídeo não é compatível com `InvokeModel` `InvokeModelWithResponseStream` e. Em vez disso, você pode usar a [StartAsyncInvoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_StartAsyncInvoke.html)operação. Para conferir um exemplo, consulte [Usar o Amazon Nova Reel para gerar um vídeo de um prompt de texto](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_Scenario_AmazonNova_TextToVideo_section.html).
+ **Suporte de documentos no corpo da solicitação:** A inclusão de documentos no corpo da solicitação não é suportada ao usar `InvokeModel` `InvokeModelWithResponseStream` e. Para incluir um documento durante a inferência, use o [playground de bate-papo/texto](playgrounds.md) nas operações Console de gerenciamento da AWS ou use o `Converse` ou. `ConverseStream`
+ **Contagem e tamanho do documento:** você pode incluir até 5 documentos por solicitação. Cada documento não pode ter mais do que 4,5 MB de tamanho. Para Claude 4 e versões posteriores, a restrição de tamanho do documento de 4,5 MB não se aplica ao `PDF` formato. Para modelos Nova, a restrição de tamanho de documento de 4,5 MB não se aplica aos `DOCX` formatos `PDF` e formatos. Essas restrições continuam sendo aplicadas no console Bedrock. Modelos individuais podem ter restrições de conteúdo adicionais além das aplicadas pelo Amazon Bedrock. Para obter mais informações, consulte **Requisitos de fornecedores de modelos terceirizados**.
+ **Contagem e tamanho das imagens**: o Amazon Bedrock não impõe restrições à contagem e ao tamanho das imagens. No entanto, modelos individuais podem ter requisitos específicos de imagem. Para obter mais informações, consulte **Requisitos de fornecedores de modelos terceirizados**.
+ **Requisitos do provedor de modelos terceirizado:** os requisitos do provedor de modelos terceirizado se aplicam quando você usa `InvokeModel` `InvokeModelWithResponseStream``Converse`,, e `ConverseStream` opera, e podem resultar em um erro se não forem atendidos. Se você usa um modelo de terceiros por meio do Amazon Bedrock (por exemplo, Anthropic Claude), consulte o guia do usuário e a documentação da API do provedor para evitar erros inesperados. Por exemplo, o endpoint padrão Anthropic Messages suporta um tamanho máximo de solicitação de 32 MB. Claude também tem requisitos específicos de conteúdo, como um máximo de 100 `PDF` páginas por solicitação e um tamanho máximo de imagem de 8000x8000 px. [Para obter as informações mais recentes sobre solicitações e respostas do Anthropic Claude Messages, incluindo requisitos de tamanho e conteúdo da solicitação, consulte a seguinte documentação do Anthropic Claude: [Visão geral da API do Anthropic Claude, Referência da API do Anthropic Claude](https://platform.claude.com/docs/en/api/overview)[Messages, Build with Claude](https://docs.anthropic.com/claude/reference/messages_post): [Vision e Build with Claude](https://platform.claude.com/docs/en/build-with-claude/vision): PDF Support.](https://platform.claude.com/docs/en/build-with-claude/pdf-support)
**dica**
Claude exige que os documentos PDF tenham no máximo 100 páginas por solicitação. Se você tiver documentos PDF maiores, recomendamos dividi-los em vários PDFs com menos de 100 páginas cada ou consolidar mais texto em menos páginas.
# Obtenha resultados JSON validados de modelos
As saídas estruturadas são um recurso do Amazon Bedrock que garante que as respostas do modelo estejam em conformidade com os esquemas JSON e as definições de ferramentas definidos pelo usuário, reduzindo a necessidade de mecanismos personalizados de análise e validação em implantações de IA de produção.
## Benefícios
Os resultados estruturados abordam desafios críticos em aplicativos de IA de produção:
+ **Garante a conformidade do esquema** — elimina as taxas de erro e os ciclos de repetição a partir de abordagens baseadas em prompts
+ **Complexidade de desenvolvimento reduzida** — elimina a necessidade de lógica personalizada de análise e validação
+ **Custos operacionais mais baixos** — reduz solicitações e novas tentativas malsucedidas
+ **Confiabilidade de produção** — permite a implantação confiável de aplicativos de IA que exigem saídas previsíveis e legíveis por máquina
## Como funciona
As saídas estruturadas restringem as respostas do modelo para que sigam um esquema específico, garantindo uma saída válida e analisável para o processamento posterior. Você pode usar saídas estruturadas por meio de dois mecanismos complementares:
### Formato de saída do esquema JSON
Para InvokeModel API com modelos Anthropic Claude, use o campo de `output_config.format` solicitação. Com modelos de peso aberto, use o campo de `response_format` solicitação. Para Converse APIs, use o campo de `outputConfig.textFormat` solicitação. A resposta do modelo estará em conformidade com o esquema JSON especificado.
### Uso estrito de ferramentas
Adicione o `strict: true` sinalizador às definições da ferramenta para habilitar a validação do esquema nos nomes e entradas das ferramentas. As chamadas de ferramentas do modelo seguirão então o esquema de entrada da ferramenta definido.
Esses mecanismos podem ser usados de forma independente ou em conjunto na mesma solicitação. Consulte a [documentação da API Bedrock](https://docs.aws.amazon.com/bedrock/latest/APIReference/welcome.html) para obter mais detalhes.
### Solicitar fluxo de trabalho
A seguir, descrevemos como o Amazon Bedrock processa solicitações com saídas estruturadas:
1. **Solicitação inicial** — Você inclui um esquema JSON por meio do `response_format` parâmetro `outputConfig.textFormat``output_config.format`, ou ou uma definição de ferramenta com o `strict: true` sinalizador em sua solicitação de inferência.
1. **Validação do esquema** — O Amazon Bedrock valida o formato do esquema JSON em relação ao subconjunto compatível do JSON Schema Draft 2020-12. Se o esquema contiver recursos não suportados, o Amazon Bedrock retornará imediatamente um erro 400.
1. **Primeira compilação** — Para novos esquemas, o Amazon Bedrock compila a gramática, o que pode levar alguns minutos.
1. **Cache** — As gramáticas compiladas com sucesso são armazenadas em cache por 24 horas a partir do primeiro acesso. As gramáticas em cache são criptografadas com chaves gerenciadas pela AWS.
1. **Solicitações subsequentes** — esquemas idênticos da mesma conta usam gramáticas em cache, resultando em latência de inferência comparável às solicitações padrão com sobrecarga mínima.
1. **Resposta** — Você recebe respostas de inferência padrão com estrita conformidade com o esquema.
## Compatível APIs com nossos recursos
Você pode usar saídas estruturadas nos seguintes recursos do Amazon Bedrock:
**Converse e ConverseStream APIs** — Use saídas estruturadas com o Converse e ConverseStream APIs para inferência conversacional.
**InvokeModel e InvokeModelWithResponseStream APIs** — Use saídas estruturadas com InvokeModel e InvokeModelWithResponseStream APIs para inferência de turno único.
**Inferência entre regiões** — Use saídas estruturadas na inferência entre regiões sem nenhuma configuração adicional.
**Inferência em lote** — Use saídas estruturadas na inferência em lote sem nenhuma configuração adicional.
**nota**
Os resultados estruturados são incompatíveis com as citações de modelos antrópicos. Se você ativar as citações ao usar saídas estruturadas, o modelo retornará um erro 400.
## Modelos compatíveis
As saídas estruturadas geralmente estão disponíveis em todas as regiões comerciais da AWS para os modelos sem servidor selecionados do Amazon Bedrock. Para ver a lista de modelos compatíveis, consulte Suporte de modelo por recurso.
### Veja todos os modelos compatíveis
Anthropic
+ Claude Haicai 4.5 () `anthropic.claude-haiku-4-5-20251001-v1:0`
+ Claude Sonnet 4.5 () `anthropic.claude-sonnet-4-5-20250929-v1:0`
+ Claude Opus 4.5 () `anthropic.claude-opus-4-5-20251101-v1:0`
+ Claude Opus 4.6 () `anthropic.claude-opus-4-6-v1`
Qwen
+ Qen3 235B A2B 2507 () `qwen.qwen3-235b-a22b-2507-v1:0`
+ Qwen3 32B (denso) () `qwen.qwen3-32b-v1:0`
+ Instrução do codificador Qwen3-30B-A3B () `qwen.qwen3-coder-30b-a3b-v1:0`
+ Instrução do codificador Qwen3 480B A35B () `qwen.qwen3-coder-480b-a35b-v1:0`
+ Qwen3 Next 80B A3B () `qwen.qwen3-next-80b-a3b`
+ Qwen3 VL 235B A2B (2) `qwen.qwen3-vl-235b-a22b`
OpenAI
+ gpt-oss-120b () `openai.gpt-oss-120b-1:0`
+ gpt-oss-20b () `openai.gpt-oss-20b-1:0`
+ GPT OSS Safeguard 120B () `openai.gpt-oss-safeguard-120b`
+ Proteção GPT OSS 20B () `openai.gpt-oss-safeguard-20b`
DeepSeek
+ DeepSeek-V3.1 () `deepseek.v3-v1:0`
Google
+ Gemma 3 12B IT () `google.gemma-3-12b-it`
+ Gemma 3 27B PT (1) `google.gemma-3-27b-it`
MiniMax
+ MiniMax M2 (`minimax.minimax-m2`)
Mistral AI
+ Magistral Small 2509 (2) `mistral.magistral-small-2509`
+ Ministerial (3) `mistral.ministral-3-3b-instruct`
+ Ministerial 3 (8B) `mistral.ministral-3-8b-instruct`
+ Ministral 14B 3.0 (3) `mistral.ministral-3-14b-instruct`
+ Mistral Grande (3) `mistral.mistral-large-3-675b-instruct`
+ Voxtral Mini 3B 2507 () `mistral.voxtral-mini-3b-2507`
+ Voxtral Small 24B 2507 () `mistral.voxtral-small-24b-2507`
IA do Moonshot
+ Kimi K2 Pensando () `moonshot.kimi-k2-thinking`
NVIDIA
+ NVIDIA Nemotron Nano 12 GB v2 VL () BF16 `nvidia.nemotron-nano-12b-v2`
+ NVIDIA Nemotron Nano 9B v2 () `nvidia.nemotron-nano-9b-v2`
## Exemplo de solicitações
### Formato de saída do esquema JSON
Os exemplos a seguir mostram como usar o formato de saída do esquema JSON com saídas estruturadas.
#### API Converse
##### Veja um exemplo
```
{
"messages": [
{
"role": "user",
"content": [
{
"text": "Given the following unstructured data, extract it into the provided structure."
},
{
"text": "..."
}
]
}
],
"outputConfig": {
"textFormat": {
"type": "json_schema",
"structure": {
"jsonSchema": {
"schema": "{\"type\": \"object\", \"properties\": {\"title\": {\"type\": \"string\", \"description\": \"title\"}, \"summary\": {\"type\": \"string\", \"description\": \"summary\"}, \"next_steps\": {\"type\": \"string\", \"description\": \"next steps\"}}, \"required\": [\"title\", \"summary\", \"next_steps\"], \"additionalProperties\": false}",
"name": "data_extraction",
"description": "Extract structured data from unstructured text"
}
}
}
}
}
```
#### InvokeModel (Claude antrópico)
##### Veja um exemplo
```
{
"anthropic_version": "bedrock-2023-05-31",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Given the following unstructured data, extract it into the provided structure."
},
{
"type": "text",
"text": "..."
}
]
}
],
"max_tokens": 3000,
"temperature": 1.0,
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "title"
},
"summary": {
"type": "string",
"description": "summary"
},
"next_steps": {
"type": "string",
"description": "next steps"
}
},
"required": [
"title",
"summary",
"next_steps"
],
"additionalProperties": false
}
}
}
}
```
#### InvokeModel (Modelos de peso aberto)
##### Veja um exemplo
```
{
"messages": [
{
"role": "user",
"content": "Given the following unstructured data, extract it into the provided structure."
},
{
"role": "user",
"content": "..."
}
],
"inferenceConfig": {
"maxTokens": 3000,
"temperature": 1.0
},
"response_format": {
"json_schema": {
"name": "summarizer",
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "title"
},
"summary": {
"type": "string",
"description": "summary"
},
"next_steps": {
"type": "string",
"description": "next steps"
}
},
"required": [
"title",
"summary",
"next_steps"
],
"additionalProperties": false
}
},
"type": "json_schema"
}
}
```
### Uso estrito de ferramentas
Os exemplos a seguir mostram como usar o campo estrito com o uso de ferramentas.
#### API Converse
##### Veja um exemplo
```
{
"messages": [
{
"role": "user",
"content": [
{
"text": "What's the weather like in New York?"
}
]
}
],
"toolConfig": {
"tools": [
{
"toolSpec": {
"name": "get_weather",
"description": "Get the current weather for a specified location",
"strict": true,
"inputSchema": {
"json": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"fahrenheit",
"celsius"
],
"description": "The temperature unit to use"
}
},
"required": [
"location",
"unit"
]
}
}
}
}
]
}
}
```
#### InvokeModel (Claude antrópico)
##### Veja um exemplo
```
{
"anthropic_version": "bedrock-2023-05-31",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What's the weather like in San Francisco?"
}
]
}
],
"max_tokens": 3000,
"temperature": 1.0,
"tools": [
{
"name": "get_weather",
"description": "Get the current weather for a specified location",
"strict": true,
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"fahrenheit",
"celsius"
],
"description": "The temperature unit to use"
}
},
"required": [
"location",
"unit"
],
"additionalProperties": false
}
}
]
}
```
#### InvokeModel (Modelos de peso aberto)
##### Veja um exemplo
```
{
"messages": [
{
"role": "user",
"content": "What's the weather like in San Francisco?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a specified location",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"fahrenheit",
"celsius"
],
"description": "The temperature unit to use"
}
},
"required": [
"location",
"unit"
]
}
}
}
],
"tool_choice": "auto",
"max_tokens": 2000,
"temperature": 1.0
}
```
# Use uma ferramenta Computer Use para concluir uma resposta do modelo do Amazon Bedrock
Computer Use é um recurso do modelo Claude da Anthropic (em versão beta) disponível somente com o Claude 3.7 Sonnet e Claude 3.5 Sonnet v2 da Anthropic. Com o Computer Use, o Claude pode ajudar a automatizar tarefas por meio de ações básicas da GUI.
**Atenção**
O recurso de uso do computador é disponibilizado para você como um “Serviço Beta”, conforme definido nos Termos do AWS Serviço. Está sujeito ao seu Contrato AWS e aos Termos AWS de Serviço e ao modelo de EULA aplicável. Esteja ciente de que a API Computer Use apresenta riscos exclusivos que são distintos dos recursos padrão de API ou das interfaces de chat. Esses riscos aumentam ao usar a API Computer Use para interagir com a internet. Para minimizar os riscos, considere tomar precauções, como:
Operar a funcionalidade Computer Use em uma máquina virtual ou contêiner dedicado com privilégios mínimos para evitar acidentes ou ataques diretos ao sistema.
Para impedir o roubo de informações, evite fornecer à API Computer Use acesso a contas ou dados sensíveis.
Limitar o acesso à internet das APIs Computer Use aos domínios necessários para reduzir a exposição a conteúdo mal-intencionado.
Para garantir a supervisão adequada, mantenha uma pessoa informada sobre tarefas confidenciais (como tomar decisões que possam ter consequências significativas no mundo real) e sobre qualquer coisa que exija consentimento afirmativo (como aceitar cookies, executar transações financeiras ou concordar com os termos de serviço).
Qualquer conteúdo que você permita que o Claude veja ou acesse pode potencialmente substituir as instruções ou provocar erros no Claude ou executar ações indesejadas. Tomar as devidas precauções, como isolar o Claude de superfícies confidenciais, é essencial, inclusive para evitar riscos relacionados à injeção de prompt. Antes de habilitar ou solicitar as permissões necessárias para habilitar os recursos do Computer Use em seus próprios produtos, informe os usuários finais sobre quaisquer riscos relevantes e obtenha o consentimento deles conforme apropriado.
A API Computer Use oferece várias ferramentas predefinidas de Computer Use (*computer\$120241022*, *bash\$120241022* e *text\$1editor\$120241022*). É possível criar um prompt com sua solicitação, como “enviar um e-mail para Ben com as anotações da minha última reunião” e uma captura de tela (quando necessário). A resposta contém uma lista de ações de `tool_use` no formato JSON (por exemplo, scroll\$1down, left\$1button\$1press, screenshot). Seu código executa as ações do computador e fornece ao Claude uma captura de tela mostrando as saídas (quando solicitado).
O parâmetro tools foi atualizado para aceitar tipos de ferramentas polimórficas; uma nova propriedade `tool.type` está sendo adicionada para diferenciá-las. `type` é opcional; se omitida, a ferramenta será considerada uma ferramenta personalizada (anteriormente o único tipo de ferramenta compatível). Além disso, um novo parâmetro, `anthropic_beta`, foi adicionado, com um valor de enumeração correspondente: `computer-use-2024-10-22`. Somente solicitações feitas com esse parâmetro e enum podem usar as novas ferramentas de Computer Use. Ele pode ser especificado da seguinte forma: `"anthropic_beta": ["computer-use-2024-10-22"] `.
Para usar o computador com a Anthropic Claude 3.5 Sonnet v2, você pode usar a Converse API ([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)). Defina os campos específicos de Computer Use no campo `additionalModelRequestFields`. Para ter informações gerais sobre como chamar a API Converse, consulte [Realizar uma conversa com as operações de API Converse](conversation-inference.md).
É possível usar ferramentas com as operações de inferência de base ([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 encontrar os parâmetros de inferência que você passa no corpo da solicitação, consulte [API Messages do Claude da Anthropic](model-parameters-anthropic-claude-messages.md).
Para obter mais informações, consulte [Computer Use (beta)](https://docs.anthropic.com/en/docs/build-with-claude/computer-use) na documentação da Anthropic.
**Topics**
+ [Código de exemplo](#computer-use-example-code)
+ [Exemplo de resposta](#example-response)
## Código de exemplo
O código a seguir mostra como chamar a API Computer Use. A entrada é uma imagem do AWS console.
```
with open('test_images/console.png', 'rb') as f:
png = f.read()
response = bedrock.converse(
modelId='anthropic.claude-3-5-sonnet-20241022-v2:0',
messages=[
{
'role': 'user',
'content': [
{
'text': 'Go to the bedrock console'
},
{
'image': {
'format': 'png',
'source': {
'bytes': png
}
}
}
]
}
],
additionalModelRequestFields={
"tools": [
{
"type": "computer_20241022",
"name": "computer",
"display_height_px": 768,
"display_width_px": 1024,
"display_number": 0
},
{
"type": "bash_20241022",
"name": "bash",
},
{
"type": "text_editor_20241022",
"name": "str_replace_editor",
}
],
"anthropic_beta": ["computer-use-2024-10-22"]
},
toolConfig={
'tools': [
{
'toolSpec': {
'name': 'get_weather',
'inputSchema': {
'json': {
'type': 'object'
}
}
}
}
]
})
print(json.dumps(response, indent=4))
```
## Exemplo de resposta
O exemplo de código emite saída semelhante à seguinte.
```
{
"id": "msg_bdrk_01Ch8g9MF3A9FTrmeywrwfMZ",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I can see from the screenshot that we're already in the AWS Console. To go to the Amazon Bedrock console specifically, I'll click on the Amazon Bedrock service from the \"Recently Visited\" section."
},
{
"type": "tool_use",
"id": "toolu_bdrk_013sAzs1gsda9wLrfD8bhYQ3",
"name": "computer",
"input": {
"action": "screenshot"
}
}
],
"stop_reason": "tool_use",
"stop_sequence": null,
"usage": {
"input_tokens": 3710,
"output_tokens": 97
}
}
```