Köra agentutvärderingar med azd CLI (förhandsversion)

azd ai eval Använd tillägget för att lägga till en uppmätt kvalitetsloop till en agent som skapats med Microsoft Foundry. Du sätter upp en utvärdering bredvid ditt projekt, genererar valfritt ett dataset och en utvärderare baserad på en bedömningsmatris, kör utvärderingen mot din agent och läser resultaten utan att lämna terminalen.

Samma utvärdering kan köras från en pipeline, och --fail-on omvandlar dess resultat till en bygggrind.

Den här artikeln beskriver den första utvärderingen med azd ai eval init och azd ai eval run start.

Förutsättningar

• En Azure-prenumeration med åtkomst till Microsoft Foundry.
• Azure Developer CLI (azd), version 1.27.1 eller senare. Installationsinstruktioner finns i Installera Azure Developer CLI.
• Tillägget azd ai eval : azd extension install azure.ai.evaluations. Kör azd extension list --installed för att kontrollera den installerade versionen.
• En autentiserad azd-session. Om du vill kontrollera autentiseringsstatusen kör du azd auth status. Om du inte är inloggad kör du azd auth login.
• Rollen Foundry User på Foundry-resursen (hette tidigare Azure AI User). Mer information finns i Rollbaserad åtkomstkontroll för Microsoft Foundry.
• Ett Foundry-projekt och en agent som ska utvärderas. För att kunna init identifiera målet måste agenten deklareras som en tjänst i projektets azure.yaml, liksom azd ai agent init . Annars namnger du den med --target. Information om värdbaserade agenter finns i Värdbaserade agenter.
• En modelldistribution som stöder chattavslutningar i samma projekt. Bedömarna bedömer med den.
• Valfritt: en JSONL-datauppsättning med representativa exempel, om du inte vill generate syntetisera en.

Så här fungerar azd-utvärderingar

En utvärdering beskrivs i en fil, evals/azure.eval.yaml, som du kan läsa, redigera och checka in. Kommandona skriver antingen filen eller agerar på vad den deklarerar.

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

Varje kommando accepterar -o json för skript och --debug diagnostik. Alla kommandon utom init accepterar --project-endpoint.

Välj var raderna kommer ifrån

En utvärdering betygsätter rader. De kommer från en av två platser, och detta beslut är det första beslutet:

• --source traces utvärderar vad din agent redan har gjort utifrån de spår den genererade. Inget att skriva.
• --source dataset utvärderar en fast uppsättning exempel, antingen dina eller genererade. Repeterbar och jämförbar mellan agentversioner.

Spårningsbaserade utvärderingar behöver en agent som genererar spårningar. Datauppsättningsbaserade utvärderingar behöver en .jsonl fil eller en registrerad datauppsättning.

Skapa en grundstruktur för utvärderingen

Kör init från projektroten:

azd ai eval init

Utan några flaggor upptäcker init agenten när azure.yaml deklarerar en, frågar när den deklarerar flera och frågar vilken modellutrullning bedömarna ska bedöma med och vilka utvärderare som ska användas. Den skriver evals/azure.eval.yaml och lägger till en utvärderingstjänst i azure.yaml. Det gör inga tjänstanrop, så det är säkert att köra innan något distribueras.

I ett projekt som inte deklarerar någon agenttjänst, stannar init snarare än att gissa:

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

Namnge agenten själv i så fall med --target.

För skriptad användning skickar du besluten direkt:

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

Så här utvärderar du en datauppsättning som du redan har:

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 tar en lokal .jsonl sökväg eller namnet på en registrerad datauppsättning. --evaluator är repeterbar och kommaavgränsad. builtin.<name> refererar till en inbyggd utvärderare och ett namn utan namn refererar till en anpassad utvärderare som är registrerad i projektet. Att skicka --evaluator ersätter standardinställningarna, så det innebär också att generering av kriterier väljs bort.

Så här identifierar du de inbyggda namnen:

azd ai eval evaluator list --builtin

Generera en datauppsättning och en utvärderare

Om du inte har något dataset, eller om du vill ha en bedömningsmatris skriven för den här agenten i stället för en allmän, generera dem:

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

Som standard genererar detta både en datauppsättning och en utvärderare för bedömningsmallar, laddar ned dem till evals/ och lägger till en katalogpost för var och en i evals/azure.eval.yaml. Begränsa den med --dataset eller --evaluator för att generera endast en och begränsa raderna med --max-samples (15 till 1 000, standard 15).

generate skickar in jobb som kostar modellanrop. Instruktionen är viktig: det är vad tjänsten använder för att bestämma vad raderna och kriteriet handlar om, så beskriv vad agenten gör och vad som ska testas.

En katalogpost deklarerar artefakten. Den bestämmer inte vilken utvärdering som använder den. Efter generate, öppna evals/azure.eval.yaml och kontrollera att den eval du tänker köra refererar till det som genererades – en eval som baseras på spår läser spår, så en genererad datauppsättning används bara när en eval anger den:

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

Så här skickar du jobben och kommer tillbaka senare:

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 och --evaluator i job väljer vilken samling åtgärden ska utföras på, och ett av dem måste anges.

