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

En este artículo, aprenderá a ejecutar evaluaciones en la nube 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 mantenidos 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 ver ejemplos completos ejecutables, consulte los ejemplos de evaluación del SDK de Python en GitHub.

Funcionamiento de la evaluación en la nube

Una evaluación de la nube tiene tres pasos:

  1. Defina lo que se va a evaluar. Describe la estructura de tus datos (data_source_config) y los evaluadores (criterios de evaluación) que la puntúan.
  2. Cree la evaluación. Envíe la definición mediante openai_client.evals.create().
  3. Ejecútelo y lea los resultados. Inicie una ejecución mediante openai_client.evals.runs.create(), sondee hasta que finalice y lea los resultados puntuados. Consulte Obtención de resultados para el esquema de resultados.

El resto de esta sección le guía por las entradas del paso 1: elegir un escenario y, a continuación, elegir evaluadores.

Elija el punto de partida.

Conjunto de datos existente

Utilice esta ruta cuando ya tenga consultas y respuestas recopiladas en un archivo (o consultas más verdad fundamental) y solo quiera que Foundry las puntúe. JSONL admite tanto filas a nivel de turno como entradas a nivel de conversación; CSV solo admite datos a nivel de turno.

Escenario Cuándo usar Tipo de origen de datos
Evaluación del conjunto de datos a nivel de turno Cada fila es un query/response par, opcionalmente con context o ground_truth. jsonl o csv
Evaluación del conjunto de datos de nivel de conversación (versión preliminar) Cada fila es una conversación expresada como una messages matriz. jsonl

Datos en Foundry o Application Insights

Utilice esta ruta cuando su agente ya esté en ejecución y quiera evaluar lo que realmente ha ocurrido. En lugar de extraer datos, se señalan a Foundry los datos donde ya están, ya sea mediante el identificador de respuesta de Foundry o mediante el Id. de seguimiento o conversación de Application Insights.

Escenario Cuándo usar Tipo de origen de datos
Evaluación de la respuesta del agente El agente se ejecuta en Foundry y usted tiene ID de respuesta para puntuar. azure_ai_responses
Evaluación de seguimiento de nivel de turno (versión preliminar) El agente emite seguimientos de OpenTelemetry a Application Insights, incluidos marcos que no son de Foundry, como LangChain o agentes personalizados instrumentados por OpenTelemetry. Cada seguimiento se puntúa de forma independiente. azure_ai_trace_data_source_preview
Evaluación de seguimiento de nivel de conversación (versión preliminar) Los mismos orígenes de seguimiento, pero se puntúan conversaciones completas, por identificador de conversación o por filtro de agente con muestreo. azure_ai_trace_data_source_preview

Entradas sin respuestas

Use esta ruta de acceso cuando tenga las entradas pero aún no haya respuestas. Foundry genera respuestas utilizando como objetivo un modelo o un agente en tiempo de evaluación y luego las puntúa. Elija una fila en función de si su entrada son consultas (enviadas como turnos individuales) o descripciones de escenarios (utilizadas para guiar una interacción a nivel de conversación).

Escenario Cuándo usar Origen de datos o destino
Finalizaciones objetivo del modelo Tiene consultas y quiere evaluar las respuestas de un despliegue de modelo. azure_ai_target_completions → azure_ai_model
Finalizaciones de destino del agente Tiene consultas y quiere evaluar las respuestas de un agente de Foundry. azure_ai_target_completions → azure_ai_agent
Simulación de conversación (versión preliminar) Dispone de descripciones de escenarios (sin consultas); Foundry simula a un usuario que mantiene una interacción a nivel de conversación con el agente. azure_ai_target_completions → azure_ai_agent

Todavía no hay datos

Use esta ruta de acceso cuando cree un nuevo modelo o agente y no haya recopilado ninguna entrada. Foundry genera los datos de prueba desde cero: elija consultas sintéticas para una amplia cobertura de calidad o indicaciones adversas para pruebas de seguridad.

