Utwórz zbiór danych do oceny i ewaluatorów

Optymalizator agenta ocenia agenta względem zestawu danych — kolekcji zadań — ocenianych przez ewaluatorów. Oba te elementy można wygenerować automatycznie za pomocą interfejsu wiersza polecenia lub ręcznie utworzyć zestaw danych w celu uzyskania pełnej kontroli.

Obie części są niezbędne do dobrej optymalizacji: zestaw danych definiuje, co należy przetestować, a ewaluatorzy definiują sposób oceniania poszczególnych odpowiedzi. Słabi ewaluatorzy generują hałaśliwe wyniki, które prowadzą do słabej optymalizacji, więc inwestują w silnych ewaluatorów tak samo jak zadania reprezentatywne.

Tworzenie tych zasobów jest drugim krokiem w procesie optymalizacji, po przygotowaniu agenta do optymalizacji. Optymalizator używa ich do oceniania punktu odniesienia i klasyfikacji kandydatów.

Wymagania wstępne

• Projekt Foundry z wdrożonym hostowanym agentem.
• Azure Developer CLI (azd), wersja 1.37.0 lub nowsza, którego wymaga rozszerzenie azure.ai.agents.
• Rozszerzenie interfejsu wiersza polecenia azure.ai.agents w wersji 1.0.0-beta.22 lub nowszej jest zainstalowane (zobacz Szybki start: Optymalizowanie hostowanego agenta).
• Rozszerzenie azure.ai.evaluations, które udostępnia polecenia azd ai eval i wymaga wersji azd 1.33.0 lub nowszej. Rozszerzenie microsoft.foundry nie zawiera go, dlatego zainstaluj je oddzielnie.
• Uwierzytelniona sesja azd . Aby sprawdzić stan uwierzytelniania, uruchom polecenie azd auth status. Jeśli nie jesteś zalogowany, uruchom azd auth login.

Generowanie zestawu danych i ewaluatorów (zalecane)

Optymalizator ponownie używa zasobów ewaluacyjnych tworzonych za azd ai eval pomocą poleceń z azure.ai.evaluations rozszerzenia. Grupa azd ai agent eval poleceń jest przestarzała. Drukuje tylko wskazówki dotyczące migracji do azd ai eval, i nie wysyła żądań obsługi ani nie zmienia plików projektu. Optymalizator nie obsługuje pliku starszego agenta eval.yaml.

Wygeneruj zestaw danych i ewaluator rubryk na podstawie instrukcji agenta:

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

Domyślnie polecenie generuje:

• Zestaw danych wierszy dla Twojego agenta.
• Niestandardowy moduł oceny według kryteriów, który jest edytowalnym plikiem JSON z ważonymi wymiarami oceniania.

Polecenie zarówno pobiera artefakty, jak i dodaje wpis wykazu dla każdego z nich w konfiguracji oceny, która jest domyślnie ustawiona na evals/azure.eval.yaml. O ile nie ustawisz wartości --dataset-name lub --evaluator-name, zestaw danych ma nazwę <deployed-agent>-turn-tests, a ewaluator ma nazwę <deployed-agent>-evaluator. Informacje o opcjach interaktywnych i nieinteraktywnych oraz szczegółowe informacje o wygenerowanych artefaktach można znaleźć tutaj: Generowanie zestawu danych i ewaluatora.

Następnie przygotuj strukturę oceny, która używa wygenerowanych zasobów. Optymalizator ponownie używa ocen na poziomie turn-level, które są przeznaczone dla agenta, więc ustaw --evaluation-level turn i --target. W tym przykładzie dodano wbudowanego builtin.task_adherence ewaluatora jako wygenerowany ewaluator rubryk:

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

Uruchom optymalizator i wybierz ewaluację według nazwy:

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

Aby dostosować wygenerowane zasoby, zobacz Dostosowywanie ewaluatorów i Tworzenie niestandardowego zestawu danych. Aby wybrać ocenę używaną przez uruchomienie, zobacz Wybieranie oceny dla uruchomienia. W przypadku innych opcji uruchamiania uruchom polecenie azd ai agent optimize --help.

Wybierz ocenę dla uruchomienia

azd ai agent optimize odczytuje zestaw danych i ewaluatorów z oceny, którą azd ai eval init zadeklarowano. Wybierz ocenę, korzystając z jednej z następujących opcji:

Optymalizator stosuje następujące reguły:

• Uwzględnia tylko oceny, które mają agent target. Nazwa docelowa musi być zgodna z nazwą wdrożonego agenta lub nazwą usługi agenta w azure.yaml.
• Używa ponownie tylko ocen na poziomie tury, które odczytują zestaw danych. Oceny, które deklarują element source lub simulation, albo używają poziomu rozmowy, nie są obsługiwane, podobnie jak ewaluatory, które ustawiają dataMapping.
• Jeśli żadna opcja nie zostanie przekazana, a projekt ma jedną zgodną ocenę, optymalizator użyje jej. Jeśli istnieje kilka dopasowań, optymalizator wyświetli monit o wybranie jednego. W przypadku --no-prompt lub -o json polecenie kończy się niepowodzeniem i monituje o przekazanie --eval.
• Jeśli przekażesz --eval lub --eval-config i nie będzie żadnego pasującego wyniku oceny, polecenie zakończy się niepowodzeniem.

Opcja --config przyjmuje samodzielny plik żądania optymalizacji. Nie można połączyć tego z --eval lub --eval-config.

Nadpisać lub rozszerzyć zawartość oceny z następującymi flagami:

• --dataset zastępuje zestaw danych oceny. Przekaż lokalny plik JSONL lub zarejestrowany zestaw danych jako name:version.
• --evaluator Dodaje wbudowany lub niestandardowy ewaluator o nazwie. Powtórz flagę, aby dodać więcej niż jedną. Ewaluator, który jest już wymieniony na liście oceny, nie jest dodawany dwukrotnie.
• --eval-model ustawia model, który ocenia odpowiedzi. Bez niego optymalizator używa modelu, który ewaluatory używane do oceny deklarują w parametrach inicjowania. Jeśli zadeklarują różne modele, przejdź dalej --eval-model.

Jeśli projekt nie ma oceny, która dotyczy Twojego agenta, przekaż zestaw danych i ewaluatorów bezpośrednio:

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

Dostosowywanie ewaluatorów (zaawansowane)

Ewaluatorzy oceniają każdą odpowiedź agenta. Optymalizator obsługuje dwa rodzaje:

• Wbudowane mechanizmy oceny, takie jak builtin.task_adherence, który ocenia każde kryterium dla danego zadania jako zaliczone lub niezaliczone.
• Niestandardowe oceniacze oparte na rubrykach, które oceniają odpowiedzi w wielu aspektach jakości dostosowanych do Twojego agenta. azd ai eval generate tworzy rubrykę i pobiera ją jako edytowalny plik JSON rubryki.

W przypadku większości agentów wygenerowany ewaluator rubryk daje najbardziej znaczące wyniki, ponieważ jest dostosowany do twojej domeny. Edytuj wygenerowany plik rubryki, aby uściślić wymiary, a następnie uruchom polecenie azd ai eval evaluator update <name> --from-file <path>, aby opublikować zmiany jako nową wersję. Aby uzyskać szczegółowe informacje na temat generowania, edytowania i wersjonowania ewaluatorów, zobacz Generowanie zestawu danych i ewaluatora.

Aby użyć ewaluatora w przebiegu, wymień go w ocenie z elementem azd ai eval init --evaluator, lub przekaż go za pomocą azd ai agent optimize --evaluator <name>. Zobacz temat Wybierz ocenę dla uruchomienia.

Tworzenie niestandardowego zestawu danych (zaawansowane)

Utwórz niestandardowy zestaw danych, gdy potrzebujesz dokładnej kontroli nad scenariuszami testowymi lub masz dane produkcyjne do bezpośredniego użycia. Zalecaną metodą jest iteracja na podstawie zestawu danych, który generuje azd ai eval generate. Przekształć go w lokalny zestaw danych lub wskaż inny zestaw danych już zarejestrowany w projekcie Foundry.

Wybieranie źródła zestawu danych

Zestaw danych może pochodzić z jednego z dwóch źródeł:

• Zestaw danych Foundry: zestaw danych już zarejestrowany w projekcie Foundry. Przekaż go za pomocą --dataset <name>:<version>metody lub zadeklaruj go w datasets katalogu konfiguracji oceny za pomocą elementu name i version. Optymalizator potrzebuje zarówno nazwy, jak i wersji.
• Lokalny zestaw danych: plik JSONL utworzony i zachowany w projekcie. Przekaż ścieżkę za pomocą polecenia --dataset lub zadeklaruj ją w katalogu datasets za pomocą polecenia file. Ścieżka względna --dataset jest rozwiązywana względem bieżącego katalogu. Ścieżka względna file jest wyznaczana względem pliku konfiguracji oceny.

Oba źródła używają tego samego schematu zadań opisanego w następnej sekcji. Aby wybrać zestaw danych dla przebiegu, zobacz Wybierz ocenę dla przebiegu.

Schemat zestawu danych