Granska azure.eval.yaml

init skriver en fil som du är tänkt att läsa. En spårningsbaserad utvärdering ser ut så här:

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

En datauppsättningsbaserad utvärdering namnger datauppsättningen i stället för en spårningskälla och registrerar agenten som den riktar in sig på:

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

Sökvägarna under source: är relativa till konfigurationsfilen. Den genererade .jsonl JSON-filen och utvärderaren är vanliga filer: redigera dem och kör create sedan igen för att registrera en ny version.

Spara den här filen. Det är den reproducerbara delen av utvärderingen.

Skapa eval och kör den

Använd create för att registrera allt som konfigurationen deklarerar – datauppsättningar, utvärderare och själva evalen:

azd ai eval create

Kör den sedan:

azd ai eval run start

run start väntar som standard på att körningen ska slutföras och skriver ut en tabell för varje utvärderare med godkännandefrekvens och genomsnittspoäng samt en länk till körningen i portalen. Använd --no-wait för att skicka och returnera och --max-samples för att begränsa de rader som skickas.

Om konfigurationen deklarerar mer än en eval namnger du den du menar:

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

Granska resultaten

Sammanfattningen visar om kvaliteten har förändrats. Raderna för varje exempel visar varför:

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

För att se körningar över tid och vilken information tjänsten innehåller för en utvärdering:

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

show returnerar eval-identiteten i projektet – ID, namn och när det skapades. Vad evalen gör finns i din evals/azure.eval.yaml.

run list har en passeringsfrekvens per körning. Uppdelningen per utvärderare finns i -o json, under per_testing_criteria_results, eftersom en kolumn för varje utvärderare inte längre är läsbar när körningar poängsätts av olika utvärderare.

Så här flyttar du resultaten till en annan plats:

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

De två skiljer sig åt, och skillnaden är viktig: run output list --output-file skriver raderna per exempel, medan run output export skriver en rad per körning – summorna bakom sammanfattningen.

Skapa en port

Ange --fail-on för att göra körningen till en kontrollkörning. Den avslutar icke-noll när körningen missar tröskelvärdet, vilket är hur en pipeline misslyckas med en ändring av den regresserade kvaliteten:

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

Utan --fail-on avslutas en slutförd körning med misslyckade exempel ändå med statuskod 0. Underkända exempel är det förväntade resultatet av en fungerande utvärdering, inte ett fel i verktyget, så spärrfunktionen är valfri.

pass-rate tar ett tal mellan 0 och 1. Ett tröskelvärde som inte är 1 avvisas innan körningen skickas in, så ett felaktigt angivet gränsvärde medför ingen kostnad.

--fail-on kräver en slutförd körning. På run show parkopplar du den med --wait.

Distribuera utvärderingar med resten av projektet

init lägger till en utvärderingstjänst i azure.yaml, så eval är en del av projektet i stället för en sidoartefakt:

azd up

Det etablerar projektet och registrerar de deklarerade dataseten, utvärderarna och utvärderingarna, samma arbete som azd ai eval create utför på egen hand.

Ändra agenten och utvärdera igen

När du har ändrat och distribuerat om agenten kör du samma utvärdering igen:

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

Återanvändning av samma eval håller datauppsättningen, utvärderarna och tröskelvärdena fasta, så jämförelsen handlar om agenten.

Om du vill ändra vad utvärderingen mäter, redigera evals/azure.eval.yaml eller de genererade artefakterna under evals/, och kör sedan create igen. create registrerar en ny version av allt som ändrats och låter tidigare körningar fortsätta vara knutna till de versioner de använde.

Metodtips

• Börja med --source traces om agenten redan körs och genererar spårningar. Den mäter vad som hände, och det finns inget att skriva.
• Byt till --source dataset när du vill ha en fast uppsättning fall som du kan jämföra mellan versioner.
• Läs den genererade datamängden och kriteriet innan du litar på poängen. generate genererar dem utifrån den instruktion du ger den, så en vag instruktion ger vaga rader.
• Använd mer än en utvärderare. Ett enda kriterium flyttar talet utan att berätta varför.
• Checka in evals/azure.eval.yaml och genererade artefakter så att utvärderingen kan granskas.
• Använd --fail-on som spärr i CI, och håll tröskeln på en nivå där en verklig regression utlöser den.

Limitations

• Tillägget är i förhandsversion och kommandoytan kan ändras.
• generate skickar in debiterade jobb. Datauppsättningar och utvärderare skapas inte av azd provision.
• En spårningsbaserad utvärdering kan bara läsa spårningar som agenten redan har genererat.
• azd slår ihop ett tilläggs exitkod, så att både ett brott mot en kontrollgräns och ett driftsfel visas som en avslutning med en exitkod som inte är noll. Läs grindmeddelandet för att skilja dem åt.

Relaterat innehåll

• Utvärdera dina agenter
• Inbyggda utvärderare
• Anpassade utvärderare
• Spårningsutvärdering
• Konfigurera spårning för din agent
• Övervaka agenter med instrumentpanelen för agentövervakning