Escenario Cuándo usar Origen de datos o destino
Evaluación de datos sintéticos (versión preliminar) Quieres una cobertura de calidad más amplia que la que escribirías manualmente. Foundry genera consultas de prueba, las envía al destino y puntúa las respuestas. azure_ai_synthetic_data_gen_preview→ azure_ai_model o azure_ai_agent
Evaluación del equipo rojo Conviene realizar pruebas adversas automatizadas: Foundry genera fugas e indicaciones con contenido dañino y puntúa la respuesta del destino. azure_ai_red_team→ azure_ai_model o azure_ai_agent

Elegir evaluadores

Cada escenario vincula los evaluadores a los campos de sus datos mediante asignaciones de columnas. Los campos disponibles dependen del origen de datos. Los escenarios del conjunto de datos exponen los campos de elementos personalizados, mientras que los escenarios generados por el destino también exponen la respuesta del modelo o del agente mediante un esquema de ejemplo. Las subsecciones por cada escenario que aparecen más adelante en este artículo muestran las asignaciones de columnas para cada caso.

Para obtener información general sobre los evaluadores disponibles y cómo seleccionarlos, consulte Evaluadores integrados y evaluadores personalizados.

Requisitos previos

  • Un proyecto de fundición.

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

  • Rol de usuario de Foundry en el proyecto Foundry.

    Importante

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

  • 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.

Comenzar

Instale el SDK y configure el cliente:

pip install "azure-ai-projects>=2.2.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
openai_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 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.

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": {
            "model": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "model": 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 = openai_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 = openai_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, consulte 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 precomputadas 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. A continuación, 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 está en el origen de datos "type": "csv".

# 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": {"model": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"model": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = openai_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 = openai_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 de objetivos del modelo

Enviar consultas a un modelo implementado en tiempo de ejecución. Evalúe las respuestas usando el tipo de origen de datos azure_ai_target_completions con azure_ai_model como destino. Los datos de entrada contienen consultas. El modelo genera respuestas, que después se evalúan.

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 mapeo 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": {
            "model": 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 = openai_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 = openai_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, consulte sample_model_evaluation.py en GitHub. Para verificar la finalización e interpretar los resultados, consulte Obtener resultados.

Sugerencia

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

Evaluación del objetivo del agente

Enviar consultas a un agente de Foundry en tiempo de ejecución y evaluar las respuestas mediante el tipo de origen de datos azure_ai_target_completions con un destino azure_ai_agent. Este escenario funciona tanto para agentes inmediatos 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 que desea evaluar por su nombre:

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 mapeo 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 Se usa 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 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": {
            "model": 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": {
            "model": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Crear evaluación y ejecutar

eval_object = openai_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 = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

Para obtener un ejemplo completo de ejecución, consulte 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. Utilice marcadores de posición {{item.*}} para sustituir campos de sus 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 = openai_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 = openai_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 de agente de instrucciones. 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 mediante identificadores de respuesta utilizando el tipo de azure_ai_responses origen de datos. 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 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 en línea como contenido de archivo, o cárguelos como un conjunto de datos (consulte Preparar los datos de entrada).

Coleccione 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 = openai_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.

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": {
            "model": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = openai_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 = openai_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, consulte sample_agent_response_evaluation.py en GitHub. Para verificar la finalización e interpretar los resultados, consulte Obtener resultados.

Evaluación de seguimiento (versión preliminar)

Evalúe las interacciones del agente que Application Insights ya ha capturado. 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 de producción real. Seleccione seguimientos de su canalización de supervisión y ejecute evaluadores sobre ellos 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. Siempre que el agente emita intervalos de OpenTelemetry siguiendo las convenciones semánticas de GenAI a Application Insights, la evaluación de seguimientos podrá evaluar sus interacciones usando los mismos evaluadores 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 valores de operation_Id 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.

Sugerencia

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

Muestreo inteligente

La evaluación de seguimiento admite el muestreo inteligente, que selecciona un subconjunto representativo de seguimientos para la evaluación en lugar de evaluar cada seguimiento capturado. Habilita esta función activando el interruptor Muestreo inteligente en el portal Foundry cuando configures una ejecución de evaluación de trazas. El muestreo inteligente reduce el coste de evaluación sin dejar de preservar la diversidad de trazas, lo que garantiza que los casos límite, las rutas de error y los distintos patrones de conversación queden incluidos en el conjunto evaluado.

