Ausführen von Auswertungen in der Cloud mithilfe des Microsoft Foundry SDK

In diesem Artikel erfahren Sie, wie Sie Auswertungen in der Cloud für Vorabbereitstellungstests auf einem Test-Dataset ausführen.

Verwenden Sie für die meisten Szenarien Auswertungen in der Cloud – insbesondere bei Tests in großem Maßstab, bei der Integration von Auswertungen in Pipelines für Continuous Integration und Continuous Delivery (CI/CD) oder bei Tests vor der Bereitstellung. Das Ausführen von Auswertungen in der Cloud beseitigt die Notwendigkeit, die lokale Computeinfrastruktur zu verwalten und umfangreiche automatisierte Testworkflows zu unterstützen. Sie können auch Auswertungen planen , die regelmäßig ausgeführt werden sollen, oder eine fortlaufende Auswertung einrichten, um stichprobenbezogene Agentantworten in der Produktion automatisch auszuwerten.

Die Ergebnisse der Cloudauswertung werden in Ihrem Foundry-Projekt gespeichert. Sie können die Ergebnisse im Portal überprüfen, sie über das SDK abrufen oder an Application Insights weiterleiten, wenn sie verbunden sind. Die Cloudauswertung unterstützt alle Microsoft kuratierten built-in-Evaluatoren und Ihre eigenen custom evaluators. Evaluatoren werden im Evaluator-Katalog mit der gleichen projektbezogenen, rollenbasierten Zugriffssteuerung verwaltet.

Tipp

Vollständige ausführbare Beispiele finden Sie in den Evaluierungsbeispielen des Python SDK auf GitHub.

Funktionsweise der Cloudauswertung

Eine Cloudauswertung umfasst drei Schritte:

  1. Definieren Sie, was ausgewertet werden soll. Beschreiben Sie Ihre Datenstruktur (die data_source_config) und die Evaluatoren (Testkriterien), mit denen sie bewertet wird.
  2. Erstellen Sie die Auswertung. Übermitteln Sie die Definition mithilfe von openai_client.evals.create().
  3. Führen Sie sie aus, und lesen Sie die Ergebnisse. Starten Sie eine Ausführung mithilfe openai_client.evals.runs.create()von , abfragen Sie, bis sie abgeschlossen ist, und lesen Sie die bewerteten Ergebnisse. Siehe "Ergebnisse abrufen " für das Ergebnisschema.

Im restlichen Abschnitt werden die Eingaben in Schritt 1 erläutert: Wählen Sie ein Szenario und dann Evaluatoren aus.

Auswählen des Startpunkts

Vorhandenes Dataset

Verwenden Sie diese Option, wenn Sie bereits Abfragen und Antworten in einer Datei gesammelt haben (oder Abfragen plus Referenzdaten) und Foundry sie nur noch bewerten soll. JSONL unterstützt sowohl Zeilen auf Äußerungsebene als auch Eingaben auf Konversationsebene; CSV unterstützt nur Zeilen auf Äußerungsebene.

Szenario Wann verwendet werden soll Datenquellentyp
Bewertung von Datensets auf Turn-Level Jede Zeile ist ein query/response Paar, optional mit context oder ground_truth. jsonl Oder csv
Auswertung des Datensatzes auf Konversationsebene (Vorschau) Jede Zeile ist eine Unterhaltung, die als messages Array ausgedrückt wird. jsonl

Daten in Foundry oder Application Insights

Verwenden Sie diese Vorgehensweise, wenn Ihr Agent bereits läuft und Sie nachvollziehen möchten, was tatsächlich passiert ist. Anstatt Daten zu verschieben, verweisen Sie Foundry auf die Daten, wo sie bereits liegen – anhand der Foundry-Antwort-ID oder der Application Insights-Trace-ID oder der Konversations-ID.

Szenario Wann verwendet werden soll Datenquellentyp
Agentantwortauswertung Ihr Agent wird in Foundry ausgeführt, und Sie haben Antwort-IDs zu bewerten. azure_ai_responses
Bewertung der Ablaufverfolgung auf Turn-Level (Vorschau) Ihr Agent sendet OpenTelemetry-Traces an Application Insights – einschließlich Frameworks, die nicht zu Foundry gehören, wie LangChain, sowie benutzerdefinierter, mit OpenTelemetry instrumentierter Agenten. Jeder Trace wird unabhängig bewertet. azure_ai_trace_data_source_preview
Bewertung von Traces auf Konversationsebene (Vorschau) Gleiche Tracing-Quellen, aber gesamte Konversationen bewerten – nach Konversations-ID oder mit Stichproben über einen Agentenfilter. azure_ai_trace_data_source_preview

Eingaben ohne Antworten

Verwenden Sie diesen Pfad, wenn Sie die Eingaben, aber noch keine Antworten haben. Foundry generiert während der Auswertung Antworten auf Grundlage eines Modell- oder Agentziels und bewertet sie. Wählen Sie eine Zeile basierend darauf aus, ob ihre Eingabe Abfragen (als einzelne Wendungen gesendet) oder Szenariobeschreibungen (die verwendet werden, um eine Interaktion auf Unterhaltungsebene zu fördern) ist.

Szenario Wann verwendet werden soll Datenquelle/Ziel
Vervollständigungen des Modellziels Sie haben Abfragen und möchten Antworten aus einer Modellbereitstellung auswerten. azure_ai_target_completions → azure_ai_model
Abschlüsse des Agent-Ziels Sie haben Abfragen und möchten Antworten von einem Foundry-Agent auswerten. azure_ai_target_completions → azure_ai_agent
Konversationssimulation (Vorschau) Sie haben Szenariobeschreibungen (keine Anfragen); Foundry simuliert einen Nutzer, der eine Interaktion auf Gesprächsebene mit dem Agenten führt. azure_ai_target_completions → azure_ai_agent

