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 Auswertung kann von einer Pipeline ausgeführt werden und --fail-on wandelt seine Ergebnisse in ein Buildgate 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 Chatabschlüsse 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 Gerüst evals/azure.eval.yaml für einen Agenten und fügt azure.yaml einen Evaluierungsdienst 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 Bewertungsrezept: Was wird ausgewertet, woher die Zeilen stammen und welche Bewerter sie benoten.
create Registriert die deklarierten Datensätze, Evaluatoren und die Eval selbst im Projekt.
run start Startet einen Lauf und wartet standardmäßig auf dessen Abschluss und gibt eine Zusammenfassung pro Evaluator aus.
run output list Die Ergebnisse pro Beispiel hinter dieser Zusammenfassung.
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 unterstützt -o json für die Skripterstellung und --debug für die Diagnose. Jeder Befehl außer init akzeptiert --project-endpoint.

Wählen Sie, woher die Zeilen kommen

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

  • --source traces wertet aus, was Ihr Agent bereits getan hat, und liest dies aus den von ihm erzeugten Traces. Nichts zu verfassen.
  • --source dataset wertet einen festen Satz von Beispielen aus, entweder Ihre oder generiert. Wiederholbar und vergleichbar über Agentversionen hinweg.

Trace-basierte Evaluierungen benötigen einen Agenten, der Traces erzeugt. 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 azure.yaml den Agenten, wenn init einen deklariert, fordert zur Auswahl auf, wenn init mehrere deklariert, und fragt, mit welcher Modellbereitstellung die Bewerter bewerten und welche Evaluatoren verwendet werden sollen. Es schreibt evals/azure.eval.yaml und fügt azure.yaml einen Bewertungsdienst hinzu. Es führt keine Dienstaufrufe aus und kann daher sicher ausgeführt werden, bevor irgendetwas bereitgestellt wird.

Bei einem Projekt, das keinen Agentdienst 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 kosten. 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

So übermitteln Sie die Aufträge, und kehren Sie später zurück:

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

Auf job wählen Sie mit --dataset und --evaluator aus, auf welche Sammlung angewendet werden soll, und eine der beiden ist erforderlich.

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

Commit für diese Datei. 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 Ausführungen im Zeitverlauf zu sehen und was der Dienst für eine Auswertung 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 führt eine Durchlaufrate pro Lauf. 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.

Tor eines Builds

Übergeben Sie --fail-on, um die Ausführung als Prüfung auszuführen. Er gibt einen Exit-Code ungleich null zurück, wenn der Lauf den Schwellenwert verfehlt. So weist eine Pipeline eine Änderung zurück, bei der sich die Qualität verschlechtert 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 Beispiele sind die erwartete Ausgabe einer funktionierenden Evaluierung und kein Toolfehler; daher muss Gating ausdrücklich aktiviert werden.

pass-rate nimmt eine Zahl zwischen 0 und 1 an. Ein Schwellenwert, der keiner ist, wird zurückgewiesen, bevor der Lauf eingereicht wird, sodass eine falsch eingegebene Prüfung keine Kosten verursacht.

--fail-on erfordert einen abgeschlossenen Lauf. 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 für alles, was sich geändert hat, eine neue Version und lässt frühere Ausführungen auf die von ihnen verwendeten Versionen festgelegt.

Bewährte Methoden

  • Beginnen Sie mit --source traces, wenn der Agent bereits läuft und Traces ausgibt. Es misst, was passiert ist, und es muss nichts manuell definiert werden.
  • 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 auf Grundlage der Anweisung, die Sie ihm geben, sodass eine vage Anweisung unklare Zeilen erzeugt.
  • Verwenden Sie mehr als einen Evaluator. Ein einzelnes Kriterium verschiebt die Zahl, ohne Ihnen mitzuteilen, warum.
  • Übernehmen Sie commit evals/azure.eval.yaml und die generierten Artefakte, sodass die Auswertung überprüft werden kann.
  • Mit --fail-on in CI absichern und den Schwellenwert so setzen, dass eine echte Regression ihn 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 Ablaufverfolgungen basierende Auswertung kann nur auf Ablaufverfolgungen zugreifen, die der Agent bereits erzeugt hat.
  • azd fasst den Exitcode einer Erweiterung zusammen, sodass sowohl ein Verstoß gegen ein Gate als auch eine Betriebsstörung als Nicht-Null-Exit erscheinen. Lesen Sie die Gate-Meldung, um sie auseinanderzuhalten.

Verwandte Inhalte

  • Last updated on