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

Importante

Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. 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 integrados 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.

Sugerencia

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

Al usar el SDK de Foundry, registra los resultados de la evaluación en el proyecto foundry para mejorar la observabilidad. Esta función es compatible con todos los evaluadoresintegrados seleccionados por Microsoft. y sus propios evaluadores personalizados. Los evaluadores se pueden encontrar en la biblioteca del evaluador y tener el mismo control de acceso basado en rol y ámbito del proyecto.

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 ejecuta cada evaluador en los datos y devuelve los resultados puntuados que puede sondear para comprobar 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 objetivo del agente Proporcionar consultas y generar respuestas de un agente Foundry (ya sea tramite mensajes 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 Recupere y evalúe las respuestas del agente de Foundry por 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. Utiliza este enfoque para agentes que no son de Foundry (LangChain y frameworks personalizados que siguen el registro basado 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 de adversidad 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 Description
file_id Haga referencia a un conjunto de datos cargado por identificador.
file_content Proporcione los datos incluidos en la solicitud.

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

  • custom — Definís un item_schema con los nombres y tipos de campo. Establezca include_sample_schema en 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. Configurado "scenario" en "responses" para evaluación de respuesta del agente, "traces" para evaluación de trazas, "synthetic_data_gen_preview" para evaluación de datos sintéticos (preview) o "red_team" para red teaming.

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

Prerrequisitos

  • Un proyecto Foundry.
  • Una implementación de Azure de OpenAI con un modelo GPT que admite la finalización de conversaciones en un chat (por ejemplo, gpt-5-mini).
  • rol de Usuario de Azure IA en el proyecto Foundry.
  • Opcionalmente, puede usar su propia cuenta de almacenamiento para ejecutar evaluaciones.

Nota:

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

Empieza ahora

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",
            }
        ),
    ],
)

Pase source como el campo "source" en la configuración del origen de datos al crear una ejecución. Las secciones del escenario que siguen utilizan 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.

Sugerencia

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}}",
        },
    },
]

Creación de evaluación y ejecución

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 sondear la finalización e interpretar los resultados, consulte Obtener los 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.

Sugerencia

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 sondear la finalización e interpretar los resultados, consulte Obtener los 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.

Sugerencia

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}}",
        },
    },
]

Creación de evaluación y ejecución

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 sondear la finalización e interpretar los resultados, consulte Obtener los resultados.

Sugerencia

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

Evaluación de objetivo del agente

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

Sugerencia

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

Sugerencia

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 el agente por nombre para evaluarlo:

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 Description Usado 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}} Campo de los datos de entrada. Campos de entrada como query o ground_truth.

Sugerencia

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}}",
        },
    },
]