Noch keine Daten

Verwenden Sie diesen Pfad, wenn Sie ein neues Modell oder einen neuen Agent erstellen und keine Eingaben gesammelt haben. Foundry generiert die Testdaten von Grund auf neu – wählen Sie synthetische Abfragen für eine umfassende Qualitätsabdeckung oder adversariale Aufforderungen für Sicherheitstests aus.

Szenario Wann verwendet werden soll Datenquelle/Ziel
Auswertung synthetischer Daten (Vorschau) Sie möchten eine hochwertige Abdeckung, die über das hinausgeht, was Sie von Hand schreiben würden. Foundry generiert Testabfragen, sendet sie an das Ziel und bewertet Antworten. azure_ai_synthetic_data_gen_preview azure_ai_model→ oderazure_ai_agent
Rote Teambewertung Sie möchten automatisierte adversariale Tests – Foundry generiert Jailbreaks und Prompts mit schädlichen Inhalten und bewertet, wie das Zielsystem reagiert. azure_ai_red_team azure_ai_model→ oderazure_ai_agent

Evaluatoren auswählen

Jedes Szenario bindet Evaluatoren an Felder in Ihren Daten über Spaltenzuordnungen. Die verfügbaren Felder hängen von der Datenquelle ab. Datasetszenarien machen Ihre benutzerdefinierten Elementfelder verfügbar, während zielgenerierte Szenarien auch die Modell- oder Agentantwort über ein Beispielschema verfügbar machen. Die Unterabschnitte pro Szenario weiter unten in diesem Artikel zeigen die Spaltenzuordnungen für jeden Fall.

Eine Übersicht über die verfügbaren Bewerter und deren Auswahl finden Sie unter integrierten Bewertern und benutzerdefinierten Bewertern.

Voraussetzungen

  • Ein Foundry-Projekt.

  • Eine Azure OpenAI-Bereitstellung mit einem GPT-Modell, das den Chatabschluss unterstützt (z. B. gpt-5-mini).

  • Rolle "Foundry User " im Foundry-Projekt.

    Wichtig

    Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

  • Optional können Sie Ihr eigenes Speicherkonto verwenden , um Auswertungen auszuführen.

Hinweis

Einige Auswertungsfeatures weisen regionale Einschränkungen auf. Ausführliche Informationen finden Sie in den unterstützten Regionen .

Beginnen

Installieren Sie das SDK, und richten Sie Ihren Client ein:

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

Vorbereiten von Eingabedaten

Die meisten Auswertungsszenarien erfordern Eingabedaten. Sie können Daten auf zwei Arten bereitstellen:

Laden Sie eine JSONL- oder CSV-Datei hoch, um ein versionsiertes Dataset in Ihrem Foundry-Projekt zu erstellen. Datasets unterstützen die Versionsverwaltung und Wiederverwendung über mehrere Bewertungsläufe hinweg. Verwenden Sie diesen Ansatz für Produktionstests und CI/CD-Workflows.

Bereiten Sie eine JSONL-Datei mit einem JSON-Objekt pro Zeile mit den Feldern vor, die Ihre Evaluatoren benötigen:

{"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."}

Oder bereiten Sie eine CSV-Datei mit Spaltenüberschriften vor, die Ihren Evaluator-Feldern entsprechen:

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

Daten inline bereitstellen

Um schnell mit kleinen Testsätzen zu experimentieren, stellen Sie Daten direkt in der Auswertungsanforderung bereit.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",
            }
        ),
    ],
)

Übergeben Sie bei der Erstellung einer Ausführung source als "source"-Feld in Ihrer Datenquellenkonfiguration. Die folgenden Szenarioabschnitte verwenden standardmäßig file_id.

Datensatzbewertung

Bewertung von vorab berechneten Antworten in einer JSONL-Datei mithilfe des jsonl Datenquellentyps. Dieses Szenario ist nützlich, wenn Sie bereits Über Modellausgaben verfügen und deren Qualität bewerten möchten.

Tipp

Bevor Sie beginnen, führen Sie "Erste Schritte " und "Vorbereiten von Eingabedaten" aus.

Definieren des Datenschemas und der Auswerter

Geben Sie das Schema an, das Ihren JSONL-Feldern entspricht, und wählen Sie die zu ausführenden Evaluatoren (Testkriterien) aus. Verwenden Sie den data_mapping-Parameter, um Felder aus Ihren Eingabedaten mit Evaluatorparametern im {{item.field}}-Syntax zu verbinden. Fügen Sie data_mapping immer zu den erforderlichen Eingabefeldern für jeden Evaluator hinzu. Ihre Feldnamen müssen mit denen in der JSONL-Datei übereinstimmen — zum Beispiel, wenn Ihre Daten "question" statt "query" enthalten, sollten Sie "{{item.question}}" in der Zuordnung verwenden. Die erforderlichen Parameter pro Evaluator finden Sie unter integrierten Bewertern.

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

Auswertung erstellen und ausführen

Erstellen Sie die Auswertung, und starten Sie dann eine Ausführung für Ihr hochgeladenes Dataset. Die Ausführung führt jeden Evaluator für jede Zeile im Dataset aus.

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

Ein vollständiges ausführungsfähiges Beispiel finden Sie unter sample_evaluations_builtin_with_dataset_id.py auf GitHub. Zum Abfragen der Beendigung und zum Interpretieren der Ergebnisse lesen Sie den Abschnitt Ergebnisse abrufen.

