Rychlý start: Optimalizace hostovaného agenta (Preview)

Important

Optimalizátor agentů je aktuálně ve verzi 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.

V tomto rychlém startu nasadíte ukázkového agenta optimalizace, spustíte optimalizátor agenta, abyste zlepšili jeho pokyny, a nasadíte vítězného kandidáta.

Informace o konceptech jednotlivých kroků a úplné ucelené cestě najdete v pracovním postupu optimalizace.

Předpoklady

Než začnete, potřebujete:

  • azd CLI (Azure Developer CLI).

  • Azure CLI pro ověřování.

  • Rozšíření microsoft.foundry pro azd (verze 0.1.40-preview nebo novější závislosti azure.ai.agents):

    azd ext install microsoft.foundry

    Pokud už je nainstalovaná, upgradujte:

    azd ext upgrade microsoft.foundry

  • Azure CLI pro ověřování.

  • Python 3.10 nebo novější.

  • Balíčky Python použité v této cestě:

    pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

  • Existující projekt Foundry, který již obsahuje hostovaného agenta, zaregistrovanou datovou sadu a vyhodnocovače, který chcete použít k optimalizaci.

  • Vaše Azure předplatné musí být v seznamu povolených pro optimalizátor agenta. Pokud chcete požádat o přístup, obraťte se na svého zástupce Microsoft.

Poznámka:

Optimalizátor agentů je aktuálně ve verzi Preview.

Krok 1: Vytvoření projektu

Inicializace nového projektu z ukázkové šablony optimalizace:

mkdir my-agent && cd my-agent
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/optimization-customer-support/azure.yaml .

Interaktivní průvodce vás vyzve k zadání předplatného Azure, oblasti a nastavení nasazení modelu. Používá azure.yaml pro konfiguraci hostovaného agenta a generuje .agent_configs/baseline/, vyhodnocovací datovou sadu a soubory infrastruktury.

Tip

Pokud už máte existující projekt agenta, přečtěte si téma Příprava optimalizátoru agenta na přidání podpory optimalizace.

Pokud už máte projekt Foundry, přidejte -p <project-resource-id> a zaměřte se na existující prostředky.

Krok 2: Zřízení a nasazení

Ověřte a zřiďte prostředky Azure:

az login
azd auth login
azd provision

Zřizování trvá přibližně dvě minuty a vytvoří se účet Foundry, projekt, Azure Container Registry a nasazení modelu.

Nasazení agenta:

azd deploy

Otestujte nasazení:

azd ai agent invoke "What is 2+2?"

Krok 3: Vygenerování zkušební sady a optimalizace

Vygenerujte vyhodnocovací datovou sadu a vyhodnocovače pro vašeho agenta:

azd ai agent eval generate

Tento krok vytvoří eval.yaml, testovací datovou sadu a hodnotitele pro skórování na základě pokynů vašeho agenta. Optimalizátor tyto soubory používá k měření zlepšení.

Spusťte optimalizátor:

azd ai agent optimize --max-candidates 2

Rozhraní příkazového řádku vás vyzve k výběru modelu optimalizace. Pokud chcete tuto výzvu přeskočit, předejte ji přímo:

azd ai agent optimize --max-candidates 2 --optimize-model gpt-5

CLI rozpozná vašeho agenta z azure.yaml a automaticky použije vygenerované eval.yaml. S dvěma kandidáty se optimalizace obvykle dokončí přibližně za 8 minut. Zobrazuje se průběh v reálném čase:

Optimizing agent "customer-support-py"...
  Config: eval.yaml
  Baseline saved to .agent_configs/baseline/metadata.yaml
  Job ID: opt_162bd0f09....
  Status: pending
  Portal: <OPTIMIZATION-JOB-URL>

Pomocí adresy URL portálu můžete monitorovat úlohu na portálu Foundry.

Vyhodnocovací model vyhodnocuje každou odpověď (lze použít jakýkoli model pro dokončování chatu). Model optimalizace (--optimize-model) generuje vylepšené kandidáty a musí být z podporovaného seznamu (rodina gpt-5 nebo DeepSeek). Můžete také nastavit optimization_model pod options: v eval.yaml, abyste nemuseli pokaždé předávat příznak.

Krok 4: Nasazení vítěze

Hvězdička (*) ve výstupu označuje nejlepšího kandidáta. Použijte optimalizovanou konfiguraci místně a pak nasaďte:

azd ai agent optimize apply --candidate <candidate-id>
azd deploy