Zestaw danych używa formatu JSONL (JSON Lines). Każdy wiersz jest jednym obiektem JSON reprezentującym pojedyncze zadanie oceny — pojedynczy scenariusz. Zadanie ma monit (query) i, opcjonalnie, poziom criteriazadania .

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

Jeśli używasz lokalnego zestawu danych, przed uruchomieniem optymalizacji zweryfikuj składnię JSONL:

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

Dodawanie kryteriów na poziomie zadania

Kryteria są opcjonalne. Ewaluatorzy wybrani dla przebiegu są stosowani do każdego zadania w zestawie danych. Dodaj criteria dla poszczególnych zadań tylko wtedy, gdy konkretne zadanie wymaga kontroli wykraczających poza te wykonywane przez współdzielonych ewaluatorów. Jeśli są obecne, criteria są oceniane i sumowane wraz ze wspólnymi ewaluatorami, aby uzyskać końcowy wynik zadania.

Poniższy zestaw danych pomocy technicznej dla klientów przedstawia zadania z kryteriami na poziomie zadania:

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

Rejestrowanie zestawu danych i tworzenie jego wersji przy użyciu interfejsu wiersza polecenia

W przypadku zestawów danych wielokrotnego użytku poza jednym uruchomieniem optymalizatora zainstaluj oddzielnie wydane rozszerzenie zestawu danych:

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 akceptuje plik JSONL lub katalog zawierający go. Użyj --version, aby jawnie wybrać wersję. W przeciwnym razie polecenie publikuje następną wersję. Zachowaj wersję używaną do oceny jako stałą podczas porównywania zmian agenta.

Opublikuj poprawione dane i sprawdź wersje:

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 Zwraca domyślnie 20 wpisów. Użyj --limit dla mniejszej liczby stron, --all dla wszystkich stron i powtórz --tag key=value, aby wymagać wielu dopasowań tagów.

Pobierz zarejestrowaną wersję, aby odtworzyć uruchomienie:

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

Użyj --output-file tylko dla zestawu danych z jednym plikiem. Istniejące pliki nie są zastępowane, chyba że przekażesz --force. Pominięcie --version powoduje pobranie najnowszej wersji i zgłoszenie, która wersja została wybrana.

Aby usunąć wersję, uruchom polecenie azd ai dataset delete support-golden --version <version>. Flaga --version jest wymagana; pominięcie jej zwraca błąd. Usuwanie nieinteraktywne wymaga jawnego --force potwierdzenia.

Grupa azd ai eval dataset udostępnia ten sam cykl życia za pośrednictwem rozszerzenia oceny. Rejestrowanie danych nie sprawia, że wszystkie schematy JSONL są zamienne: zachowaj kształt wiersza wymagany przez ewaluatora i cel.

Porady dotyczące pisania dobrych zestawów danych

Uwzględnij przypadki brzegowe

Przetestuj poza szczęśliwą ścieżką. Załącz:

• Żądania poza zakresem — żądania, które agent powinien odrzucać lub przekierowywać
• Zapytania niejednoznaczne — zadania, w których agent powinien poprosić o wyjaśnienie
• Wrogie dane wejściowe — próby nakłonienia agenta do niewłaściwego działania
• Zadania wieloetapowe — złożone żądania wymagające strukturalnych rozumowania

Wytyczne dotyczące rozmiaru

Większe zestawy danych zapewniają szerszy zakres, ale ocena trwa dłużej.

Podaj podstawy prawdy, gdy jest to przydatne

Pole ground_truth daje ewaluatorom odpowiedź referencyjną na porównanie. Nie jest to wymagane — ewaluatorzy mogą również oceniać odpowiedzi na podstawie swoich instrukcji i niezależnie od kryteriów na poziomie zadania.

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

Pisz prompty jak prawdziwi użytkownicy

Jeśli to możliwe, użyj rzeczywistych komunikatów od użytkowników. Rzeczywiste prompty oddają słownictwo i kontekst, z jakimi agent ma do czynienia w środowisku produkcyjnym, co pomaga również tworzyć realistyczne kryteria oceny na poziomie zadań.

Określ dokładnie kryteria

Niejasne kryteria prowadzą do niespójnego oceniania. Ustaw każde kryterium jako specyficzne i testowalne.

Źle:

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

Dobry:

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

Troubleshooting

Treści powiązane

• Omówienie optymalizatora agentów
• Przygotuj swojego agenta do współpracy z optymalizatorem
• Optymalizowanie instrukcji agenta, umiejętności, narzędzi i modeli
• Szybki start: optymalizowanie hostowanego agenta
• Przeprowadzanie ocen agentów za pomocą narzędzia wiersza polecenia azd