Evaluación de las interacciones del agente y del modelo implementados

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.
• Identificadores de respuestas almacenadas para la evaluación de respuestas, o bien un recurso de Application Insights conectado a su proyecto Foundry para la evaluación de trazas.
• OpenTelemetry abarca que cumplen los requisitos de datos de seguimiento al evaluar los seguimientos.

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

También puede recopilar identificadores de respuesta de las interacciones del agente en los registros de trazabilidad o en la canalización de monitoreo 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,
)

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.

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 IDs de seguimiento - Evalúe interacciones específicas del agente proporcionando los valores 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 cuando configure 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 de MinHash que se ejecuta en varias fases:

1. Eliminación exacta de duplicados: elimina seguimientos duplicados del conjunto.
2. Filtros estrictos - Elimina las sesiones dañadas, las trazas truncadas y las llamadas a herramientas mal formadas que no son adecuadas para la evaluación.
3. Agregación : combina señales de nivel de seguimiento en una representación unificada.
4. Selección del más lejano con MinHash - Calcula hashes sensibles a la localidad (firmas MinHash) del texto del usuario para estimar la similitud entre trazas y, a continuación, selecciona de forma iterativa la traza 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.
• Selección del conjunto de datos para ajuste fino - Selecciona trazas 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 los agentes de Python creados con el SDK del servidor del agente de IA de Azure, agregue el complemento [tracing] para habilitar la emisión automática de spans:

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

Requisitos previos para la evaluación de seguimiento

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

• Un recurso de Application Insights conectado 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. 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 los mismos ámbitos para que el servicio pueda leer las tablas de seguimiento protegidas.
• 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 a considerar al retroceder en la consulta de trazas. 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 Application Insights para obtener los valores de operation_Id de los seguimientos 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},
    ),
    # Safety evaluators — work even with partial trace data
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="violence",
        evaluator_name="builtin.violence",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        initialization_parameters={"threshold": 4},
    ),
]

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.