Spuštění vyhodnocení agenta pomocí rozhraní příkazového řádku azd (Preview)

Important

Položky označené (Preview) v tomto článku jsou aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Pomocí prostředí pro vyhodnocování v Azure Developer CLI (azd) můžete k agentovi vytvořenému pomocí Microsoft Foundry přidat cyklus měření kvality. Tento článek se zaměřuje na životní cyklus hostovaného agenta, ve azdkterém vytvoříte, zřídíte, nasadíte, inicializujete vyhodnocovací prostředky, spustíte první vyhodnocení, zkontrolujete spuštění a znovu použijete recept na vyhodnocení pro pozdější spuštění.

Agenty založené na promptech lze také vyhodnotit, když jsou v projektu Foundry k dispozici jako cíloví agenti. Kroky nasazení hostovaného agenta se vztahují pouze na hostované agenty.

Tento článek popisuje, jak spustit první vyhodnocení agenta s azd ai agent eval generate a azd ai agent eval run.

Předpoklady

  • Předplatné Azure s přístupem k Microsoft Foundry.
  • Azure Developer CLI (azd). Pokyny k instalaci najdete v tématu Instalace rozhraní příkazového řádku pro vývojáře Azure.
  • Rozšíření azd ai agent , verze 0.1.40-preview nebo novější, nainstalované (azd ext install azure.ai.agents). Pokud rozšíření nemáte nainstalované, při inicializaci úvodní šablony nebo spuštění rozšíření se nainstaluje azd ai agent automaticky. Spuštěním azd ext list ověřte nainstalovanou verzi a spusťte azd ext upgrade azure.ai.agents ji, pokud potřebujete upgradovat. Další informace o rozšíření agenta AI azd najdete v článku Rozšíření agenta Microsoft Foundry.
  • Autentizovaná azd relace. Pokud chcete zkontrolovat stav ověřování, spusťte azd auth statuspříkaz . Pokud nejste přihlášení, spusťte azd auth loginpříkaz .
  • Role Foundry User u prostředku Foundry (dříve s názvem Azure AI User). Další informace naleznete v tématu Řízení přístupu na základě rolí pro Microsoft Foundry.
  • Pro hostované agenty: Není vyžadován žádný existující projekt Foundry. azd ai agent init a azd provision vytvoří potřebné zdroje.
  • Pro agenty založené na promptech: Existující projekt Foundry s agentem, který je již nasazený a dostupný jako cíl pro vyhodnocení.
  • Nasazení modelu, které podporuje dokončení chatu ve stejném projektu Foundry.
  • Volitelné: Datová sada vyhodnocení JSONL se reprezentativními příklady, pokud nechcete eval generate generovat kouřovou datovou sadu.

Jak fungují vyhodnocení agenta AZD

Primární prostředí pro vyhodnocení rozhraní příkazového řádku azd je navržené pro životní cyklus hostovaného agenta:

azd ai agent init
azd provision
azd deploy
azd ai agent eval generate
azd ai agent eval run
azd ai agent eval update
# Optional, after the agent and eval recipe meet optimization prerequisites:
azd ai agent optimize

Tok vyhodnocení zahrnuje následující artefakty a příkazy.

Item Description
eval generate Vytvoří nebo opraví místní prostředky pro vyhodnocení pro cíl agenta.
eval.yaml Lokálně spustitelný postup vyhodnocení. Zaznamenává cíl agenta, odkaz na datovou sadu, odkazy na vyhodnocovače a možnosti generování.
Vygenerované místní artefakty Upravitelné místní kopie vygenerovaných datových sad a vyhodnocovacích rubrik. Artefakty jsou uloženy pod datasets/ a evaluators/ ve složce agenta (například src/<agent-name>/datasets/ a src/<agent-name>/evaluators/).
Registrované artefakty služby Verze datové sady Foundry a evaluátoru používané při spuštěních vyhodnocení. Toto jsou jediný spolehlivý zdroj pro generované assety.
eval run Spustí vyhodnocovací proceduru vůči vybranému cíli agenta.
eval update Zaregistruje nové verze služby z lokální datové sady nebo z úprav evaluátoru a po potvrzení aktualizuje eval.yaml.
eval list a eval show Zkontrolujte běhy vyhodnocení a výsledky pomocí rozhraní příkazového řádku.
optimize --config eval.yaml Volitelně lze spustit optimalizaci z vyhodnocovacího receptu poté, co agent a recept splní předpoklady pro optimalizaci.