CSV-Datasetauswertung

Bewerten von vorkompilierten Antworten in einer CSV-Datei mithilfe des csv Datenquellentyps. Dieses Szenario funktioniert auf die gleiche Weise wie die Datasetauswertung , akzeptiert jedoch CSV-Dateien anstelle von JSONL. Verwenden Sie CSV, wenn Ihre Daten bereits im Tabellenkalkulations- oder Tabellenformat vorliegen.

Tipp

Bevor Sie beginnen, führen Sie "Erste Schritte " und "Vorbereiten von Eingabedaten" aus.

Vorbereiten einer CSV-Datei

Erstellen Sie eine CSV-Datei, deren Spaltenüberschriften den Feldern entsprechen, die Ihre Bewerter benötigen. Jede Zeile stellt einen Testfall dar.

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.

Hochladen und Ausführen

Laden Sie die CSV-Datei als Dataset hoch. Erstellen Sie dann eine Auswertung mithilfe des csv Datenquellentyps. Die Schemadefinition und die Evaluatorkonfiguration sind identisch mit JSONL-Auswertungen. Der einzige Unterschied ist das "type": "csv" in der Datenquelle.

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

Zum Abfragen der Beendigung und zum Interpretieren der Ergebnisse lesen Sie den Abschnitt Ergebnisse abrufen.

Modellzielbewertung

Senden von Abfragen an ein bereitgestelltes Modell zur Laufzeit. Bewerten Sie die Antworten mithilfe des azure_ai_target_completions Datenquellentyps mit einem azure_ai_model Ziel. Ihre Eingabedaten enthalten Abfragen. Das Modell generiert Antworten, die Sie dann auswerten.

Tipp

Bevor Sie beginnen, führen Sie "Erste Schritte " und "Vorbereiten von Eingabedaten" aus.

Definieren Sie die Nachrichtenvorlage und das Ziel

Die input_messages Vorlage steuert, wie Abfragen an das Modell gesendet werden. Verwenden Sie {{item.query}}, um Felder aus Ihren Eingabedaten zu referenzieren. Geben Sie das Modell an, das ausgewertet werden soll, und optionale Samplingparameter:

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

Einrichten von Evaluatoren und Daten-Mappings

Wenn das Modell zur Laufzeit Antworten generiert, verwenden Sie {{sample.output_text}} in data_mapping um auf die Ausgabe des Modells zu verweisen. Verwenden Sie {{item.field}}, um Felder aus Ihren Eingabedaten zu referenzieren.

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

Auswertung erstellen und ausführen

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

Ein vollständiges ausführungsfähiges Beispiel finden Sie unter sample_model_evaluation.py für GitHub. Zum Abfragen der Beendigung und zum Interpretieren der Ergebnisse lesen Sie den Abschnitt Ergebnisse abrufen.

Tipp

Wenn Sie eine weitere Auswertungsausführung hinzufügen möchten, verwenden Sie denselben Code.

Agent-Zielauswertung

Senden Sie Abfragen zur Laufzeit an einen Foundry-Agent, und bewerten Sie die Antworten mithilfe des azure_ai_target_completions Datenquellentyps mit einem azure_ai_agent Ziel. Dieses Szenario funktioniert sowohl für Eingabeaufforderungs-Agents als auch für gehostete Agents.

Tipp

Bevor Sie beginnen, führen Sie "Erste Schritte " und "Vorbereiten von Eingabedaten" aus.

Tipp

Gehostete Agents, die das Antwortprotokoll verwenden, funktionieren mit den hier gezeigten Codebeispielen. Bei gehosteten Agents, die das Aufrufprotokoll verwenden, unterscheidet sich das input_messages Format. Ausführliche Informationen finden Sie im Protokoll für Aufrufe des gehosteten Agents .

Definieren Sie die Nachrichtenvorlage und das Ziel

Die input_messages Vorlage steuert, wie Abfragen an den Agent gesendet werden. Verwenden Sie {{item.query}}, um Felder aus Ihren Eingabedaten zu referenzieren. Geben Sie den Agent an, der anhand des Namens ausgewertet werden soll:

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

Einrichten von Evaluatoren und Daten-Mappings

Wenn der Agent zur Laufzeit Antworten generiert, verwenden Sie {{sample.*}}-Variablen in data_mapping, um auf die Ausgabe des Agents zu verweisen.

Variable Beschreibung Verwendung für
{{sample.output_text}} Die Nur-Text-Antwort des Agents. Evaluatoren, die eine Zeichenfolgenantwort erwarten (z. B coherence. , violence).
{{sample.output_items}} Die strukturierte JSON-Ausgabe des Agents, einschließlich Toolaufrufen. Auswerter, die vollständigen Interaktionskontext benötigen (z. B. task_adherence).
{{item.field}} Ein Feld aus Ihren Eingabedaten. Eingabefelder wie query oder ground_truth.

Tipp

Das query Feld kann strukturierte JSON enthalten, einschließlich Systemnachrichten und Unterhaltungsverlauf. Einige Agentenbewertungsprogramme wie task_adherence verwenden diesen Kontext für eine genauere Bewertung. Ausführliche Informationen zur Abfrageformatierung finden Sie unter Agent-Evaluatoren.

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

Auswertung erstellen und ausführen

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

Ein vollständiges ausführungsfähiges Beispiel finden Sie unter sample_agent_evaluation.py für GitHub. Zum Abfragen der Beendigung und zum Interpretieren der Ergebnisse lesen Sie den Abschnitt Ergebnisse abrufen.

