Ejecución de evaluaciones en la nube mediante el SDK de Microsoft Foundry

Importante

Los elementos marcados (versión preliminar) de este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para obtener más información, vea Supplemental Terms of Use for Microsoft Azure Previews.

En este artículo, aprenderá a ejecutar evaluaciones en la nube (versión preliminar) para realizar pruebas previas a la implementación en un conjunto de datos de prueba.

Use evaluaciones en la nube para la mayoría de los escenarios, especialmente al probar a escala, integrar evaluaciones en canalizaciones de integración continua y entrega continua (CI/CD) o realizar pruebas previas a la implementación. La ejecución de evaluaciones en la nube elimina la necesidad de administrar la infraestructura de proceso local y admite flujos de trabajo de pruebas automatizadas a gran escala. También puede programar evaluaciones para que se ejecuten periódicamente o configurar la evaluación continua para evaluar automáticamente las respuestas de agente muestreadas en producción.

Los resultados de la evaluación en la nube se almacenan en el proyecto foundry. Puede revisar los resultados en el portal, recuperarlos a través del SDK o enrutarlos a Application Insights si están conectados. La evaluación en la nube admite todos los evaluadores curados por Microsoft y sus propios evaluadores personalizados. Los evaluadores se administran en el catálogo del evaluador con el mismo control de acceso basado en rol y ámbito del proyecto.

Propina

Para obtener ejemplos completos de ejecución, consulte los ejemplos de evaluación de SDK de Python en GitHub.

Funcionamiento de la evaluación en la nube

Para ejecutar una evaluación en la nube, cree una definición de evaluación con el esquema de datos y los criterios de prueba (evaluadores) y, a continuación, cree una ejecución de evaluación. La ejecución evalúa cada evaluador contra tus datos y devuelve los resultados calificados que puedes consultar para verificar su finalización.

La evaluación en la nube admite los siguientes escenarios:

Escenario Cuándo usar Tipo de origen de datos Objetivo
Evaluación del conjunto de datos Evalúe las respuestas calculadas previamente en un archivo JSONL. jsonl —
Evaluación del conjunto de datos CSV Evalúe las respuestas calculadas previamente en un archivo CSV. csv —
Evaluación del objetivo del modelo Proporcione consultas y genere respuestas a partir de un modelo en tiempo de ejecución para su evaluación. azure_ai_target_completions azure_ai_model
Evaluación de objetivos del agente Proporcione consultas y genere respuestas de un agente Foundry (invitado o alojado) en tiempo de ejecución para su evaluación. azure_ai_target_completions azure_ai_agent
Evaluación de la respuesta del agente Recupera y evalúa las respuestas del agente de Foundry mediante los identificadores de respuesta. azure_ai_responses —
Evaluación de seguimiento Evalúe las interacciones del agente ya capturadas en Application Insights por identificador de seguimiento. Usa este enfoque para agentes no Foundry (LangChain y marcos personalizados que sigan la metodología de registro basada en OpenTelemetry). azure_ai_traces —
Evaluación de datos sintéticos (versión preliminar) Genere consultas de prueba sintéticas, envíelas a un modelo o agente y evalúe las respuestas. azure_ai_synthetic_data_gen_preview azure_ai_model o azure_ai_agent
Evaluación del equipo rojo Realice pruebas adversariales automatizadas en un modelo o agente. azure_ai_red_team azure_ai_model o azure_ai_agent

La mayoría de los escenarios requieren datos de entrada. Puede proporcionar datos de dos maneras:

Tipo de origen Descripción
file_id Haga referencia a un conjunto de datos subido mediante su identificador.
file_content Proporcione los datos en línea en la solicitud.

Cada evaluación requiere un data_source_config que indique al servicio qué campos deben esperar en los datos:

  • custom — define un item_schema con los nombres y tipos de campo. include_sample_schema Establézcalo como true cuando se utilice un objetivo para que los evaluadores puedan hacer referencia a las respuestas generadas.
  • azure_ai_source : el esquema se deduce del servicio. Establézcalo "scenario" en para la evaluación de respuesta del agente, "responses" para la "traces", para la "synthetic_data_gen_preview" o para "red_team".

Cada escenario requiere evaluadores que definan los criterios de prueba. Para obtener instrucciones sobre cómo seleccionar evaluadores, consulte Evaluadores integrados.

Requisitos previos

Nota

Algunas características de evaluación tienen restricciones regionales. Consulte las regiones admitidas para obtener más información.

Comenzar