azd provision nevytvoří vyhodnocovací datové sady, vyhodnocovače, sady ani úlohy optimalizace. Nastavení vyhodnocení může zahrnovat generování, které může trvat i několik minut, proto je ponecháno jako explicitní a opakovatelné.

U hostovaných agentů první vyhodnocení vyžaduje, aby byl cíl agenta nasazen a bylo ho možné vyvolat. U agentů založených na promptech se krok nasazení nepoužívá; agent už musí existovat v projektu Foundry a být k dispozici jako cíl pro vyhodnocení.

Vytvoření a nasazení hostovaného agenta

Pokud ještě nemáte projekt hostovaného agenta, inicializujte ho pomocí azd:

azd ai agent init

Zřiďte prostředky Foundry a nasaďte agenta:

azd provision
azd deploy

Po dokončení nasazení ověřte, že lze agenta vyvolat:

azd ai agent show

Hostovaný agent musí být nasazený a vyvolán před inicializací zkušebních prostředků.

Po úspěšném nasazení rozhraní příkazového řádku navrhne vyhodnocení jako explicitní další krok:

Set up an evaluation suite to measure quality and impact in one step with `azd ai agent eval generate`

Pokud chcete vyhodnotit agenta na základě výzvy, přeskočte příkazy pro vytvoření a nasazení hostovaného agenta. Pokračujte k další části poté, co potvrdíte, že agent založený na promptu existuje v projektu Foundry a je k dispozici jako cíl pro vyhodnocení.

Note

Vyhodnocování založené na cíli přímo spouští vašeho hostovaného agenta. Funguje s agenty, kteří používají protokol odpovědí nebo vyvolání s synchronním spouštěním bez streamování. Pokud chcete vyhodnotit agenty, kteří používají protokol A2A nebo protokol Activity, případně jiné vzorce provádění, například dlouhotrvající běhy nebo streamování, vyhodnocujte místo toho trasovací záznamy, které váš agent generuje. Viz vyhodnocení trasování.

Inicializovat prostředky pro vyhodnocení

Spusťte eval generate z pracovního prostoru azd nebo ze složky projektu agenta:

azd ai agent eval generate

Bez příznaků příkaz spustí interaktivního průvodce. Průvodce z prostředí azd rozpozná cíl agenta a poté požádá o instrukci pro generování, aby služba mohla vytvořit užitečná počáteční hodnoticí data a hodnoticí rubriku.

Příklad interaktivního výstupu:

? Eval suite name: reservation-agent
? How would you like to provide the agent instruction?: Type inline
? Describe what this agent does and what scenarios to test: This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement.
? Include agent traces for evaluator generation?: No
? Select the model for evaluation and generation: gpt-4o (deployed)
? Max samples (between 15 and 1000): 100
  (–) Running  Evaluator generation  (evaluatorgen-reservation-agent-v3-abc12345)
  (–) Running  Dataset generation  (datagen-abc123456)
  (✓) Done  Evaluator generation  (20 seconds)
  (✓) Done  Dataset generation  (2m 9s)

Eval suite created
  Config:     src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  Evaluator dimensions (4):
    Weight  Dimension
    ──────  ─────────
        10  booking_accuracy
         5  policy_enforcement
         6  cancellation_handling
         5  general_quality

  Portal:
    Dataset:   https://ai.azure.com/.../build/data/datasets/reservation-agent-dev-eval-seed/1.0
    Evaluator: https://ai.azure.com/.../build/evaluations/catalog/reservation-agent-quality/1

  Next steps:
    azd ai agent eval run
      Run the eval suite against your agent.
    azd ai agent eval update
      Edit the generated dataset or evaluator locally, then upload changes.

Pro skriptované použití předejte vstupy generování přímo:

azd ai agent eval generate \
  --gen-instruction "This agent handles restaurant reservations. Test booking, modification, cancellation, and policy enforcement." \
  --eval-model gpt-4o \
  --max-samples 100

--out-file je volitelný a výchozí hodnota je eval.yaml v kořenovém adresáři projektu agenta. Použijte --out-file <path> k zapsání konfigurace na jiné místo.