Protokoll für Aufrufe des gehosteten Agents

Gehostete Agents , die das Aufrufprotokoll verwenden, unterstützen denselben azure_ai_agent Zieltyp, verwenden jedoch ein Freihandformformat input_messages . Stellen Sie anstelle des strukturierten Vorlagenformats ein JSON-Objekt bereit, das dem Anforderungstext des /invocations Agents direkt zugeordnet wird. Verwenden Sie {{item.*}} Platzhalter, um Felder aus Ihren Eingabedaten zu ersetzen.

Wenn ein gehosteter Agent sowohl die Antworten als auch Aufrufprotokolle unterstützt, verwendet der Dienst standardmäßig das Aufrufprotokoll.

Definieren des Nachrichtenformats und des Ziels

input_messages = {"message": "{{item.query}}"}

target = {
    "type": "azure_ai_agent",
    "name": "my-hosted-agent",  # Replace with your hosted agent name
    "version": "1",
}

Auswertung erstellen und ausführen

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

Die Einrichtung des Evaluators und die Datenzuordnungen sind identisch mit der Auswertung des Prompt-Agents. Verwenden Sie {{sample.output_text}} für die Textantwort des Agenten und {{sample.output_items}} für die vollständige strukturierte Ausgabe einschließlich Toolaufrufen.

Auswertung der Agentenantwort

Im nächsten Schritt erfolgt das Abrufen und Auswerten der Reaktionen des Foundry-Agents anhand der Reaktions-IDs mithilfe des Datenquellentyps azure_ai_responses. Verwenden Sie dieses Szenario, um bestimmte Agentinteraktionen auszuwerten, nachdem sie aufgetreten sind.

Tipp

Bevor Sie beginnen, schließen Sie "Erste Schritte" 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, oder laden Sie sie als Dataset hoch (siehe Vorbereiten von Eingabedaten).

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

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

Ein vollständiges ausführungsfähiges Beispiel finden Sie unter sample_agent_response_evaluation.py für GitHub. Zum Abfragen der Beendigung und zum Interpretieren der Ergebnisse lesen Sie den Abschnitt Ergebnisse abrufen.

Ablaufverfolgungsauswertung (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 Ablaufverfolgungen aus Ihrer Überwachungspipeline aus und wenden Evaluatoren darauf an, ohne Anfragen erneut abzuspielen.

Wichtig

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 "Erste Schritte" 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 dieses Feature, indem Sie beim Konfigurieren eines Ablaufverfolgungsauswertungslaufs die Umschaltfläche "Intelligentes Sampling " im Foundry-Portal aktivieren. 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 Ablaufverfolgungen.

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:

Attribute Erforderlich Beschreibung
gen_ai.operation.name Ja 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 Rolle user oder system Zuordnung zu query; Nachrichten mit Rolle assistant oder tool Zuordnung zu response.
gen_ai.output.messages Abfrageeingaben für Evaluatoren JSON-Array von vom Modell generierten Ausgabemeldungen. Alle Ausgabemeldungen werden response zugeordnet. Wenn die Ausgabe auch type: tool_call oder type: tool_result enthält, wird dies tool_calls zugeordnet.
gen_ai.tool.definitions Fakultativ 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 Fakultativ Konversationsbezeichner, der an Auswertungsergebnisse zur Korrelation weitergegeben wird.

Hinweis

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.
  • 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, dem Dienst das automatische Ermitteln und Auswerten der letzten Ablaufverfolgungen für einen bestimmten Agent zu ermöglichen. Es ist keine manuelle Nachverfolgungs-ID-Erfassung erforderlich.

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 Daten-Mappings

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 Beschreibung
{{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. 
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,
        },
    },
]

Ein vollständiges ausführbares Beispiel finden Sie auf GitHub unter sample_evaluations_builtin_with_traces.py. Zum Abfragen der Beendigung und zum Interpretieren der Ergebnisse lesen Sie den Abschnitt Ergebnisse abrufen.

Auswertung synthetischer Daten (Vorschau)

Verwenden Sie den azure_ai_synthetic_data_gen_preview Datenquellentyp, um synthetische Testabfragen zu generieren, sie an ein bereitgestelltes Modell oder einen Foundry-Agent zu senden und die Antworten auszuwerten. Verwenden Sie dieses Szenario, wenn Sie nicht über ein Testdatenset verfügen. Der Dienst generiert Abfragen basierend auf einer Eingabeaufforderung, die Sie bereitstellen (und/oder aus den Anweisungen des Agents), führt sie für Ihr Ziel aus und wertet die Antworten aus.

Tipp

Bevor Sie beginnen, schließen Sie "Erste Schritte" ab.

Funktionsweise der synthetischen Datenauswertung

  1. Der Dienst generiert synthetische Abfragen basierend auf Ihrem prompt und optionalen Startdatendateien.
  2. Jede Abfrage wird an das angegebene Ziel (Modell oder Agent) gesendet, um eine Antwort zu generieren.
  3. Evaluatoren bewerten jede Antwort mithilfe der generierten Abfrage und Antwort.
  4. Die generierten Abfragen werden als Dataset in Ihrem Projekt zur Wiederverwendung gespeichert.

Parameter

