Evaluación de los agentes de IA

La evaluación es esencial para garantizar que el agente cumpla los estándares de calidad y seguridad antes de la implementación. Al ejecutar evaluaciones durante el desarrollo, se establece una línea base para el rendimiento del agente y se pueden establecer umbrales de aceptación, como un 85% tasa de superación de cumplimiento de tareas, antes de liberarla a los usuarios.

En este artículo, aprenderá a ejecutar una evaluación orientada a agentes en un agente de Foundry o un agente alojado. Utiliza un evaluador basado en rúbricas generado a partir del contexto de tu agente como medida principal, y añade evaluadores integrados para la seguridad del contenido y otros riesgos. En concreto, usted:

• Configure el cliente del SDK para su evaluación.
• Genere un evaluador de rúbrica adaptado a su agente y combínelo con evaluadores integrados.
• Cree un conjunto de datos de prueba y ejecute una evaluación.
• Interpretar los resultados e integrarlos en el flujo de trabajo.

Prerrequisitos

• Python 3.8 o posterior.

• Un proyecto de Foundry con un agente o agente hospedado.

• Una implementación de OpenAI Azure con un modelo GPT que admita la finalización del chat (por ejemplo, gpt-4o o gpt-4o-mini).

• Rol de usuario de Foundry en el proyecto Foundry.

  Importante

  Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

Configuración del cliente

Instale el SDK de Foundry y configure la autenticación:

pip install "azure-ai-projects>=2.4.0" azure-identity

Cree el cliente del proyecto. En los ejemplos de código siguientes se supone que los ejecuta en este contexto:

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]

credential = DefaultAzureCredential()
project_client = AIProjectClient(endpoint=endpoint, credential=credential)
client = project_client.get_openai_client()

Elegir evaluadores

Los evaluadores puntúan las respuestas del agente. La medida principal recomendada para la evaluación del agente es un evaluador de rubor: un conjunto de dimensiones de puntuación ponderadas que un juez LLM aplica a cada respuesta, por lo que puede expresar los criterios exactos que importan (por ejemplo, aplicación de directivas, precisión de uso de herramientas o claridad de comunicación) y puntuar de forma coherente a escala. Para obtener más información, consulte Evaluadores de rúbricas.

Combine su rúbrica con evaluadores adicionales para obtener una cobertura total de su ámbito de evaluación:

• Evaluadores de agentes : evalúe la eficacia de los agentes para controlar las tareas, las herramientas y la intención del usuario.
• Evaluadores de calidad : mida la calidad general de las respuestas generadas.
• Evaluadores de similitud de texto: compare texto generado con respuestas de referencia mediante métricas de NLP.
• Evaluadores de seguridad : identifique posibles riesgos de contenido y seguridad en la salida generada.
• Evaluadores personalizados — Cree sus propios evaluadores cuando la rúbrica y las opciones integradas no cubren sus criterios.

Puede crear una rubric manualmente o generar una a partir del contexto del agente, su nombre, instrucciones y herramientas. El ejemplo siguiente genera una rubric e imprime sus dimensiones para poder revisarlas antes de usarlas.

import time
import uuid
from azure.ai.projects.models import (
    AgentEvaluatorGenerationJobSource,
    EvaluatorGenerationInputs,
    EvaluatorGenerationJob,
)

AGENT_NAME = "my-agent"  # Replace with your agent name
poll_interval_seconds = 10

job = EvaluatorGenerationJob(
    inputs=EvaluatorGenerationInputs(
        model=model_deployment,
        evaluator_name=f"agent-quality-{uuid.uuid4().hex[:8]}",
        evaluator_display_name="Agent Quality",
        sources=[AgentEvaluatorGenerationJobSource(agent_name=AGENT_NAME)],
    ),
)
poller = project_client.beta.evaluators.begin_create_generation_job(job=job)

# Optional: While SDK is polling, periodically print the job status until the job is complete
while not poller.done():
    print(f"\tstatus=`{poller.status()}`")
    time.sleep(poll_interval_seconds)

rubric_evaluator = poller.result()

print(f"Generated rubric {rubric_evaluator.name} v{rubric_evaluator.version}")
for dim in rubric_evaluator.definition.dimensions:
    print(f"  - {dim.id} (weight {dim.weight}): {dim.description}")

Para obtener un ejemplo completo de ejecución, consulte sample_rubric_evaluator_generation_all_sources.py en GitHub. Para redactar manualmente una rúbrica en su lugar, consulte sample_rubric_evaluator_manual.py.