Příkaz apply stáhne optimalizovanou konfiguraci do .agent_configs/<candidate_id>/ a aktualizuje azure.yaml, aby používal nové instrukce. Příkaz deploy nasadí optimalizovaného agenta do produkce pomocí nástroje pro nasazení kódu.

Vyvolejte agenta a ověřte vylepšení:

azd ai agent invoke "What is your return policy?"

Můžete také spustit vyhodnocení, abyste potvrdili zlepšení skóre:

azd ai agent eval run

cesta sady Python SDK

Následující postup použijte, pokud chcete spustit optimalizátor z Python místo pracovního postupu rozhraní příkazového řádku pro vývojáře Azure popsaného výše.

Tato cesta předpokládá, že již máte v existujícím projektu Foundry následující zdroje:

  • Hostovaný agent pro optimalizaci.
  • Registrovaná trénovací datová sada.
  • Registrovaný hodnotitel.

Na rozdíl od postupu Azure Developer CLI popsaného dříve cesta Python SDK za vás nevytvoří kostru projektu ani nevygeneruje eval.yaml, datovou sadu ani evaluátory. Pokud chcete, aby ukázka vytvořila tyto prostředky automaticky, použijte azd ai agent eval generate nejprve.

1. Vytvoření .env souboru

Vytvořte pracovní složku a pak přidejte .env soubor s těmito hodnotami:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_AGENT_NAME=<your-hosted-agent-name>
DATASET_NAME=<your-registered-dataset-name>
EVALUATOR_NAME=<your-registered-evaluator-name>
DATASET_VERSION=1
POLL_INTERVAL_SECONDS=10
EVAL_MODEL=<your-eval-model-deployment-name>
OPTIMIZATION_MODEL=<your-optimization-model-deployment-name>

Spusťte skript z této pracovní složky, aby load_dotenv() mohl soubor .env automaticky načíst. Pokud ho chcete spustit z jiného adresáře, nejprve nastavte stejné hodnoty v prostředí prostředí.

Použijte přesný koncový bod projektu ze stránky Přehled projektu Foundry. Skript Python odešle svůj první požadavek okamžitě. Pokud FOUNDRY_PROJECT_ENDPOINT je pouze zástupný symbol nebo odkazuje na nesprávný projekt, spuštění selže s ResourceNotFound: The project does not exist.

Nastavte EVAL_MODEL a OPTIMIZATION_MODEL na názvy nasazení, které už existují ve vašem projektu Foundry, nejen na názvy rodin modelů. Pokud je například vaše nasazení projektu pojmenováno gpt-4.1-mini nebo DeepSeek-V3.2, použijte tento přesný název nasazení v souboru .env.

2. Spusťte úlohu optimalizace.

Vytvořte soubor s názvem optimize_hosted_agent.py ve stejné složce jako .env:

import os
import time

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
  JobStatus,
  OptimizationAgentIdentifier,
  OptimizationEvaluatorRef,
  OptimizationJob,
  OptimizationJobInputs,
  OptimizationOptions,
  OptimizationReferenceDatasetInput,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
dataset_name = os.environ["DATASET_NAME"]
evaluator_name = os.environ["EVALUATOR_NAME"]
dataset_version = os.environ.get("DATASET_VERSION", "1")
poll_interval = int(os.environ.get("POLL_INTERVAL_SECONDS", "10"))
eval_model = os.environ.get("EVAL_MODEL", "gpt-4o")
optimization_model = os.environ.get("OPTIMIZATION_MODEL", "gpt-5")

terminal_statuses = {JobStatus.SUCCEEDED, JobStatus.FAILED, JobStatus.CANCELLED}