Parameter Erforderlich Beschreibung
samples_count Ja Maximale Anzahl synthetischer Testabfragen, die generiert werden sollen.
model_deployment_name Ja Einsatz des Modells zur Generierung synthetischer Abfragen. Es werden nur Modelle mit der Antwort-API-Funktion unterstützt. Verfügbarkeit finden Sie unter Antwort-API Regionsverfügbarkeit.
prompt Nein Anweisungen zur Beschreibung des Typs der zu generierenden Abfragen. Optional, wenn das Agentziel Anweisungen konfiguriert hat.
output_dataset_name Nein Name für das Ausgabe-Dataset, in dem generierte Abfragen gespeichert werden. Wenn Sie keinen Namen angeben, generiert der Dienst automatisch einen.
sources Nein Seed-Datendateien (nach Datei-ID), um die Relevanz generierter Abfragen zu verbessern. Derzeit wird nur eine Datei unterstützt.

Einrichten von Evaluatoren und Daten-Mappings

Der Generator für synthetische Daten erzeugt Abfragen im {{item.query}} Feld. Das Zielobjekt generiert Antworten, die in {{sample.output_text}} verfügbar sind. Ordnen Sie diese Felder Ihren Evaluatoren zu:

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

Auswertung erstellen und ausführen

Modellziel

Generieren von synthetischen Abfragen und Auswerten eines Modells:

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

Optional können Sie eine Systemaufforderung hinzufügen, um das Verhalten des Zielmodells zu gestalten. Wenn Sie input_messages mit der Generierung synthetischer Daten verwenden, fügen Sie nur Nachrichten der Rolle system hinzu – der Dienst stellt die generierten Abfragen automatisch als Benutzernachrichten bereit.

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."
                }
            }
        ]
    },
}

Agentenziel

Generieren Sie synthetische Abfragen, und bewerten Sie einen Foundry-Agent:

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

Zum Abfragen der Beendigung und zum Interpretieren der Ergebnisse lesen Sie den Abschnitt Ergebnisse abrufen. Die Antwort enthält eine output_dataset_id Eigenschaft, die die ID des generierten Datasets enthält, mit der Sie die synthetischen Daten abrufen oder wiederverwenden können.

Bewertung auf Konversationsebene (Vorschau)

Bewerten Sie vollständige Unterhaltungen, um die Agentqualität über ganze Benutzerinteraktionen hinweg zu bewerten – nicht nur einzelne Antworten. Verwenden Sie die Evaluierung auf Konversationsebene, um Qualitätsprobleme wie unvollständige Aufgabenlösung, Benutzerfrustration und Regressionen bei Tool-Aufrufen zu identifizieren, die bei der Bewertung auf Turn-Ebene übersehen werden.

Betrachten Sie beispielsweise einen Support-Agenten, bei dem der Benutzer im Verlauf mehrerer Gesprächsrunden zunehmend frustriert wird:

Turn 1 — User: "Ich muss mein Kennwort zurücksetzen." Agent: "Ich habe Ihr Konto gefunden. Ich schicke einen Link zum Zurücksetzen.

Turn 2 — User: "Ich habe die E-Mail nicht erhalten." Agent: "Ich habe den Link erneut gesendet. Bitte überprüfen Sie Spam."

Turn 3 — Benutzer: "Immer noch nichts. „Können Sie es nicht einfach direkt zurücksetzen?“ Agent: „Ich habe einen weiteren Link zum Zurücksetzen gesendet.“

Ein Evaluator auf Turn-Ebene bewertet nur die letzte Antwort – die höflich ist und handelt – und erhält daher eine gute Bewertung. Ein Evaluator auf Gesprächsebene, der die Kundenzufriedenheit über den gesamten Gesprächsverlauf hinweg bewertet, stellt fest, dass der Agent dieselbe erfolglose Maßnahme dreimal wiederholt hat, ohne eine Alternative zu versuchen, sodass das Problem des Nutzers ungelöst blieb.

Die Bewertung auf Konversationsebene unterscheidet sich in mehreren Punkten von der Bewertung auf Turn-Ebene:

Aspect Turn-Ebene Konversationsebene
Scope Einzelne Abfrageantwortpaare Vollständige Konversationen mit mehreren Nachrichten
Metriken Qualität und Sicherheit pro Reaktion Ergebnisse auf Konversationsebene und Benutzerzufriedenheit
Datenformat JSONL mit query und response Feldern JSONL mit einem messages Array, das die vollständige Unterhaltung enthält
Anwendungsfall Testen einzelner Modellantworten Testen der End-to-End-Agent-Erfahrungen

Die Bewertung auf Konversationsebene unterstützt vier Optionen für Datenquellen:

Auswahl Wann verwendet werden soll Datenquellentyp
Aus Datensatz oder Inline Sie haben lokale Gesprächsprotokolle oder Testdaten. jsonl mit file_id oder file_content
Nach Konversations-ID Sie möchten bestimmte Unterhaltungen aus App Insights auswerten azure_ai_trace_data_source_preview mit trace_source
Nach Agentenfilter mit Sampling Sie möchten die Qualität des Agenten insgesamt anhand von stichprobenartig erfasstem Produktivverkehr bewerten. azure_ai_trace_data_source_preview mit trace_source
Simulierte Unterhaltungen Sie möchten synthetische Testgespräche generieren azure_ai_target_completions mit conversation_gen_preview

Auswählen einer Auswertungsstufe

Der evaluation_level Parameter für die Ausführung bestimmt, ob Evaluatoren einzelne Wendungen oder vollständige Unterhaltungen bewerten:

Wert Behavior
"turn" Die Bewertungen der Evaluatoren werden jeweils unabhängig voneinander bewertet.
"conversation" Evaluatoren bewerten die gesamte Unterhaltung als Ganzes.
(weggelassen) Wird standardmäßig auf "turn" festgelegt.

Wichtig

