Analisar os resultados da avaliação e os clusters de falhas

Antes de começar

Para conferir e analisar os resultados da avaliação, verifique se você tem o seguinte:

  • Execute pelo menos uma avaliação conforme descrito em Avaliar seus agentes ou Executar avaliações off-line.
  • Configure um bucket do Cloud Storage para a saída da avaliação se estiver executando avaliações off-line.
  • (Opcional) Se você estiver usando o SDK para buscar resultados, verifique se o ambiente está autenticado.

Depois de executar uma avaliação, o Agent Platform fornece ferramentas de diagnóstico para ajudar você a identificar as causas raiz da falha. É possível analisar os resultados em três níveis: tendências agregadas no painel, grupos semânticos em clusters de falhas e caminhos lógicos granulares em rastreamentos individuais.

O painel de avaliação para monitores on-line

Para agentes com monitores on-line ativos, é possível conferir tendências de desempenho agregadas no painel:

  1. No console Google Cloud , navegue até a página Agent Platform > Agentes.
  2. No menu de navegação à esquerda, selecione Implantações.

  3. Selecione seu agente.

    Acessar "Implantações"

  4. Clique na guia Painel e selecione a subseção Avaliação.

  • Tendências de performance:veja como as pontuações de métricas como Sucesso da tarefa ou Qualidade do uso da ferramenta mudam em diferentes versões de agentes ou períodos.
  • Estado zero:para agentes sem monitores on-line ativos, essa visualização identifica lacunas de cobertura e oferece uma call-to-action para iniciar a avaliação.

Conferir os resultados da avaliação com o SDK

É possível acessar os resultados da avaliação de maneira programática usando o SDK da Agent Platform. O SDK oferece visualizações interativas integradas para ambientes do Colab e do notebook Jupyter que mostram métricas de resumo agregadas e resultados detalhados por caso.

Depois de executar uma avaliação, chame .show() no objeto de resultado para renderizar um relatório interativo diretamente no notebook:

from vertexai import evals, types

# Run an evaluation
result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.FINAL_RESPONSE_QUALITY,
        types.RubricMetric.TOOL_USE_QUALITY,
        types.RubricMetric.HALLUCINATION,
        types.RubricMetric.SAFETY,
    ],
)

# Visualize aggregate and per-case results in your notebook
result.show()

A visualização inclui:

  • Métricas de resumo:agregam pontuações em todos os casos de avaliação, incluindo pontuação média e taxa de aprovação para cada métrica.
  • Resultados por caso:pontuações de casos de avaliação individuais que podem ser expandidas para inspecionar resultados detalhados.

O exemplo a seguir mostra as métricas de resumo de result.show():

Relatório de resumo da avaliação mostrando as pontuações médias e o desvio padrão de cada métrica.

É possível expandir casos de avaliação individuais para conferir pontuações por métrica, veredictos da rubrica e justificativas:

Resultados da avaliação por caso mostrando pontuações de métricas e veredictos individuais de aprovação ou reprovação da rubrica com explicações.

Interpretar os resultados da avaliação

As métricas predefinidas retornam resultados em dois formatos, dependendo do tipo de métrica:

  • As métricas de rubrica adaptativa geram automaticamente rubricas com base na configuração do agente e no comando do usuário. Cada rubrica recebe um veredito individual de Aprovado ou Reprovado com uma justificativa em linguagem natural explicando o raciocínio do LLM de avaliação. A pontuação geral representa a taxa de aprovação, ou seja, a proporção de rubricas que receberam um veredito de Aprovado.
  • Métricas de rubrica estática usam um conjunto fixo de critérios de avaliação. Por exemplo, a métrica de alucinação segmenta a resposta em declarações atômicas e verifica cada uma delas em relação às evidências de uso da ferramenta. As verificações de segurança procuram PII, discurso de ódio, conteúdo perigoso e outras violações de política. Essas métricas retornam uma única pontuação numérica (de 0 a 1).

Identificar e classificar falhas

Depois de analisar os resultados da avaliação, a próxima etapa é identificar padrões de falha sistêmica e classificá-los para melhorar seu agente. A Agent Platform oferece a Análise automática de perda, que analisa os indicadores de aprovação ou reprovação de métricas baseadas em rubricas, classifica as falhas em padrões de perda predefinidos e as agrupa em clusters semânticos. Isso ajuda você a entender não apenas que o agente falhou, mas por que e como ele falhou.

Acessar clusters de falha no console

  1. Acesse a página Agent Platform > Agentes > Avaliação.
  2. Selecione a guia Avaliações.
  3. Clique no nome de uma execução de avaliação concluída para abrir o relatório.
  4. Se a avaliação detectar clusters, eles vão aparecer na seção Clusters de falha do relatório.

Gerar clusters de falha com o SDK

Também é possível gerar clusters de falha de maneira programática usando o método generate_loss_clusters:

# Generate failure clusters from evaluation results
loss_clusters = client.evals.generate_loss_clusters(
    eval_result=result,
)

# Visualize the loss pattern analysis in your notebook
loss_clusters.show()

O exemplo a seguir mostra a análise de padrão de perda de loss_clusters.show():

Relatório de análise de padrão de perda mostrando clusters de falha agrupados por categoria com exemplos de cenários e justificativas.

Taxonomias de padrões de perda

A análise automática de perdas classifica cada falha em um ou mais padrões de perda predefinidos. Esses padrões foram criados para serem concretos e práticos, mapeando diretamente áreas específicas do seu agente que podem ser melhoradas.

Há duas taxonomias predefinidas, cada uma alinhada a uma métrica específica:

Taxonomia de sucesso da tarefa do agente

Essa taxonomia é usada com a métrica Sucesso da tarefa multiturno do agente (multi_turn_task_success_v1). Ela abrange falhas comportamentais de alto nível do agente em alucinação, obediência a instruções, chamadas de ferramentas, processamento de saída de ferramentas e qualidade da ferramenta:

Categoria Padrão de perda Descrição
Alucinação Alucinação de ação O agente afirma ter concluído uma ação sem executar a chamada de ferramenta necessária.
Alucinação de informações ausentes O agente inventa um detalhe (como um valor, um fato ou uma data) que não está presente na consulta do usuário ou na saída da ferramenta.
Alucinação de ferramenta ou recurso O agente afirma ter uma ferramenta ou capacidade que não possui.
Instruções seguidas Violação de restrição O agente realiza a tarefa, mas viola restrições explícitas do usuário (como regras de formatação ou restrições negativas).
Ação inútil (chute curto) O agente realiza uma ação irrelevante em vez de afirmar que a tarefa é impossível com as ferramentas disponíveis.
Execução incompleta O agente conclui parcialmente uma tarefa, mas para prematuramente ou pede permissão desnecessária para etapas explicitamente solicitadas.
Over-Punting O agente recusa uma tarefa, alegando que não tem uma ferramenta ou capacidade que ele realmente possui.
Chamadas de ferramentas Seleção incorreta de ferramentas O agente seleciona a ferramenta errada entre as opções disponíveis.
Parâmetros de ferramenta semanticamente incorretos A chamada de função é sintaticamente válida, mas contém um erro lógico ou semântico nos valores de parâmetro.
Chamada de ferramenta sintaticamente incorreta A chamada de ferramenta tem erros de sintaxe, parâmetros obrigatórios ausentes ou valores de argumentos inválidos.
Tratamento da saída da ferramenta Processamento incorreto da saída da ferramenta O agente recebe uma saída válida da ferramenta, mas extrai, processa ou interpreta as informações de maneira incorreta.
Qualidade da ferramenta Resposta da ferramenta insuficiente A ferramenta é executada com êxito, mas retorna dados insuficientes ou ausentes necessários para que o agente continue.
Falha da ferramenta A ferramenta falha devido a problemas de infraestrutura, como falhas de autenticação, tempos limite ou erros internos.

Taxonomia de qualidade do uso de ferramentas

Essa taxonomia é usada com a métrica Qualidade do uso de ferramentas multiturno do agente (multi_turn_tool_use_quality_v1). Ela se concentra especificamente na correção da chamada de ferramenta e no processamento da resposta da ferramenta:

Categoria Padrão de perda Descrição
Alucinação Alucinação de valor de parâmetro O agente inventa um valor específico para um parâmetro que não foi fornecido pelo usuário ou não pode ser derivado do contexto.
Alucinação da ferramenta O agente tenta chamar uma função que não existe no conjunto de ferramentas definido.
Chamadas de ferramentas Falha ao definir o parâmetro O agente omite um parâmetro necessário para atender às restrições do usuário, usando um valor não intencional.
Tipo de dados de parâmetro incorreto O agente fornece um valor do tipo de dados errado para um parâmetro (como uma string quando um número inteiro é necessário).
Mapeamento de parâmetros incorreto O agente atribui um valor ao parâmetro errado (como trocar as datas de início e término).
Valor de parâmetro incorreto O agente fornece um valor de parâmetro que está logicamente ou factualmente incorreto ou não aplica as transformações de dados necessárias.
Seleção incorreta de ferramentas O agente seleciona a função errada no conjunto de ferramentas disponível.
Sintaxe de chamada de ferramenta inválida O agente gera uma chamada de função com um erro de sintaxe que impede a análise ou a execução.
Parâmetro inexistente O agente inclui um argumento de parâmetro que não está definido na assinatura da ferramenta.
Omissão da chamada de ferramenta obrigatória O agente não executa uma função necessária, seja respondendo diretamente, pulando parte de uma solicitação composta ou pulando uma etapa de pré-requisito.
Under-Punting O agente força uma chamada de ferramenta quando deveria responder com linguagem natural (como pedir esclarecimentos ou recusar uma solicitação fora do escopo).
Resposta da ferramenta Resposta irrelevante da ferramenta A ferramenta é executada com sucesso, mas retorna dados que não são relevantes para a consulta específica do usuário.
Erro na ferramenta A ferramenta retorna um erro explícito ou um status de falha devido a um problema externo, como uma interrupção da API ou permissões inválidas.

Use o fluxo de trabalho a seguir para triar sistematicamente as falhas de avaliação:

  1. Comece com as métricas de resumo para identificar as métricas com as pontuações mais baixas no conjunto de dados de avaliação.
  2. Analise os resultados por caso para encontrar casos de avaliação específicos que falharam.
  3. Gere clusters de falhas para identificar padrões de perda sistêmica em falhas.
  4. Detalhe os rastreamentos para encontrar o ponto exato em que a falha ocorreu. No console, navegue até Plataforma de agentes > Agentes > Implantações, selecione seu agente e abra a guia Rastreamentos. Selecione um rastreamento para conferir o histórico completo da conversa e a sequência exata de entradas do modelo, chamadas de ferramentas e respostas.
  5. Identifique a causa raiz: use a categoria de padrão de perda para determinar se o problema é de solicitação, configuração de ferramenta ou dados.
  6. Aplique uma correção direcionada às instruções do sistema, definições de ferramentas ou exemplos few-shot do agente.
  7. Execute a avaliação novamente e compare as pontuações para verificar a melhoria.