Een evaluatiedataset en beoordelaars maken

De agentoptimalisator evalueert uw agent aan de hand van een dataset - een verzameling taken - beoordeeld door beoordelaars. U kunt beide automatisch genereren vanuit de CLI of handmatig een gegevensset maken voor volledig beheer.

Beide onderdelen zijn essentieel voor een goede optimalisatie: de gegevensset definieert wat er moet worden getest en de evaluators bepalen hoe elke reactie moet worden beoordeeld. Zwakke evaluators produceren luidruchtige scores die leiden tot slechte optimalisatie, dus investeer in sterke evaluators net zo veel als representatieve taken.

Het maken van deze assets is de tweede stap in de optimalisatiewerkstroom nadat u de optimalisatie van uw agent gereed hebt gemaakt. De optimizer gebruikt deze om uw basislijn te scoren en kandidaten te rangschikken.

Prerequisites

• Een Foundry-project met een geïmplementeerde gehoste agent.
• De Azure Developer CLI (azd), versie 1.37.0 of hoger, waarvoor de azure.ai.agents extensie is vereist.
• De azure.ai.agents CLI-extensie, versie 1.0.0-beta.22 of hoger, is geïnstalleerd (zie Quickstart: Een gehoste agent optimaliseren).
• De azure.ai.evaluations extensie, die de azd ai eval opdrachten biedt en azd 1.33.0 of hoger vereist. De microsoft.foundry extensie bevat deze niet, dus installeer deze afzonderlijk.
• Een geverifieerde azd sessie. Voer azd auth status uit om uw authenticatiestatus te controleren. Als u niet bent aangemeld, voert u het volgende uit azd auth login.

Een gegevensset en evaluators genereren (aanbevolen)

De optimizer gebruikt evaluatieassets die u maakt met de azd ai eval opdrachten uit de azure.ai.evaluations extensie. De azd ai agent eval opdrachtgroep is verouderd. Er worden alleen migratierichtlijnen naar azd ai evalafgedrukt en er worden geen serviceaanvragen ingediend of projectbestanden gewijzigd. De optimizer biedt geen ondersteuning voor het bestand van de verouderde agent eval.yaml.

Genereer een gegevensset en een rubrieksbeoordelaar uit de instructies van uw agent:

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

Met de opdracht wordt standaard het volgende gegenereerd:

• Een gegevensset met rijen voor uw agent.
• Een aangepaste rubriekbeoordelaar, een bewerkbaar JSON-bestand met gewogen scoredimensies.

De opdracht downloadt beide artefacten en voegt een catalogusvermelding voor elk toe aan de evaluatieconfiguratie, die standaard evals/azure.eval.yaml is. Tenzij u <deployed-agent>-turn-tests of --dataset-name instelt, heet de gegevensset --evaluator-name en heet de evaluator <deployed-agent>-evaluator. Zie Een gegevensset en een evaluator genereren voor de interactieve en niet-interactieve opties en details over de gegenereerde artefacten.

Vervolgens zet u een evaluatie op die gebruikmaakt van de gegenereerde assets. De optimizer hergebruikt evaluaties op turn-level die gericht zijn op uw agent, dus stel --evaluation-level turn en --target in. Dit voorbeeld voegt de ingebouwde builtin.task_adherence evaluator toe aan de gegenereerde rubriekevaluator:

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

Voer de optimizer uit en selecteer de evaluatie op naam:

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

Zie Evaluators aanpassen en een aangepaste gegevensset maken om de gegenereerde assets aan te passen. Als u wilt kiezen welke evaluatie een run gebruikt, raadpleegt u De evaluatie voor een run selecteren. Voer voor de andere uitvoeringsopties azd ai agent optimize --help uit.

Selecteer de evaluatie voor een run

azd ai agent optimize leest de gegevensset en evaluators uit een evaluatie die door azd ai eval init is opgegeven. Selecteer de evaluatie met een van de volgende opties:

De optimalisator past deze regels toe:

