Skapa en utvärderingsdatauppsättning och utvärderare

Agentoptimeraren utvärderar din agent mot en datauppsättning – en samling uppgifter – som utvärderarna har gjort. Du kan generera båda automatiskt från CLI eller skapa en datauppsättning manuellt för fullständig kontroll.

Båda delarna är viktiga för god optimering: datauppsättningen definierar vad som ska testas och utvärderarna definierar hur varje svar ska bedömas. Svaga utvärderare producerar bullriga poäng som leder till dålig optimering, så investera i starka utvärderare lika mycket som representativa uppgifter.

Att skapa dessa resurser är det andra steget i optimeringsarbetsflödet, efter att du har gjort din agent redo för optimering . Optimeraren använder dem för att poängsätta din baslinje och rangordna kandidater.

Förutsättningar

• Ett Foundry-projekt med en distribuerad hostad agent.
• Azure Developer CLI (azd), version 1.37.0 eller senare, som azure.ai.agents-tillägget kräver.
• Ha azure.ai.agents CLI-tillägget, version 1.0.0-beta.22 eller senare, installerat (se Snabbstart: Optimera en värdbaserad agent).
• Tillägget azure.ai.evaluations , som innehåller azd ai eval kommandona och kräver azd 1.33.0 eller senare. Tillägget microsoft.foundry inkluderar det inte, så installera det separat.
• 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.

Generera en datauppsättning och utvärderare (rekommenderas)

Optimeraren återanvänder utvärderingstillgångar som du skapar med azd ai eval kommandona från azure.ai.evaluations tillägget. Kommandogruppen azd ai agent eval är föråldrad. Den skriver bara ut migreringsvägledning till azd ai eval och skickar inga tjänstförfrågningar eller ändrar projektfiler. Optimeraren stöder inte den äldre agent-eval.yamlfilen.

Generera en datauppsättning och en bedömningsmatrisutvärderare från agentens instruktioner:

azd extension install azure.ai.evaluations
azd ai eval generate \
  --from prompt \
  --target <agent-name> \
  --generation-model <generation-deployment> \
  --agent-instruction "<agent-instructions>" \
  --no-prompt

Som standard genererar kommandot:

• En datamängd med rader för din agent.
• En anpassad bedömare för bedömningsmatris, som är en redigerbar JSON-fil med viktade bedömningsdimensioner.

Kommandot laddar ned båda artefakterna och lägger till en katalogpost för var och en i utvärderingskonfigurationen, som standard är evals/azure.eval.yaml. Om du inte anger --dataset-name eller <deployed-agent>-turn-tests, heter datauppsättningen <deployed-agent>-evaluator och utvärderaren --evaluator-name. För information om de interaktiva och icke-interaktiva alternativen och information om de genererade artefakterna, se Generera en datauppsättning och en utvärderare.

Skapa sedan en grundstruktur för en utvärdering som använder de genererade tillgångarna. Optimeraren återanvänder utvärderingar på turnivå som riktar sig mot din agent, så ange --evaluation-level turn och --target. Det här exemplet lägger till den inbyggda builtin.task_adherence utvärderaren i den genererade bedömningsmatrisutvärderaren:

azd ai eval init \
  --source dataset \
  --evaluation-level turn \
  --target <agent-name> \
  --dataset <generated-dataset-name> \
  --evaluator <generated-evaluator-name>,builtin.task_adherence \
  --judge-model <judge-deployment> \
  --name optimizer-eval \
  --no-prompt

Kör optimeringen och välj utvärderingen efter namn:

azd ai agent optimize --eval optimizer-eval --optimize-model <optimization-deployment>

Information om hur du anpassar de genererade tillgångarna finns i Anpassa utvärderare och Skapa en anpassad datauppsättning. Om du vill välja vilken utvärdering en körning använder, se Välj utvärdering för en körning. För de andra körningsalternativen, kör azd ai agent optimize --help.

Välj utvärderingen för ett körningstillfälle

azd ai agent optimize läser datamängden och utvärderarna från en utvärdering som azd ai eval init deklarerade. Välj utvärderingen med något av följande alternativ:

Optimeraren tillämpar följande regler:

• Den beaktar endast utvärderingar som har ett agent target. Målnamnet måste matcha det distribuerade agentnamnet eller agentens tjänstnamn i azure.yaml.
• Den återanvänder endast utvärderingar på turnivå som använder en inläst datauppsättning. Utvärderingar som deklarerar en source eller en simulation, eller som använder konversationsnivån, stöds inte och inte heller utvärderare som anger dataMapping.
• Om du inte anger något av alternativen och projektet har en matchande utvärdering använder optimeraren den. Om flera matchar uppmanar optimeraren dig att välja en. Med --no-prompt eller -o json misslyckas kommandot och du uppmanas att ange --eval.
• Om du skickar --eval eller --eval-config och ingen utvärdering matchar, misslyckas kommandot.

