Freigeben über

Ausführen von Auswertungen aus dem SDK

Von Bedeutung

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 Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

In diesem Artikel erfahren Sie, wie Sie Auswertungen in der Cloud (Vorschau) für Vorabbereitstellungstests für ein Test-Dataset ausführen.

Verwenden Sie für die meisten Szenarien Stapelbewertungen – insbesondere beim Testen in größerem Maßstab, bei der Integration von Bewertungen in Continuous Integration und Continuous Delivery (CI/CD)-Pipelines oder beim Durchführen von Vorabbereitstellungstests. 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.

Batchauswertungsergebnisse 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 Batchauswertung unterstützt alle von Microsoft kuratierten integrierten Bewerter und Ihre eigenen benutzerdefinierten Bewerter. Evaluatoren werden im Evaluator-Katalog mit der gleichen projektbezogenen, rollenbasierten Zugriffssteuerung verwaltet.

Tipp

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

Wenn Sie das Foundry SDK verwenden, protokolliert es auswertungsergebnisse in Ihrem Foundry-Projekt, um eine bessere Observability zu erzielen. Dieses Feature unterstützt alle von Microsoft kuratierten integrierten Bewerter und Ihre eigenen benutzerdefinierten Bewerter. Ihre Evaluatoren können sich in der Auswertungsbibliothek befinden und haben dieselbe projektbezogene, rollenbasierte Zugriffssteuerung.

Funktionsweise der Batchauswertung

Zum Ausführen einer Batchauswertung erstellen Sie eine Auswertungsdefinition mit Ihrem Datenschema und Testkriterien (Evaluatoren), und erstellen dann eine Auswertungsausführung. Die Ausführung führt jeden Auswerter für Ihre Daten aus und gibt bewertete Ergebnisse zurück, die Sie zur Fertigstellung abfragen können.

Die Batchauswertung unterstützt die folgenden Szenarien:

Scenario Wann verwenden Datenquellentyp Ziel
Datasetauswertung Bewerten von vorab berechneten Antworten in einer JSONL-Datei. jsonl —
Modellzielauswertung Generieren Sie für die Auswertung zur Laufzeit Abfragen und Antworten aus einem Modell. azure_ai_target_completions azure_ai_model
Agentenzielbewertung Generieren Sie für die Auswertung zur Laufzeit Abfragen und Antworten aus einem Foundry-Agent. azure_ai_target_completions azure_ai_agent
Agentantwortauswertung Abrufen und Auswerten der Antworten des Foundry-Agents anhand von Antwort-IDs. azure_ai_responses —
Auswertung synthetischer Daten (Vorschau) Generieren Sie synthetische Testabfragen, senden Sie sie an ein Modell oder einen Agent, und bewerten Sie die Antworten. azure_ai_synthetic_data_gen_preview azure_ai_model oder azure_ai_agent
Rote Teambewertung Führen Sie automatisierte Adversarialtests für ein Modell oder einen Agent aus. azure_ai_red_team azure_ai_model oder azure_ai_agent

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

Quelltyp Description
file_id Verweisen Sie auf ein hochgeladenes Dataset anhand der ID.
file_content Geben Sie Daten inline in der Anforderung an.

Jede Auswertung erfordert eine data_source_config , die dem Dienst angibt, welche Felder in Ihren Daten erwartet werden:

  • custom – Sie definieren eine item_schema mit ihren Feldnamen und -typen. Bei Verwendung eines Ziels legen Sie include_sample_schema auf true fest, damit Evaluatoren auf generierte Antworten verweisen können.
  • azure_ai_source — Das Schema wird vom Dienst abgeleitet. Setze "scenario" für die Agentenantwortauswertung, "responses" für "synthetic_data_gen_preview" oder für "red_team" ein.

Jedes Szenario erfordert Bewertungen, die Ihre Testkriterien definieren. Anleitungen zum Auswählen von Bewertern finden Sie im Abschnitt eingebaute Bewerter.

Voraussetzungen

  • Ein Foundry-Projekt.
  • Eine Azure OpenAI-Bereitstellung mit einem GPT-Modell, das den Chatabschluss unterstützt (z. B. gpt-5-mini).
  • Azure AI User Rolle im Foundry-Projekt.
  • 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 .

Get started

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

pip install "azure-ai-projects>=2.0.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
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-Datei hoch, um ein versionsiertes Dataset in Ihrem Foundry-Projekt zu erstellen. Datasets unterstützen Versionierung und Wiederverwendung über mehrere Auswertungslä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."}