• Het beschouwt alleen evaluaties die een agent target hebben. De doelnaam moet overeenkomen met de naam van de geïmplementeerde agent of de servicenaam van de agent in azure.yaml.
• Het hergebruikt alleen evaluaties op turn-level die een dataset inlezen. Evaluaties die een source of een simulation declareren, of die het gespreksniveau gebruiken, worden niet ondersteund, en evaluators die dataMapping instellen ook niet.
• Als u geen van beide opties doorgeeft en het project één overeenkomende evaluatie heeft, gebruikt de optimizer deze. Als er meerdere overeenkomsten zijn, wordt u door de optimizer gevraagd om er een te selecteren. Met --no-prompt of -o json mislukt de opdracht en wordt u gevraagd --eval door te geven.
• Als u --eval of --eval-config doorgeeft en geen evaluatie overeenkomt, mislukt de opdracht.

De --config optie accepteert een zelfstandig optimalisatieaanvraagbestand. U kunt het niet combineren met --eval of --eval-config.

Overschrijf of breid uit wat de evaluatie biedt met deze vlaggen:

• --dataset vervangt de gegevensset van de evaluatie. Geef een lokaal JSONL-bestand of een geregistreerde gegevensset door als name:version.
• --evaluator voegt een ingebouwde of aangepaste evaluator toe op basis van naam. Herhaal de flag om meer dan één toe te voegen. Een evaluator die al in de evaluatie staat, wordt niet tweemaal toegevoegd.
• --eval-model stelt het model in waarmee reacties worden beoordeeld. Zonder dit gebruikt de optimizer het model dat de evaluatie-evaluators in hun initialisatieparameters opgeven. Als ze verschillende modellen declareren, sla --eval-model over.

Als het project geen evaluatie heeft die gericht is op uw agent, geeft u de gegevensset en evaluators rechtstreeks door:

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

Evaluators aanpassen (geavanceerd)

Evaluators beoordelen elk antwoord van de agent. De optimizer ondersteunt twee soorten:

• Ingebouwde evaluators, zoals builtin.task_adherence, waarmee elk criterium op taakniveau wordt gescoord als geslaagd of mislukt.
• Aangepaste rubrieken, die reacties beoordelen op verschillende kwaliteitsdimensies die zijn afgestemd op uw agent. Met azd ai eval generate maakt u er een aan en downloadt u het als een bewerkbaar JSON-bestand.

Voor de meeste agents geeft de gegenereerde rubriek-evaluator de meest zinvolle scores omdat deze is afgestemd op uw domein. Bewerk het gegenereerde rubrieksbestand om dimensies te verfijnen en voer vervolgens azd ai eval evaluator update <name> --from-file <path> uit om de wijzigingen als een nieuwe versie te publiceren. Zie Een gegevensset en een evaluator genereren voor meer informatie over het genereren, bewerken en het beheren van versies.

Als u een evaluator in een uitvoering wilt gebruiken, vermeldt u deze in de evaluatie met azd ai eval init --evaluator, of geeft u deze door met azd ai agent optimize --evaluator <name>. Zie De evaluatie voor een run selecteren.

Een aangepaste gegevensset maken (geavanceerd)

Maak een aangepaste gegevensset wanneer u nauwkeurige controle over testscenario's nodig hebt of productiegegevens rechtstreeks wilt gebruiken. De aanbevolen aanpak is om voort te bouwen op de gegevensset die azd ai eval generate produceert. Verwerk deze tot een lokale gegevensset of wijs een andere gegevensset aan die al is geregistreerd in uw Foundry-project.

Een gegevenssetbron kiezen

Een gegevensset kan afkomstig zijn van een van de twee bronnen:

• Foundry-gegevensset: een gegevensset die al is geregistreerd in uw Foundry-project. Geef deze door met --dataset <name>:<version>, of geef deze op in de datasets catalogus van uw evaluatieconfiguratie met een name en een version. De optimizer heeft zowel de naam als de versie nodig.
• Lokale gegevensset: een JSONL-bestand dat u maakt en in uw project bewaart. Geef het pad door met --dataset, of declareer het in de datasets catalogus met file. Een relatief --dataset pad wordt opgelost ten opzichte van de huidige map. Een relatief file pad wordt bepaald ten opzichte van het evaluatieconfiguratiebestand.

Beide bronnen gebruiken hetzelfde taakschema dat in de volgende sectie wordt beschreven. Zie De evaluatie voor een uitvoering selecteren om een gegevensset voor een uitvoering te selecteren.

Gegevenssetschema