Použití existující datové sady a vybraných vyhodnocovačů:

azd ai agent eval generate \
  --dataset ./tests/support-golden.jsonl \
  --gen-instruction "Support quality, policy adherence, and escalation behavior" \
  --max-samples 50 \
  --evaluator builtin.intent_resolution \
  --evaluator support-quality \
  --out-file eval.yaml

Nahraďte ./tests/support-golden.jsonl cestou k vlastní evaluační datové sadě.

Hodnota --dataset může odkazovat na místní soubor nebo název registrované datové sady. Opakujte, --evaluator pokud chcete zahrnout více předdefinovaných nebo registrovaných vlastních vyhodnocovačů. Odkazy vyhodnocovače používají formát <source>.<name>:

Odložit generování pomocí --no-wait

Pokud generování datové sady nebo vyhodnocovače trvá příliš dlouho, použijte --no-wait k odeslání úloh generování a okamžité ukončení:

azd ai agent eval generate \
  --gen-instruction "..." \
  --no-wait

ID čekajících operací se zapisují do eval.yaml. Po pozdějším spuštění azd ai agent eval runse tyto operace před spuštěním vyhodnocení automaticky obnoví.

Použijte cíl agenta založeného na promptech

Pokud jste inicializovali vyhodnocovací prostředky pro agenta založeného na výzvě, můžete použít stejný postup vyhodnocení receptu. Krok nasazení hostovaného agenta není nutný pro agenty založené na výzev.

Před spuštěním vyhodnocení ověřte, že:

  • Agent založený na promptech je součástí projektu Foundry.
  • Agent je k dispozici jako cíl vyhodnocení.
  • Máte přístup ke koncovému bodu projektu a cíli agenta.
  • eval.yaml vybere zamýšleného agenta založeného na příkazovém řádku.

Pokud chcete zobrazit seznam agentů dostupných v aktuálním projektu Foundry, spusťte:

azd ai agent list

Pak ke spuštění a kontrole vyhodnocení použijte stejné příkazy:

azd ai agent eval run --config eval.yaml
azd ai agent eval show

Zkontrolujte eval.yaml

Jakmile eval generate proběhne úspěšně, otevřete eval.yaml v kořenovém adresáři projektu agenta. Příklad:

src/reservation-agent/eval.yaml

Spusťte eval run z tohoto adresáře nebo předejte cestu explicitně pomocí --config src/reservation-agent/eval.yamlpříkazu . Soubor identifikuje cíl agenta, odkaz na datovou sadu, odkazy na vyhodnocovače a možnosti generování. Zjednodušený obrazec je:

name: reservation-agent
agent:
  name: reservation-agent
  kind: hosted
  version: "3"
  config: .agent_configs\baseline\metadata.yaml
dataset_reference:
  name: reservation-agent-dev-eval-seed
  version: "1.0"
  local_uri: datasets\reservation-agent-dev-eval-seed
evaluators:
  - builtin.task_adherence
  - name: reservation-agent-quality
    version: "1"
    local_uri: evaluators\reservation-agent-quality\rubric_dimensions.json
options:
  eval_model: gpt-4o
max_samples: 100
  • eval.yaml žije v kořenovém adresáři projektu agenta, například src/<agent-name>/eval.yaml.
  • Vygenerované datové sady se ve složce agenta nacházejí v datasets/ a vygenerované hodnoticí rubriky evaluátoru v evaluators/.
  • local_uri cesty v eval.yaml jsou relativní vůči adresáři projektu agenta.
  • Místní soubory, na které local_uri odkazuje, se dají upravovat. Spusťte azd ai agent eval update, chcete-li zaregistrovat místní změny jako novou verzi ve službě a navýšit verzi v eval.yaml.
  • eval run používá zaregistrovanou verzi připnutou v eval.yamlsouboru . Chcete-li použít místní úpravy, spusťte eval update před eval run.
  • Vyhodnocovače mohou být integrované reference (například builtin.task_adherence) nebo vlastní vyhodnocovače vygenerované pomocí name, version a local_uri.
  • Zacházejte s poli verze jako s řetězci, i když vypadají číselně, takže recept zůstává stabilní napříč analyzátory YAML.

