Auswerten der bereitgestellten Agent- und Modellinteraktionen

Wertet gespeicherte Antworten oder OpenTelemetry-Ablaufverfolgungen von bereitgestellten Agents und Modellen aus, ohne die ursprünglichen Anforderungen erneut zu wiedergeben.

Voraussetzungen

• Schließen Sie die Voraussetzungen für die Cloudauswertung und die Clienteinrichtung ab.
• Gespeicherte Antwort-IDs für die Antwortauswertung oder eine Application Insights-Ressource, die mit Ihrem Foundry-Projekt für die Ablaufverfolgungsbewertung verbunden ist.
• OpenTelemetry erstreckt sich über die Anforderungen an die Ablaufverfolgungsdaten, wenn Sie Ablaufverfolgungen auswerten.

In den Beispielen wird der in SDK-Client einrichten konfigurierte SDK-Client verwendet.

Interaktionen anhand der Antwort-ID auswerten

Abrufen und Auswerten der Reaktionen von Foundry-Agenten mithilfe von Antwort-IDs unter Verwendung des azure_ai_responses Datenquellentyps. Verwenden Sie dieses Szenario, um bestimmte Agentinteraktionen auszuwerten, nachdem sie aufgetreten sind.

Eine Antwort-ID ist ein eindeutiger Bezeichner, der jedes Mal zurückgegeben wird, wenn ein Foundry-Agent eine Antwort generiert. Sie können Antwort-IDs aus Agentinteraktionen mithilfe der Antwort-API oder aus den Ablaufverfolgungsprotokollen Ihrer Anwendung sammeln. Geben Sie die IDs als Dateiinhalt inline an.

Sammeln von Antwort-IDs

Jeder Aufruf der Antwort-API gibt ein Antwortobjekt mit einem eindeutigen id Feld zurück. Sammeln Sie diese IDs aus den Interaktionen Ihrer Anwendung, oder generieren Sie sie direkt:

# 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

Sie können auch Antwortkennungen aus Interaktionen mit Agenten in den Tracing-Protokollen oder der Überwachungspipeline Ihrer Anwendung sammeln. Jede Antwort-ID identifiziert eindeutig eine gespeicherte Antwort, die der Auswertungsdienst abrufen kann.

Auswertung erstellen und ausführen

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

Ein vollständiges runnables Beispiel finden Sie unter sample_agent_response_evaluation.py auf GitHub. Informationen zum Abfragen des Abschlussstatus und zum Interpretieren der Ergebnisse finden Sie unter Abrufen von Cloudauswertungsergebnissen.

Ablaufverfolgungen auswerten (Vorschau)

Bewerten sie Agentinteraktionen, die application Insights bereits erfasst haben. Verwenden Sie den azure_ai_traces Datenquellentyp. Dieses Szenario ist für die Auswertung von echtem Produktivverkehr nach der Bereitstellung nützlich. Sie wählen Traces aus Ihrer Überwachungspipeline aus und wenden Evaluatoren darauf an, ohne Anforderungen erneut abzuspielen.

Die Tracerauswertung unterstützt zwei Modi:

• Nach Trace-IDs - Bewerten Sie bestimmte Agentinteraktionen, indem Sie ihre operation_Id Werte aus Application Insights angeben.
• Nach Agent filtern – Aktuelle Traces für einen bestimmten Agenten automatisch ermitteln und auswerten, ohne Trace-IDs manuell zu sammeln.

Intelligentes Sampling

Die Traceauswertung unterstützt intelligentes Sampling, bei dem eine repräsentative Teilmenge von Traces für die Auswertung ausgewählt wird, anstatt jeden erfassten Trace auszuwerten. Aktivieren Sie im Foundry-Portal beim Konfigurieren einer Ausführung der Traceauswertung den Schalter Intelligentes Sampling. Intelligente Stichprobenauswahl senkt die Evaluierungskosten und bewahrt zugleich die Vielfalt der Abläufe, sodass Randfälle, Fehlerpfade und unterschiedliche Gesprächsmuster in der ausgewerteten Menge enthalten sind.

Funktionsweise intelligenter Samplings

Der Samplingalgorithmus verwendet einen MinHash-Diversitätsansatz nach dem Farthest-First-Prinzip, der in mehreren Stufen abläuft:

1. Exakte Deduplizierung – Entfernt doppelte Traces aus dem Pool.
2. Harte Filter – Entfernt fehlerhafte Sitzungen, abgeschnittene Ablaufverfolgungen und falsch formatierte Toolaufrufe, die nicht für die Auswertung geeignet sind.
3. Aggregation - Kombiniert Signale auf Trace-Ebene zu einer einheitlichen Darstellung.
4. Farthest-First-Auswahl mit MinHash - Berechnet lokalitätssensitive Hashes (MinHash-Signaturen) von Nutzertext, um die Ähnlichkeit zwischen Traces zu schätzen, und wählt dann iterativ den unähnlichsten Trace aus dem verbleibenden Pool aus. Jede nachfolgende Auswahl maximiert den Abstand zu allen zuvor ausgewählten Traces.