Funcionamiento del muestreo inteligente

El algoritmo de muestreo usa un enfoque de diversidad más lejano primero de MinHash que se ejecuta en varias fases:

  1. Eliminación exacta de duplicados: elimina seguimientos duplicados del conjunto.
  2. Filtros estrictos: elimina sesiones dañadas, seguimientos truncados y llamadas a herramientas con formato incorrecto que no son adecuadas para evaluación.
  3. Agregación : combina señales de nivel de seguimiento en una representación unificada.
  4. Selección de más lejano primero con MinHash: calcula hashes sensibles a la ubicación (firmas MinHash) del texto del usuario para estimar la similitud entre los seguimientos y, a continuación, selecciona de forma iterativa el seguimiento menos similar del conjunto restante. Cada selección sucesiva maximiza la distancia respecto de todas las trazas seleccionadas previamente.

Este enfoque produce una diversidad léxica significativamente mayor y una cobertura de vocabulario más amplia en comparación con el muestreo aleatorio, lo que significa que el conjunto evaluado representa mejor la gama completa de interacciones del agente, incluidos casos poco frecuentes, duros y noveles que tiende a perder el muestreo aleatorio.

El muestreo inteligente es especialmente eficaz para:

  • Evaluación y pruebas comparativas : maximiza la cobertura de la distribución de entrada para que las puntuaciones de evaluación reflejen la diversidad del mundo real.
  • Generación de rubric : genera rubrices más centradas y accionables mediante la exposición de diversos patrones de conversación.
  • Conservación de conjuntos de datos de ajuste preciso: selecciona seguimientos que ayudan a los modelos a aprender de forma más eficiente.

El algoritmo se ejecuta completamente en el proceso local sin llamadas API adicionales, por lo que no incurre en costos de inferencia de modelos adicionales más allá de la propia evaluación.

Ejemplo de muestreo inteligente

# Eval group for trace-based evaluations
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

print("Creating trace-based evaluation group")
eval_object = client.evals.create(
    name="Trace Evaluation (Agent Smart Filter)",
    data_source_config=data_source_config,  # type: ignore
    testing_criteria=testing_criteria,
)
print(f"Evaluation created (id: {eval_object.id})")

# Compute time window in unix seconds
# Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
now_unix = int(time.time())
end_time = now_unix + 600
start_time = now_unix - (args.lookback_hours * 3600)

# Build trace_source based on mode
trace_source: dict = {
    "type": "agent_filter",
    "start_time": start_time,
    "end_time": end_time,
    "max_traces": args.max_traces,
    "filter_strategy": "smart_filtering"
}

# Add agent name/version or agent id
trace_source["agent_name"] = agent_name
trace_source["agent_version"] = agent_version
## trace_source["agent_id"] = args.agent_id

data_source = {
    "type": "azure_ai_trace_data_source_preview",
    "trace_source": trace_source,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="trace-evaluation-agent-smart-filter-run",
    data_source=data_source,  # type: ignore
)

Requisitos de datos de seguimiento

La evaluación de seguimiento requiere que el agente emita intervalos que sigan las convenciones semánticas de OpenTelemetry para la inteligencia artificial generativa. 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:

Attribute 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 de filtro del agente Nombre del agente comprensible para 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 entradas de consulta destinadas a 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 type: tool_call o type: tool_result, se corresponde con 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 podrían 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) devuelven score=None. Los evaluadores de seguridad (violencia, auto-daño, sexual, odio/injusticia) pueden producir puntuaciones con datos parciales, pero podrían 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.2.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 es permitir 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 = openai_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 = openai_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. Este método es útil cuando desea evaluar un conjunto seleccionado de interacciones, como trazas señaladas por alertas o seleccionadas mediante muestreo para una 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 = openai_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 = openai_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 mapeo de datos

