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.
Configura un bucket de Cloud Storage para el resultado 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, la plataforma de agentes 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 de lógica detalladas en seguimientos individuales.

El panel de evaluación para supervisores en línea

Para los agentes con supervisores en línea activos, puedes ver las tendencias de rendimiento agregadas en el panel:

En la Google Cloud consola de, navega a la página Plataforma de agentes > Agentes.
En el menú de navegación de la izquierda, selecciona Implementaciones.
Selecciona el agente.
Ir a Implementaciones
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 o períodos del agente.
Estado cero: Para los agentes sin supervisores en línea activos, esta vista identifica las brechas de cobertura y proporciona una llamada 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 manera programática con el SDK de la plataforma de agentes. El SDK proporciona visualizaciones interactivas integradas para entornos de Colab y notebooks de Jupyter que muestran métricas de resumen agregadas y 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: Puntuaciones individuales de casos de evaluación que puedes expandir para inspeccionar los resultados detallados.

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

Informe de resumen de la evaluación que muestra las puntuaciones medias y la desviación estándar de cada métrica.

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

Resultados de la evaluación por caso que muestran las puntuaciones de las métricas y los veredictos individuales de aprobación o rechazo de la rúbrica con explicaciones.

Interpreta 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 adaptables generan automáticamente rúbricas en función de la configuración del agente y la instrucción del usuario. Cada rúbrica recibe un veredicto individual de Aprobado o Reprobado con un fundamento en lenguaje natural que explica el razonamiento del LLM del evaluador. 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, la alucinación segmenta la respuesta en declaraciones atómicas y verifica cada una con la evidencia de uso de herramientas. Verificaciones de seguridad para PII, incitación al odio o a la violencia, contenido peligroso y otros incumplimientos de políticas. Estas métricas muestran una sola puntuación numérica (de 0 a 1).

Identifica y prioriza las fallas

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

Accede a los clústeres de fallas en la consola

Navega a la página Plataforma de agentes > Agentes > Evaluación.
Selecciona la pestaña Evaluaciones.
Haz clic en el nombre de una ejecución de evaluación completada para abrir el informe.
Si la evaluación detectó clústeres, se muestran en la sección Clústeres de fallas 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 de patrones de pérdida de loss_clusters.show():

Informe de análisis de patrones de pérdida que muestra clústeres de fallas agrupados por categoría con ejemplos de situaciones y explicaciones.

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 Éxito de tareas de varios turnos del agente (multi_turn_task_success_v1). Abarca fallas de comportamiento de alto nivel del agente en 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 inútil (subestimación)	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 de forma prematura o solicita permisos innecesarios para los pasos solicitados de forma explícita.
	Sobreestimación	El agente rechaza una tarea y afirma que no tiene una herramienta o capacidad que sí posee.
Llamadas a herramientas	Selección incorrecta de herramientas	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 sintácticos, faltan parámetros obligatorios, o los valores de los argumentos no son válidos.
Manejo de resultados de herramientas	Procesamiento incorrecto de resultados de herramientas	El agente recibe un resultado de herramienta válido, pero extrae, procesa o interpreta la información de forma incorrecta.
Calidad de herramientas	Resultado de herramienta insuficiente	La herramienta se ejecuta correctamente, pero muestra datos insuficientes o faltantes que el agente necesita para continuar.
Calidad de herramientas	Falla de la herramienta	La herramienta falla debido a problemas de infraestructura, como fallas de autenticación fallas, 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 respuestas de 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 no proporcionó el usuario o que no se puede derivar del contexto.
Alucinación	Alucinación de herramienta	El agente intenta llamar a una función que no existe en su conjunto de herramientas definido.
Llamadas a herramientas	No se pudo configurar el parámetro	El agente omite un parámetro necesario para cumplir con las restricciones del usuario, y usa un valor no deseado de forma predeterminada.
	Tipo de datos de parámetro incorrecto	El agente proporciona un valor del tipo de datos incorrecto para un parámetro (como una cadena cuando se requiere un número entero).
	Asignación de parámetros incorrecta	El agente asigna un valor al parámetro incorrecto (como intercambiar 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 factualmente incorrecto, o no aplica las transformaciones de datos necesarias.
	Selección incorrecta de herramientas	El agente selecciona la función incorrecta de su conjunto de herramientas disponible.
	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 inexistente	El agente incluye un argumento de parámetro que no está definido 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 de requisito previo step.
	Subestimación	El agente fuerza una llamada a la herramienta cuando debería responder con lenguaje natural (como solicitar una aclaración o rechazar una solicitud fuera del alcance ).
Respuesta de la herramienta	Respuesta de la herramienta irrelevante	La herramienta se ejecuta correctamente, pero muestra datos que no son relevantes para la búsqueda específica del usuario.
Respuesta de la herramienta	Error de la herramienta	La herramienta muestra 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 priorización recomendado

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

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.
Profundiza en los resultados por caso para encontrar casos de evaluación específicos que fallaron.
Genera clústeres de fallas para identificar patrones de pérdida sistémicos en las fallas.
Desglosa los seguimientos para encontrar el turno o la llamada a la herramienta exactos en los que se produjo la falla. En la consola de , navega a Plataforma de agentes > Agentes > Implementaciones , selecciona tu agente y abre la pestaña Seguimientos. Selecciona un seguimiento para ver el historial completo de la conversación y la secuencia exacta de entradas del modelo, llamadas a herramientas y respuestas.
Identifica la causa raíz: Usa la categoría de patrón de pérdida para determinar si el problema es una instrucción, una configuración de herramienta o un dato.
Aplica una corrección segmentada a las instrucciones del sistema, las definiciones de herramientas o los ejemplos de pocas tomas del agente.
Vuelve a ejecutar la evaluación y compara las puntuaciones para verificar la mejora.

Analiza los resultados de la evaluación y los clústeres de errores Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.