Evaluatorkompatibilität: Jeder Evaluator unterstützt bestimmte Auswertungsstufen. Überprüfen Sie das Feld des supported_evaluation_levelsEvaluators im Evaluator-Katalog.

  • Evaluatoren nur für einzelne Turns (z. B. fluency, relevance) können nicht mit evaluation_level="conversation" verwendet werden.
  • Derzeit unterstützen alle Evaluatoren auf Konversationsebene sowohl die Ebenen "turn" als auch "conversation".

Häufige Fehler

Fehler Ursache Lösung
Inkompatible Auswertungsebene Verwendung von evaluation_level="conversation" mit einem Evaluator nur für Turns Entfernen sie den reinen Evaluator, oder ändern Sie den Wert in evaluation_level="turn"

Gesprächsdaten vorbereiten

Erstellen Sie eine JSONL-Datei, in der jede Zeile eine vollständige Unterhaltung im messages Feld enthält. Jede Nachricht sollte ein role (Benutzer, Assistent oder System) und ein content enthalten. Ein vollständiges Beispiel finden Sie in den Beispielen zur konversationsauswertung im 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?"}]}

Sie können auch Tooldefinitionen und Toolaufrufe einschließen, wenn Ihr Agent Tools verwendet:

{"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."}]}

Definieren des Datenschemas und der Auswerter

Geben Sie das Schema für Ihre Unterhaltungsdaten, "Nachrichten" an, und wählen Sie Evaluatoren aus, die für die Auswertung auf Unterhaltungsebene entwickelt wurden. Evaluatoren auf Unterhaltungsebene bewerten die gesamte Interaktion und nicht einzelne Wendungen.

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

Auswertung erstellen und ausführen

Vorbereitung: sample_data_multiturn_conversations.jsonl herunterladen

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

Zum Abfragen der Beendigung und zum Interpretieren der Ergebnisse lesen Sie den Abschnitt Ergebnisse abrufen.

Konversationen anhand der ID aus Ablaufverfolgungen auswerten

Bewerten Sie bestimmte Unterhaltungen aus Application Insights, indem Sie ihre Unterhaltungs-IDs bereitstellen. Verwenden Sie diese Option, um Ursachen von Problemen zu ermitteln oder Fehlerbehebungen bei bestimmten Interaktionen zu überprüfen. Sie können z. B. eine Unterhaltung untersuchen, die durch eine Warnung gekennzeichnet ist, oder eine Lösung für ein bekanntes Problem überprüfen.

Wo Sie Konversations-IDs finden

Finden Sie Konversations-IDs in:

  • Benutzeroberfläche der Application Insights-Ablaufverfolgungsprotokolle — Wechseln Sie zu relevanten Ablaufverfolgungen, und suchen Sie das Feld conversation_id in den Details der Ablaufverfolgung.
  • Die Protokollierungsausgabe Ihrer Anwendung – Wenn Sie beim Erstellen von Agentantworten explizit festlegen conversation_id , rufen Sie sie aus Ihren Protokollen ab.
  • OpenTelemetry-Trace-Kontext — Das conversation_id kann auch aus dem traceparent-Header abgeleitet werden, wenn Ihr Agent die standardmäßige Weitergabe des Trace-Kontexts verwendet.

Hinweis

Tooldefinitionen werden automatisch aus den Ablaufverfolgungen abgerufen oder aus der Agentregistrierung abgefragt. Sie müssen sie nicht in der Anforderung angeben.

Parameter für die Suche nach Konversations-ID

Parameter Erforderlich Beschreibung
conversation_ids Ja Array von Konversations-IDs zur Auswertung.
lookback_hours Nein Stunden, die ab end_time zurück durchsucht werden sollen. Der Standardwert ist sieben Tage (168 Stunden).
end_time Nein Ende des Suchfensters (ISO 8601-Format). Standardmäßig ist die aktuelle Uhrzeit eingestellt. 
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"},
    )

Hinweis

  • Die Erfassung von Application Insights-Daten kann zu einer Verzögerung zwischen dem Generieren von Ablaufverfolgungen und dem Zeitpunkt führen, an dem sie für die Auswertung verfügbar sind. Wenn die Abfrage keine Traces findet, warten Sie einige Minuten und versuchen Sie es erneut.
  • Der maximale Lookback beträgt 7 Tage (168 Stunden). Um auf ältere Ablaufverfolgungen zuzugreifen, verwenden Sie start_time und end_time innerhalb Ihrer App Insights-Aufbewahrungsgrenzen.

Stichprobenartig ausgewählte Gespräche nach Agentenfilter auswerten

Bewerten Sie eine stichprobenbasierte Gruppe von Unterhaltungen aus Application Insights, indem Sie nach Agentnamen filtern. Verwenden Sie diese Option, um die Gesamtqualität des Agenten über den gesamten Produktionsdatenverkehr hinweg zu bewerten. Führen Sie z. B. regelmäßige Qualitätsbewertungen aus, oder überwachen Sie qualitätsbeeinträchtigungen in der Produktion.

Der Agent, den Sie zum Filtern angeben, kann Teil einer Konversation mit mehreren Agenten sein. Der Filter entspricht jeder Unterhaltung, an der dieser Agent teilgenommen hat.

Hinweis

Definitionen der Tools werden automatisch aus den Ablaufverfolgungen abgerufen oder über die Agent-Registrierung abgefragt. Sie müssen sie nicht in der Anforderung angeben.

Agent-Identitätsfelder

Geben Sie den zu filternden Agent mithilfe eines der folgenden Formate an:

Format Example Beschreibung
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" Zwei separate Felder. Wenn agent_version weggelassen wird, verwenden Sie die neueste Version.
agent_id "agent_id": "my-agent:1" Einzelne Zeichenfolge im "name:version" Format.