Al evaluar las trazas, el servicio extrae automáticamente los datos de conversación 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) 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. Solo es necesario para evaluadores relacionados con 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": {
            "model": 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": {
            "model": 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)

Use el azure_ai_synthetic_data_gen_preview tipo de origen de datos para generar consultas de prueba sintéticas, enviarlas a un modelo implementado o agente foundry y evaluar las respuestas. Use este escenario cuando no tenga un conjunto de datos de prueba. El servicio genera consultas a partir de una indicación proporcionada por usted (y/o a partir de las instrucciones del agente), las ejecuta en su objetivo 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 semilla 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 que se va a usar para generar 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 agente de destino tiene instrucciones configuradas.
output_dataset_name No Nombre del conjunto de datos de salida donde se almacenan las consultas generadas. Si no proporciona un nombre, el servicio genera uno automáticamente.
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 mapeo de datos

El generador de datos sintéticos genera consultas en el {{item.query}} campo . El destino genera respuestas disponibles en {{sample.output_text}}. Correlacione 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": {
            "model": 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 = openai_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 = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-data-evaluation",
    data_source=data_source,
)

Puede agregar opcionalmente una instrucción 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

Genere consultas sintéticas y evalúe 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 = openai_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.

Evaluación de nivel de conversación (versión preliminar)

Evalúe las conversaciones completas para evaluar la calidad del agente en todas las interacciones del usuario, no solo las respuestas individuales. Utilice la evaluación a nivel de conversación para identificar problemas de calidad, como la resolución incompleta de tareas, la frustración del usuario y las regresiones en las llamadas a herramientas que la evaluación a nivel de turno no detecta.

Por ejemplo, consideremos un agente de soporte en el que el usuario se va frustrando a lo largo de varios turnos:

Turn 1 — Usuario: "Necesito restablecer mi contraseña". Agente: "He encontrado su cuenta. Enviaré un vínculo de restablecimiento".

Turn 2 — Usuario: "No he recibido el correo electrónico." Agente: "He reenviado el enlace." Por favor, compruebe el correo no deseado".

Turn 3 — Usuario: "Todavía no hay nada. ¿Puede restablecerlo directamente?" Agente: "He enviado otro vínculo de restablecimiento".

Un evaluador a nivel de turno puntúa solo la última respuesta, que es amable y actúa, por lo que obtiene una buena puntuación. Un evaluador a nivel de conversación que califica la satisfacción del cliente a lo largo de toda la conversación señala que el agente repitió la misma acción fallida tres veces sin intentar una alternativa, dejando sin resolver el problema del usuario.

La evaluación de nivel de conversación difiere de la evaluación de nivel de turno de varias maneras:

Aspecto Nivel de turno Nivel de conversación
Ámbito Pares individuales de consulta-respuesta Completar conversaciones con varios intercambios
Métricas Calidad y seguridad de cada respuesta Resultados de nivel de conversación y satisfacción del usuario
Formato de datos JSONL con campos query y response JSONL con messages matriz que contiene la conversación completa
Caso de uso Prueba de respuestas de modelos individuales Pruebas integrales de las experiencias del agente

La evaluación de nivel de conversación admite cuatro opciones de origen de datos:

Opción Cuándo usar Tipo de origen de datos
De conjunto de datos o insertado Tiene registros de conversaciones locales o datos de prueba jsonl con file_id o file_content
Por identificador de conversación Quieres evaluar conversaciones específicas de App Insights. azure_ai_trace_data_source_preview con trace_source
Por filtro de agente con muestreo Conviene evaluar la calidad general del agente en el tráfico de producción muestreado. azure_ai_trace_data_source_preview con trace_source
Conversaciones simuladas Conviene generar conversaciones de prueba sintética azure_ai_target_completions con conversation_gen_preview

Elección de un nivel de evaluación

El parámetro evaluation_level de la ejecución determina si los evaluadores evalúan turnos individuales o conversaciones completas:

Value Comportamiento
"turn" Los evaluadores puntúan cada turno de forma independiente.
"conversation" Los evaluadores puntúan toda la conversación como un todo.
(omitido) Tiene como valor predeterminado "turn".

Importante

