Evaluación de interacciones individuales de los modelos y agentes implementados con Microsoft SDK de Foundry

Evalúe las respuestas almacenadas o los seguimientos de OpenTelemetry de los agentes y modelos implementados sin reproducir las solicitudes originales.

Prerequisites

• Complete los requisitos previos de evaluación en la nube y la configuración del cliente.
• ID de respuesta almacenados para la evaluación de respuestas, o un recurso de Application Insights conectado a su proyecto de Foundry para la evaluación de trazas.
• Spans de OpenTelemetry que cumplen los requisitos de datos de trazas al evaluar las trazas.

En los ejemplos se usa el cliente del SDK configurado en Configuración del cliente del SDK.

Evaluación de interacciones por identificador de respuesta

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.

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 del archivo.

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

ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient
  .GetProjectResponsesClientForModel(modelDeploymentName);
ResponseResult response = await responseClient.CreateResponseAsync(
  "What is machine learning?");
Console.WriteLine(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

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

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

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"model": model_deployment_name},
    ),
    TestingCriterionAzureAIEvaluator(
        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,
)

object[] testingCriteria =
[
    new
    {
        type = "azure_ai_evaluator",
        name = "coherence",
        evaluator_name = "builtin.coherence",
        initialization_parameters = new { model = modelDeploymentName }
    },
    new
    {
        type = "azure_ai_evaluator",
        name = "violence",
        evaluator_name = "builtin.violence"
    }
];
BinaryData evaluationData = BinaryData.FromObjectAsJson(new
{
    name = "Agent Response Evaluation",
    data_source_config = new
    {
        type = "azure_ai_source",
        scenario = "responses"
    },
    testing_criteria = testingCriteria
});
using BinaryContent evaluationContent = BinaryContent.Create(evaluationData);
ClientResult evaluation = await evaluationClient.CreateEvaluationAsync(
    evaluationContent);
string evaluationId = GetString(evaluation, "id");

object dataSource = new
{
    type = "azure_ai_responses",
    item_generation_params = new
    {
        type = "response_retrieval",
        data_mapping = new { response_id = "{{item.resp_id}}" },
        source = new
        {
            type = "file_content",
            content = new[]
            {
                new { item = new { resp_id = "resp_abc123" } },
                new { item = new { resp_id = "resp_def456" } }
            }
        }
    }
};
BinaryData runData = BinaryData.FromObjectAsJson(new
{
    name = "agent-response-evaluation",
    data_source = dataSource
});
using BinaryContent runContent = BinaryContent.Create(runData);
ClientResult evaluationRun = await evaluationClient.CreateEvaluationRunAsync(
    evaluationId: evaluationId,
    content: runContent);
Console.WriteLine($"Evaluation run created: {GetString(evaluationRun, "id")}");

const evalObject = await openaiClient.evals.create({
    name: "Agent Response Evaluation",
    data_source_config: { type: "azure_ai_source", scenario: "responses" },
    testing_criteria: [
        {
            type: "azure_ai_evaluator",
            name: "coherence",
            evaluator_name: "builtin.coherence",
            initialization_parameters: { model: modelDeploymentName },
        },
        {
            type: "azure_ai_evaluator",
            name: "violence",
            evaluator_name: "builtin.violence",
        },
    ],
});

const responseEvalRun = await openaiClient.evals.runs.create(evalObject.id, {
    name: "agent-response-evaluation",
    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" } },
                ],
            },
        },
    },
});
console.log(`Evaluation run created: ${responseEvalRun.id}`);

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-response-evaluation",
    "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"}}
          ]
        }
      }
    }
  }'

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 Obtención de resultados de evaluación en la nube.

Para obtener un ejemplo completo de evaluación de respuesta .NET, consulte Sample7_EvaluationsAgent.md en GitHub.

Evaluar trazas (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.

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.

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. Active el conmutador Muestreo inteligente en el portal de Foundry al configurar 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:

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 Reader en el recurso de Application Insights. Si las tablas que almacenan los seguimientos están protegidas (su nivel de protección está establecido en Protegido), asigne también el rol Lector de datos de supervisión con privilegios en ese recurso. Si el área de trabajo de Log Analytics vinculada está configurada con la opción Requerir permisos del área de trabajo, asigne también Lector de Log Analytics en esa área de trabajo. Para ver todos los requisitos de rol de evaluación de seguimiento y otras configuraciones de área de trabajo, consulte Configuración de permisos para flujos de trabajo de evaluación.
• 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 es necesario recopilar manualmente identificadores de seguimiento.

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 mapeos 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):

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

testing_criteria = [
    # Quality evaluators — require query and response from trace data
    TestingCriterionAzureAIEvaluator(
        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
    TestingCriterionAzureAIEvaluator(
        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},
    ),
]

Ejecución de una evaluación de seguimiento con .NET

Escriba los identificadores de seguimiento de Application Insights que desea evaluar. El servicio recupera los intervalos correspondientes del recurso de Application Insights conectado.

string[] traceIds = ["trace-id-1", "trace-id-2"];
object[] testingCriteria =
[
    new
    {
        type = "azure_ai_evaluator",
        name = "intent_resolution",
        evaluator_name = "builtin.intent_resolution",
        initialization_parameters = new { model = modelDeploymentName },
        data_mapping = new
        {
            query = "{{item.query}}",
            response = "{{item.response}}",
            tool_definitions = "{{item.tool_definitions}}"
        }
    },
    new
    {
        type = "azure_ai_evaluator",
        name = "violence",
        evaluator_name = "builtin.violence",
        data_mapping = new
        {
            query = "{{item.query}}",
            response = "{{item.response}}"
        },
        initialization_parameters = new { threshold = 4 }
    }
];
BinaryData evaluationData = BinaryData.FromObjectAsJson(new
{
    name = "Agent Trace Evaluation",
    data_source_config = new
    {
        type = "azure_ai_source",
        scenario = "traces"
    },
    testing_criteria = testingCriteria
});
using BinaryContent evaluationContent = BinaryContent.Create(evaluationData);
ClientResult evaluation = await evaluationClient.CreateEvaluationAsync(
    evaluationContent);
string evaluationId = GetString(evaluation, "id");

BinaryData runData = BinaryData.FromObjectAsJson(new
{
    name = "agent-trace-evaluation",
    data_source = new
    {
        type = "azure_ai_traces",
        trace_ids = traceIds,
        lookback_hours = 1
    }
});
using BinaryContent runContent = BinaryContent.Create(runData);
ClientResult evaluationRun = await evaluationClient.CreateEvaluationRunAsync(
    evaluationId: evaluationId,
    content: runContent);
Console.WriteLine($"Evaluation run created: {GetString(evaluationRun, "id")}");

Referencia: EvaluationClient métodos de protocolo

Pasos siguientes

• Para sondear la finalización e interpretar los resultados, consulte Obtención de resultados de evaluación en la nube.
• Para ver un ejemplo completo de ejecución, vea sample_evaluations_builtin_with_traces.py en GitHub.