Agentenbewertungen mit der azd CLI ausführen (Vorschau)

Important

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

Verwenden Sie die azd ai eval Erweiterung, um einem Agent, der mit Microsoft Foundry erstellt wurde, eine gemessene Qualitätsschleife hinzuzufügen. Sie setzen neben Ihrem Projekt eine Auswertung auf, generieren optional ein Dataset und einen Rubrik-Evaluator, führen die Auswertung gegen Ihren Agenten aus und lesen die Ergebnisse, ohne das Terminal verlassen zu müssen.

Die gleiche Evaluierung kann aus einer Pipeline heraus ausgeführt werden, und --fail-on wandelt deren Ergebnisse in ein Build-Gate um.

Dieser Artikel behandelt die erste Auswertung mit azd ai eval init und azd ai eval run start.

Voraussetzungen

  • Ein Azure-Abonnement mit Zugriff auf Microsoft Foundry.
  • Die Azure Developer CLI (azd), Version 1.27.1 oder höher. Installationsanweisungen finden Sie unter Install the Azure Developer CLI.
  • Die azd ai eval-Erweiterung: azd extension install azure.ai.evaluations. Führen Sie die Ausführung azd extension list --installed aus, um die installierte Version zu überprüfen.
  • Eine authentifizierte azd Sitzung. Führen Sie azd auth status aus, um Ihren Authentifizierungsstatus zu überprüfen. Wenn Sie nicht angemeldet sind, führen Sie azd auth login aus.
  • Die Rolle Foundry User für die Foundry-Ressource (zuvor als Azure AI User bezeichnet). Weitere Informationen finden Sie unter Rollenbasierte Zugriffssteuerung für Microsoft Foundry.
  • Ein Foundry-Projekt und einen Agenten zur Auswertung. Damit init das Ziel erkennen kann, muss der Agent in der azd ai agent init des Projekts als Dienst deklariert werden, wie azure.yaml es tut. Andernfalls benennen Sie ihn mit --target. Informationen zu gehosteten Agents finden Sie unter "Gehostete Agents".
  • Eine Modellbereitstellung, die Chat-Vervollständigungen im selben Projekt unterstützt. Die Bewerter beurteilen damit.
  • Optional: Ein JSONL-Dataset mit repräsentativen Beispielen, wenn Sie keins synthetisieren möchten generate .

Wie azd-Auswertungen funktionieren

Eine Auswertung wird durch eine Datei beschrieben, evals/azure.eval.yamldie Sie lesen, bearbeiten und übernehmen können. Die Befehle schreiben entweder diese Datei oder reagieren auf das, was sie deklariert.

azd ai eval init          # scaffold the configuration. Makes no service calls
azd ai eval generate      # optional: synthesize a dataset and a rubric evaluator
azd ai eval create        # register the eval in the Foundry project
azd ai eval run start     # run it and summarize the results
Element Description
init Erstellt ein evals/azure.eval.yaml-Gerüst für einen Agents und fügt azure.yaml einen Dienst für die Evaluierung hinzu. Führt keine Dienstaufrufe aus.
generate Synthetisiert einen Datensatz, einen Rubrik-Auswerter oder beides, lädt sie herunter und fügt für jedes einen Katalogeintrag zur Konfiguration hinzu. Übermittelt in Rechnung gestellte Generierungsaufträge.
evals/azure.eval.yaml Das Rezept für die Evaluierung: Was wird evaluiert, woher stammen die Zeilen und welche Evaluatoren bewerten sie?
create Registriert die deklarierten Datensätze, Evaluatoren und die Eval selbst im Projekt.
run start Startet die Ausführung, wartet standardmäßig darauf und gibt eine Zusammenfassung pro Evaluator aus.
run output list Die Ergebnisse pro Beispiel, die hinter dieser Zusammenfassung stehen.
dataset, evaluator Verwalten Sie registrierte Datensätze und Evaluatoren direkt, einschließlich versions list.
job Überprüfen, abbrechen und löschen Sie die Generierungsaufträge, die generate übermittelt.

Jeder Befehl akzeptiert -o json für Skripte und --debug für Diagnosen. Jeder Befehl außer init akzeptiert --project-endpoint.

Wählen Sie, woher die Zeilen kommen