# 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

Bereitstellung von Daten in-line

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 source als "source"-Feld in Ihrer Datenquellenkonfiguration bei der Erstellung eines Durchlaufs. Die folgenden Szenarioabschnitte verwenden standardmäßig file_id.

Datasetauswertung

Bewerten Sie vorab berechnete 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 der {{item.field}}-Syntax auf Evaluator-Parameter zu verbinden. Achten Sie darauf, data_mapping mit den erforderlichen Eingabefeldern für jeden Evaluator zu verwenden. Ihre Feldnamen müssen mit denen in Ihrer JSONL-Datei übereinstimmen, z. B. wenn Ihre Daten "question" anstelle von "query" haben, verwenden Sie "{{item.question}}" in der Zuordnung. 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": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "deployment_name": 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}}",
        },
    },
]

Bewertung 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 = 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 = 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ührbares Beispiel finden Sie auf GitHub unter sample_evaluations_builtin_with_dataset_id.py. Um auf Abschlüsse zu prüfen und Ergebnisse zu interpretieren, siehe "Ergebnisse abrufen".

Modellzielauswertung

Senden Sie zur Laufzeit Abfragen an ein bereitgestelltes Modell und bewerten Sie die Antworten mithilfe des Datenquellentyps azure_ai_target_completions und des Ziels azure_ai_model. Ihre Eingabedaten enthalten Abfragen; das Modell generiert Antworten, die dann ausgewertet werden.

Tipp

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

Definieren der Nachrichtenvorlage und des Ziels

Die input_messages Vorlage steuert, wie Abfragen an das Modell gesendet werden. Verwenden Sie {{item.query}}, um auf Felder aus Ihren Eingabedaten zu verweisen. 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 Datenzuordnungen

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 auf Felder aus Ihren Eingabedaten zu verweisen.

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

Bewertung erstellen und ausführen

eval_object = 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 = 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. Um auf Abschlüsse zu prüfen und Ergebnisse zu interpretieren, siehe "Ergebnisse abrufen".

Tipp

Wenn Sie eine weitere Auswertungsausführung hinzufügen möchten, führen Sie dieselbe Auswertung erneut mit derselben Auswertungsgruppe aus. Jede Ausführung erstellt einen neuen Lauf in derselben Gruppe, mit dem Sie die Ergebnisse > nach dem Ändern von Elementen wie dem Modell, dem Eingabebefehl oder dem Dataset vergleichen können, ohne eine neue Auswertung zu erstellen oder eine andere API zu verwenden.

Sehen Sie sich das Beispiel an, das dieselbe Auswertungsgruppe wiederverwendet, um mehrere Ausführungen für den Vergleich zu erstellen.

Agentenzielbewertung

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.

Tipp

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

Definieren der Nachrichtenvorlage und des Ziels

Die input_messages Vorlage steuert, wie Abfragen an den Agent gesendet werden. Verwenden Sie {{item.query}}, um auf Felder aus Ihren Eingabedaten zu verweisen. 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 Datenzuordnungen

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

Variable Description 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 den 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 Agenten-Evaluatoren 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": {
            "deployment_name": 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": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

Bewertung erstellen und ausführen

eval_object = 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 = 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. Um auf Abschlüsse zu prüfen und Ergebnisse zu interpretieren, siehe "Ergebnisse abrufen".

Tipp

Wenn Sie eine weitere Auswertungsausführung hinzufügen möchten, führen Sie dieselbe Auswertung erneut mit derselben Auswertungsgruppe aus. Jede Ausführung erstellt einen neuen Vorgang unter derselben Gruppe, mit der Sie die Ergebnisse >nach dem Ändern von Elementen wie dem Modell, der Aufforderung oder dem Dataset vergleichen können, ohne eine neue Bewertung zu erstellen oder eine andere API zu verwenden.

Sehen Sie sich das Beispiel an, das dieselbe Auswertungsgruppe wiederverwendet, um mehrere Ausführungen für den Vergleich zu erstellen.

Agentantwortauswertung

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 "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 = client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

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

Bewertung 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": {
            "deployment_name": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = 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 = 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. Um auf Abschlüsse zu prüfen und Ergebnisse zu interpretieren, siehe "Ergebnisse abrufen".

Tipp