Compatibilidad del evaluador: cada evaluador admite niveles de evaluación específicos. Compruebe el campo supported_evaluation_levels del evaluador en el catálogo de evaluadores.

  • Los evaluadores solo por turno (por ejemplo, fluency, relevance) no se pueden usar con evaluation_level="conversation".
  • Actualmente, todos los evaluadores de nivel de conversación admiten tanto niveles "turn" como "conversation" .

Errores frecuentes

Error Causa Solución
Nivel de evaluación incompatible Uso de evaluation_level="conversation" con un evaluador por turnos Quitar el evaluador de solo turno o cambiar a evaluation_level="turn"

Preparación de los datos de conversación

Cree un archivo JSONL donde cada línea contenga una conversación completa en el messages campo. Cada mensaje debe incluir un role (usuario, asistente o sistema) y content. Para obtener un ejemplo completo, consulte los ejemplos de evaluación de conversation en el SDK:

 {"messages": [{"role": "user", "content": "What's my account balance?"}, {"role": "assistant", "content": "Your current balance is $1,234.56."}, {"role": "user", "content": "Thanks!"}, {"role": "assistant", "content": "You're welcome! Is there anything else?"}]}

También puede incluir definiciones de herramientas y llamadas a herramientas si el agente usa herramientas:

{"messages": [{"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Paris"}]}
{"messages": [{"role": "user", "content": "How do I reverse a string in Python?"}, {"role": "assistant", "content": "You can reverse a string in Python by using slicing: string[::-1]"}]}
{"messages": [{"role": "user", "content": "What are the main causes of climate change?"}, {"role": "assistant", "content": "The main causes of climate change are the increase in greenhouse gases in the atmosphere, primarily due to human activities such as burning fossil fuels and deforestation."}]}
{"messages": [{"role": "user", "content": "What's my account balance?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_abc123", "type": "function", "function": {"name": "get_account_balance", "arguments": "{\"account_id\": \"ACCT-7890\"}"}}]}, {"role": "tool", "tool_call_id": "call_abc123", "content": "{ \"balance\": 1234.56, \"currency\": \"USD\" }"}, {"role": "assistant", "content": "Your current balance is 1,234.56."}, {"role": "user", "content": "Thanks!"}, {"role": "assistant", "content": "You're welcome! Is there anything else?"}], "tool_definitions": [{"name": "get_account_balance", "description": "Retrieves the current balance for a customer account", "parameters": {"type": "object", "properties": {"account_id": {"type": "string"}}, "required": ["account_id"]}}]}
{"messages": [{"role": "user", "content": "Explain the theory of relativity in simple terms."}, {"role": "assistant", "content": "Einstein's theory of relativity shows that space and time are interconnected and relative to the observer's frame of reference."}]}
{"messages": [{"role": "user", "content": "What's the weather in Seattle?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_002", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\": \"Seattle, WA\"}"}}]}, {"role": "tool", "tool_call_id": "call_002", "content": "{ \"temperature\": 55, \"condition\": \"Cloudy\" }"}, {"role": "assistant", "content": "It's currently 55F and cloudy in Seattle."}], "tool_definitions": [{"name": "get_weather", "description": "Get the current weather for a location", "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}]}
{"messages": [{"role": "user", "content": "What is the tallest mountain in the world?"}, {"role": "assistant", "content": "Mount Everest is the tallest mountain in the world."}]}
{"messages": [{"role": "user", "content": "Is 4 x 2 = 16?"}, {"role": "assistant", "content": "No, 4 x 2 = 8."}]}
{"messages": [{"role": "user", "content": "What is the best Italian desert?"}, {"role": "assistant", "content": "Tiramisu is a popular Italian dessert."}]}
{"messages": [{"role": "user", "content": "What is the chemical formula for water?"}, {"role": "assistant", "content": "The chemical formula for water is H2O."}]}

Definir el esquema de datos y los evaluadores

Especifique el esquema de los datos de conversación, "mensajes" y seleccione evaluadores diseñados para la evaluación de nivel de conversación. Los evaluadores a nivel de conversación evalúan toda la interacción en lugar de evaluar turnos individuales.

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

import os
from openai.types.eval_create_params import DataSourceConfigCustom
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"type": "array"},
                "tool_definitions": {"type": "array"},
            },
            "required": ["messages"],
        },
        include_sample_schema=False,
    )

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