Alternativet --config tar en fristående fil för optimeringsbegäran. Du kan inte kombinera den med --eval eller --eval-config.

Åsidosätt eller utöka vad utvärderingen ger med dessa flaggor:

• --dataset ersätter utvärderingens datauppsättning. Skicka en lokal JSONL-fil eller en registrerad datauppsättning som name:version.
• --evaluator lägger till en inbyggd eller anpassad utvärderare med namn. Upprepa flagga för att lägga till mer än en. En utvärderare som utvärderingen redan listar läggs inte till två gånger.
• --eval-model anger den modell som bedömer svar. Utan den använder optimeraren den modell som utvärderingens utvärderare deklarerar i sina initieringsparametrar. Om de deklarerar olika modeller hoppar du över --eval-model.

Om projektet inte har någon utvärdering som riktar sig till din agent skickar du datamängden och utvärderarna direkt:

azd ai agent optimize <agent-name> \
  --dataset eval.jsonl \
  --evaluator builtin.task_adherence \
  --eval-model <judge-deployment> \
  --optimize-model <optimization-deployment>

Anpassa utvärderare (avancerat)

Utvärderare bedömer varje agentsvar. Optimeraren stöder två typer:

• Inbyggda utvärderare, till exempel builtin.task_adherence, som poängsätter varje kriterium på aktivitetsnivå som godkänt eller misslyckat.
• Anpassade bedömare för bedömningsmatriser, som bedömer svar utifrån flera kvalitetsdimensioner anpassade för din agent. azd ai eval generate skapar en och laddar ned den som en redigerbar JSON-fil.

För de flesta agenter ger den genererade bedömningsutvärderaren de mest meningsfulla resultaten eftersom den är skräddarsydd för din domän. Redigera den genererade kriteriefilen för att förfina dimensioner och kör azd ai eval evaluator update <name> --from-file <path> sedan för att publicera ändringarna som en ny version. Mer information om hur du genererar, redigerar och versionshanterar utvärderare finns i Generera en datauppsättning och en utvärderare.

Om du vill använda en utvärderare i en körning listar du den i utvärderingen med azd ai eval init --evaluatoreller skickar den med azd ai agent optimize --evaluator <name>. Se Välj utvärderingen i en körning.

Skapa en anpassad datauppsättning (avancerat)

Skapa en anpassad datauppsättning när du behöver exakt kontroll över testscenarier eller har produktionsdata att använda direkt. Den rekommenderade metoden är att iterera ovanpå den datauppsättning som azd ai eval generate producerar. Förfina den till en lokal datauppsättning eller peka på en annan datauppsättning som redan är registrerad i ditt Foundry-projekt.

Välj en datauppsättningskälla

En datauppsättning kan komma från någon av två källor:

• Foundry-datauppsättning: en datauppsättning som redan har registrerats i ditt Foundry-projekt. Skicka med det --dataset <name>:<version>, eller deklarera det i datasets katalogen för din utvärderingskonfiguration med en name och en version. Optimeraren behöver både namnet och versionen.
• Lokal datauppsättning: en JSONL-fil som du skapar och behåller i projektet. Ange dess sökväg med --dataset, eller deklarera den i datasets-katalogen med file. En relativ --dataset sökväg tolkas utifrån den aktuella katalogen. En relativ file sökväg beräknas relativt utvärderingskonfigurationsfilen.

Båda källorna använder samma aktivitetsschema som beskrivs i nästa avsnitt. Om du vill välja en datauppsättning för en körning, se Välj utvärderingen för en körning.

Schema för datauppsättning

En datauppsättning använder JSONL-format (JSON Lines). Varje rad är ett JSON-objekt som representerar en enda utvärderingsaktivitet – ett enskilt scenario. En uppgift har en fråga (query) och, om du vill, uppgiftsnivå criteria.

{"name": "task_1", "query": "Your prompt here"}
{"name": "task_2", "query": "Another prompt", "ground_truth": "Expected answer"}

När du använder en lokal datauppsättning validerar du JSONL-syntaxen innan du kör optimering:

python -c "import json; [json.loads(l) for l in open('eval.jsonl')]"

Lägg till kriterier på uppgiftsnivå

Villkor är valfria. Utvärderarna som du väljer för körningen gäller för varje uppgift i datamängden. Lägg till criteria per uppgift endast när en specifik uppgift behöver kontroller utöver de gemensamma evaluatorerna. När de finns poängsätts en uppgifts criteria och aggregeras tillsammans med de delade utvärderarna för att skapa uppgiftens övergripande poäng.