Dieser Ansatz erzeugt eine deutlich höhere lexikalische Vielfalt und eine breitere Vokabularabdeckung im Vergleich zu zufälligen Stichproben, was bedeutet, dass der ausgewertete Satz besser das gesamte Spektrum der Agentinteraktionen darstellt - einschließlich seltener, harter und neuer Fälle, die zufällige Stichproben tendenziell verpassen.

Intelligente Samplings sind besonders effektiv für:

• Bewertungen und Benchmarks – Maximiert die Abdeckung der Eingabeverteilung, sodass Bewertungsergebnisse die reale Vielfalt widerspiegeln.
• Erstellung von Bewertungskriterien – Erzeugt gezieltere und besser anwendbare Bewertungskriterien, indem vielfältige Gesprächsmuster sichtbar gemacht werden.
• Kurierung von Finetuning-Datensätzen – Wählt Traces aus, die Modellen helfen, effizienter zu lernen.

Der Algorithmus wird vollständig auf lokaler Compute ohne zusätzliche API-Aufrufe ausgeführt, sodass es keine zusätzlichen Modellleitungskosten über die Auswertung selbst hinaus verursacht.

Beispiel für intelligentes Sampling

# 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
)

Tracing-Datenanforderungen

Die Trace-Auswertung erfordert, dass Ihr Agent Spans ausgibt, die den semantischen Konventionen von OpenTelemetry für generative KI entsprechen. Der Auswertungsdienst liest spezifische Bereiche aus Application Insights aus und extrahiert Konversationsdaten aus deren Attributen.

Die folgenden Span-Attribute werden verwendet:

Fügen Sie für Python Agents, die mit dem AZURE AI Agent Server SDK erstellt wurden, das zusätzliche [tracing] hinzu, um die automatische Span-Emission zu ermöglichen:

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

Voraussetzungen für die Ablaufverfolgungsauswertung

Zusätzlich zu den allgemeinen Voraussetzungen erfordert die Tracer-Auswertung Folgendes:

• Eine Application Insights-Ressource , die mit Ihrem Foundry-Projekt verbunden ist. Siehe Tracing in Microsoft Foundry einrichten.
• Die verwaltete Identität des Projekts muss sowohl in der Ressource "Application Insights" als auch im verknüpften Log Analytics-Arbeitsbereich über die Rolle Log Analytics Reader verfügen. Wenn die Tabellen, in denen Ihre Ablaufverfolgungen gespeichert werden, geschützt sind (deren Schutzebene auf "Geschützt" festgelegt ist), weisen Sie auch die Rolle "Privileged Monitoring Data Reader " in denselben Bereichen zu, damit der Dienst die geschützten Ablaufverfolgungstabellen lesen kann.
• Das Paket azure-monitor-query Python (nur erforderlich, wenn Sie Trace-IDs manuell erfassen).

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

Legen Sie diese Umgebungsvariablen fest:

• APPINSIGHTS_RESOURCE_ID – Die Application Insights-Ressourcen-ID (z. B. /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
• AGENT_ID — Die Agentenkennung, die vom Trace-Integrationsteil (gen_ai.agent.id Attribut) ausgegeben wird und zum Filtern von Traces verwendet wird. Format: agent-name:version.
• TRACE_LOOKBACK_HOURS — (Optional) Anzahl der Stunden, die beim Abfragen von Ablaufverfolgungen berücksichtigt werden sollen. Wird standardmäßig auf 1 festgelegt.

Option A: Evaluieren durch Agent-Filter

Der einfachste Ansatz besteht darin, den Dienst automatisch die jüngsten Traces für einen bestimmten Agent ermitteln und auswerten zu lassen. Sie müssen Ablaufverfolgungs-IDs nicht manuell erfassen.

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

Der Dienst filtert invoke_agent Spannen nach dem gen_ai.agent.id Attribut, erfasst bis zu max_traces eindeutige Trace-IDs und wertet alle Spannen dieser Traces aus.

Option B: Auswerten nach Trace-IDs

Für mehr Kontrolle sammeln Sie bestimmte Trace-IDs aus Application Insights und bewerten Sie diese. Diese Methode ist nützlich, wenn Sie eine kuratierte Auswahl von Interaktionen auswerten möchten, z. B. durch Warnmeldungen markierte Traces oder für eine Qualitätsprüfung stichprobenartig ausgewählte Interaktionen.

Sammeln von Trace-IDs aus Application Insights

Fragen Sie Application Insights für operation_Id Werte aus den Ablaufverfolgungen Ihres Agenten ab. Jede operation_Id stellt eine vollständige Agentinteraktion dar:

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")

Erstellen Sie eine Auswertung und führen Sie diese mit Ablaufverfolgungs-IDs aus.

# 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}")

Einrichten von Evaluatoren und Datenzuordnungen

Wenn Sie Traces auswerten, extrahiert der Dienst automatisch Konversationsdaten aus den OpenTelemetry-Span-Attributen. ** Verwenden Sie diese Feldnamen direkt in data_mapping (ohne die in anderen Szenarien verwendeten Präfixe item. oder sample.).

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

Nächste Schritte

• Informationen zum Abfragen des Abschlussstatus und zum Interpretieren der Ergebnisse finden Sie unter Abrufen von Cloudauswertungsergebnissen.
• Ein vollständiges ausführbares Beispiel finden Sie auf GitHub unter sample_evaluations_builtin_with_traces.py.