Crear evaluación y ejecutar

Preparación: descargue sample_data_multiturn_conversations.jsonl

from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileID,
)

# Upload conversation data
data_id = project_client.datasets.upload_file(
    name="multiturn-conversation-data",
    version="1",
    file_path="./sample_data_multiturn_conversations.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run with evaluation_level set to "conversation"
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="multiturn-conversation-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
    extra_body={"evaluation_level": "conversation"},
)

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

Evaluar conversaciones por ID a partir de seguimientos

Evalúe conversaciones específicas de Application Insights proporcionando sus identificadores de conversación. Use esta opción para solucionar problemas de causa principal o comprobar correcciones en interacciones específicas. Por ejemplo, puede investigar una conversación marcada por una alerta o comprobar una corrección de un problema conocido.

Dónde encontrar identificadores de conversación

Busque identificadores de conversación en:

  • Interfaz de usuario de registros de seguimiento de Application Insights: vaya a seguimientos de interés y busque el campo conversation_id en los detalles del seguimiento.
  • Salida de registro de la aplicación : si establece conversation_id explícitamente al crear respuestas del agente, recuperela de los registros.
  • Contexto de seguimiento de OpenTelemetry: El conversation_id también puede obtenerse del encabezado traceparent si el agente usa la propagación estándar del contexto de seguimiento.

Nota

Las definiciones de herramientas se recuperan automáticamente de los seguimientos o se consultan desde el registro del agente. No es necesario proporcionarlos en la solicitud.

Parámetros para la búsqueda de ID de conversación

Parámetro Obligatorio Descripción
conversation_ids Sí Lista de identificadores de conversaciones para evaluar.
lookback_hours No Horas para volver a buscar desde end_time. El valor predeterminado es siete días (168 horas).
end_time No Fin de la ventana de búsqueda (formato ISO 8601). El valor predeterminado es la hora actual. 
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]

# Provide conversation IDs or trace IDs from App Insights
conversation_ids = ["conversation_1234", "conversation_5678"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    # Create evaluation with traces scenario
    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (by ID)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Run evaluation on specific conversation IDs
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-trace-by-id-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": {
                "type": "conversation_id_source",
                "conversation_ids": conversation_ids,
            },
        },
        extra_body={"evaluation_level": "conversation"},
    )

Nota

  • La ingestión de datos de Application Insights puede provocar un retraso entre el momento en que se generan las trazas y aquel en que están disponibles para evaluarlas. Si la consulta no encuentra trazas, espere unos minutos y vuelva a intentarlo.
  • El periodo retrospectivo máximo es de 7 días (168 horas). Para acceder a seguimientos más antiguos, use start_time y end_time dentro de los límites de retención de App Insights.

Evaluación de conversaciones muestreadas por filtro de agente

Evalúe un conjunto muestreado de conversaciones de Application Insights filtrando por el nombre del agente. Use esta opción para evaluar la calidad general del agente en el tráfico de producción. Por ejemplo, ejecute evaluaciones de calidad normales o supervise la degradación de la calidad en producción.

El agente que especifique para el filtrado puede formar parte de una conversación multiagente. El filtro coincide con cualquier conversación en la que participó ese agente.

Nota

Las definiciones de herramientas se recuperan automáticamente de los seguimientos o se consultan desde el registro del agente. No es necesario proporcionarlos en la solicitud.

Campos de identidad del agente

Especifique el agente que se va a filtrar mediante uno de estos formatos:

Formato Example Descripción
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Dos campos independientes. Si agent_version se omite, use la versión más reciente.
agent_id "agent_id": "my-agent:1" Una sola cadena en formato "name:version".

Estrategias de filtro

