# Usar a API Converse A API Converse fornece uma interface unificada para interagir com os modelos do Amazon Nova. Ela abstrai detalhes específicos do modelo e fornece uma maneira consistente de lidar com conversas em vários turnos, prompts do sistema e respostas de streaming em todos os modelos do Amazon Nova. **Topics** + [Estrutura de solicitações](#converse-api-request-structure) + [Uso de prompts do sistema](#converse-api-system-prompt) + [Parâmetros de inferência](#converse-api-inference-params) + [Uso do raciocínio](#converse-api-reasoning) ## Estrutura de solicitações + **Conversas em vários turnos:** mantenha o contexto em várias interações + **Prompts do sistema:** instruções do sistema, como personas ou diretrizes de resposta + **Chat de documentos:** interaja com e consulte documentos ou coleções de documentos + **Visão:** processe e analise imagens e vídeos + **Uso de ferramentas:** permita que os modelos usem ferramentas e APIs externas + **Barreiras de proteção:** aplique filtros de conteúdo e controles de segurança + **Raciocínio:** pensamento estendido para a resolução de problemas complexos Uma solicitação básica da API Converse inclui o ID do modelo e uma lista de mensagens: ``` import boto3 bedrock = boto3.client('bedrock-runtime', region_name='us-east-1') response = bedrock.converse( modelId='us.amazon.nova-2-lite-v1:0', messages=[ { 'role': 'user', 'content': [{'text': 'What is machine learning?'}] } ] ) content_list = response["output"]["message"]["content"] # Extract the first text block text = next((item["text"] for item in content_list if "text" in item), None) if text is not None: print(text) ``` ## Uso de prompts do sistema Prompts do sistema fornecem instruções e contexto ao modelo: ``` import boto3 bedrock = boto3.client('bedrock-runtime', region_name='us-east-1') response = bedrock.converse( modelId='us.amazon.nova-2-lite-v1:0', system=[ {'text': 'You are a helpful AI assistant specializing in cloud computing.'} ], messages=[ { 'role': 'user', 'content': [{'text': 'Explain serverless computing.'}] } ] ) # Print the response text content_list = response["output"]["message"]["content"] text = next((item["text"] for item in content_list if "text" in item), None) if text is not None: print(text) ``` ## Parâmetros de inferência Controle a saída do modelo usando parâmetros de inferência. Os parâmetros de inferência a seguir estão disponíveis. + maxTokens (número inteiro): número máximo de tokens a serem gerados (até 65.000). Se não for especificado, o modelo usa um padrão dinâmico com base no contexto da solicitação. + temperature (flutuação): controla a randomização (0,0 a 1,0, padrão 0,7). Valores mais baixos tornam a saída mais determinística + topP (flutuação): limite de amostragem por núcleo (0 a 1, padrão 0,9). Valores mais baixos tornam a saída mais focada + stopSequences (matriz): sequências de caracteres que interrompem a geração ao serem detectadas Exemplo: ``` import boto3 bedrock = boto3.client('bedrock-runtime', region_name='us-east-1') response = bedrock.converse( modelId='us.amazon.nova-2-lite-v1:0', messages=[ { 'role': 'user', 'content': [{'text': 'Write a short story.'}] } ], inferenceConfig={ 'maxTokens': 512, 'temperature': 0.7, 'topP': 0.9, 'stopSequences': ['END'] } ) content_list = response["output"]["message"]["content"] text = next((item["text"] for item in content_list if "text" in item), None) if text is not None: print(text) ``` ## Uso do raciocínio O Nova 2 Lite é compatível com o pensamento estendido para a resolução de problemas complexos. Habilite o raciocínio com `reasoningConfig`. Por padrão, o raciocínio está desabilitado para otimizar a velocidade e o custo em consultas simples. Quando precisar ir além dessas tarefas simples, você pode habilitar o raciocínio. O Nova 2 permite controlar de forma flexível a profundidade de raciocínio por meio de três níveis de esforço: Baixo esforço (`maxReasoningEffort: "low"`) IDEAL PARA: TAREFAS COM MAIOR COMPLEXIDADE QUE EXIGEM PENSAMENTO ESTRUTURADO. Por exemplo, você pode usar para análise de código e sugestões de melhoria em que o modelo precisa considerar cuidadosamente a qualidade do código existente, tarefas de análise que exigem consideração cuidadosa de vários fatores ou cenários de solução de problemas que se beneficiam de uma abordagem metódica. O baixo esforço é ideal para tarefas compostas em que o raciocínio básico melhora a precisão sem exigir um planejamento profundo em várias etapas. Esforço médio (`maxReasoningEffort: "medium"`) IDEAL PARA: TAREFAS DE VÁRIAS ETAPAS E FLUXOS DE TRABALHO DE CODIFICAÇÃO. Por exemplo, você pode usar para desenvolvimento e depuração de software em que o modelo precisa entender a estrutura de código existente antes de implementar alterações, geração de código que requer coordenação entre vários arquivos ou componentes, cálculos de várias etapas com interdependências ou tarefas de planejamento com várias restrições. O esforço médio é ideal para fluxos de trabalho agênticos que coordenam várias ferramentas e exigem que o modelo mantenha o contexto em várias operações sequenciais. Alto esforço (`maxReasoningEffort: "high"`) IDEAL PARA: RACIOCÍNIO LÓGICO-CIENTÍFICO E RESOLUÇÃO AVANÇADA DE PROBLEMAS. Por exemplo, você pode usar para comprovações e problemas matemáticos avançados que exigem verificação passo a passo rigorosa, análise científica e tarefas de pesquisa que exigem investigação aprofundada, design de sistema complexo com considerações de arquitetura em várias dimensões ou cenários críticos de tomada de decisão com implicações significativas. O alto esforço proporciona a máxima precisão para tarefas que exigem raciocínio sofisticado, avaliação cuidadosa das alternativas e validação completa das conclusões. Os seguintes exemplos mostram diferentes níveis de esforço de raciocínio: ------ #### [ Low effort ] ``` import boto3 bedrock = boto3.client('bedrock-runtime', region_name='us-east-1') response = bedrock.converse( modelId='us.amazon.nova-2-lite-v1:0', system=[{"text": "You are a highly capable personal assistant"}], messages=[{ "role": "user", "content": [{"text": "Provide a meal plan for a gluten free family of 4."}] }], inferenceConfig={ "temperature": 0.7, "topP": 0.9, "maxTokens": 10000 }, additionalModelRequestFields={ "reasoningConfig": { "type": "enabled", "maxReasoningEffort": "low" } } ) ``` ------ ** Parâmetros de raciocínio: ** Confira abaixo os parâmetros de raciocínio + `type`: `enabled` ou `disabled` (padrão: `disabled`) + `maxReasoningEffort`: `low`, `medium`, ou `high`. É necessário quando o raciocínio está habilitado. **nota** Temperature, topP e topK não podem ser usados com `maxReasoningEffort` definido como `high`. Isso causará um erro. A resposta inclui conteúdo de raciocínio: ``` { "output": { "message": { "role": "assistant", "content": [ { "reasoningContent": { "reasoningText": { "text": "[REDACTED]" } } }, { "text": "Based on the premises, we can conclude..." } ] } }, "stopReason": "end_turn" } ``` **nota** Com o Amazon Nova 2, o conteúdo de raciocínio é exibido como `[REDACTED]`. Você ainda é cobrado pelos tokens de raciocínio, pois eles contribuem para melhorar a qualidade da saída. Esse campo foi incluído na estrutura de respostas para preservar a opção de expor o conteúdo de raciocínio no futuro. Estamos trabalhando ativamente com os clientes para determinar a melhor abordagem para desenvolver o processo de raciocínio do modelo.