Een gegevensset maakt gebruik van de JSONL-indeling (JSON Lines). Elke regel is één JSON-object dat één evaluatietaak vertegenwoordigt: een afzonderlijk scenario. Een taak heeft een prompt (query) en, optioneel, taakniveau criteria.

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

Wanneer u een lokale gegevensset gebruikt, valideert u de JSONL-syntaxis voordat u optimalisatie uitvoert:

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

Criteria op taakniveau toevoegen

Criteria zijn optioneel. De beoordelaars die u selecteert voor de run zijn van toepassing op elke taak in de gegevensset. Voeg criteria alleen per taak toe als een specifieke taak controles nodig heeft die verder gaan dan die van de gedeelde evaluatoren. Wanneer deze aanwezig zijn, worden de criteria van een taak gescoord en samen met de gedeelde evaluatoren geaggregeerd om de totaalscore van de taak te bepalen.

De volgende gegevensset voor klantondersteuning toont taken met criteria op taakniveau:

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

Een gegevensset registreren en versioneren met de CLI

Installeer de afzonderlijk uitgebrachte extensie voor gegevenssets voor herbruikbare gegevenssets voor meer dan één optimizeruitvoering:

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 accepteert een JSONL-bestand of een map die een JSONL-bestand bevat. Gebruik --version om expliciet een versie te kiezen; anders publiceert de opdrachtregel de volgende versie. Behoud de versie die voor een evaluatie wordt gebruikt vast bij het vergelijken van agentwijzigingen.

Herziene gegevens publiceren en de versies controleren:

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 retourneert standaard 20 vermeldingen. Gebruik --limit voor een kleinere pagina, --all voor alle pagina's en herhaal --tag key=value om meerdere tagovereenkomsten te vereisen.

Download een geregistreerde versie om een run te reproduceren:

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

Gebruik --output-file alleen voor een gegevensset met één bestand. Bestaande bestanden worden niet overschreven tenzij u --force opgeeft. Als u --version weglaat, wordt de nieuwste versie gedownload en wordt gemeld welke versie is geselecteerd.

Als u een versie wilt verwijderen, voert u azd ai dataset delete support-golden --version <version> uit. De --version vlag is vereist. Als u deze weglaat, wordt er een fout geretourneerd. Voor niet-interactieve verwijdering is expliciet --forcevereist.

De azd ai eval dataset groep maakt dezelfde levenscyclus beschikbaar via de evaluatie-extensie. Het registreren van gegevens maakt niet elk JSONL-schema uitwisselbaar: behoud de rijshape die vereist is voor uw evaluator en doel.

Tips voor het schrijven van goede gegevenssets

Randgevallen opnemen

Test ook buiten het ideale scenario. Neem op:

• Aanvragen buiten het bereik : invoer die uw agent moet weigeren of omleiden
• Dubbelzinnige query's : taken waarbij de agent om verduidelijking moet vragen
• Adversariële invoer — Pogingen om de agent tot slecht gedrag te verleiden
• Taken met meerdere stappen : complexe aanvragen waarvoor gestructureerde redenering is vereist

Richtlijnen voor grootte

Grotere gegevenssets bieden een bredere dekking, maar het duurt langer om te evalueren.

Geef de grondwaar wanneer nuttig

Het ground_truth veld geeft evaluators een referentieantwoord om mee te vergelijken. Dit is niet vereist: evaluators kunnen ook antwoorden beoordelen op basis van hun instructies en criteria op taakniveau.

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

Schrijfprompts zoals echte gebruikers

Gebruik indien mogelijk werkelijke berichten van uw gebruikers. Echte prompts leggen het vocabulaire en de context vast waarmee uw agent te maken krijgt in productie, waardoor u ook realistische criteria op taakniveau kunt schrijven.

Wees specifiek in criteria

Vage criteria leiden tot inconsistent scoren. Maak elk criterium specifiek en testbaar.

Slechte:

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

Goed:

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

Troubleshooting

Verwante inhoud

• Overzicht van de agent-optimalisator
• Maak je agent klaar voor optimalisatie
• Agentinstructies, vaardigheden, hulpprogramma's en modellen optimaliseren
• Quickstart: Een gehoste agent optimaliseren
• Agentevaluaties uitvoeren met de azd CLI