Auswerten der bereitgestellten Agent- und Modellinteraktionen

Important

Die in diesem Artikel markierten Elemente (Vorschau) sind aktuell als öffentliche Vorschau verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und sollte nicht für Produktionsworkloads verwendet werden. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbedingungen für Microsoft Azure-Vorschauversionen.

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.

Tipp

Bevor Sie beginnen, schließen Sie die Clienteinrichtung ab.

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.

Important

Auswertungen von Agentenantworten (azure_ai_responses) unterstützen zur Bereitstellung von Antwort-IDs nur file_content. Der file_id Quelltyp wird nicht unterstützt und gibt einen 400 Bad Request Fehler zurück.

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

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.

Important

Die Tracebewertung ist der empfohlene Ansatz zur Auswertung von Agents, die nicht mit dem Microsoft Foundry Agent Service erstellt wurden, einschließlich LangChain und benutzerdefinierter Frameworks. Solange Ihr Agent OpenTelemetry-Spans gemäß den GenAI-Semantikkonventionen an Application Insights sendet, kann die Traceauswertung seine Interaktionen mithilfe derselben Auswertungsmodule bewerten, die auch für Foundry-Agenten verfügbar sind.

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.

Tipp

Bevor Sie beginnen, schließen Sie die Clienteinrichtung ab. Dieses Szenario erfordert auch eine Application Insights-Ressource, die mit Ihrem Foundry-Projekt verbunden ist.

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:

Merkmal Erforderlich Description
gen_ai.operation.name Yes Muss gleich sein "invoke_agent". Der Dienst ignoriert alle anderen Spannen.
gen_ai.agent.id Für den Agent-Filtermodus Eindeutiger Agentbezeichner (Format: agent-name:version).
gen_ai.agent.name Für den Agent-Filtermodus Name des Agenten, der für Menschen lesbar ist.
gen_ai.input.messages Abfrageeingaben für Evaluatoren JSON-Array mit Eingabemeldungen nach dem GenAI-Semantikkonventionen-Nachrichtenformat. Nachrichten mit der Rolle user oder system werden query zugeordnet. Nachrichten mit der Rolle assistant oder tool werden response zugeordnet.
gen_ai.output.messages Abfrageeingaben für Evaluatoren JSON-Array von vom Modell generierten Ausgabemeldungen. Alle Ausgabemeldungen werden response zugeordnet. Wenn die Ausgabe auch enthält type: tool_call oder type: tool_result, wird sie zugeordnet tool_calls.
gen_ai.tool.definitions Optional JSON-Array von Toolschemas, die für den Agent verfügbar sind. Wenn nicht vorhanden, versucht der Dienst, Tooldefinitionen aus Toolaufrufnachrichten zu ableiten, aber abgeleitete Schemas sind möglicherweise unvollständig.
gen_ai.conversation.id Optional Konversationsbezeichner, der an Auswertungsergebnisse zur Korrelation weitergegeben wird.

Note

Wenn gen_ai.input.messages und gen_ai.output.messages leer sind oder fehlen, geben Qualitätsbewerter (Kohärenz, Sprachflüssigkeit, Relevanz, Absichtserkennung) score=None zurück. Sicherheitsbewertungen (Gewalt, Selbstverletzung, Sexueller Hass/Unfairität) können weiterhin Bewertungen mit Teildaten erzeugen, aber sie können keine sinnvollen Ergebnisse erzielen.

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

Variable Quell-Attribut Description
{{item.query}} gen_ai.input.messages (Benutzer-/Systemrollen) Die aus der Protokollspur extrahierte Benutzeranfrage.
{{item.response}} gen_ai.input.messages (Assistenten-/Toolrollen) + gen_ai.output.messages Die Antwort des Agenten, die aus der Ablaufverfolgung extrahiert wurde.
{{item.tool_definitions}} gen_ai.tool.definitions Toolschemas, die für den Agent verfügbar sind. Nur für werkzeugbezogene Evaluatoren erforderlich.
{{item.tool_calls}} Extrahiert aus Assistentennachrichten in gen_ai.input.messages / gen_ai.output.messages Toolaufrufe des Agents während der Interaktion. Wird von Toolvaluatoren verwendet. Nur für werkzeugbezogene Evaluatoren erforderlich. 
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

  • Last updated on