with (
  DefaultAzureCredential() as credential,
  AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
  job = project_client.beta.agents.create_optimization_job(
    job=OptimizationJob(
      inputs=OptimizationJobInputs(
        agent=OptimizationAgentIdentifier(agent_name=agent_name),
        train_dataset=OptimizationReferenceDatasetInput(
          name=dataset_name,
          version=dataset_version,
        ),
        evaluators=[OptimizationEvaluatorRef(name=evaluator_name)],
        options=OptimizationOptions(
          max_candidates=2,
          eval_model=eval_model,
          optimization_model=optimization_model,
        ),
      )
    )
  )

  print(f"Created optimization job: {job.id}")
  print(f"Initial status: {job.status}")

  while job.status not in terminal_statuses:
    time.sleep(poll_interval)
    job = project_client.beta.agents.get_optimization_job(job_id=job.id)
    print(f"Status: {job.status}")

  if job.status == JobStatus.FAILED:
    message = job.error.message if job.error else "<no error message>"
    raise RuntimeError(f"Optimization job failed: {message}")

  if job.result:
    print(f"Baseline candidate: {job.result.baseline}")
    print(f"Best candidate: {job.result.best}")

    for candidate in job.result.candidates or []:
      print(
        f"{candidate.name}: candidate_id={candidate.candidate_id}, "
        f"avg_score={candidate.avg_score:.4f}, "
        f"avg_tokens={candidate.avg_tokens:.0f}"
      )

Spusťte skript:

python optimize_hosted_agent.py

Když se úloha podaří, skript vytiskne vítězného kandidáta a jeho candidate_id.

Na rozdíl od azd ai agent optimize proces v sadě Python SDK nevytváří místní soubor .agent_configs/baseline/metadata.yaml. Metadata úlohy optimalizace zůstávají ve vráceném job objektu a v odpovědi služby Foundry, včetně seznamu kandidátů podle směrného plánu, nejlepšího kandidáta a seznamu vyhodnocených kandidátů.

3. Použít vítězného kandidáta

Pokud také pracujete v místním azd projektu použitém ve výše uvedeném postupu v CLI, použijte vítězný kandidát pomocí hodnoty candidate_id, kterou vrátil skript Python:

azd ai agent optimize apply --candidate <candidate-id>
azd deploy

Pokud potřebujete zkontrolovat pouze výsledek, použijte kandidátské skóre a identifikátory vyhodnocení vytištěné skriptem a zkontrolujte vítěznou konfiguraci v Foundry předtím, než ho propagujete.

Vyčistěte zdroje

Pokud jste použili předchozí pracovní postup rozhraní příkazového řádku pro vývojáře Azure, odstraňte zřízené prostředky po dokončení experimentování:

azd down --force --purge

Tip

Proč --purge? Ve výchozím nastavení účty Foundry používají odstranění s možností obnovení. Bez --purge zůstane název prostředku rezervován po dobu 48 hodin a opětovné zřízení prostředku se stejným názvem selže.

Řešení problémů

Problém Příčina Opravit
Příkaz azd ai agent optimize se nenašel Rozšíření je příliš staré Spuštěním azd ext upgrade microsoft.foundry získáte verzi 0.1.40-preview nebo novější.
optimization_model is required Spuštění v neinteraktivním režimu bez nakonfigurovaného modelu Přidejte --optimize-model gpt-5 do příkazu nebo nastavte položku optimization_model: gpt-5 v části options: v eval.yaml. V interaktivním režimu se rozhraní příkazového řádku vyzve k výběru modelu.
Skript v Pythonu selže kvůli KeyError: 'DATASET_NAME' nebo jiné chybějící proměnné Skript nenačetl váš .env soubor nebo chybí proměnná. Spusťte skript ze stejné složky jako .env, nebo před spuštěním python optimize_hosted_agent.py exportujte v shellu požadované hodnoty.
Python skript selže s chybouResourceNotFound: The project does not exist FOUNDRY_PROJECT_ENDPOINT neodkazuje na existující projekt Foundry. Zkopírujte koncový bod projektu ze stránky Přehled projektu Foundry a aktualizujte FOUNDRY_PROJECT_ENDPOINT v .env.
Python skript selže s chybouOptimization model deployment '<name>' not found OPTIMIZATION_MODEL není název nasazeného modelu v projektu Foundry. Použijte přesný název nasazení z Sestavení>Nasazení, například existující řadu gpt-5 nebo nasazení DeepSeek ve vašem projektu.
Skóre optimalizace je 0 nebo velmi nízké Vyhodnocení obsahuje mnoho chybných řádků. Ve výsledcích otevřete odkaz Eval . Opravte chyby generování nebo vyhodnocovače odpovědí a pak je spusťte znovu.
azd provision selže kvůli chybě kvóty Předplatné nemá dostatečnou kapacitu Zkuste jinou oblast nebo požádejte o navýšení kvóty.

Co jste se naučili

V tomto rychlém průvodci vám:

  • Nasadili jsme ukázkového agenta optimalizace pomocí šablony zákaznické podpory.
  • Spuštěním optimalizátoru agenta automaticky vylepšíte pokyny agenta.
  • Nasadili vítězného kandidáta a ověřili vylepšení.

Další kroky

  • Last updated on