Följande datauppsättning för kundsupport visar uppgifter med kriterier på uppgiftsnivå:

{"name": "refund_policy", "query": "What is your refund policy?", "criteria": [{"name": "mentions_30_days", "instruction": "Response must mention the 30-day refund window"}, {"name": "polite_tone", "instruction": "Response must be professional and empathetic"}]}
{"name": "order_status", "query": "Where is my order #12345?", "criteria": [{"name": "asks_for_details", "instruction": "Agent should ask for email or order details to look up the order"}, {"name": "no_hallucination", "instruction": "Agent must NOT make up a fake order status"}]}
{"name": "out_of_scope", "query": "Can you help me fix my car?", "criteria": [{"name": "polite_decline", "instruction": "Agent should politely explain this is outside its scope"}, {"name": "redirect", "instruction": "Agent should suggest contacting an appropriate service"}]}

Registrera och versionshantera en datauppsättning med CLI

Installera det separat utgivna datamängdstillägget för återanvändbara datamängder utöver en optimerarkörning:

azd ext install azure.ai.dataset
azd ai project set <project-endpoint>
azd ai dataset create support-golden --from-file ./support-golden.jsonl

--from-file tar emot en JSONL-fil eller en katalog som innehåller en. Använd --version för att välja en version explicit. Annars publicerar kommandot nästa version. Håll den version som används för en utvärdering oförändrad när du jämför agentändringar.

Publicera reviderade data och granska versionerna:

azd ai dataset update support-golden --from-file ./support-golden-v2.jsonl
azd ai dataset list --all
azd ai dataset show support-golden
azd ai dataset versions list support-golden

list returnerar 20 poster som standard. Använd --limit för en mindre sida, --all för alla sidor och upprepa --tag key=value för att kräva flera taggmatchningar.

Ladda ned en registrerad version för att återskapa en körningsexekvering:

azd ai dataset download support-golden --version 1.0 \
  --output-dir ./downloaded-dataset

Använd --output-file endast för en datauppsättning med en fil. Befintliga filer skrivs inte över om du inte skickar --force. Om du utelämnar --version hämtas den senaste versionen och det rapporteras vilken version som har valts.

Om du vill ta bort en version kör du azd ai dataset delete support-golden --version <version>. Flaggan --version krävs. Om du utelämnar den returneras ett fel. Icke-interaktiv borttagning kräver uttrycklig --force.

Gruppen azd ai eval dataset exponerar samma livscykel via utvärderingstillägget. Att registrera data gör inte alla JSONL-scheman utbytbara: behåll den radstruktur som krävs av utvärderaren och mål.

Råd för att skriva bra datauppsättningar

Inkludera gränsfall

Testa bortom den lyckliga vägen. Inkluderar:

• Förfrågningar utanför omfånget – Indata som din agent bör avvisa eller omdirigera
• Tvetydiga frågor – Uppgifter där agenten bör be om förtydligande
• Kontradiktoriska indata – Försök att lura agenten till dåligt beteende
• Uppgifter i flera steg – Komplexa begäranden som kräver strukturerade resonemang

Riktlinjer för storlek

Större datamängder ger bredare täckning men tar längre tid att utvärdera.

Ange grund sanning när det är användbart

Fältet ground_truth ger utvärderarna ett referenssvar att jämföra med. Det krävs inte – utvärderare kan också bedöma svar utifrån sina instruktioner och eventuella uppgiftsspecifika kriterier.

{"name": "geography_fact", "query": "What is the largest city in France by population?", "ground_truth": "Paris", "criteria": [{"name": "correct_answer", "instruction": "Response must state that Paris is the largest city in France by population"}]}

Skriv promptar som om du vore en riktig användare

Använd faktiska meddelanden från dina användare om möjligt. Faktiska promptar fångar upp det ordval och den kontext som agenten möter i produktion, vilket också hjälper dig att skriva realistiska kriterier på uppgiftsnivå.

Var specifik i kriterier

Vaga kriterier leder till inkonsekvent bedömning. Gör varje kriterium specifikt och testbart.

Dålig:

{"name": "good_answer", "instruction": "The response should be good"}

Bra:

{"name": "mentions_30_days", "instruction": "Response must explicitly mention the 30-day refund window"}

Troubleshooting

Relaterat innehåll

• Översikt över agentoptimerare
• Gör din agent redo för optimering
• Optimera agentinstruktioner, färdigheter, verktyg och modeller
• Snabbstart: Optimera en värdbaserad agent
• Köra agentutvärderingar med azd CLI