Analiza los resultados de la evaluación y los clústeres de errores

Antes de comenzar

Para ver y analizar los resultados de la evaluación, asegúrate de tener lo siguiente:

• Ejecuta al menos una evaluación como se describe en Evalúa tus agentes o Ejecuta evaluaciones sin conexión.
• Configuraste un bucket de Cloud Storage para la salida de la evaluación si ejecutas evaluaciones sin conexión.
• (Opcional) Si usas el SDK para recuperar resultados, asegúrate de que tu entorno esté autenticado.

Después de ejecutar una evaluación, Agent Platform proporciona herramientas de diagnóstico para ayudarte a identificar las causas raíz de las fallas. Puedes analizar los resultados en tres niveles: tendencias agregadas en el panel, grupos semánticos en clústeres de fallas y rutas lógicas detalladas en registros individuales.

El panel de evaluación para los monitores en línea

En el caso de los agentes con Monitores en línea activos, puedes ver las tendencias de rendimiento agregadas en el panel:

1. En la consola de Google Cloud , navega a la página Agent Platform > Agents.
2. En el menú de navegación de la izquierda, selecciona Implementaciones.

3. Selecciona el agente.

   Ir a Implementaciones

4. Haz clic en la pestaña Panel y selecciona la subsección Evaluación.

• Tendencias de rendimiento: Visualiza cómo cambian las puntuaciones de métricas como Éxito de la tarea o Calidad del uso de herramientas en diferentes versiones de agentes o períodos.
• Estado cero: En el caso de los agentes sin Supervisores en línea activos, esta vista identifica las brechas de cobertura y proporciona un llamado a la acción para comenzar la evaluación.

Visualiza los resultados de la evaluación con el SDK

Puedes acceder a los resultados de la evaluación de forma programática con el SDK de Agent Platform. El SDK proporciona visualizaciones interactivas integradas para los entornos de notebooks de Colab y Jupyter que muestran tanto las métricas de resumen agregadas como los resultados detallados por caso.

Después de ejecutar una evaluación, llama a .show() en el objeto de resultado para renderizar un informe interactivo directamente en tu 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()

La visualización incluye lo siguiente:

• Métricas de resumen: Puntuaciones agregadas en todos los casos de evaluación, incluida la puntuación media y la tasa de aprobación de cada métrica.
• Resultados por caso: Son las puntuaciones de casos de evaluación individuales que puedes expandir para inspeccionar los resultados detallados.

En el siguiente ejemplo, se muestran las métricas de resumen de result.show():

Puedes expandir los casos de evaluación individuales para ver las puntuaciones por métrica, los veredictos de la rúbrica y las justificaciones:

Cómo interpretar los resultados de la evaluación

Las métricas predefinidas muestran resultados en dos formatos, según el tipo de métrica:

• Las métricas de rúbrica adaptativa generan automáticamente rúbricas basadas en la configuración del agente y la instrucción del usuario. Cada rúbrica recibe un veredicto individual de Aprobado o Reprobado con una explicación en lenguaje natural que explica el razonamiento del LLM del juez. La puntuación general representa la tasa de aprobación, es decir, la proporción de rúbricas que recibieron un veredicto de Aprobado.
• Las métricas de rúbrica estáticas usan un conjunto fijo de criterios de evaluación. Por ejemplo, Hallucination segmenta la respuesta en afirmaciones atómicas y verifica cada una con la evidencia de uso de la herramienta. Verificaciones de seguridad para la PII, la incitación al odio o a la violencia, el contenido peligroso y otros incumplimientos de políticas Estas métricas devuelven una sola puntuación numérica (de 0 a 1).

Identifica y clasifica las fallas

Después de revisar los resultados de la evaluación, el siguiente paso es identificar patrones de fallas sistémicas y clasificarlos para mejorar tu agente. La Plataforma de agentes proporciona Análisis automático de pérdidas, que analiza los indicadores de aprobación o rechazo de las métricas basadas en rúbricas, clasifica los errores en patrones de pérdida predefinidos y los agrupa en clústeres semánticos. Esto te ayuda a comprender no solo que tu agente falló, sino por qué y cómo falló.

Accede a los clústeres de fallas en la consola

1. Navega a la página Agent Platform > Agents > Evaluation.
2. Selecciona la pestaña Evaluaciones.
3. Haz clic en el nombre de una ejecución de evaluación completada para abrir el informe.
4. Si la evaluación detectó clústeres, estos se mostrarán en la sección Failure Clusters del informe.

Genera clústeres de fallas con el SDK

También puedes generar clústeres de fallas de manera programática con el 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()

En el siguiente ejemplo, se muestra el análisis del patrón de pérdida de loss_clusters.show():

Taxonomías de patrones de pérdida

El análisis automático de pérdidas clasifica cada falla en uno o más patrones de pérdida predefinidos. Estos patrones están diseñados para ser concretos y prácticos, y se asignan directamente a áreas específicas de tu agente que puedes mejorar.

Existen dos taxonomías predefinidas, cada una alineada con una métrica específica:

Taxonomía de éxito de tareas del agente

Esta taxonomía se usa con la métrica Agent Multi-turn Task Success (multi_turn_task_success_v1). Abarca las fallas de comportamiento de alto nivel del agente en cuanto a alucinaciones, seguimiento de instrucciones, llamadas a herramientas, manejo de resultados de herramientas y calidad de herramientas:

Categoría	Patrón de pérdida	Descripción
Alucinación	Alucinación de acción	El agente afirma haber completado una acción sin ejecutar la llamada a la herramienta necesaria.
	Alucinación de información faltante	El agente inventa un detalle (como un valor, un hecho o una fecha) que no está presente en la búsqueda del usuario ni en el resultado de la herramienta.
	Alucinación de herramienta o capacidad	El agente afirma tener una herramienta o capacidad que no posee.
Seguimiento de las instrucciones	Incumplimiento de restricción	El agente realiza la tarea, pero incumple las restricciones explícitas del usuario (como reglas de formato o restricciones negativas).
	Acción fútil (Under-Punting)	El agente realiza una acción irrelevante en lugar de indicar que la tarea es imposible con las herramientas disponibles.
	Ejecución incompleta	El agente completa parcialmente una tarea, pero se detiene antes de tiempo o solicita permiso innecesario para los pasos solicitados de forma explícita.
	Exceso de despejes	El agente rechaza una tarea y afirma que carece de una herramienta o capacidad que en realidad posee.
Llamadas a herramientas	Selección incorrecta de la herramienta	El agente selecciona la herramienta incorrecta de las opciones disponibles.
	Parámetros de herramientas semánticamente incorrectos	La llamada a la herramienta es sintácticamente válida, pero contiene un error lógico o semántico en los valores de los parámetros.
	Llamada a la herramienta sintácticamente incorrecta	La llamada a la herramienta tiene errores de sintaxis, faltan parámetros obligatorios o los valores de los argumentos no son válidos.
Manejo del resultado de la herramienta	Procesamiento incorrecto del resultado de la herramienta	El agente recibe un resultado válido de la herramienta, pero extrae, procesa o interpreta la información de forma imprecisa.
Calidad de la herramienta	Resultado de la herramienta insuficiente	La herramienta se ejecuta correctamente, pero devuelve datos insuficientes o faltantes que el agente necesita para continuar.
	Falla de la herramienta	La herramienta falla debido a problemas de infraestructura, como errores de autenticación, tiempos de espera o errores internos.

Taxonomía de calidad del uso de herramientas

Esta taxonomía se usa con la métrica Calidad del uso de herramientas en varios turnos del agente (multi_turn_tool_use_quality_v1). Se enfoca específicamente en la corrección de las llamadas a herramientas y el manejo de las respuestas de las herramientas:

Categoría	Patrón de pérdida	Descripción
Alucinación	Alucinación del valor del parámetro	El agente inventa un valor específico para un parámetro que el usuario no proporcionó o que no se puede derivar del contexto.
	Alucinación de la herramienta	El agente intenta llamar a una función que no existe en su conjunto de herramientas definido.
Llamadas a herramientas	No se pudo establecer el parámetro	El agente omite un parámetro necesario para satisfacer las restricciones del usuario y, de forma predeterminada, usa un valor no deseado.
	Tipo de datos de parámetro incorrecto	El agente proporciona un valor del tipo de datos incorrecto para un parámetro (por ejemplo, una cadena cuando se requiere un número entero).
	Asignación incorrecta de parámetros	El agente asigna un valor al parámetro incorrecto (por ejemplo, intercambia las fechas de inicio y finalización).
	Valor de parámetro incorrecto	El agente proporciona un valor de parámetro que es lógica o fácticamente incorrecto, o no aplica las transformaciones de datos necesarias.
	Selección incorrecta de la herramienta	El agente selecciona la función incorrecta de su conjunto de herramientas disponibles.
	Sintaxis de llamada a la herramienta no válida	El agente genera una llamada a función con un error de sintaxis que impide el análisis o la ejecución.
	Parámetro no existente	El agente incluye un argumento de parámetro que no se define en la firma de la herramienta.
	Omisión de la llamada a la herramienta obligatoria	El agente no ejecuta una función necesaria, ya sea respondiendo directamente, omitiendo parte de una solicitud compuesta o omitiendo un paso previo.
	Pateo insuficiente	El agente fuerza una llamada a herramienta cuando debería responder con lenguaje natural (por ejemplo, cuando pide una aclaración o rechaza una solicitud fuera del alcance).
Respuesta de la herramienta	Respuesta de herramienta irrelevante	La herramienta se ejecuta correctamente, pero devuelve datos que no son relevantes para la consulta específica del usuario.
	Error de la herramienta	La herramienta devuelve un error explícito o un estado de falla debido a un problema externo (como una interrupción de la API o permisos no válidos).

Flujo de trabajo de clasificación recomendado

Sigue el siguiente flujo de trabajo para priorizar sistemáticamente las fallas de evaluación:

1. Comienza con las métricas de resumen para identificar las métricas con la puntuación más baja en tu conjunto de datos de evaluación.
2. Desglosa los resultados por caso para encontrar casos de evaluación específicos que fallaron.
3. Genera agrupaciones de fallas para identificar patrones de pérdidas sistémicas en las fallas.
4. Desglosa los seguimientos para encontrar el giro o la llamada a la herramienta exactos en los que se produjo la falla. En la consola, navega a Agent Platform > Agents > Deployments, selecciona tu agente y abre la pestaña Traces. Selecciona un registro para ver el historial de conversaciones completo y la secuencia exacta de entradas del modelo, llamadas a herramientas y respuestas.
5. Identifica la causa raíz: Usa la categoría de patrón de pérdida para determinar si el problema se debe a una instrucción, a la configuración de una herramienta o a los datos.
6. Aplica una corrección segmentada a las instrucciones del sistema, las definiciones de herramientas o los ejemplos de pocas tomas del agente.
7. Vuelve a ejecutar la evaluación y compara las puntuaciones para verificar la mejora.