View a markdown version of this page

Solução de problemas - Amazon Nova
Autenticação e configuraçãoAcesso ao modelo negadoProblemas de disponibilidade regionalConfiguração de tempo limiteProblemas de respostas das APIsErros do modo de raciocínioProblemas de uso das ferramentas

Solução de problemas

Esta seção fornece soluções para problemas comuns ao trabalhar com modelos do Amazon Nova.

Autenticação e configuração

Permissões ausentes

Sintomas: não é possível acessar os modelos ou recursos do Nova

Solução:

  • Certifique-se de que seu perfil do IAM tenha a permissão Amazon-BedrockFullAccess ou as permissões apropriadas

  • Solicite acesso a modelos específicos por meio do console do Amazon Bedrock

  • Verifique as permissões para acesso ao modelo e uso da ferramenta

Acesso ao modelo negado

Sintomas: falha na solicitação de acesso ao modelo

Solução:

  • Solicite acesso a modelos específicos por meio do console do Amazon Bedrock

  • Verifique se sua conta possui permissão para acessar o modelo solicitado

  • Confira a disponibilidade regional do modelo

Problemas de disponibilidade regional

Sintomas: recurso não disponível na região selecionada

Solução:

  • A Ancoragem na Web está disponível somente nas regiões dos EUA com os perfis CRIS dos EUA

  • Verifique se o modelo e os recursos estão disponíveis na região selecionada

  • Mude para uma região com suporte, se necessário

Configuração de tempo limite

Sintomas: o tempo limite das solicitações é atingido antes da conclusão

Causa: tempo limite padrão muito curto para operações complexas

Solução: defina as configurações de tempo limite estendido

from botocore.config import Config

bedrock = boto3.client(
    'bedrock-runtime',
    region_name='us-east-1',
    config=Config(
        read_timeout=3600      # 60 minutes
    )
)
nota

As solicitações de inferência do Amazon Nova podem levar até 60 minutos para operações complexas.

Problemas de respostas das APIs

Compreensão dos motivos da interrupção:

end_turn

Conclusão normal. Nenhuma ação é necessária.

max_tokens

Limite de tokens atingido.

Solução: aumente o parâmetro maxTokens em inferenceConfig.

content_filtered

O conteúdo violou a política de IA responsável da AWS.

Solução: revise e modifique sua entrada para estar em conformidade com as políticas de conteúdo.

malformed_model_output

Formato de saída inválido.

Solução: verifique o esquema de saída e as restrições; verifique se o esquema JSON está formatado corretamente.

malformed_tool_use

Formato de chamada de ferramenta inválido.

Solução: verifique se as definições da ferramenta correspondem ao esquema esperado; verifique se os parâmetros de entrada da ferramenta estão formatados corretamente.

service_unavailable

Serviço de ferramentas integradas indisponível.

Solução: tente fazer a solicitação novamente após um breve intervalo; verifique o painel de integridade do serviço da AWS.

invalid_query

Consulta inválida para a ferramenta integrada.

Solução: revise o formato e os parâmetros da consulta; garanta que a consulta atenda aos requisitos da ferramenta.

max_tool_invocations

As novas tentativas da ferramenta se esgotaram.

Solução: simplifique a tarefa ou divida-a em etapas menores; analise as mensagens de erro da ferramenta em busca de problemas específicos.

Erros do modo de raciocínio

Respostas truncadas com alto esforço de raciocínio

Solução: para um alto esforço de raciocínio, desconfigure estes parâmetros: temperature, topP, maxToken. Isso permite que o modelo use configurações ideais para tarefas complexas de raciocínio.

Tokens insuficientes para o raciocínio

Erro: “maxTokens is insufficient”

Solução: faça uma nova tentativa automática com aumento de limite

token_limits = {
    "low": 15000,
    "medium": 30000,
    "high": 50000
}

try:
    response = client.converse(
        modelId="us.amazon.nova-2-lite-v1:0",
        messages=messages,
        inferenceConfig={
            "maxTokens": token_limits[max_effort]
        },
        additionalModelRequestFields={
            "reasoningConfig": {
                "type": "enabled",
                "maxReasoningEffort": max_effort
            }
        }
    )