Instale el SDK y configure el cliente:

pip install "azure-ai-projects>=2.0.0"

import os
from azure.identity import DefaultAzureCredential 
from azure.ai.projects import AIProjectClient 
from openai.types.eval_create_params import DataSourceConfigCustom
from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileContent,
    SourceFileContentContent,
    SourceFileID,
)

# Azure AI Project endpoint
# Example: https://<account_name>.services.ai.azure.com/api/projects/<project_name>
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

# Model deployment name (for AI-assisted evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Dataset details (optional, for reusing existing datasets)
dataset_name = os.environ.get("DATASET_NAME", "")
dataset_version = os.environ.get("DATASET_VERSION", "1")

# Create the project client
project_client = AIProjectClient( 
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
)

# Get the OpenAI client for evaluation API
client = project_client.get_openai_client()

Preparación de los datos de entrada

La mayoría de los escenarios de evaluación requieren datos de entrada. Puede proporcionar datos de dos maneras:

Cargue un archivo JSONL o CSV para crear un conjunto de datos con versiones en el proyecto foundry. Los conjuntos de datos admiten el control de versiones y la reutilización en varias ejecuciones de evaluación. Use este enfoque para pruebas de producción y flujos de trabajo de CI/CD.

Prepare un archivo JSONL con un objeto JSON por línea que contenga los campos que necesitan los evaluadores:

{"query": "What is machine learning?", "response": "Machine learning is a subset of AI.", "ground_truth": "Machine learning is a type of AI that learns from data."}
{"query": "Explain neural networks.", "response": "Neural networks are computing systems inspired by biological neural networks.", "ground_truth": "Neural networks are a set of algorithms modeled after the human brain."}

O prepare un archivo CSV con encabezados de columna que coincidan con los campos del evaluador:

query,response,ground_truth
What is machine learning?,Machine learning is a subset of AI.,Machine learning is a type of AI that learns from data.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are a set of algorithms modeled after the human brain.

# Upload a local JSONL file. Skip this step if you already have a dataset registered.
data_id = project_client.datasets.upload_file(
    name=dataset_name,
    version=dataset_version,
    file_path="./evaluate_test_data.jsonl",
).id

Proporcionar datos en línea

Para experimentar rápidamente con conjuntos de pruebas pequeños, proporcione datos directamente en la solicitud de evaluación mediante file_content.

source = SourceFileContent(
    type="file_content",
    content=[
        SourceFileContentContent(
            item={
                "query": "How can I safely de-escalate a tense situation?",
                "ground_truth": "Encourage calm communication, seek help if needed, and avoid harm.",
            }
        ),
        SourceFileContentContent(
            item={
                "query": "What is the largest city in France?",
                "ground_truth": "Paris",
            }
        ),
    ],
)

Pasa source como el campo "source" en la configuración de tu origen de datos al crear un run. Las secciones del escenario que siguen usan file_id de forma predeterminada.

Evaluación del conjunto de datos

Evalúe las respuestas calculadas previamente en un archivo JSONL mediante el tipo de jsonl origen de datos. Este escenario es útil cuando ya tiene salidas de modelo y desea evaluar su calidad.

Propina

Antes de comenzar, complete Introducción y Preparación de los datos de entrada.

Definir el esquema de datos y los evaluadores

Especifique el esquema que coincida con los campos JSONL y seleccione los evaluadores (criterios de prueba) que se van a ejecutar. Use el data_mapping parámetro para conectar campos de los datos de entrada a los parámetros del evaluador con {{item.field}} sintaxis. data_mapping Incluya siempre los campos de entrada necesarios para cada evaluador. Los nombres de campo deben coincidir con los del archivo JSONL; por ejemplo, si los datos tienen "question" en lugar de "query", usen "{{item.question}}" en la asignación. Para conocer los parámetros necesarios por evaluador, consulte evaluadores integrados.

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

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
            "response": "{{item.response}}",
            "ground_truth": "{{item.ground_truth}}",
        },
    },
]

Crear evaluación y ejecutar

Cree la evaluación y, a continuación, inicie una ejecución en el conjunto de datos cargado. La ejecución ejecuta cada evaluador en cada fila del conjunto de datos.

# Create the evaluation
eval_object = client.evals.create(
    name="dataset-evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the uploaded dataset
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="dataset-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
)

Para obtener un ejemplo completo de ejecución, vea sample_evaluations_builtin_with_dataset_id.py en GitHub. Para verificar la finalización e interpretar los resultados, consulte Obtener resultados.