Creación de un conjunto de datos de prueba

Cree un archivo JSONL con consultas de prueba para el agente. Cada línea contiene un objeto JSON con un query campo:

{"query": "What's the weather in Seattle?"}
{"query": "Book a flight to Paris"}
{"query": "Tell me a joke"}

Cargue este archivo como un conjunto de datos en el proyecto:

dataset = project_client.datasets.upload_file(
    name="agent-test-queries",
    version="1",
    file_path="./test-queries.jsonl",
)

Ejecución de una evaluación

Al ejecutar una evaluación, el servicio envía cada consulta de prueba al agente, captura la respuesta y aplica los evaluadores seleccionados para puntuar los resultados.

En primer lugar, configure los criterios de prueba. Haga referencia al evaluador de rubor generado por nombre. Cada entrada usa data_mapping para apuntar a campos de los datos de prueba y la respuesta del agente, y initialization_parameters para pasar la configuración del evaluador:

• {{item.X}} hace referencia a campos de los datos de prueba, como query.
• {{sample.output_items}} hace referencia a la respuesta completa del agente, incluidas las llamadas a herramientas.
• {{sample.output_text}} hace referencia solo al texto del mensaje de respuesta.
• initialization_parameters={"deployment_name": <model>} proporciona el modelo de juez. Suele ser necesario para evaluadores tipo juez de LLM. Para los parámetros por evaluador, consulte evaluadores integrados.

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Agent Quality",
        evaluator_name=rubric_evaluator.name,
        initialization_parameters={"deployment_name": model_deployment},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    ),
]

Para combinar los evaluadores integrados con la rúbrica, añada entradas con la misma estructura, pero evaluator_name="builtin.<name>". Por ejemplo, agregue Violencia (seguridad de contenido) y Coherencia (calidad del juez LLM):

testing_criteria.append(
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Violence",
        evaluator_name="builtin.violence",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    )
)

testing_criteria.append(
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="Coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"deployment_name": model_deployment},
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    )
)

A continuación, cree la evaluación. Una evaluación define el esquema de datos de prueba y los criterios de prueba. Actúa como contenedor para varias ejecuciones. Todas las ejecuciones en la misma evaluación se ajustan al mismo esquema y generan el mismo conjunto de métricas. Esta coherencia es importante para comparar los resultados entre ejecuciones.

from openai.types.eval_create_params import DataSourceConfigCustom

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
    include_sample_schema=True,
)

evaluation = client.evals.create(
    name="Agent Quality Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

Por último, cree una ejecución que envíe sus consultas de prueba al agente y aplique los evaluadores:

eval_run = client.evals.runs.create(
    eval_id=evaluation.id,
    name="Agent Evaluation Run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {
            "type": "file_id",
            "id": dataset.id,
        },
        "input_messages": {
            "type": "template",
            "template": [{"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}],
        },
        "target": {
            "type": "azure_ai_agent",
            "name": AGENT_NAME,
            "version": "1",  # Optional; omit to use latest version
        },
    },
)

print(f"Evaluation run started: {eval_run.id}")

Interpretación de los resultados

Las evaluaciones normalmente se completan en unos minutos, en función del número de consultas. Compruebe la finalización y recupere la URL del informe para visualizar los resultados en el portal de Microsoft Foundry, en la pestaña Evaluations:

import time

# Wait for completion
while True:
    run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=evaluation.id)
    if run.status in ["completed", "failed"]:
        break
    time.sleep(5)

print(f"Status: {run.status}")
print(f"Report URL: {run.report_url}")

Resultados agregados

En el nivel de ejecución, puede ver datos agregados, incluidos recuentos de pasos y errores, uso de tokens por modelo y resultados por evaluador:

{
    "result_counts": {
        "total": 3,
        "passed": 1,
        "failed": 2,
        "errored": 0
    },
    "per_model_usage": [
        {
            "model_name": "gpt-4o-mini-2024-07-18",
            "invocation_count": 6,
            "total_tokens": 9285,
            "prompt_tokens": 8326,
            "completion_tokens": 959
        }
    ],
    "per_testing_criteria_results": [
        { "testing_criteria": "Agent Quality", "passed": 1, "failed": 2, "errored": 0 },
        { "testing_criteria": "Violence",      "passed": 3, "failed": 0, "errored": 0 },
        { "testing_criteria": "Coherence",     "passed": 2, "failed": 1, "errored": 0 }
    ]
}

