Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Depois de interpretar as pontuações de avaliação e identificar as áreas de foco, determine por que cada caso de teste falhou e quem precisa agir.
Este artigo fornece orientações estruturadas para diagnosticar falhas no nível do caso de teste. Ela ajuda você a classificar a causa raiz, distinguir entre problemas de agente, avaliação e infraestrutura, e escolher a próxima ação indicada.
Antes de começar
Antes de começar a triagem de falha:
- Conclua a interpretação da pontuação e a avaliação de prontidão e identifique quais conjuntos de avaliação requerem atenção.
- Concentre-se nas falhas de mais alta prioridade com base na prontidão e no risco.
Importante
Se você ignorar esta etapa, poderá gastar tempo em problemas de baixo impacto ou sem bloqueio.
Checagem Pré-Triagem: Verifique a Saúde da Infraestrutura
Antes de diagnosticar falhas individuais, confirme se as dependências estavam íntegras durante a execução da avaliação. Problemas de infraestrutura podem causar falhas que se assemelham a problemas de agente ou de avaliação, mas não estão relacionados a nenhum deles.
Verifique as seguintes condições:
- As fontes de conhecimento são acessíveis e totalmente indexadas.
- Back-ends ou conectores de API não retornam erros, tempos limites ou respostas de limite de taxa.
- Os tokens de autenticação são válidos durante toda a execução.
- O ambiente de avaliação corresponde à configuração do agente desejada.
Se uma dependência não estiver íntegra, corrija o problema e reexecute a avaliação antes de continuar. A triagem de resultados de um processo não íntegro pode levar a conclusões incorretas.
Etapa 0: Priorize falhas
Antes de triar casos de teste individuais, decida onde concentrar seus esforços primeiro.
Priorize as falhas nesta ordem:
| Prioridade | Triagem primeiro | Justificativa |
|---|---|---|
| 1 | Falhas de segurança e conformidade | Consequência máxima. Resolva essas falhas antes da implantação. |
| 2 | Falhas em Cenários de Negócio Essenciais | Impacto direto na proposta de valor do agente. |
| 3 | Falhas no conjunto de avaliação de pontuação mais baixa | Provavelmente sistêmico. Corrigir a causa raiz pode resolver múltiplas falhas. |
| 4 | Falhas Recorrentes em Várias Execuções | Falhas consistentes são mais fáceis de diagnosticar. |
| 5 | Falhas em cenário de capacidade | Importante, mas normalmente de menor impacto. |
Se você tiver muitas falhas (p. ex., mais de 15), não faça a triagem de cada falha individualmente. Comece com o conjunto de avaliação com a menor pontuação e revise manualmente algumas falhas. Se eles compartilham uma causa raiz, corrigi-la pode resolver muitas falhas ao mesmo tempo.
Identifique o sinal de qualidade para um teste que falhou
Se um resultado de avaliação apresentar um teste que falhou, mas não identificar claramente o sinal de qualidade, utilize o conjunto de avaliação e o método de avaliação para inferir o sinal.
Por exemplo:
- O conjunto de avaliação indica a área de competência, como segurança, fundamentação ou uso de ferramentas.
- O método de avaliação, como correspondência de palavras-chave ou pontuação baseada em rubricas, fornece mais contexto.
Identificar o sinal de qualidade pretendido ajuda você a escolher as perguntas diagnósticas mais relevantes.
Etapa 1: Verifique a configuração da avaliação
Importante
Sempre comece por aqui. Antes de investigar o agente, verifique se a configuração de avaliação está correta.
Para cada falha, revise manualmente a resposta real do agente, comparando-a com o valor esperado e o método de avaliação.
Siga as perguntas a seguir na ordem. Pare quando chegar a um resultado.
A resposta do agente é aceitável? Um usuário real se sentiria satisfeito com essa resposta, mesmo que ela tenha sido reprovada na avaliação?
- Se Sim, a configuração de avaliação tem um problema: o avaliador ou o valor esperado está errado.
- Se Não, continue para a próxima pergunta.
A resposta esperada é atual e precisa em relação à fonte?
- Se Sim continue para a próxima pergunta.
- Se Não, a configuração de avaliação tem um problema: a resposta esperada está desatualizada ou errada.
O caso de teste reflete uma entrada realista do usuário?
- Se Sim continue para a próxima pergunta.
- Se não, há um problema na configuração da avaliação: o caso de teste é irrealista.
Uma resposta alternativa razoável também poderia estar correta, mas o avaliador não permite?
- Se sim, a configuração da avaliação tem um problema: o avaliador é muito rígido e não considera variações válidas.
- Se Não, continue para a próxima pergunta.
O método de avaliação é adequado para o que você está testando?
- Se Sim, a avaliação é válida. Prossiga para Etapa 2: Diagnosticar o agente.
- Se Não, a configuração de avaliação apresenta um problema: o método de avaliação não é adequado para este sinal de qualidade.
Avaliação da aceitabilidade da resposta
Use os seguintes sinais para ajudar a determinar se a resposta do agente é aceitável:
- Mesmos fatos principais, redação diferente → Frequentemente aceitável (o avaliador pode ser rígido demais).
- Falta de informações críticas presentes na fonte → Frequentemente inaceitável.
- Limite ambíguo de "bom o suficiente" → os critérios de aceitação podem estar pouco claros (marcar para a etapa 4).
Se você estiver em dúvida, compare o conteúdo com a fonte original, não apenas com a resposta esperada.
Esses sinais informam seu julgamento, mas não o substituem.
Tipos Comuns de Falha de Configuração de Avaliação
| Tipo de falha | Descrição | Exemplo |
|---|---|---|
| Resposta esperada desatualizada | O conteúdo de origem mudou, mas o valor esperado não foi atualizado | Política atualizada para 15 dias, mas a avaliação ainda espera "prazo de devolução de 30 dias." |
| Avaliador excessivamente rígido | Falha na correspondência de palavra-chave em sinônimos ou reformulações válidas | Esperava-se “água fria”. A resposta do agente foi “água fresca, 30 graus C”, que é semanticamente equivalente. |
| Caso de teste irrealista | O cenário de teste não corresponde ao comportamento real do usuário | Teste de uma consulta de 4 parágrafos quando usuários reais digitam de 5 a 10 palavras. |
| Método de Avaliação Errado | O método de avaliação não está alinhado com o que está sendo testado | Usando Correspondência de palavra-chave (Tudo) para uma pergunta de síntese em que a Comparação de significado é apropriada. |
| Erro factual do avaliador | O modelo de linguagem como juiz inventa um motivo de falha inexistente (erro isolado) | O avaliador de modelo de linguagem diz que "a resposta não menciona a política de retorno" quando menciona claramente. |
| Viés Sistemático do Avaliador | O modelo de linguagem como juiz aplica um padrão inconsistente entre os casos de teste (problema de calibração) | O avaliador aprova respostas curtas, mas reprova as mais longas com o mesmo sinal de qualidade, independentemente do conteúdo. |
| Critérios de Aceitação Ambíguos | O valor esperado pode ser interpretado de várias maneiras | "Deve incluir informações de preço." Mensalmente? Anual? Por usuário? |
Validação do classificador
A confiabilidade do avaliador é pré-requisito para uma triagem confiável. Se o próprio classificador não for confiável, você diagnosticará incorretamente cada falha que ele envolver.
Para validar a confiabilidade do avaliador:
- Selecione de 5 a 10 casos de teste onde você sabe o resultado correto de aprovação/reprovação pela revisão manual.
- Realize a avaliação e compare o resultado do avaliador com o veredito manual.
- Se o classificador discordar em mais de 20% de casos, recalibra o classificador antes de depurar o agente.
Sinais de que um avaliador precisa de atenção:
- O mesmo caso de teste produz resultados diferentes em execuções diferentes.
- As falhas se agrupam em conjuntos de avaliação que usam avaliação baseada em modelo, enquanto os métodos determinísticos passam.
- A ferramenta de avaliação aponta problemas que você não consegue reproduzir ao revisar a resposta do agente.
Opções de Recalibração do Avaliador:
- Use métodos determinísticos sempre que possível.
- Adicione exemplos explícitos de "aceitável" e "não aceitável" à rubrica.
- Amplie os conjuntos de palavras-chave para incluir sinônimos e reformulações válidas.
- Use Comparar significado em vez de Correspondência de palavras-chave (Todos) para verificações de equivalência semântica.
Etapa 2: Diagnosticar o agente
Neste ponto, a avaliação é válida e o agente produziu uma resposta incorreta. Diagnostique o que deu errado na configuração do agente.
Dica
Algumas perguntas diagnósticas exigem visibilidade sobre o que o agente fez internamente (p. ex., qual fonte de conhecimento foi acessada, qual ferramenta foi acionada ou qual tópico foi disparado). Use logs de rastreamento, transcrições de conversas ou análises de testes se disponíveis. Se sua plataforma não disponibilizar esses detalhes, infira-os a partir da resposta (p. ex., conteúdo que aparece apenas na Fonte A provavelmente veio da Fonte A).
Verifique a precisão factual e falhas de fundamentação do conhecimento
| Question | Se sim: causa raiz |
|---|---|
| O agente recuperou a partir da fonte de conhecimento errada? | Configuração da fonte de conhecimento Indexação ou priorização da fonte errada. |
| O agente recuperou a fonte correta, mas extraiu informações incorretas? | Lacuna de prompt ou instrução. O modelo precisa de orientação para extração. |
| O conteúdo da fonte está incorreto ou desatualizado? | Conteúdo da fonte de conhecimento. Atualize o documento de origem. |
| O agente respondeu sem usar nenhuma fonte de conhecimento (inventou uma resposta)? | Acessibilidade de fonte. A fonte não está indexada, ou a formulação da consulta não corresponde ao vocabulário da fonte. |
| O agente contradisse informações presentes na fonte? | Informações incorretas. Adicione instrução explícita de fundamentação. |
Verificar se há falhas de invocação da ferramenta
| Question | Se sim: causa raiz |
|---|---|
| A ferramenta errada foi ativada? | Ambiguidade na descrição da ferramenta. Sobreposição de descrições entre ferramentas. |
| A ferramenta certa foi acionada com parâmetros errados? | Definição de parâmetro. Esquema ou descrição pouco claros. |
| A ferramenta não acionou de forma alguma? | Condição do gatilho. A entrada não atende aos critérios de invocação. |
| A ferramenta foi acionada quando não deveria? | Ausência de proteção negativa. Sem instruções para quando não chamar a ferramenta. |
| A ferramenta foi acionada corretamente, mas a resposta usou indevidamente o resultado da saída? | Instrução da resposta. O agente precisa de orientação sobre como formatar as saídas das ferramentas. |
| A ferramenta foi acionada corretamente, mas ela mesma falhou (erro, tempo limite, dados incorretos)? | Problema de ferramenta ou integração; a falha está no sistema de backend, não no agente. Corrija a ferramenta, não o agente. |
Verificar se há falhas de roteamento de gatilho
| Question | Se sim: causa raiz |
|---|---|
| Foi acionado o tópico incorreto? | Sobreposição de gatilho do tópico. Gatilhos são ambíguos entre tópicos. |
| Não houve nenhum disparo de tópico (fallback de ocorrência)? | Lacuna na cobertura do tópico. Nenhum tópico trata desse tipo de entrada. |
| Vários tópicos foram associados à desambiguação errada? | Lógica de desambiguação. Configuração incorreta do fluxo de prioridade ou clarificação. |
Verifique falhas de tom e qualidade de resposta
| Question | Se sim: causa raiz |
|---|---|
| O tom do agente é inconsistente com as orientações de prompt do sistema? | Lacuna na instrução de tom. Resolva orientações ausentes ou contraditórias. |
| A resposta é muito detalhada ou muito breve para a pergunta? | Instrução de formato. Inclua orientações de comprimento ou estrutura. |
| O agente carece de empatia em contextos sensíveis? | Lacuna na Instrução de Empatia. Adicione orientações explícitas para as entradas emocionais. |
| A resposta está mal estruturada (texto muito longo, sem etapas)? | Instrução de formato. Adicionar requisitos de formatação. |
Verificar se há falhas de segurança e limite
| Question | Se sim: causa raiz |
|---|---|
| O agente revelou informações do sistema? | Proteção de prompt do sistema. Adicione instruções de "não revelar". |
| O agente saiu do escopo? | Lacuna da definição do escopo. Defina limites de maneira mais clara. |
| O agente está em conformidade com a injeção de prompt? | Instruções de segurança. Adicione orientações para resistência a ataques adversariais. |
| O agente tratou dados pessoais de forma inadequada? | Regras de tratamento de PII. Adicione instruções de proteção de dados. |
Verificar se há escalonamento e falha normal
| Question | Se sim: causa raiz |
|---|---|
| O agente deixou de escalonar quando deveria? | Gatilho de escalonamento. Critérios não definidos ou muito restritos. |
| O agente escalou prematuramente? | Limite de escalonamento. Critérios muito sensíveis. |
| A escalada perdeu o contexto da conversa? | Configuração de entrega. Preservação de contexto não configurada. |
| O agente entrou em loop em vez de reconhecer a falha? | Lógica de Fallback. Limite de tentativas ou comportamento de fallback não configurado. |
Após o diagnóstico, mapeie padrões de falha para estratégias de remediação conforme a causa raiz.
Etapa 3: Identificar limitações da plataforma
Se a avaliação estiver correta e mudanças razoáveis na configuração não melhorarem os resultados, o problema pode ser uma limitação da plataforma.
Indicadores de limitação de plataforma
| Indicador | O que isso sugere |
|---|---|
| A mesma falha persiste em múltiplas variações de prompt e configuração | Não é um problema de configuração |
| A recuperação retorna consistentemente documentos incorretos, apesar da configuração correta da fonte | Limitação de classificação de recuperação |
| O agente não consegue executar o raciocínio requerido apesar das instruções claras | Limite de capacidade do modelo |
| Padrão de orquestração necessário não é suportado por nenhuma opção de configuração | Limitação da lógica de orquestração |
| O avaliador baseado em modelos classifica incorretamente de forma consistente, mesmo após ajustes nos critérios de avaliação | Limitação do modelo avaliador |
Caminho de ação para limitações de plataforma
- Documente claramente a limitação (o que falha, o que você tentou e evidências de que não se trata de um problema de configuração).
- Aplique uma solução alternativa sempre que possível (p. ex., reestruture o documento de origem para melhorar a recuperação).
- Marque o caso de teste como uma limitação conhecida ou ajuste os limiares de modo que não impeça o progresso de áreas não relacionadas.
- Escalone fornecendo evidências para a equipe da plataforma.
- Registre o item no registro de falhas para reavaliação quando as capacidades da plataforma forem atualizadas.
Depois de classificar, examine as diretrizes de solução alternativa e escalonamento para responder às limitações da plataforma.
Quando uma falha não se encaixa na estrutura
Algumas falhas não se encaixam claramente em um único tipo de causa raiz. Os exemplos comuns incluem:
- Problemas de qualidade de dados do backend: o conteúdo da fonte de conhecimento está tecnicamente correto, mas ambíguo, portanto, nem o agente nem a avaliação estão errados.
- Problemas intermitentes de infraestrutura: Timeouts de rede, limitação de taxa de API e problemas de conectores que não se reproduzem de forma consistente.
- Mudanças na versão do modelo: O comportamento do agente mudou após uma atualização do modelo da plataforma que você não iniciou.
- Casos de teste ambíguos: O cenário é ambíguo, e pessoas razoáveis discordam quanto à resposta correta.
Abordagem sugerida: Documente o que você observou (a falha, a resposta do agente, o que você verificou). Registre o item como "não classificado" no log de falhas. Se a falha se repetir, frequentemente se torna classificável com evidências adicionais.
Tratamento de causas compostas
Uma única falha pode ter múltiplas causas raiz contribuintes. Por exemplo:
- Uma falha de precisão factual em que a resposta esperada está um pouco desatualizada (configuração de avaliação) e a fonte de conhecimento também está incompleta (configuração do agente).
- Uma falha na invocação de ferramenta em que a descrição da ferramenta é ambígua (configuração do agente) e a orquestração não suporta chamadas condicionais de ferramenta (limitação da plataforma).
Abordagem sugerida: Complete a triagem completa para cada falha. Se houver múltiplos tipos de causas raiz, aborde-os por ordem de prioridade:
- Corrija a avaliação primeiro para obter um sinal claro para ver se a alteração no agente realmente faz diferença.
- Corrija a configuração do agente para determinar se a falha restante é realmente um problema da plataforma.
- Documente a limitação da plataforma somente após os pontos 1 e 2 serem resolvidos.
Execute novamente os casos de teste afetados após cada alteração antes de prosseguir.
Lidar com falhas de conversa com várias rodadas
Para cenários de várias rodadas, as falhas surgem apenas em rodadas.
Quando suspeitar de um problema de várias rodadas
- O agente responde corretamente nos primeiros turnos, mas se contradiz depois.
- O agente perde o contexto de uma chamada de ferramenta anterior ou recuperação de conhecimento em uma etapa posterior.
- O tempo de escalonamento só faz sentido ao considerar o histórico completo da conversa.
- O tom do agente vai se degradando progressivamente à medida que a conversa se prolonga.
- O agente pede informações que o usuário já forneceu.
Dica
Uma falha pode aparecer em um turno posterior, enquanto a causa raiz ocorre mais cedo. Rastreie para identificar o primeiro turno em que a conversa divergiu.
Perguntas Diagnósticas Adicionais
| Question | Se sim: causa raiz |
|---|---|
| A falha dependia de informações de um turno anterior cujas informações foram perdidas? | Problema de gerenciamento de contexto; estado de conversa não preservado entre turnos. |
| O agente se contradisse em relação a algo que disse em um turno anterior? | Lacuna de orientação de consistência; nenhuma instrução para manter a coerência entre turnos. |
| O agente pediu novamente informações que o usuário já forneceu? | Problema de recuperação de contexto; agente não referenciando turnos anteriores. |
| A falha só ocorreu após muitos turnos (5+)? | Tamanho Efetivo do Contexto Excedido. |
Diretrizes de correção para problemas de várias rodadas
- Perda de contexto: Verifique a configuração do estado da conversa. Verifique se as saídas da ferramenta e os principais fatos persistem entre rodadas.
- Contradições: Adicione uma instrução de consistência, como: "Mantenha a consistência com suas respostas anteriores nesta conversa."
- Solicitação nova: verifique a configuração de memória de conversa da plataforma.
- Degradação de conversas longas: Considere estratégias de sumarização ou poda de contexto.
Validando casos de teste aprovados (verificação de falso positivo)
Essa estrutura foca em casos de teste que falham. No entanto, um caso de teste que passa incorretamente pode criar lacunas de qualidade ocultas.
Prática recomendada: Revise manualmente de 5 a 10% dos casos de teste aprovados por execução de avaliação, especialmente para:
- Avaliação baseada em modelos (maior risco de falsos positivos)
- Sinais subjetivos (tom, ajuda)
- Testes que anteriormente falharam e agora passam após uma alteração
Se encontrar falsos positivos, recalibre o avaliador.
Próximas etapas
Após concluir a triagem de falhas:
- Use a Camada 3: Mapear padrões de falha para estratégias de remediação.
- Use a Camada 4: Analise padrões para identificar questões sistêmicas.
- Reveja exemplos práticos que demonstram como as camadas do framework trabalham juntas em cenários do mundo real.