Wenn Sie eine weitere Auswertungsausführung hinzufügen möchten, führen Sie dieselbe Auswertung erneut mit derselben Auswertungsgruppe aus. Jede Ausführung erzeugt einen neuen Lauf innerhalb derselben Gruppe, mit dem Sie die Ergebnisse über die Läufe hinweg vergleichen können, nachdem Sie Elemente wie das Modell, den Prompt oder das Dataset geändert haben—ohne eine neue Auswertung zu erstellen oder eine andere API zu verwenden.

Sehen Sie sich das Beispiel an, das dieselbe Auswertungsgruppe wiederverwendet, um mehrere Ausführungen für den Vergleich zu erstellen.

Auswertung synthetischer Daten (Vorschau)

Generieren Sie synthetische Testabfragen, senden Sie sie an ein bereitgestelltes Modell oder einen Foundry-Agent, und bewerten Sie die Antworten mithilfe des azure_ai_synthetic_data_gen_preview Datenquellentyps. Verwenden Sie dieses Szenario, wenn Sie nicht über ein Testdatenset verfügen . Der Dienst generiert Abfragen basierend auf einer von Ihnen bereitgestellten Aufforderung (und/oder aus den Anweisungen des Agents), führt diese anhand Ihres Ziels 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 Ihren prompt und optionalen Seed-Datendateien.
  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 Description
samples_count Ja Maximale Anzahl synthetischer Testabfragen, die generiert werden sollen.
model_deployment_name Ja Bereitstellung eines Modells zum Generieren synthetischer Abfragen. Es werden nur Modelle mit der Antwort-API-Funktion unterstützt. Verfügbarkeit siehe Antwort-API-Regionenverfügbarkeit.
prompt Nein Anweisungen zur Beschreibung des Typs der zu generierenden Abfragen. Optional, wenn für das Ziel des Agents Anweisungen konfiguriert wurden.
output_dataset_name Nein Name für das Ausgabe-Dataset, in dem generierte Abfragen gespeichert werden. Wenn nicht angegeben, generiert der Dienst automatisch einen Namen.
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 Datenzuordnungen

Der Generator für synthetische Daten erzeugt Abfragen im {{item.query}} Feld. Das Ziel generiert Antworten, die in {{sample.output_text}}. 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": {
            "deployment_name": 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}}",
        },
    },
]

Bewertung erstellen und ausführen

Modellziel

Generieren von synthetischen Abfragen und Auswerten eines Modells:

eval_object = 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 = 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 synthetischer Datengenerierung verwenden, schließen Sie nur system-Rollenmeldungen ein – 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."
                }
            }
        ]
    },
}

Ziel der Agenten

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 = client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-agent-evaluation",
    data_source=data_source,
)

Um auf Abschlüsse zu prüfen und Ergebnisse zu interpretieren, siehe "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.

Ergebnisse abrufen

Rufen Sie nach der Durchführung eines Auswertungslaufs die bewerteten Ergebnisse ab und überprüfen Sie sie im Portal oder programmatisch.

Umfrage für Ergebnisse

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

if run.status == "failed":
    print(f"Evaluation run failed: {run.error}")
else:
    # Retrieve results
    output_items = list(
        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 des einzelnen Evaluators. 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 basierend auf dem „threshold“ (Schwellenwert) im Feld „Label“ in einen der binären Werte „pass“ (bestanden) oder „fail“ (nicht bestanden) umgewandelt.
  • Schwellenwert: Alle nicht binären Bewertungen werden basierend auf einem Standardschwellenwert, den der Benutzer in der SDK-Oberfläche außer Kraft setzen kann, auf "Übergeben" oder "Fehlschlagen" binarisiert.
  • 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 (Aggregat)

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

Ein Job, der lange läuft

Ihr Auswertungsauftrag kann für längere Zeit im Status "Läuft " bleiben. Dies 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.

Lösung:

  1. Abbrechen des aktuellen Auswertungsauftrags mithilfe von 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:

  • Ihr DefaultAzureCredential ist ordnungsgemäß konfiguriert (führen Sie az login aus, wenn Sie Azure CLI verwenden).
  • Ihr Konto verfügt über die Rolle Azure AI 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.
  • Vergewissern Sie sich, dass 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.

Ratenbegrenzungsfehler

Für die Erstellung von Auswertungsausführungen gelten auf Mandanten-, Abonnement- und Projektebene Ratenlimits. 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 Anfragen 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-Kontingent (TPM) für die Modellbereitstellung im Azure-Portal.

Fehler des Agent-Evaluator-Tools

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