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

Prévia: avaliação de agentes na plataforma de agentes do Gemini Enterprise

Esse recurso está sujeito aos "Termos da solução pré-GA" na seção Termos gerais de serviço dos Termos específicos de serviço, bem como aos Termos específicos de serviço da IA generativa. Esse recurso permite que os clientes avaliem agentes de IA. Portanto, os Termos específicos de serviço de "IA agêntica" se aplicam. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Antes de começar

Para visualizar 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, a plataforma de agentes fornece ferramentas de diagnóstico para ajudar 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 rastros individuais.

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

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

1. No Google Cloud console do, navegue até a página Plataforma de agentes > 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 desempenho:visualize como as pontuações de métricas como Sucesso da tarefa ou Qualidade do uso da ferramenta mudam em diferentes versões ou períodos do agente.
• Estado zero: para agentes sem monitores on-line ativos, essa visualização identifica lacunas de cobertura e fornece uma chamada para ação 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 plataforma de agentes. O SDK fornece visualizações interativas integradas para ambientes de notebook do Colab e do 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:pontuações agregadas em todos os casos de avaliação, incluindo a pontuação média e a taxa de aprovação de 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():

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

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 adaptáveis geram rubricas automaticamente com base na configuração do agente e no comando do usuário. Cada rubrica recebe um veredito Aprovado ou Reprovado individual com uma justificativa em linguagem natural explicando o raciocínio do LLM do juiz. A pontuação geral representa a taxa de aprovação, ou seja, a proporção de rubricas que receberam um veredito Aprovado.
• As métricas de rubrica estáticas usam um conjunto fixo de critérios de avaliação. Por exemplo, a 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. Verificações de segurança para informações de identificação pessoal, discurso de ódio, conteúdo perigoso e outras violações de políticas. 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êmicos e classificá-los para melhorar o agente. A plataforma de agentes fornece a Análise automática de perdas, 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 falhas no console

1. Navegue até a página Plataforma de agentes > 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 detectou clusters, eles serão mostrados na seção Clusters de falhas do relatório.

Gerar clusters de falhas com o SDK

Também é possível gerar clusters de falhas 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():

Taxonomias de padrão de perda

A análise automática de perdas classifica cada falha em um ou mais padrões de perda predefinidos. Esses padrões são projetados para serem concretos e acionáveis, mapeando diretamente para áreas específicas do 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, instruções seguidas, chamadas de ferramentas, tratamento de saída de ferramentas e qualidade de ferramentas:

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 um recurso que não possui.
Instruções seguidas	Violação de restrição	O agente executa a tarefa, mas viola restrições explícitas do usuário (como regras de formatação ou restrições negativas).
	Ação inútil (subestimada)	O agente realiza uma ação irrelevante em vez de declarar 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 solicitadas explicitamente.
	Superestimada	O agente recusa uma tarefa, alegando que não tem uma ferramenta ou um recurso que realmente possui.
Chamadas de ferramentas	Seleção incorreta de ferramentas	O agente seleciona a ferramenta errada nas opções disponíveis.
	Parâmetros de ferramenta semanticamente incorretos	A chamada de ferramenta é sintaticamente válida, mas contém um erro lógico ou semântico nos valores dos parâmetros.
	Chamada de ferramenta sintaticamente incorreta	A chamada de ferramenta tem erros sintáticos, parâmetros obrigatórios ausentes, ou valores de argumentos inválidos.
Tratamento de saída de ferramentas	Processamento incorreto da saída da ferramenta	O agente recebe uma saída de ferramenta válida, mas extrai, processa ou interpreta as informações de maneira imprecisa.
Qualidade da ferramenta	Saída de ferramenta insuficiente	A ferramenta é executada com sucesso, mas retorna dados insuficientes ou ausentes necessários para que o agente prossiga.
	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 da ferramenta

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 tratamento da resposta da ferramenta:

Categoria	Padrão de perda	Descrição
Alucinação	Alucinação do valor do 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 de ferramenta	O agente tenta chamar uma função que não existe no seu 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 datas de início e término).
	Valor de parâmetro incorreto	O agente fornece um valor de parâmetro que é 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 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 necessária	O agente não executa uma função necessária, seja respondendo diretamente, ignorando parte de uma solicitação composta ou ignorando uma etapa de pré-requisito step.
	Subestimada	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 de ferramenta irrelevante	A ferramenta é executada com sucesso, mas retorna dados não relevantes para a consulta específica do usuário.
	Erro de 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).

Fluxo de trabalho de triagem recomendado

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

1. Comece com métricas de resumo para identificar as métricas com menor pontuação 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êmicos em falhas.
4. Detalhe os rastros para encontrar o turno ou a chamada de ferramenta exata em que a falha ocorreu. No console, navegue até Plataforma de agentes > Agentes > Implantações, selecione seu agente e abra a guia Traces. Selecione um rastro para conferir o histórico completo da conversa e a sequência exata de entradas de modelo, chamadas de ferramentas e respostas.
5. Identifique a causa raiz: use a categoria de padrão de perda para determinar se o problema é um comando, uma configuração de ferramenta ou um problema de dados.
6. Aplique uma correção direcionada às instruções do sistema do agente, às definições de ferramentas ou a exemplos de poucos disparos.
7. Execute a avaliação novamente e compare as pontuações para verificar a melhoria.