Filterstrategien

Strategie Beschreibung
random_sampling (Standard) Gleichverteilte Zufallsstichprobe von bis zu max_traces Konversationen.
smart_filtering Dienstverwaltete Heuristik, die interessante Traces bevorzugt – also Konversationen mit potenziellen Problemen, Randfällen oder Anomalien.

Parameter

Parameter Erforderlich Beschreibung
agent_name Ja Der Name des Agenten, nach dem Ablaufverfolgungen gefiltert werden sollen.
agent_version Nein Die Agent-Version. Wenn sie weggelassen wird, wird die neueste Version verwendet.
agent_id Nein Alternative zu agent_name + agent_version. Einzelne Zeichenfolge im Format "name:version".
start_time Ja Beginn des Zeitfensters (Unix-Epochenzeit in Sekunden, UTC).
end_time Ja Ende des Zeitfensters (Sekunden seit der Unix-Epoche, UTC). Um +600 Sekunden auffüllen, um Verzögerungen bei der Datenaufnahme zu vermeiden.
max_traces Nein Maximale Anzahl an Konversationen zur Auswahl. Der Standardwert ist 1.000.
filter_strategy Nein "random_sampling" (Standard) oder "smart_filtering" (vom Dienst verwaltete Heuristik, die interessante Traces bevorzugt).

Wichtig

Das Zeitfenster (end_time - start_time) muss mindestens 15 Minuten (900 Sekunden) betragen. Diese Anforderung ist vorhanden, da Abfragen auf Unterhaltungsebene einen 5-minütigen Inaktivitätspuffer auf jedem Rand anwenden, um partielle Unterhaltungen zu vermeiden.

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

Hinweis

Der Zeitbereich der App Insights-Abfrage ist derzeit auf maximal 7 Tage (168 Stunden) beschränkt. Sie können nicht auf Ablaufverfolgungen zugreifen, die älter als 7 Tage sind, ohne start_time und end_time innerhalb der Aufbewahrungsgrenzen von App Insights explizit anzugeben.

Zum Abfragen der Beendigung und zum Interpretieren der Ergebnisse lesen Sie den Abschnitt Ergebnisse abrufen.

Dialogsimulation

Generieren Sie simulierte Unterhaltungen aus Szenariobeschreibungen, und bewerten Sie sie auf Unterhaltungsebene. Verwenden Sie dieses Szenario, um das Verhalten Ihres Agents in kontrollierten Situationen vor der Bereitstellung zu testen. Der Dienst generiert realistische Unterhaltungen basierend auf Ihren Szenariobeschreibungen und wertet sie dann aus.

Dieser Ansatz ist nützlich für:

  • Tests vor der Bereitstellung: Überprüfen des Agentverhaltens in verschiedenen Szenarien ohne echten Benutzerdatenverkehr.
  • Abdeckung von Grenzfällen: Testszenarien, die in der Praxis nur selten auftreten, jedoch gut gehandhabt werden müssen.
  • Regressionstests: Stellen Sie sicher, dass Agentupdates die Leistung in bekannten Szenarien nicht beeinträchtigen.
  • Tests im großen Maßstab: Generieren Sie schnell viele Konversationen, um die Fähigkeiten des Agenten einem Belastungstest zu unterziehen.

So funktioniert die Konversationssimulation

  1. Sie stellen ein Dataset mit Szenariobeschreibungen bereit. Jede Zeile beschreibt eine Situation, die der simulierte Benutzer zu erreichen versucht.
  2. Der Dienst verwendet ein Simulatormodell, um die Rolle des Benutzers zu spielen und basierend auf dem Szenario mit Ihrem Agent zu interagieren.
  3. Jedes Szenario generiert eine oder mehrere vollständige Unterhaltungen.
  4. Bewerter auf der Ebene ganzer Konversationen bewerten die generierten Konversationen.
  5. Ihr Projekt speichert sowohl die Unterhaltungen als auch die Auswertungsergebnisse.

Vorbereiten von Szenariodaten

Erstellen Sie eine JSONL-Datei, in der jede Zeile ein Szenario für den simulierten Benutzer beschreibt. Das Schema erfordert id, test_case_descriptionund desired_num_turns. Fügen Sie Details zum Ziel, Kontext und einschränkungen des Benutzers hinzu. Ein vollständiges Beispiel finden Sie in den Beispielen zur konversationsauswertung im 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}

Parameter

Parameter Erforderlich Beschreibung
num_conversations Nein Anzahl der Unterhaltungen, die pro Szenario generiert werden sollen. Standardmäßig 5, serverseitige Obergrenze von 5.
max_turns Nein Maximale Anzahl von Wendungen (Austausch) pro Unterhaltung. Standardmäßig 10, serverseitige Obergrenze von 20.
model Ja Modellbereitstellung zur Simulation des Benutzers. Beispiel: gpt-4.1
sampling_params Nein Samplingparameter für das Simulatormodell, einschließlich temperature, top_pund max_completion_tokens.
data_mapping Nein Ordnet Felder aus Ihrem Szenario JSONL zu Simulationsparametern zu. Allgemeine Zuordnungen: test_case_description, id, desired_num_turns.

Bewerter definieren

Wählen Sie Evaluatoren aus, die für Bewertungen auf Konversationsebene entwickelt wurden. Die simulierten Unterhaltungen werden automatisch den Bewertern zugeordnet.

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

Auswertung erstellen und ausführen

Vorbereitung: sample_data_simulation_scenarios.jsonl herunterladen.

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

Zum Abfragen der Beendigung und zum Interpretieren der Ergebnisse lesen Sie den Abschnitt Ergebnisse abrufen.