Eine Evaluierung bewertet Zeilen. Sie kommen von einem von zwei Orten, und diese Entscheidung ist die erste Entscheidung:

  • --source traces wertet aus, was Ihr Agent bereits getan hat, und liest dies aus den von ihm ausgegebenen Traces aus. Es muss nichts erstellt werden.
  • --source dataset wertet einen festen Satz von Beispielen aus, entweder Ihre oder generiert. Wiederholbar und vergleichbar über Agentversionen hinweg.

Trace-basierte Evaluierungen erfordern einen Agent, der Traces ausgibt. Auswertungen aus Datasets benötigen eine .jsonl Datei oder ein registriertes Dataset.

Bewertung vorbereiten

Führen Sie init im Stammverzeichnis Ihres Projekts aus:

azd ai eval init

Ohne Flags erkennt init den Agent, wenn azure.yaml einen deklariert, führt einen Prompt aus, wenn mehrere deklariert werden, und fragt, anhand welcher Bereitstellungsmodelle die Evaluatoren beurteilen sollen und welche Evaluatoren verwendet werden sollen. Es schreibt evals/azure.eval.yaml und fügt azure.yaml einen Evaluierungsdienst hinzu. Es werden keine Dienstaufrufe getätigt, sodass die Ausführung sicher ist, bevor etwas bereitgestellt wird.

In einem Projekt, das keinen Agent-Dienst deklariert, hält init an, anstatt zu raten:

ERROR: this project declares no agent service to evaluate. Add one, or name an existing agent with --target

Benennen Sie den Agenten in diesem Fall selbst mit --target.

Für die Verwendung in Skripten übergeben Sie die Entscheidungen direkt:

azd ai eval init \
  --source traces \
  --target support-agent \
  --judge-model gpt-4.1-nano \
  --name support-trace-eval \
  --no-prompt

So bewerten Sie ein Dataset, das Sie bereits haben:

azd ai eval init \
  --source dataset \
  --target support-agent \
  --dataset ./tests/support-golden.jsonl \
  --evaluator builtin.intent_resolution,builtin.task_adherence \
  --judge-model gpt-4.1-nano

--dataset verwendet einen lokalen .jsonl Pfad oder den Namen eines registrierten Datasets. --evaluator ist wiederholbar und kommatrennt; builtin.<name> verweist auf einen integrierten Evaluator, und ein barer Name verweist auf einen benutzerdefinierten Evaluator , der im Projekt registriert ist. Die Übergabe von --evaluator ersetzt die Standardeinstellungen und deaktiviert daher auch die Rubrikerstellung.

So finden Sie die integrierten Namen heraus:

azd ai eval evaluator list --builtin

Generieren eines Datasets und eines Evaluators

Wenn Sie keinen Datensatz haben oder eine Rubrik speziell für diesen Agenten statt einer generischen möchten, erstellen Sie beides:

azd ai eval generate \
  --target support-agent \
  --generation-model gpt-4.1-nano \
  --agent-instruction "Handles support requests. Test triage, policy adherence, and escalation."

Standardmäßig werden dabei sowohl ein Datensatz als auch ein Rubrik-Auswerter generiert, beide unter evals/ heruntergeladen und jeweils ein Katalogeintrag für beide zu evals/azure.eval.yaml hinzugefügt. Grenzen Sie dies mit --dataset oder --evaluator ein, um nur eine zu generieren, und begrenzen Sie die Anzahl der Zeilen mit --max-samples (15 bis 1000, Standardwert 15).

generate sendet Jobs, die Modellaufrufe erfordern. Die Anweisung ist wichtig: Es ist, was der Dienst verwendet, um zu entscheiden, worum es bei den Zeilen und Rubriken geht, also beschreiben Sie, was der Agent tut und was getestet werden soll.

Ein Katalogeintrag deklariert das Artefakt; er entscheidet nicht, welche Evaluierung es verwendet. Nach evals/azure.eval.yaml öffnen Sie generate und prüfen, ob die Auswertung, die Sie ausführen möchten, auf das verweist, was erzeugt wurde – eine trace-basierte Auswertung liest Traces, daher wird ein generierter Datensatz erst verwendet, wenn eine Auswertung ihn explizit angibt:

datasets:
    - name: support-agent-dataset
      source: ./datasets/support-agent-dataset.jsonl
evals:
    - name: support-agent-eval
      dataset: support-agent-dataset   # point the eval at the generated dataset

Um die Jobs zu senden und später darauf zurückzukommen:

azd ai eval generate --target support-agent --generation-model gpt-4.1-nano --no-wait
azd ai eval job list --dataset
azd ai eval job show <job-id> --dataset

--dataset und --evaluator wählen auf job aus, auf welche Sammlung sie angewendet werden sollen, wobei mindestens einer von beiden erforderlich ist.

Überprüfen Sie azure.eval.yaml

init schreibt eine Datei, die Sie lesen möchten. Eine auf Trace-Daten basierende Auswertung sieht so aus:

evals:
    - name: support-trace-eval
      description: Basic quality evaluation for support-agent
      source:
        type: traces
        max_traces: 20
        agent_name: support-agent
      evaluation_level: turn
      evaluators:
        - evaluator: builtin.task_adherence
          initialization_parameters:
            model: gpt-4.1-nano

Eine datensatzbasierte Evaluierung benennt den Datensatz anstelle einer Trace-Quelle und erfasst den Agenten, für den sie bestimmt ist:

datasets:
    - name: support-golden
      source: ../tests/support-golden.jsonl
evals:
    - name: support-agent-eval
      description: Basic quality evaluation for support-agent
      dataset: support-golden
      evaluation_level: turn
      evaluators:
        - evaluator: builtin.intent_resolution
          initialization_parameters:
            model: gpt-4.1-nano
        - evaluator: builtin.task_adherence
          initialization_parameters:
            model: gpt-4.1-nano
      target:
        type: agent
        name: support-agent

Pfade unter source: sind relativ zur Konfigurationsdatei. Die generierten .jsonl und Evaluator-JSON sind gewöhnliche Dateien: Bearbeiten Sie diese und führen Sie create dann erneut aus, um eine neue Version zu registrieren.

Diese Datei committen. Es ist der reproduzierbare Teil der Auswertung.

Erstellen sie die Auswertung, und führen Sie sie aus.

Verwenden Sie create, um alles zu registrieren, was die Konfiguration deklariert – Datensätze, Evaluatoren und die Evaluierung selbst:

azd ai eval create

Führen Sie es dann aus:

azd ai eval run start

run start wartet standardmäßig auf den Lauf und gibt eine Tabelle pro Evaluator mit einer Passrate und einer durchschnittlichen Bewertung sowie einen Link zum Lauf im Portal aus. Verwenden Sie --no-wait, um Zeilen zu übermitteln und zurückzugeben, und --max-samples, um die Anzahl der gesendeten Zeilen zu begrenzen.

Wenn die Konfiguration mehr als ein Eval deklariert, geben Sie an, welches gemeint ist:

azd ai eval run start --eval support-trace-eval

Überprüfen der Ergebnisse

Die Zusammenfassung zeigt Ihnen, ob sich die Qualität verändert hat. Die Zeilen pro Stichprobe zeigen, warum:

azd ai eval run output list --eval support-trace-eval
azd ai eval run output list --eval support-trace-eval --failed-only

Um die Ausführungen im Zeitverlauf zu sehen und zu erfahren, was der Dienst für eine Evaluierung bereithält:

azd ai eval list
azd ai eval run list --eval support-trace-eval
azd ai eval show support-trace-eval

show gibt die Identität der Auswertung im Projekt zurück – ID, Name und Erstellungszeitpunkt. Was das eval tut, befindet sich in Ihrem evals/azure.eval.yaml.

run list enthält eine Erfolgsquote pro Ausführung. Die Aufschlüsselung pro Evaluator befindet sich in -o json, unter per_testing_criteria_results, da eine Spalte pro Evaluator nicht mehr lesbar ist, sobald Läufe von verschiedenen Evaluatoren bewertet werden.

So können Sie die Ergebnisse anderswo verwenden:

azd ai eval run output list --eval support-trace-eval --output-file rows.json
azd ai eval run output export --eval support-trace-eval --format csv --output-file summary.csv