Spuštění vyhodnocení

Ve složce projektu agenta spusťte:

azd ai agent eval run

Ve výchozím nastavení eval run bez argumentů odkazuje na eval.yaml v kořenovém adresáři projektu agenta. Můžete také explicitně předat cestu konfigurace:

azd ai agent eval run --config eval.yaml

Pokud eval generate --no-wait vytvořil nevyřízené operace generování, eval run tyto operace obnoví před zahájením vyhodnocovacího běhu. Nespouští nové úlohy generování datové sady ani vyhodnocovače od nuly.

Zkontrolovat běhy vyhodnocení

Vypište nedávné běhy vyhodnocení:

azd ai agent eval list

Zobrazit nejnovější běh:

azd ai agent eval show

Bez příznaků eval show se ve výchozím nastavení zobrazí nejnovější vyhodnocení a zobrazí se seznam jeho spuštění.

Chcete-li zobrazit podrobnosti o konkrétním spuštění, předejte jako argument ID vyhodnocení a ID spuštění pomocí --eval-run-id. Zkopírujte ID eval z výstupu azd ai agent eval list a ID spuštění z výstupu azd ai agent eval show <eval-id>:

azd ai agent eval show <eval-id> --eval-run-id <run-id>

Použijte výstup běhu k odpovědi:

  • Jaká verze agenta byla vyhodnocena.
  • Které verze datové sady a vyhodnocovače byly vyřešeny.
  • Zda byl běh dokončen, selhal nebo byl dokončen pouze částečně.
  • Které metriky nebo skóre vyhodnocovače byly vytvořeny.
  • Jestli protokoly využití tokenů nebo vyhodnocovače potřebují šetření.

Opětovné spuštění po změně agenta

Po aktualizaci a opětovném nasazení hostovaného agenta spusťte stejný zkušební recept znovu:

azd deploy
azd ai agent eval run --config eval.yaml

U agentů založených na promptech aktualizujte agenta ve Foundry a poté znovu spusťte stejný postup vyhodnocení.

Opětovné spuštění stejného eval.yaml pomáhá udržovat datové sady, vyhodnocovače a prahové odkazy stabilní napříč změnami agenta.

Aktualizace, resetování nebo oprava zkušebních prostředků

Tok vyhodnocení agenta používá eval.yaml jako místní recept pro vyhodnocení. Používá se azd ai agent eval update při úpravách místních souborů datových sad nebo vyhodnocovacích rubrik a chcete tyto úpravy zaregistrovat jako nové verze služby.

Pokud chcete aktualizovat, co zkušební běh používá, zvolte cestu, která odpovídá typu změny:

Change Postup aktualizace
Změna prahových hodnot, odkazů na vyhodnocovače, nastavení výstupu nebo jiných polí receptu Upravit eval.yamla pak spustit azd ai agent eval run --config eval.yaml.
Použití jiné místní nebo registrované datové sady Upravte odkaz na datovou sadu v eval.yaml, nebo znovu spusťte azd ai agent eval generate --dataset <path-or-name> --out-file eval.yaml.
Přidat nebo změnit odkazy na vyhodnocení Upravit eval.yamlnebo spustit azd ai agent eval generate znovu s opakovatelnými --evaluator hodnotami
Zaregistrujte místní úpravy ve vygenerované datové sadě nebo hodnoticí rubrice evaluátoru Spusťte azd ai agent eval update, zkontrolujte zjištěné změny a potvrďte aktualizaci odkazu na referenci verze v eval.yaml.
Začněte znovu od výchozího vygenerovaného nastavení Spusťte azd ai agent eval generate --reset-defaults.

Například po úpravě vygenerované vyhodnocovací rubriky evaluators/ ve složce agenta spusťte:

azd ai agent eval update
azd ai agent eval run --config eval.yaml

Příkaz update vytvoří novou registrovanou datovou sadu nebo vyhodnocovací verze. Existující zkušební běhy zůstávají svázané s verzemi, které původně používaly.

Pokud eval.yaml už existuje, eval generate zjistí ji a vytiskne existující konfiguraci:

Eval config already exists: src/reservation-agent/eval.yaml
  Dataset:    reservation-agent-dev-eval-seed (1.0)
              src/reservation-agent/datasets/reservation-agent-dev-eval-seed
  Evaluator:  builtin.task_adherence
  Evaluator:  reservation-agent-quality (1)
              src/reservation-agent/evaluators/reservation-agent-quality/rubric_dimensions.json

  To run the evaluation:
    azd ai agent eval run

  To update local edits as new versions:
    azd ai agent eval update

  To overwrite and regenerate:
    azd ai agent eval generate --reset-defaults

Pokud chcete přepsat místní konfiguraci a znovu vygenerovat výchozí zkušební prostředky, spusťte:

azd ai agent eval generate --reset-defaults

--reset-defaults přepíše místní eval.yaml a znovu vygeneruje výchozí prostředky pro vyhodnocení. Stávající verze datové sady a vyhodnocovače zaregistrované službou se neodstraní; pouze místní recept je nahrazen.

Nespoléhejte na to, že nejnovější vzdálené verze budou bez upozornění měnit místní recipe. Místní eval.yaml zaznamenává verze datové sady, vyhodnocovače nebo sady, které recept používá, kvůli zajištění reprodukovatelnosti.

Volitelné: Spusťte optimalizaci ze zkušebního signálu.

Po úspěšném spuštění aspoň jednoho vyhodnocení můžete jako vstup do optimalizace agenta použít eval.yaml , pokud agent a recept splňují požadavky optimalizace.

Před zahájením optimalizace ověřte, že:

  • Cíl agenta je připraven k optimalizaci. U hostovaných agentů je agent nasazený a lze ho vyvolat.
  • eval.yaml odkazuje na zamýšleného agenta, datovou sadu, verze vyhodnocovače a prahové hodnoty.
  • Alespoň jedno zkušební spuštění bylo úspěšně dokončeno.
  • Příprava agenta vyžadovaná optimalizátorem je dokončená. Požadavky optimalizátoru a požadavky na přípravu agenta najdete v tématu Optimalizace výzvy agenta s využitím Nástroje pro optimalizaci výzvy.

Poté spusťte:

azd ai agent optimize --config eval.yaml

Příkaz optimize čte cíl agenta, datovou sadu, vyhodnocovače a prahové hodnoty z eval.yaml. Odešle optimalizační úlohu, ale automaticky neprovede změny zdrojového kódu ani znovu nenasadí kandidátního agenta. Před použitím změn zkontrolujte veškerý výstup optimalizátoru.

Osvědčené postupy

  • Spusťte azd ai agent eval generate až poté, co je agent dostupný jako cíl pro vyhodnocení. Pro hostované agenty musí být agent nasazen a musí být možné ho spustit.
  • Začněte malou vygenerovanou datovou sadou nebo malou podmnožinou zlaté datové sady.
  • Předtím, než budete skóre důvěřovat, zkontrolujte vygenerovanou datovou sadu a artefakty z kontroly hodnotitelem.
  • Po úpravě vygenerovaných datových sad nebo souborů evaluátoru spusťte azd ai agent eval update, aby se upravené prostředky zaregistrovaly, před opětovným spuštěním vyhodnocení.
  • Správa eval.yaml zdrojového kódu, pokud váš tým chce revidovatelný, reprodukovatelný vzorec hodnocení.
  • Zvažte správu verzí generovaných datových sad a hodnoticích rubrik v části datasets/ a evaluators/ ve složce agenta, pokud je váš tým v rámci postupu hodnocení kontroluje a upravuje.
  • Po změnách agenta znovu spusťte stejný eval.yaml, aby porovnání používala stejný testovací postup.
  • Použijte azd ai agent optimize --config eval.yaml až poté, co máte užitečný výsledek výchozího hodnocení a agent je připraven na optimalizaci.

Omezení

  • Primární tok příkazů je optimalizovaný pro hostované agenty a smyčku vyhodnocení po nasazení.
  • azd provision nevytvoří vyhodnocovací prostředky.
  • eval run negeneruje nové datové sady ani vyhodnocovače, s výjimkou obnovení čekajících operací z eval generate --no-wait.
  • Pro první způsob vyhodnocení nejsou vyžadovány úplný životní cyklus sady, plánované vyhodnocení, průběžné vyhodnocování, výstrahy ani porovnávací pracovní postupy.

Související obsah

  • Last updated on