Ergebnisse abrufen

Rufen Sie nach Abschluss einer Auswertung die bewerteten Ergebnisse ab, und überprüfen Sie sie im Portal oder programmgesteuert.

Poll für Ergebnisse durchführen

Auswertungsläufe sind asynchron. Rufen Sie den Ausführungsstatus auf, bis er abgeschlossen ist, und rufen Sie dann die Ergebnisse ab:

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

Interpretieren von Ergebnissen

Für ein einzelnes Datenbeispiel geben alle Bewerter das folgende Schema aus:

  • Beschriftung: eine binäre "Pass"- oder "fail"-Bezeichnung, ähnlich der Ausgabe eines Komponententests. Verwenden Sie dieses Ergebnis, um Vergleiche über Evaluatoren hinweg zu vereinfachen.
  • Bewertung: eine Bewertung aus der natürlichen Skala der einzelnen Evaluatoren. Einige Bewerter verwenden eine feinkörnige Rubrik, eine Bewertung auf einer 5-Punkt-Skala (Qualitätsbewertungen) oder eine 7-Punkt-Skala (Inhaltssicherheits-Evaluatoren). Andere, wie textbezogene Ähnlichkeitsbewertungen, verwenden F1-Bewertungen, die zwischen 0 und 1 schweben. Jeder nicht-binäre „score“ wird anhand des „threshold“ im Feld „label“ zu „pass“ oder „fail“ binarisiert.
  • Schwellenwert: Alle nichtbinären Werte werden anhand eines Standardschwellenwerts in „Bestanden“ oder „Nicht bestanden“ umgewandelt, den der Benutzer im SDK außer Kraft setzen kann.
  • Grund: Um die Verständlichkeit zu verbessern, geben alle LLM-Richter-Evaluatoren auch ein Begründungsfeld aus, um zu erläutern, warum eine bestimmte Bewertung angegeben wird.
  • Details: (optional) Bei einigen Bewertern, z. B. tool_call_accuracy, gibt es möglicherweise ein "Details"-Feld oder Flags, das zusätzliche Informationen enthält, um Benutzern beim Debuggen ihrer Anwendungen zu helfen.

Beispielausgabe (einzelnes Element)

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

Beispielausgabe (Aggregatdaten)

Bei über mehrere Datenbeispiele (ein Dataset) aggregierten Ergebnissen bildet die durchschnittliche Rate der Beispiele mit der Bewertung „bestanden“ die Erfolgsquote für dieses Dataset.

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

Problembehandlung

Auftrag, der lange ausgeführt wird

Ihr Auswertungsauftrag kann für längere Zeit im Status Wird ausgeführt verbleiben. Diese Bedingung tritt in der Regel auf, wenn die Azure OpenAI-Modellbereitstellung nicht über genügend Kapazität verfügt, was dazu führt, dass der Dienst Anforderungen erneut versucht.

Auflösung:

  1. Abbrechen des aktuellen Auswertungsauftrags mithilfe von openai_client.evals.runs.cancel(run_id, eval_id=eval_id).
  2. Erhöhen Sie die Modellkapazität im Azure-Portal.
  3. Führen Sie die Auswertung erneut aus.

Authentifizierungsfehler

Wenn Sie einen 401 Unauthorized- oder 403 Forbidden-Fehler erhalten, überprüfen Sie Folgendes:

  • Ihre DefaultAzureCredential Konfiguration ist korrekt. Wenn Sie Azure CLI verwenden, führen Sie az login aus.
  • Ihr Konto verfügt über die Rolle " Foundry User " im Foundry-Projekt.
  • Die URL des Projektendpunkts ist korrekt und enthält sowohl die Konto- als auch die Projektnamen.

Datenformatfehler

Wenn die Auswertung mit einem Schema- oder Datenzuordnungsfehler fehlschlägt:

  • Überprüfen Sie, ob die JSONL-Datei ein gültiges JSON-Objekt pro Zeile aufweist.
  • Überprüfen Sie, ob die Feldnamen in data_mapping genau mit den Feldnamen in Ihrer JSONL-Datei übereinstimmen (Groß-/Kleinschreibung wird beachtet).
  • Überprüfen Sie, ob item_schema die Eigenschaften den Feldern in Ihrem Dataset entsprechen.

Fehler beim Rategrenzwert

Auf Mandanten-, Abonnement- und Projektebene ist die Erstellung von Auswertungsläufen ratenbegrenzt. Wenn Sie eine 429 Too Many Requests Antwort erhalten:

  • Überprüfen Sie den retry-after Header in der Antwort auf die empfohlene Wartezeit.
  • Überprüfen Sie den Antworttext auf Details zum Zinsgrenzwert.
  • Verwenden Sie exponentielles Backoff, wenn Sie fehlgeschlagene Anforderungen wiederholen.

Wenn ein Auswertungsauftrag während der Ausführung mit einem 429 Fehler fehlschlägt:

  • Verringern Sie die Größe Ihres Auswertungsdatensatzes, oder teilen Sie es in kleinere Batches auf.
  • Erhöhen Sie das Token pro Minute (TPM)-Kontingent für die Modellbereitstellung im Azure-Portal.

Fehler des Agentenbewertungstools

Wenn ein Agent-Evaluator einen Fehler für nicht unterstützte Tools zurückgibt:

  • Überprüfen Sie die unterstützten Tools für Agent-Auswertungen.
  • Umschließen Sie als Problemumgehung nicht unterstützte Tools als benutzerdefinierte Funktionstools, damit der Evaluator sie bewerten kann.

Verwandte Inhalte

  • Last updated on