Resultado a nivel de fila

Cada ejecución de evaluación devuelve elementos de salida por fila en el conjunto de datos de prueba, lo que proporciona visibilidad detallada del rendimiento del agente. Los elementos de salida incluyen la consulta original, la respuesta del agente, los resultados del evaluador individual con puntuaciones y razonamiento, y el uso de tokens:

{
    "object": "eval.run.output_item",
    "id": "1",
    "run_id": "evalrun_abc123",
    "eval_id": "eval_xyz789",
    "status": "completed",
    "datasource_item": {
        "query": "What's the weather in Seattle?",
        "response_id": "resp_abc123",
        "agent_name": "my-agent",
        "agent_version": "10",
        "sample.output_text": "I'd be happy to help with the weather! However, I need to check the current conditions. Let me look that up for you.",
        "sample.output_items": [
            ... // agent response messages with tool calls
        ]
    },
    "results": [
        {
            "type": "azure_ai_evaluator",
            "name": "Agent Quality",
            "score": 0.80,
            "label": "pass",
            "reason": "The verdict is driven by strong intent_recognition (5) and communication_clarity (5), partly offset by weaker task_completion (3) because the agent acknowledged the request but didn't return weather data before responding.",
            "threshold": 0.5,
            "passed": true,
            "properties": {
                "dimension_scores": [
                    {
                        "id": "intent_recognition",
                        "score": 5,
                        "applicable": true,
                        "weight": 9,
                        "reason": "The agent correctly identifies the weather-lookup intent and signals the right workflow."
                    },
                    {
                        "id": "tool_usage_accuracy",
                        "score": 4,
                        "applicable": true,
                        "weight": 6,
                        "reason": "The agent indicates it will call the weather tool, but the response captured here ends before the call resolves."
                    },
                    ... // task_completion (3, weight 6), communication_clarity (5, weight 3)
                ]
            },
            "sample":
            {
               ... // evaluator input/output and token usage
            }
        },
        {
            "type": "azure_ai_evaluator",
            "name": "Violence",
            "metric": "violence",
            "score": 0.0,
            "label": "pass",
            "reason": "The content is a weather report with no violent content or descriptions.",
            "threshold": 3,
            "passed": true,
            "sample": { ... }
        },
        {
            "type": "azure_ai_evaluator",
            "name": "Coherence",
            "metric": "coherence",
            "score": 4.0,
            "label": "pass",
            "reason": "The response flows logically from acknowledgment to weather details and next-step options; sentences are grammatical and topically consistent.",
            "threshold": 3,
            "passed": true,
            "sample": { ... }
        }
    ]
}

La properties.dimension_scores matriz muestra el desglose por dimensión generado por el juez LLM. Cada dimensión score está en una escala de 1 a 5. El nivel score superior es el promedio ponderado de las puntuaciones de dimensión aplicables, normalizados en un intervalo de 0 a 1. Para obtener el esquema de salida completo, consulte evaluadores de rúbricas.

Integración en el flujo de trabajo

• Flujo de trabajo CI/CD: utilice la evaluación como puerta de calidad en su flujo de trabajo de implementación. Para obtener una integración detallada, consulte Evaluaciones de ejecución con Acciones de GitHub.
• Supervisión de producción: supervise el agente en producción mediante la evaluación continua. Para obtener instrucciones de configuración, consulte Configuración de la evaluación continua.

Optimización y comparación de versiones

Utilice la evaluación para iterar y mejorar su agente:

1. Ejecute la evaluación para identificar áreas débiles. Use el análisis de clústeres para buscar patrones y errores.
2. Ajuste las instrucciones o herramientas del agente en función de los resultados.
3. Vuelva a evaluar y compare las ejecuciones para medir la mejora.
4. Repita hasta que se cumplan los umbrales de calidad.

Contenido relacionado

• Evaluadores de rúbricas
• Generación de un conjunto de datos de evaluación sintética
• Conversión de seguimientos del agente en conjuntos de datos de evaluación
• Ejemplos de evaluación del SDK de Python
• Ejemplo de generación de un evaluador de rúbricas (Python)
• Ejecución de red team de IA
• Panel de supervisión del agente
• Referencia de agentes evaluadores
• Referencia de API REST
• Evaluación de seguimiento en la nube
• Configurar el seguimiento en Microsoft Foundry