Ocena Twoich agentów: metryki i punkty odniesienia
Na tej stronie
Ocena Twoich agentów: metryki i punkty odniesienia
Agent działający w środowisku deweloperskim może zawieść na produkcji. Systematyczna ocena to jedyny sposób na zagwarantowanie jakości przed i po wdrożeniu. W tej lekcji nauczysz się definiować metryki, tworzyć zestawy testowe i automatyzować proces ewaluacji.
Dlaczego warto oceniać?
Bez formalnej oceny działasz po omacku. Poprawiasz instrukcję, bo użytkownik się poskarżył, ale nic nie mówi Ci, czy agent faktycznie działa lepiej, czy może właśnie zepsułeś trzy inne scenariusze. Wahasz się między Terrą a Luną dla swojego przypadku użycia – albo między dwoma poziomami rozumowania na tym samym modelu – i bez pomiarów decyzja opiera się na przeczuciu po pięciu ręcznych próbach. Zmieniasz schemat narzędzia, agent przestaje go wywoływać w konkretnym przypadku i nikt tego nie zauważa, dopóki liczba zgłoszeń nie wystrzeli w górę. Zestaw ewaluacyjny zamienia każdą z tych sytuacji w porównywalną liczbę dla kolejnych wersji.
Kluczowe metryki
Dokładność
Pierwsze pytanie jest najbardziej bezpośrednie: czy agent podaje prawidłową odpowiedź? Odtwarzasz zestaw pytań, na które znasz odpowiedź, i sprawdzasz jej obecność w wyniku. Porównanie podciągów bez uwzględniania wielkości liter jest celowo zgrubne – toleruje frazę „Laptop Pro kosztuje 1299 € brutto“, gdzie ścisła równość by zawiodła – ale wystarcza dla faktów podlegających weryfikacji i oblicza się je w sekundę.
from agents import Agent, Runner
async def evaluate_accuracy(agent, test_cases):
results = []
for case in test_cases:
result = await Runner.run(agent, case["question"])
# Weryfikacja automatyczna lub oparta na LLM
is_correct = case["expected_answer"].lower() in result.final_output.lower()
results.append({
"question": case["question"],
"answer": result.final_output,
"expected": case["expected_answer"],
"correct": is_correct,
})
rate = sum(1 for r in results if r["correct"]) / len(results)
print(f"Dokładność: {rate:.1%} ({sum(1 for r in results if r['correct'])}/{len(results)})")
return results
# Zestaw testowy
test_cases = [
{"question": "Jaka jest cena laptopa Pro?", "expected_answer": "1299"},
{"question": "Ile laptopów jest na stanie?", "expected_answer": "45"},
{"question": "Jaki jest najtańszy produkt?", "expected_answer": "tablet"},
]
Prawidłowe użycie narzędzi
Prawidłowa odpowiedź uzyskana przypadkowo nadal stanowi problem. Agent, który recytuje zapamiętaną cenę zamiast odpytywać katalog, przejdzie dziś test dokładności, a jutro poda nieaktualną stawkę. Druga metryka patrzy więc na ścieżkę, a nie na wynik: czy agent wywołuje właściwe narzędzia z odpowiednimi argumentami? Odczytujesz wywołania w raw_responses, filtrując wyniki typu function_call, a porównanie wykorzystuje zbiory, aby pozostać obojętnym na kolejność.
async def evaluate_tools(agent, test_cases):
results = []
for case in test_cases:
result = await Runner.run(agent, case["question"])
# Wyodrębnienie wywołanych narzędzi z surowych odpowiedzi
called_tools = []
for response in result.raw_responses:
for output in getattr(response, "output", []):
if hasattr(output, "type") and output.type == "function_call":
called_tools.append(output.name)
tools_correct = set(case["expected_tools"]) == set(called_tools)
results.append({
"question": case["question"],
"called_tools": called_tools,
"expected_tools": case["expected_tools"],
"correct": tools_correct,
})
rate = sum(1 for r in results if r["correct"]) / len(results)
print(f"Prawidłowe narzędzia: {rate:.1%}")
return results
tool_cases = [
{
"question": "Jaka jest cena laptopa?",
"expected_tools": ["search_product"],
},
{
"question": "Cena laptopa z 10% rabatem",
"expected_tools": ["search_product", "calculate_discount"],
},
]
Drugi przypadek testowy jest najbardziej pouczający: pytanie wymaga połączenia dwóch narzędzi, a to właśnie ten rodzaj kompozycji może zostać cicho zepsuty przez zmianę w opisie.
Opóźnienie i koszt
Na koniec wymiar operacyjny. Średnia nic nie mówi o rzeczywistym doświadczeniu: to ogon rozkładu odstrasza użytkowników, gdy jedno żądanie na sto trwa dwadzieścia sekund. Powtarzając każdą wiadomość kilka razy, uzyskujesz użyteczny rozkład i odczytujesz medianę jako typowe zachowanie, a P99 jako Twój powszechny scenariusz najgorszego przypadku.
import time
async def evaluate_performance(agent, messages, iterations=10):
latencies = []
for message in messages:
for _ in range(iterations):
start = time.perf_counter()
result = await Runner.run(agent, message)
duration = time.perf_counter() - start
latencies.append(duration)
import statistics
print(f"Średnie opóźnienie: {statistics.mean(latencies):.2f}s")
print(f"Opóźnienie P50: {statistics.median(latencies):.2f}s")
print(f"Opóźnienie P99: {sorted(latencies)[int(len(latencies) * 0.99)]:.2f}s")
Ocena przez LLM (LLM-as-Judge)
Te trzy metryki pomijają wszystko, co nie ma jednej prawidłowej odpowiedzi: wyjaśnienie polityki zwrotów, przeredagowanie oferty sprzedażowej, wiadomość z przeprosinami. W przypadku tych otwartych odpowiedzi użyj modelu do oceny jakości. Sędzia otrzymuje pytanie i odpowiedź, stosuje kryteria, które napisałeś – dokładność, trafność, profesjonalizm – i zwraca ustrukturyzowany wynik dzięki typowi wyjścia Pydantic output_type. To ograniczenie formatu sprawia, że proces jest użyteczny: otrzymujesz agregowalną liczbę całkowitą, a nie komentarz do ponownego przeczytania.
from pydantic import BaseModel
class Evaluation(BaseModel):
score: int # 1-5
reason: str
is_correct: bool
is_relevant: bool
is_professional: bool
evaluator_agent = Agent(
name="Evaluator",
instructions="""Oceń jakość odpowiedzi agenta.
Kryteria:
- Dokładność: Czy odpowiedź jest faktograficzna i poprawna?
- Trafność: Czy odpowiedź dotyczy zadanego pytania?
- Profesjonalizm: Czy ton jest odpowiedni?
Ocena od 1 (bardzo słabo) do 5 (znakomicie).""",
model="gpt-5.6-sol",
output_type=Evaluation,
)
async def evaluate_quality(question, agent_response):
prompt = f"""Zadane pytanie: {question}
Odpowiedź agenta: {agent_response}
Oceń tę odpowiedź."""
result = await Runner.run(evaluator_agent, prompt)
return result.final_output
Pole reason zasługuje na Twoją uwagę podczas przeglądów: to tutaj sędzia wyjaśnia, dlaczego przyznał 3 na 5, i często jest to sformułowanie wady, której nie udało Ci się wcześniej nazwać.
Ustrukturyzowane zestawy testowe
Ocena, której nie można powtórzyć, jest bezużyteczna. Zorganizuj przypadki testowe w stabilnym formacie, gdzie każdy wpis zawiera ID, kategorię, pytanie, oczekiwaną odpowiedź, oczekiwane narzędzia i kryteria jakościowe. Kategoria wykonuje tutaj całą pracę: ogólny wynik 4,2 na 5 myląco uspokaja, podczas gdy szczegółowy wynik ujawnia, że kategoria „stan magazynowy“ spada do 2,8, podczas gdy „cena“ podnosi średnią.
import json
# evaluation_dataset.json
DATASET = [
{
"id": "test_001",
"category": "price",
"question": "Jaka jest cena laptopa Pro?",
"expected_answer": "1299 €",
"expected_tools": ["search_product"],
"criteria": ["contains_price", "professional_tone"],
},
{
"id": "test_002",
"category": "stock",
"question": "Czy Tablet Air jest na stanie?",
"expected_answer": "tak",
"expected_tools": ["search_product"],
"criteria": ["clear_answer", "stock_information"],
},
]
async def run_complete_evaluation(agent):
results = []
for case in DATASET:
result = await Runner.run(agent, case["question"])
eval_result = await evaluate_quality(case["question"], result.final_output)
results.append({
**case,
"agent_response": result.final_output,
"score": eval_result.score,
"evaluation": eval_result.reason,
})
# Raport
average_score = sum(r["score"] for r in results) / len(results)
print(f"\nŚredni wynik: {average_score:.1f}/5")
for cat in set(r["category"] for r in results):
cat_scores = [r["score"] for r in results if r["category"] == cat]
print(f" {cat}: {sum(cat_scores)/len(cat_scores):.1f}/5")
return results
Uruchamiaj tę ocenę w potoku ciągłej integracji (CI), tak jak testy jednostkowe, i ustaw próg, poniżej którego dostawa jest blokowana. Od tego momentu każda zmiana – nowy model, dostosowane instrukcje, dodane narzędzie – jest porównywana z poprzednią na tych samych przypadkach, a dyskusja przestaje kręcić się wokół wrażeń.
Kluczowe wnioski
- Oceniaj dokładność, użycie narzędzi, opóźnienie i koszt
- Ocena przez LLM (LLM-as-Judge) obsługuje odpowiedzi otwarte
- Twórz ustrukturyzowane i powtarzalne zestawy testowe
- Automatyzuj ocenę w CI/CD, aby wykrywać regresje
- Systematycznie porównuj zmiany (model, instrukcje, narzędzia)