Evaluación del conjunto de datos CSV

Evalúe las respuestas calculadas previamente en un archivo CSV mediante el tipo de csv origen de datos. Este escenario funciona del mismo modo que la evaluación del conjunto de datos , pero acepta archivos CSV en lugar de JSONL. Use CSV cuando los datos ya estén en formato tabular o hoja de cálculo.

Propina

Antes de comenzar, complete Introducción y Preparación de los datos de entrada.

Preparación de un archivo CSV

Cree un archivo CSV con encabezados de columna que coincidan con los campos que necesitan los evaluadores. Cada fila representa un caso de prueba:

query,response,context,ground_truth
What is cloud computing?,Cloud computing delivers computing services over the internet.,Cloud computing is a technology for on-demand resource delivery.,Cloud computing is the delivery of computing services including servers storage and databases over the internet.
What is machine learning?,Machine learning is a subset of AI that learns from data.,Machine learning is a branch of artificial intelligence.,Machine learning is a type of AI that enables computers to learn from data without being explicitly programmed.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are used in deep learning.,Neural networks are a set of algorithms modeled after the human brain designed to recognize patterns.

Carga y ejecución

Cargue el archivo CSV como un conjunto de datos y cree una evaluación mediante el tipo de csv origen de datos. La definición de esquema y la configuración del evaluador son las mismas que para las evaluaciones JSONL; la única diferencia es en "type": "csv" el origen de datos.

# Upload the CSV file
data_id = project_client.datasets.upload_file(
    name="eval-csv-data",
    version="1",
    file_path="./evaluation_data.csv",
).id

# Define the schema matching your CSV columns
data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "context": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": [],
    },
    include_sample_schema=True,
)

# Define evaluators with data mappings to CSV columns
testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = client.evals.create(
    name="CSV evaluation with built-in evaluators",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the CSV data source type
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="csv-evaluation-run",
    data_source={
        "type": "csv",
        "source": {
            "type": "file_id",
            "id": data_id,
        },
    },
)

Para verificar la finalización e interpretar los resultados, consulte Obtener resultados.

Evaluación del objetivo del modelo

Envíe consultas a un modelo implementado en tiempo de ejecución y evalúe las respuestas mediante el tipo de azure_ai_target_completions origen de datos con un azure_ai_model destino. Los datos de entrada contienen consultas; el modelo genera respuestas que se evalúan a continuación.

Propina

Antes de comenzar, complete Introducción y Preparación de los datos de entrada.

Definir la plantilla de mensaje y el destino

La input_messages plantilla controla cómo se envían las consultas al modelo. Use {{item.query}} para hacer referencia a campos de los datos de entrada. Especifique el modelo para evaluar y los parámetros de muestreo opcionales:

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_model",
    "model": "gpt-5-mini",
    "sampling_params": {
        "top_p": 1.0,
        "max_completion_tokens": 2048,
    },
}

Configurar evaluadores y mapeos de datos

Cuando el modelo genera respuestas en tiempo de ejecución, use {{sample.output_text}} en data_mapping para hacer referencia a la salida del modelo. Use {{item.field}} para hacer referencia a campos de los datos de entrada.

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

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Crear evaluación y ejecutar

eval_object = client.evals.create(
    name="Model Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

Para obtener un ejemplo completo de ejecución, vea sample_model_evaluation.py en GitHub. Para verificar la finalización e interpretar los resultados, consulte Obtener resultados.

Propina

Para agregar otra ejecución de evaluación, puede usar el mismo código.

Evaluación del objetivo del agente

Envíe consultas a un agente de Foundry en tiempo de ejecución y evalúe las respuestas utilizando un tipo de origen de datos azure_ai_target_completions con un objetivo azure_ai_agent como destino. Este escenario funciona tanto para agentes inmediatos como para agentes hospedados.

Propina

Antes de comenzar, complete Introducción y Preparación de los datos de entrada.

Propina

Los agentes hospedados que usan el protocolo de respuestas funcionan con los mismos ejemplos de código que se muestran aquí. En el caso de los agentes hospedados que usan el protocolo de invocaciones, el input_messages formato es diferente. Consulte Protocolo de invocaciones de agente hospedado para obtener más información.

Definir la plantilla de mensaje y el destino

La input_messages plantilla controla cómo se envían las consultas al agente. Use {{item.query}} para hacer referencia a campos de los datos de entrada. Especifique por nombre el agente que se va a evaluar.

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "developer",
            "content": {
                "type": "input_text",
                "text": "You are a helpful assistant. Answer clearly and safely."
            }
        },
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_agent",
    "name": "my-agent",
    "version": "1"  # Optional. Uses latest version if omitted.
}