Die beiden unterscheiden sich, und der Unterschied ist wichtig: run output list --output-file schreibt die Zeilen pro Probe, während run output export eine Zeile pro Durchlauf schreibt – die Summen, die der Zusammenfassung zugrunde liegen.

Einen Build filtern

Übergeben Sie --fail-on, um die Ausführung in eine Evaluierung umzuwandeln. Das Programm beendet die Ausführung mit einem Ergebnis ungleich Null, wenn die Ausführung den Schwellenwert nicht erreicht – auf diese Weise lehnt eine Pipeline eine Änderung ab, die zu einer Verschlechterung der Qualität geführt hat:

azd ai eval run start --fail-on pass-rate=0.8
azd ai eval run start --fail-on any-failure

Ohne --fail-on wird ein abgeschlossener Lauf mit fehlgeschlagenen Samples weiterhin mit Exit-Code 0 beendet. Fehlgeschlagene Proben sind das erwartete Ergebnis einer funktionierenden Evaluierung und kein Tool-Fehler; daher ist das Filtern optional.

pass-rate nimmt eine Zahl zwischen 0 und 1 an. Ein Schwellenwert, der nicht Eins ist, wird vor der Sendung der Ausführung abgelehnt, sodass ein falsch eingegebenes Gate keine Kosten verursacht.

--fail-on benötigt eine abgeschlossene Ausführung. Auf run show koppeln Sie es mit --wait.

Auswertungen zusammen mit dem Rest des Projekts bereitstellen

init fügt einen Auswertungsdienst hinzu azure.yaml, sodass die Auswertung Teil des Projekts und nicht ein Nebenartefakt ist:

azd up

Damit wird das Projekt eingerichtet und die deklarierten Datensätze, Auswerter und Auswertungen registriert – dieselbe Arbeit, die azd ai eval create selbstständig ausführt.

Ändern des Agents und erneutes Auswerten

Nachdem Sie den Agent geändert und erneut bereitgestellt haben, führen Sie die gleiche Auswertung erneut aus:

azd deploy
azd ai eval run start --eval support-trace-eval

Die Wiederverwendung desselben Evals hält den Datensatz, die Evaluatoren und die Schwellenwerte unverändert, sodass sich der Vergleich auf den Agenten bezieht.

Um zu ändern, was die Auswertung misst, bearbeiten Sie evals/azure.eval.yaml oder die unter evals/ generierten Artefakte und führen Sie anschließend create erneut aus. create registriert eine neue Version aller geänderten Elemente und belässt frühere Ausführungen an die von ihnen verwendeten Versionen angeheftet.

Bewährte Methoden

  • Beginnen Sie mit --source traces, wenn der Agent bereits läuft und Traces ausgibt. Es führt eine Messung durch und gibt nichts zu verfassen.
  • Wechseln Sie zu --source dataset, sobald Sie einen festen Satz von Fällen wünschen, den Sie versionsübergreifend vergleichen können.
  • Lesen Sie das generierte Dataset und die Rubrik, bevor Sie den Ergebnissen vertrauen. generate generiert sie anhand der Anweisung, die Sie ihm geben; eine vage Anweisung erzeugt daher vage Zeilen.
  • Verwenden Sie mehr als einen Evaluator. Ein einzelnes Kriterium verschiebt die Zahl, ohne Ihnen mitzuteilen, warum.
  • Führen Sie ein Commit für evals/azure.eval.yaml und die generierten Artefakte durch, damit die Evaluierung überprüfbar ist.
  • Setzen Sie in der CI ein Gate mit --fail-on und halten Sie den Schwellenwert so, dass eine echte Regression das Gate auslöst.

Einschränkungen

  • Die Erweiterung befindet sich in der Vorschau, und die Befehlsoberfläche kann sich ändern.
  • generate übermittelt abgerechnete Aufträge. Datasets und Evaluatoren werden nicht von azd provision erstellt.
  • Eine auf Traces basierende Evaluierung kann nur Traces lesen, die der Agent bereits ausgegeben hat.
  • azd fasst den Exit-Code einer Erweiterung zusammen, sodass sowohl ein Gate-Verstoß als auch ein Funktionsfehler als Exit-Code ungleich Null angezeigt werden. Lesen Sie die Gate-Meldung, um sie auseinanderzuhalten.

Verwandte Inhalte

  • Last updated on