except Exception as e:
    if "maxTokens is insufficient" in str(e):
        higher_limit = int(token_limits[max_effort] * 1.5)
        # Retry with higher limit

Problemas de uso das ferramentas

Ocorrem falhas de validação do esquema

Erros de validação do esquema da ferramenta

Solução:

  • Limite os esquemas JSON a duas camadas de aninhamento para obter o melhor desempenho

  • Certifique-se de que todos os campos obrigatórios estejam definidos corretamente

  • Valide o esquema em relação à especificação do esquema JSON

O modelo não está usando as ferramentas corretamente

Solução:

  • Certifique-se de que o nome da ferramenta descreva claramente sua finalidade

  • Forneça uma descrição detalhada da funcionalidade da ferramenta

  • Defina explicitamente o esquema de entrada com descrições claras dos parâmetros

  • Inclua exemplos na descrição quando for útil

Comportamento inconsistente da chamada de ferramentas

Solução: defina temperature como 0 para chamar a ferramenta:

inferenceConfig={
    "temperature": 0,
    "maxTokens": 10000
}

Isso permite uma decodificação ágil para um uso mais confiável da ferramenta.

Conflitos de escolha de ferramentas

Problema: erro ao usar ferramentas personalizadas com pesquisa na web ou interpretador de código

Solução: não inclua um toolSpec personalizado com o nome nova_grounding, pois entra em conflito com a ferramenta do sistema. Use a configuração da ferramenta do sistema:

# Correct - use system tool
tool_config = {
    "tools": [{
        "systemTool": {"name": "nova_grounding"}
    }]
}

# Incorrect - don't create custom tool with this name
# tool_config = {
#     "tools": [{
#         "toolSpec": {"name": "nova_grounding", ...}
#     }]
# }

Problemas na ancoragem na web

Problemas de controle de acesso

Problema: a ancoragem na web e o interpretador de código não estão funcionando

Solução: garanta que sua política do IAM inclua:

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["bedrock:InvokeTool"],
      "Resource": ["arn:aws:bedrock::{YOUR_ACCOUNT_ID}:system-tool/amazon.nova_grounding"]
    }
  ]
}
Problemas com a política de controle de serviços

Problema: a ancoragem na web está bloqueada pela SCP

Solução: se você tiver políticas de controle de serviços com a condição aws:requestedRegion, atualize-as para permitir uma região “não especificada” para a funcionalidade Ancoragem na Web.

Limitações de processamento de mídia

Compreensão ruim do conteúdo multilíngue em imagens e vídeos

Limitação: os modelos Nova têm uma compreensão limitada do conteúdo multilíngue na mídia visual

Solução:

  • Forneça traduções de texto junto com imagens

  • Use entradas baseadas em texto para conteúdo multilíngue sempre que possível

Identificação de pessoas

Problema: o modelo se recusa a identificar pessoas em imagens

Comportamento esperado: os modelos se recusarão a identificar ou nomear indivíduos em imagens, documentos ou vídeos por motivos de privacidade e segurança

Solução alternativa: pergunte sobre características gerais ou o contexto em vez de identidades específicas

Limitações do raciocínio espacial

Problema: análise de layout ou localização imprecisa

Limitação: recursos limitados para raciocínio espacial preciso

Solução:

  • Use a detecção de caixa delimitadora para a localização de objetos

  • Forneça pontos de referência claros em seus prompts

  • Divida consultas espaciais complexas em componentes mais simples

Texto pequeno em imagens e vídeos

Problema: não é possível ler texto pequeno na mídia

Solução:

  • Recorte imagens para focar as seções de texto relevantes

  • Aumente a resolução da mídia de origem

  • Forneça o texto separadamente, se disponível

Gerenciamento de documentos e arquivos

Conteúdo não compatível

Problema: falha no processamento do PDF

Causas:

  • PDFs com perfis de cores CMYK

  • PDFs contendo imagens SVG

Solução:

  • Converta PDFs em perfil de cores RGB

  • Rasterize imagens SVG antes de incluí-las em PDFs

Estimativa de tokens

Problema: uso inesperado de tokens com PDFs

Diretriz: estime aproximadamente 2.560 tokens por página PDF padrão de 8,5×11"

Solução: ajuste maxTokens adequadamente com base no tamanho do documento