Configurar evaluadores y mapeos de datos

Cuando el agente genera respuestas en tiempo de ejecución, use {{sample.*}} variables en data_mapping para hacer referencia a la salida del agente:

Variable Descripción Uso para
{{sample.output_text}} Respuesta de texto sin formato del agente. Evaluadores que esperan una respuesta de cadena (por ejemplo, coherence, violence).
{{sample.output_items}} Salida JSON estructurada del agente, incluidas las llamadas a herramientas. Evaluadores que necesitan contexto de interacción completo (por ejemplo, task_adherence).
{{item.field}} Un campo de sus datos de entrada. Campos de entrada como query o ground_truth.

Propina

El query campo puede contener JSON estructurado, incluidos los mensajes del sistema y el historial de conversaciones. Algunos evaluadores de agentes, como task_adherence, usan este contexto para obtener una puntuación más precisa. Para más información sobre el formato de consulta, consulte evaluadores de agentes.

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

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "task_adherence",
        "evaluator_name": "builtin.task_adherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Crear evaluación y ejecutar

eval_object = client.evals.create(
    name="Agent Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

agent_eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

Para ver un ejemplo completo de ejecución, vea sample_agent_evaluation.py en GitHub. Para verificar la finalización e interpretar los resultados, consulte Obtener resultados.

Protocolo de invocaciones de agente hospedado

Los agentes hospedados que usan el protocolo de invocaciones admiten el mismo azure_ai_agent tipo de destino, pero usan un formato de forma input_messageslibre. En lugar del formato de plantilla estructurado, proporcione un objeto JSON que se asigne directamente al cuerpo de la solicitud del /invocations agente. Utiliza {{item.*}} marcadores de posición para sustituir los campos de los datos de entrada.

Si un agente hospedado admite tanto las respuestas como los protocolos de invocación, el servicio usa el protocolo de invocaciones de forma predeterminada.

Definir el formato de mensaje y el destino

input_messages = {"message": "{{item.query}}"}

target = {
    "type": "azure_ai_agent",
    "name": "my-hosted-agent",  # Replace with your hosted agent name
    "version": "1",
}

Crear evaluación y ejecutar

eval_object = client.evals.create(
    name="Hosted Agent Invocations Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="hosted-agent-invocations-evaluation",
    data_source=data_source,
)

La configuración del evaluador y las asignaciones de datos son las mismas que para la evaluación del agente de indicaciones. Use {{sample.output_text}} para la respuesta de texto del agente y {{sample.output_items}} para la salida estructurada completa, incluidas las llamadas a herramientas.

Evaluación de la respuesta del agente

Recupere y evalúe las respuestas del agente Foundry por identificadores de respuesta usando el tipo de origen de datos azure_ai_responses. Use este escenario para evaluar interacciones específicas del agente después de que se produzcan.

Propina

Antes de comenzar, complete Introducción.

Un identificador de respuesta es un identificador único devuelto cada vez que un agente de Foundry genera una respuesta. Puede recopilar identificadores de respuesta de las interacciones del agente mediante la API de respuestas o los registros de seguimiento de la aplicación. Proporcione los identificadores directamente como contenido de archivo o súbalos como un conjunto de datos (consulte Preparar los datos de entrada).

Recopilar identificadores de respuesta

Cada llamada a la API de respuestas devuelve un objeto de respuesta con un campo único id . Recopile estos identificadores de las interacciones de la aplicación o indíquelos directamente:

# Generate response IDs by calling a model through the Responses API
response = client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

También puede recopilar identificadores de respuesta de las interacciones del agente en los registros de seguimiento de su aplicación o su canalización de supervisión. Cada identificador de respuesta identifica de forma única una respuesta almacenada que el servicio de evaluación puede recuperar.

Crear evaluación y ejecutar

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

Para obtener un ejemplo completo de ejecución, vea sample_agent_response_evaluation.py en GitHub. Para verificar la finalización e interpretar los resultados, consulte Obtener resultados.

Evaluación de seguimiento

Evalúe las interacciones del agente que ya se capturaron en Application Insights. Utilice el tipo de origen de datos azure_ai_traces. Este escenario es útil para la evaluación posterior a la implementación del tráfico real en producción: se seleccionan trazas de la canalización de monitoreo y se ejecutan evaluadores sobre ellas sin volver a enviar ninguna solicitud.

Importante

La evaluación de seguimiento es el enfoque recomendado para evaluar agentes no creados con el servicio de agente de Microsoft Foundry, incluidos LangChain y marcos personalizados. Siempre que el agente emita OpenTelemetry siguiendo las convenciones semánticas de GenAI a Application Insights, la evaluación de trazas puede analizar sus interacciones mediante los mismos evaluadores que están disponibles para los agentes de Foundry.

La evaluación de seguimiento admite dos modos:

  • Por identificadores de seguimiento : evalúe interacciones específicas del agente proporcionando sus operation_Id valores de Application Insights.
  • Por filtro de agente : detecta y evalúa automáticamente los seguimientos recientes de un agente determinado, sin recopilar manualmente identificadores de seguimiento.

Propina

Antes de comenzar, complete Introducción. Este escenario también requiere un recurso de Application Insights conectado al proyecto Foundry.

Requisitos de datos de seguimiento

La evaluación de seguimiento requiere que el agente emita intervalos siguiendo las convenciones semánticas de OpenTelemetry para la inteligencia artificial generativa. En concreto, el servicio de evaluación lee segmentosinvoke_agent de Application Insights y extrae los datos de conversación de sus atributos.

Se usan los siguientes atributos span:

Atributo Obligatorio Descripción
gen_ai.operation.name Sí Debe ser igual a "invoke_agent". El servicio omite todos los demás intervalos.
gen_ai.agent.id Para el modo de filtro del agente Identificador de agente único (formato: agent-name:version).
gen_ai.agent.name Para el modo filtro del agente Nombre de agente legible por humanos.
gen_ai.input.messages Para entradas de consulta destinadas a evaluadores Matriz JSON de mensajes de entrada siguiendo el formato de mensaje de convenciones semánticas de GenAI. Mensajes con rol user o system se asignan a query; mensajes con rol assistant o tool se asignan a response.
gen_ai.output.messages Para las entradas de consulta de evaluadores Matriz JSON de mensajes de salida generados por el modelo. Todos los mensajes de salida se asignan a response. Si la salida también contiene tipo: tool_call o tipo: tool_result, se asigna a tool_calls
gen_ai.tool.definitions Opcional Matriz JSON de esquemas de herramientas disponibles para el agente. Si no está presente, el servicio intenta deducir las definiciones de herramientas de los mensajes de llamada a la herramienta, pero los esquemas inferidos pueden estar incompletos.
gen_ai.conversation.id Opcional Identificador de conversación, pasado a los resultados de evaluación para la correlación.

Nota

Si gen_ai.input.messages y gen_ai.output.messages están vacíos o faltan, los evaluadores de calidad (coherencia, fluidez, relevancia, resolución de intenciones) devolverán score=None. Los evaluadores de seguridad (violencia, auto-daño, sexual, odio/injusticia) pueden producir puntuaciones con datos parciales, pero pueden no producir resultados significativos.

Para los agentes de Python creados con el SDK del servidor del agente de IA de Azure, agregue el complemento [tracing] para habilitar la emisión automática de spans:

pip install "azure-ai-agentserver-core[tracing]"

Requisitos previos para la evaluación de seguimiento

Además de los requisitos previos generales, la evaluación de seguimiento requiere:

  • Un recurso de Application Insights conectado al proyecto Foundry. Consulte Configurar el seguimiento en Microsoft Foundry.
  • La identidad administrada del proyecto debe tener el rol Log Analytics Reader tanto en el recurso de Application Insights como en su área de trabajo de Log Analytics vinculada.
  • El paquete azure-monitor-query Python (solo es necesario si recopila identificadores de seguimiento manualmente).
pip install "azure-ai-projects>=2.0.0" azure-monitor-query

Establezca estas variables de entorno:

  • APPINSIGHTS_RESOURCE_ID: el identificador de recurso de Application Insights (por ejemplo, /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
  • AGENT_ID : identificador del agente emitido por la integración de seguimiento (gen_ai.agent.id atributo), que se usa para filtrar los seguimientos. Formato: agent-name:version.
  • TRACE_LOOKBACK_HOURS — (Opcional) Número de horas a considerar al retroceder en la consulta de trazas. Por defecto es 1.

Opción A: Evaluar por filtro del agente

El enfoque más sencillo: permite que el servicio detecte y evalúe automáticamente los seguimientos recientes de un agente específico. No se necesita ninguna colección de identificadores de seguimiento manual.

import os

agent_id = os.environ["AGENT_ID"]  # e.g., "my-weather-agent:1"
trace_lookback_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = client.evals.create(
    name="Agent Trace Evaluation (by agent)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run — the service queries App Insights for matching traces
data_source = {
    "type": "azure_ai_traces",
    "agent_id": agent_id,
    "max_traces": 50,           # Maximum number of traces to evaluate
    "lookback_hours": trace_lookback_hours,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    data_source=data_source,
)

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

Los filtros invoke_agent del servicio se aplican según el atributo gen_ai.agent.id, selecciona hasta max_traces identificadores únicos de trazas, y evalúa todos los tramos de esas trazas.

Opción B: Evaluar por identificadores de seguimiento

Para obtener más control, recopile identificadores de seguimiento específicos de Application Insights y evalúelos. Esto es útil cuando desea evaluar un conjunto seleccionado de interacciones (por ejemplo, rastros marcados por alertas o muestreados para la revisión de calidad).

Recopilación de identificadores de seguimiento de Application Insights

Consulte Application Insights para ver los operation_Id valores de los seguimientos del agente. Cada operation_Id representa una interacción completa del agente:

import os
from datetime import datetime, timedelta, timezone
from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, LogsQueryStatus

appinsights_resource_id = os.environ["APPINSIGHTS_RESOURCE_ID"]
agent_id = os.environ["AGENT_ID"]
trace_query_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(hours=trace_query_hours)

query = f"""dependencies
| where timestamp between (datetime({start_time.isoformat()}) .. datetime({end_time.isoformat()}))
| extend agent_id = tostring(customDimensions["gen_ai.agent.id"])
| where agent_id == "{agent_id}"
| distinct operation_Id"""

credential = DefaultAzureCredential()
logs_client = LogsQueryClient(credential)
response = logs_client.query_resource(
    appinsights_resource_id,
    query=query,
    timespan=None,  # Time range is specified in the query itself
)

trace_ids = []
if response.status == LogsQueryStatus.SUCCESS:
    for table in response.tables:
        for row in table.rows:
            trace_ids.append(row[0])

print(f"Found {len(trace_ids)} trace IDs")

Crear evaluación y ejecutar con identificadores de seguimiento

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = client.evals.create(
    name="Agent Trace Evaluation (by trace IDs)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run using the collected trace IDs
data_source = {
    "type": "azure_ai_traces",
    "trace_ids": trace_ids,
    "lookback_hours": trace_query_hours,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    metadata={
        "agent_id": agent_id,
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
    },
    data_source=data_source,
)

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

Configurar evaluadores y mapeos de datos

Al evaluar trazas, el servicio extrae automáticamente los datos de conversaciones de los atributos de span de OpenTelemetry. Use estos nombres de campo directamente en data_mapping (sin los item. prefijos o sample. usados en otros escenarios):

Variable Atributo de origen Descripción
{{item.query}} gen_ai.input.messages (roles de usuario/sistema) Consulta de usuario extraída del seguimiento.
{{item.response}} gen_ai.input.messages (roles de asistente/herramienta) + gen_ai.output.messages La respuesta del agente extraída de la traza.
{{item.tool_definitions}} gen_ai.tool.definitions Esquemas de herramientas disponibles para el agente. Solo es necesario para evaluadores vinculados a herramientas
{{item.tool_calls}} Extraído de los mensajes del asistente en gen_ai.input.messages / gen_ai.output.messages Las solicitudes de herramienta realizadas por el agente durante la interacción. Usado por evaluadores de herramientas. Solo es necesario para evaluadores relacionados con herramientas 
testing_criteria = [
    # Quality evaluators — require query and response from trace data
    {
        "type": "azure_ai_evaluator",
        "name": "intent_resolution",
        "evaluator_name": "builtin.intent_resolution",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    # Tool evaluators — assess tool usage quality
    {
        "type": "azure_ai_evaluator",
        "name": "tool_call_accuracy",
        "evaluator_name": "builtin.tool_call_accuracy",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_calls": "{{item.tool_calls}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    # Safety evaluators — work even with partial trace data
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {
            "threshold": 4,
        },
    },
]

Para ver un ejemplo completo de ejecución, vea sample_evaluations_builtin_with_traces.py en GitHub. Para verificar la finalización e interpretar los resultados, consulte Obtener resultados.

Evaluación de datos sintéticos (versión preliminar)

Genere consultas de prueba sintéticas, envíelas a un modelo implementado o al agente foundry y evalúe las respuestas mediante el tipo de azure_ai_synthetic_data_gen_preview origen de datos. Use este escenario cuando no tenga un conjunto de datos de prueba: el servicio genera consultas basadas en una solicitud que proporcione (o desde las instrucciones del agente), las ejecuta en el destino y evalúa las respuestas.

Propina

Antes de comenzar, complete Introducción.

Funcionamiento de la evaluación de datos sintéticos

  1. El servicio genera consultas sintéticas basadas en tu prompt y en archivos de datos de inicialización opcionales.
  2. Cada consulta se envía al destino especificado (modelo o agente) para generar una respuesta.
  3. Los evaluadores puntúan cada respuesta mediante la consulta y la respuesta generadas.
  4. Las consultas generadas se almacenan como un conjunto de datos en el proyecto para su reutilización.

Parámetros

Parámetro Obligatorio Descripción
samples_count Sí Número máximo de consultas de prueba sintéticas que se van a generar.
model_deployment_name Sí Implementación de modelo para utilizar como generación de consultas sintéticas. Solo se admiten modelos con la funcionalidad de la API de respuestas. Para obtener disponibilidad, consulte Disponibilidad de la región de la API de respuestas.
prompt No Instrucciones que describen el tipo de consultas que se van a generar. Opcional cuando el destino del agente tiene instrucciones configuradas.
output_dataset_name No Nombre del conjunto de datos de salida donde se almacenan las consultas generadas. Si no se proporciona, el servicio genera automáticamente un nombre.
sources No Archivos de datos de inicialización (por identificador de archivo) para mejorar la relevancia de las consultas generadas. Actualmente solo se admite un archivo.

Configurar evaluadores y mapeos de datos

El generador de datos sintéticos genera consultas en el {{item.query}} campo . El objetivo genera respuestas que están disponibles en {{sample.output_text}}. Relacione estos campos con sus evaluadores:

data_source_config = {"type": "azure_ai_source", "scenario": "synthetic_data_gen_preview"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Crear evaluación y ejecutar

Objetivo del modelo

Genere consultas sintéticas y evalúe un modelo:

eval_object = client.evals.create(
    name="Synthetic Data Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
        "output_dataset_name": "my-synthetic-dataset",
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-data-evaluation",
    data_source=data_source,
)

Opcionalmente, puede agregar un prompt del sistema para configurar el comportamiento del modelo de destino. Cuando se usa input_messages con la generación de datos sintéticos, incluya solo system mensajes de rol: el servicio proporciona las consultas generadas como mensajes de usuario automáticamente.

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
    "input_messages": {
        "type": "template",
        "template": [
            {
                "type": "message",
                "role": "system",
                "content": {
                    "type": "input_text",
                    "text": "You are a helpful customer service agent. Be empathetic and solution-oriented."
                }
            }
        ]
    },
}

Objetivo del agente

Generar consultas sintéticas y evaluar un agente de Foundry.

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent_name,
        "version": agent_version,
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-agent-evaluation",
    data_source=data_source,
)

Para verificar la finalización e interpretar los resultados, consulte Obtener resultados. La respuesta incluye una output_dataset_id propiedad que contiene el identificador del conjunto de datos generado, que puede usar para recuperar o reutilizar los datos sintéticos.

Obtención de resultados

Una vez completada una ejecución de evaluación, recupere los resultados puntuados y repase los resultados en el portal o mediante programación.

Consultar los resultados

Las ejecuciones de evaluación son asincrónicas. Sondee el estado de ejecución hasta que finalice y recupere los resultados:

import time
from pprint import pprint

while True:
    run = client.evals.runs.retrieve(
        run_id=eval_run.id, eval_id=eval_object.id
    )
    if run.status in ("completed", "failed"):
        break
    time.sleep(5)
    print("Waiting for eval run to complete...")

# Retrieve results
output_items = list(
    client.evals.runs.output_items.list(
        run_id=run.id, eval_id=eval_object.id
    )
)
pprint(output_items)
print(f"Report URL: {run.report_url}")

Interpretación de los resultados

Para obtener un único ejemplo de datos, todos los evaluadores generan el esquema siguiente:

  • Etiqueta: una etiqueta binaria "pass" o "fail", similar a la salida de una prueba unitaria. Use este resultado para facilitar las comparaciones entre evaluadores.
  • Puntuación: una puntuación de la escala natural de cada evaluador. Algunos evaluadores usan una referencia específica, la puntuación en una escala de 5 puntos (evaluadores de calidad) o una escala de 7 puntos (evaluadores de seguridad de contenido). Otros, como evaluadores de similitud textual, usan puntuaciones F1, que son floats entre 0 y 1. Cualquier "puntuación" no binaria está binarizada a "pasar" o "fallar" en el campo "etiqueta" en función del "umbral".
  • Umbral: las puntuaciones no binarias se binarizan como "pasar" o "fallar" en función de un umbral predeterminado, que el usuario puede invalidar en el entorno del SDK.
  • Motivo: Para mejorar la inteligibilidad, todos los evaluadores de LLM-juez también generan un campo de razonamiento para explicar por qué se da una puntuación determinada.
  • Detalles: (opcional) Para algunos evaluadores, como tool_call_accuracy, puede haber un campo o marcas de "detalles" que contengan información adicional para ayudar a los usuarios a depurar sus aplicaciones.

Salida de ejemplo (elemento único)

{
  "type": "azure_ai_evaluator",
  "name": "Coherence",
  "metric": "coherence",
  "score": 4.0,
  "label": "pass",
  "reason": "The response is well-structured and logically organized, presenting information in a clear and coherent manner.",
  "threshold": 3,
  "passed": true
}

Resultado de ejemplo (agregado)

Para obtener resultados agregados en varios ejemplos de datos (un conjunto de datos), la tasa media de los ejemplos con un "aprobado" forma la tasa de aprobación de ese conjunto de datos.

{
  "eval_id": "eval_abc123",
  "run_id": "run_xyz789",
  "status": "completed",
  "result_counts": {
    "passed": 85,
    "failed": 15,
    "total": 100
  },
  "per_testing_criteria_results": [
    {
      "name": "coherence",
      "passed": 92,
      "failed": 8,
      "pass_rate": 0.92
    },
    {
      "name": "relevance", 
      "passed": 78,
      "failed": 22,
      "pass_rate": 0.78
    }
  ]
}

Solución de problemas

Trabajo en ejecución durante mucho tiempo

El trabajo de evaluación puede permanecer en el estado En ejecución durante un tiempo prolongado. Esto suele ocurrir cuando la implementación del modelo de OpenAI de Azure no tiene suficiente capacidad, lo que provoca que el servicio vuelva a intentar las solicitudes.

Resolución:

  1. Cancele el trabajo de evaluación actual mediante client.evals.runs.cancel(run_id, eval_id=eval_id).
  2. Aumente la capacidad del modelo en el portal de Azure.
  3. Vuelva a ejecutar la evaluación.

Errores de autenticación

Si recibe un error 401 Unauthorized o 403 Forbidden, compruebe que:

  • El DefaultAzureCredential está configurado correctamente (ejecute az login si usa CLI de Azure).
  • Su cuenta tiene el rol Azure AI User en el proyecto Foundry.
  • La dirección URL del punto de conexión del proyecto es correcta e incluye los nombres de cuenta y proyecto.

Errores de formato de datos

Si la evaluación falla con un error de asignación de datos o de esquema:

  • Compruebe que el archivo JSONL tiene un objeto JSON válido por línea.
  • Confirme que los nombres de campo en data_mapping coinciden exactamente con los nombres de campo de su archivo JSONL, teniendo en cuenta las mayúsculas.
  • Compruebe que item_schema las propiedades coinciden con los campos del conjunto de datos.

Errores de límite de velocidad

Las creaciones de ejecuciones de evaluación están limitadas por tasa a nivel de inquilino, suscripción y proyecto. Si recibe una 429 Too Many Requests respuesta:

  • Compruebe el retry-after encabezado en la respuesta para el tiempo de espera recomendado.
  • Revise el cuerpo de la respuesta para ver los detalles del límite de velocidad.
  • Utilice el retroceso exponencial al reintentar solicitudes fallidas.

Si falla un trabajo de evaluación con un error 429 durante la ejecución:

  • Reduzca el tamaño del conjunto de datos de evaluación o divida en lotes más pequeños.
  • Aumente la cuota de tokens por minuto (TPM) para la implementación del modelo en el portal de Azure.

Errores de la herramienta de evaluador de agentes

Si un evaluador de herramientas devuelve un error debido a herramientas no admitidas:

  • Compruebe las herramientas admitidas para los evaluadores de agentes.
  • Como solución alternativa, encapsula las herramientas no admitidas como herramientas de función definidas por el usuario para que el evaluador pueda evaluarlas.

Contenido relacionado

  • Last updated on