# 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
)
)
```
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