Strategy Descripción
random_sampling (Valor predeterminado) Muestra aleatoria uniforme de hasta max_traces conversaciones.
smart_filtering Heurística gestionada por el servicio que prioriza las trazas "interesantes": conversaciones con posibles problemas, casos extremos o anomalías.

Parámetros

Parámetro Obligatorio Descripción
agent_name Sí Nombre del agente por el que se van a filtrar los seguimientos.
agent_version No La versión del agente. Si se omite, usa la versión más reciente.
agent_id No Alternativa a agent_name + agent_version. Cadena única con formato "name:version".
start_time Sí Inicio del período de tiempo (segundos de época de Unix, UTC).
end_time Sí Fin del período de tiempo (segundos de época de Unix, UTC). Rellene +600 segundos para evitar retrasos en la ingesta.
max_traces No Número máximo de conversaciones que se van a muestrear. Su valor predeterminado es 1,000.
filter_strategy No "random_sampling" (predeterminado) o "smart_filtering" (heurística gestionada por el servicio que da prioridad a las trazas interesantes).

Importante

El período de tiempo (end_time - start_time) debe ser de al menos 15 minutos (900 segundos). Este requisito existe porque las consultas a nivel de conversación aplican un margen de inactividad de 5 minutos en cada extremo para evitar conversaciones parciales.

import os
import time
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
agent_version = os.environ.get("FOUNDRY_AGENT_VERSION", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (Agent Filter)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Compute time window in unix seconds
    # Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
    now_unix = int(time.time())
    end_time = now_unix + 600
    start_time = now_unix - (24 * 3600)  # 24 hours lookback

    # Build trace_source with agent filter
    trace_source = {
        "type": "agent_filter",
        "agent_name": agent_name,
        "start_time": start_time,
        "end_time": end_time,
        "max_traces": 5,
    }
    if agent_version:
        trace_source["agent_version"] = agent_version

    # Run evaluation on sampled agent conversations
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-agent-filter-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": trace_source,
        },
        extra_body={"evaluation_level": "conversation"},
    )

Nota

El intervalo de tiempo de consulta de App Insights está limitado actualmente a un máximo de 7 días (168 horas). No puedes acceder a trazas de hace más de 7 días sin proporcionar explícitamente start_time y end_time, siempre que estén dentro del período de retención de App Insights.

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

Simulación de conversación

Genere conversaciones simuladas a partir de descripciones de escenarios y evalúelas en el nivel de conversación. Use este escenario para probar el comportamiento del agente en situaciones controladas antes de la implementación. El servicio genera conversaciones realistas en función de las descripciones del escenario y, a continuación, las evalúa.

Este enfoque es útil para:

  • Pruebas previas a la implementación: valide el comportamiento del agente en diversos escenarios sin tráfico de usuario real.
  • Cobertura de casos límite: escenarios de prueba que rara vez surgen de forma natural, pero que es importante gestionar correctamente.
  • Pruebas de regresión: asegúrese de que las actualizaciones del agente no degradan el rendimiento en escenarios conocidos.
  • Pruebas de escala: Generar muchas conversaciones rápidamente para poner a prueba al límite las capacidades del agente.

Funcionamiento de la simulación de conversación

  1. Proporcione un conjunto de datos de descripciones de escenarios: cada fila describe una situación que el usuario simulado intenta realizar.
  2. El servicio usa un modelo de simulador para desempeñar el rol del usuario, interactuando con el agente en función del escenario.
  3. Cada escenario genera una o varias conversaciones completas.
  4. Los evaluadores de nivel de conversación evalúan las conversaciones generadas.
  5. El proyecto almacena las conversaciones y los resultados de evaluación.

Preparación de los datos del escenario

Cree un archivo JSONL donde cada línea describe un escenario para el usuario simulado. El esquema requiere id, test_case_descriptiony desired_num_turns. Incluya detalles sobre el objetivo, el contexto y las restricciones del usuario. Para obtener un ejemplo completo, consulte los ejemplos de evaluación de conversation en el SDK.