Creación de evaluación y ejecución

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 sondear la finalización e interpretar los resultados, consulte Obtener los 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. Utilice {{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",
}

Creación de evaluación y ejecución

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 indicación. 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 medio de los identificadores de respuesta utilizando 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.

Sugerencia

Antes de comenzar, complete Introducción.

Un identificador de respuesta es un identificador único devuelto cada vez que un agente 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 IDs en línea como contenido de archivo, o súbalos como un conjunto de datos (consulte Preparación de 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 o en la canalización de supervisión de la aplicación. Cada identificador de respuesta identifica de forma única una respuesta almacenada que el servicio de evaluación puede recuperar.

Creación de evaluación y ejecución

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 sondear la finalización e interpretar los resultados, consulte Obtener los resultados.

Evaluación de seguimiento

Evalúe las interacciones del agente que ya se capturaron en Application Insights. Use el tipo de origen de datos azure_ai_traces. Este escenario es útil para la evaluación posterior al despliegue del tráfico real de producción: seleccionas trazas de tu pipeline de monitorización y ejecutas evaluadores contra ellas sin reproducir 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. Mientras tu agente emita abarcados de OpenTelemetry siguiendo las convenciones semánticas de GenAI para Application Insights, la evaluación de trazas puede evaluar sus interacciones utilizando los mismos evaluadores disponibles para los agentes de Foundry.

La evaluación de seguimiento admite dos modos:

  • Mediante identificadores de seguimiento — Evalúe interacciones específicas de agentes proporcionando sus valores de operation_Id 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.

Sugerencia

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 trazos requiere que tu agente emita spans siguiendo las convenciones semánticas de OpenTelemetry para IAgenerativa. En concreto, el servicio de evaluación lee intervalos de tiempoinvoke_agent de Application Insights y extrae datos de interacción de sus atributos.

Se usan los siguientes atributos span:

Atributo Obligatorio Description
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 de filtro del agente Nombre del agente comprensible para humanos.
gen_ai.input.messages Para evaluadores, consultas de entrada 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 evaluadores, consultas de entrada 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, transferido a los resultados de evaluación para su 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 agentes Python construidos con el SDK Azure AI Agent Server, añade el [tracing] extra para habilitar la emisión automática de sparring:

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 a tu 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 para revisar al consultar trazos. Tiene como valor predeterminado 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}")

El servicio filtra los tramos invoke_agent por el atributo gen_ai.agent.id, selecciona hasta max_traces IDs de seguimiento únicos y evalúa todos los tramos de esos seguimientos.

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 resulta útil cuando desea evaluar un conjunto seleccionado de interacciones (por ejemplo, rastros marcados por alertas o muestreados para la revisión de calidad).

Recopila identificadores de seguimiento de Application Insights

Consulta en Application Insights para obtener operation_Id valores de las pistas de tu 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")

Creación y ejecución de evaluación 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 datos de conversación de los atributos de OpenTelemetry span. Use estos nombres de campo directamente en data_mapping (sin los item. prefijos o sample. usados en otros escenarios):

Variable Atributo de origen Description
{{item.query}} gen_ai.input.messages (roles de usuario/sistema) La consulta del usuario extraída del trazo.
{{item.response}} gen_ai.input.messages (roles de asistente/herramienta) + gen_ai.output.messages La respuesta del agente extraída del rastro.
{{item.tool_definitions}} gen_ai.tool.definitions Esquemas de herramientas disponibles para el agente. Únicamente necesario para evaluadores de herramientas
{{item.tool_calls}} Extraído de los mensajes del asistente en gen_ai.input.messages / gen_ai.output.messages Llamadas a herramientas realizadas por el agente durante la interacción. Usado por evaluadores de herramientas. Únicamente necesario para evaluadores de 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 sondear la finalización e interpretar los resultados, consulte Obtener los 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.

Sugerencia

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 Description
samples_count Sí Número máximo de consultas de prueba sintéticas que se van a generar.
model_deployment_name Sí Despliegue de modelos para usar en la 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. Es opcional cuando el objetivo 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 destino genera respuestas disponibles en {{sample.output_text}}. Asigna estos campos a tus 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}}",
        },
    },
]

Creación de evaluación y ejecución

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 indicador del sistema para dar forma al 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 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 sondear la finalización e interpretar los resultados, consulte Obtener los 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 números flotantes entre 0 y 1. Cualquier "puntuación" no binaria se binariza como "pasar" o "fallar" en el campo "etiqueta" en función del "umbral".
  • Umbral: las puntuaciones no binarias se binarizan para "pasar" o "fallar" en función de un umbral predeterminado, que el usuario puede anular en la interfaz del SDK.
  • Motivo: con el fin de mejorar la inteligibilidad, todos los evaluadores de LLM también generan un campo de justificación 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
}

Ejemplo de resultados (conjunto)

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 período 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, verifique que:

  • El DefaultAzureCredential está configurado correctamente (ejecute az login si usa Azure CLI).
  • 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 se produce un error en la evaluación con un error de asignación de datos o 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 (respetando mayúsculas y minúsculas).
  • Compruebe que item_schema las propiedades coinciden con los campos del conjunto de datos.

Errores de límite de tasa

Las creaciones de ejecución de evaluación tienen la velocidad limitada a nivel de inquilino, suscripción y proyecto. Si recibe una respuesta 429 Too Many Requests:

  • 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 retroceso exponencial al reintentar solicitudes con error.

Si se produce un error 429 en un trabajo de evaluación 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 agentes devuelve un error cuando las herramientas no son compatibles:

  • 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