{"id": "contoso_refund_timeline", "test_case_description": "Customer returned an item to Contoso Electronics 5 days ago and hasn't received their refund yet. They want to know how long Contoso refunds take.", "desired_num_turns": 10}
{"id": "contoso_store_hours_lookup", "test_case_description": "Customer wants to know what time the Contoso Electronics store closes today. Simple single-fact question with possibly one clarifying turn about which location.", "desired_num_turns": 3}

Parámetros

Parámetro Obligatorio Descripción
num_conversations No Número de conversaciones que se van a generar por escenario. El valor predeterminado es 5, límite del lado servidor de 5.
max_turns No Número máximo de turnos (intercambios) por conversación. El valor predeterminado es 10, con un límite en el servidor de 20.
model Sí Implementación del modelo que se va a usar para simular al usuario. Por ejemplo: gpt-4.1.
sampling_params No Parámetros de muestreo para el modelo del simulador, incluidos temperature, top_py max_completion_tokens.
data_mapping No Asigna campos de tu JSONL del escenario a los parámetros de simulación. Asignaciones comunes: test_case_description, id, desired_num_turns.

Definir evaluadores

Seleccione evaluadores diseñados para la evaluación de nivel de conversación. Las conversaciones simuladas se asignan automáticamente a los evaluadores.

import os
from openai.types.eval_create_params import DataSourceConfigCustom
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator, PromptAgentDefinition

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ.get("FOUNDRY_AGENT_NAME", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Simulation uses the same "custom" eval group type as dataset evaluation (S1),
    # since the generated conversations follow the same messages schema.
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"type": "array"},
            },
            "required": ["messages"],
        },
        include_sample_schema=False,
    )

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

Crear evaluación y ejecutar

Preparación: descargue sample_data_simulation_scenarios.jsonl.

# Create (or update) an agent to simulate against
agent = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=model_deployment_name,
        instructions="You are a helpful customer service agent. Be empathetic and solution-oriented.",
    ),
)

# Upload scenario data
scenarios_id = project_client.datasets.upload_file(
    name="simulation-scenarios",
    version="1",
    file_path="./sample_data_simulation_scenarios.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Simulation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a simulation run
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="conversation-simulation-run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {
            "type": "file_id",
            "id": scenarios_id,
        },
        "target": {
            "type": "azure_ai_agent",
            "name": agent.name,
            "version": agent.version,
        },
        "item_generation_params": {
            "type": "conversation_gen_preview",
            "model": model_deployment_name,
            "num_conversations": 2,
            "max_turns": 5,
            "sampling_params": {
                "temperature": 0.7,
                "top_p": 1.0,
                "max_completion_tokens": 800,
            },
            "data_mapping": {
                "test_case_description": "test_case_description",
                "id": "id",
                "desired_num_turns": "desired_num_turns",
            },
        },
    },
    extra_body={"evaluation_level": "conversation"},
)

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

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 = openai_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(
    openai_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 "aprobado" o "suspenso" en el campo "etiqueta" en función del "umbral".
  • Umbral: las puntuaciones no binarias se binarizan como "aprobado" o "suspenso" en función de un umbral predeterminado, que el usuario puede modificar en la experiencia 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
}

Salida de ejemplo (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

Es posible que su trabajo de evaluación permanezca en el estado En ejecución durante un período prolongado. Normalmente, esta condición se produce cuando la implementación del modelo de OpenAI Azure no tiene suficiente capacidad, lo que hace que el servicio vuelva a intentar las solicitudes.

Resolución:

  1. Cancele el trabajo de evaluación actual mediante openai_client.evals.runs.cancel(run_id, eval_id=eval_id).
  2. Aumente la capacidad del modelo en Azure Portal.
  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. Si usa CLI de Azure, ejecute az login.
  • Su cuenta tiene el rol Foundry 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 debido a 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 (sensible a mayúsculas y minúsculas).
  • Compruebe que item_schema las propiedades coinciden con los campos del conjunto de datos.

Errores de límite de velocidad

Los niveles de inquilino, suscripción y proyecto limitan la frecuencia de creación de ejecuciones de evaluación. 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 el retroceso exponencial al reintentar solicitudes fallidas.

Si un trabajo de evaluación falla con un 429 error 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 para herramientas no 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