Evalwa l-Aġenti Tiegħek: Metriċi u Punti ta' Referenza
F'din il-paġna
Evalwa l-Aġenti Tiegħek: Metriċi u Punti ta’ Referenza
Aġent li jaħdem fl-iżvilupp jista’ jfalli fil-produzzjoni. L-evalwazzjoni sistematika hija l-uniku mod biex tiggarantixxi l-kwalità qabel u wara l-implimentazzjoni. F’din il-lezzjoni, se titgħallem kif tiddefinixxi l-metriċi, toħloq settijiet ta’ testijiet, u tawtomatizza l-evalwazzjoni.
Għaliex Tevalwa?
Mingħajr evalwazzjoni formali, qed itir bl-individwu. Terġa’ tifformula istruzzjoni għax utent ilmenta, iżda xejn ma jgħidlek jekk l-aġent titjibx jew jekk sempliċiment kisserx tliet xenarji oħra. Tittardja bejn Terra u Luna għall-każ ta’ użu tiegħek—jew bejn żewġ livelli ta’ raġunar fuq l-istess mudell—u mingħajr kejl, id-deċiżjoni tibqa’ fuq is-sensazzjoni wara ħames provi manwali. Tibdel skema ta’ għodda, l-aġent jieqaf isejjaħha f’każ speċifiku, u ħadd ma jinnota sakemm il-volum tat-tikketti jiżdied b’mod qawwi. Sett ta’ evalwazzjoni jħawwal kull waħda minn dawn is-sitwazzjonijiet f’numru li tista’ tqabbel minn verżjoni għall-oħra.
Metriċi Ewlenin
Preċiżjoni
L-ewwel mistoqsija hija l-aktar diretta: l-aġent jagħti t-tweġiba t-tajba? Doħħol mill-ġdid sett ta’ mistoqsijiet fejn taf it-tweġiba u vverifika l-preżenza tagħha fl-output. It-tqabbil ta’ sottostringa insensittiv għall-każ huwa intenzjonalment grossolan—jittollera “Il-laptop Pro jiswa €1,299 inkluż it-taxxa” fejn l-ugwaljanza stretta tkun tfalli—iżda biżżejjed għal fatti verifikabbli u jikkalkula f’sekonda.
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"])
# Verifika awtomatika jew ibbażata fuq 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"Accuracy: {rate:.1%} ({sum(1 for r in results if r['correct'])}/{len(results)})")
return results
# Sett ta' testijiet
test_cases = [
{"question": "What is the price of the Pro laptop?", "expected_answer": "1299"},
{"question": "How many laptops are in stock?", "expected_answer": "45"},
{"question": "What is the cheapest product?", "expected_answer": "tablet"},
]
Użu Korrett tal-Għodod
Tweġiba korretta miksuba b’kumbinazzjoni tibqa’ problema. Aġent li jirreċita prezz memorizzat minflok ma jikkonsulta l-katalogu jgħaddi mit-test tal-preċiżjoni llum u jagħti rata antiquata għada. Għalhekk, it-tieni metrika tħares lejn il-mogħdija, mhux lejn ir-riżultat: l-aġent isejjaħ l-għodod it-tajbin bl-argumenti t-tajbin? Taqra s-sejħiet f’raw_responses, tiffiltra għal outputs function_call, u t-tqabbil juża settijiet biex jibqa’ indifferenti għall-ordni.
async def evaluate_tools(agent, test_cases):
results = []
for case in test_cases:
result = await Runner.run(agent, case["question"])
# Estrazzjoni tal-għodod imsejħa mir-risposti mhux ipproċessati
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"Correct tools: {rate:.1%}")
return results
tool_cases = [
{
"question": "What is the price of the laptop?",
"expected_tools": ["search_product"],
},
{
"question": "Price of the laptop with 10% discount",
"expected_tools": ["search_product", "calculate_discount"],
},
]
It-tieni każ ta’ test huwa l-aktar istruttiv: il-mistoqsija teħtieġ katina ta’ żewġ għodod, u dan huwa eżattament it-tip ta’ kompożizzjoni li bidla fid-deskrizzjoni tista’ tkisser b’mod silenzjuż.
Latenza u Spiża
Fl-aħħar nett, hemm id-dimensjoni operattiva. Medja ma tgħid xejn dwar l-esperjenza reali: hija d-denb tad-distribuzzjoni li tbiegħed lill-utenti, meta talba waħda minn mitt tieħu għoxrin sekonda. Billi tirrepeti kull messaġġ diversi drabi, tikseb distribuzzjoni użabbli u taqra l-medjan bħala l-imġiba tipika, u l-P99 bħala l-agħar xenarju komuni tiegħek.
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"Average latency: {statistics.mean(latencies):.2f}s")
print(f"P50 latency: {statistics.median(latencies):.2f}s")
print(f"P99 latency: {sorted(latencies)[int(len(latencies) * 0.99)]:.2f}s")
Evalwazzjoni permezz ta’ LLM (LLM-as-Judge)
Dawn it-tliet metriċi iħallu barra kull ħaġa mingħajr tweġiba waħda korretta: spjegazzjoni ta’ politika ta’ ritorn, riformulazzjoni tal-bejgħ, messaġġ ta’ apoloġija. Għal dawn ir-risposti miftuħa, uża mudell biex tevalwa l-kwalità. L-imħallef jirċievi l-mistoqsija u t-tweġiba, japplika kriterji li ktibt int—preċiżjoni, rilevanza, professjonaliżma—u jirritorna punteġġ strutturat grazzi għal output_type ta’ Pydantic. Il-vincolu tal-format huwa dak li jagħmel il-proċess użabbli: tikseb numru sħiħ li tista’ taggrega, mhux kumment li trid terġa’ taqra.
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="""Evaluate the quality of the agent's response.
Criteria:
- Accuracy: Is the response factual and correct?
- Relevance: Does the response answer the question asked?
- Professionalism: Is the tone appropriate?
Score from 1 (very poor) to 5 (excellent).""",
model="gpt-5.6-sol",
output_type=Evaluation,
)
async def evaluate_quality(question, agent_response):
prompt = f"""Question asked: {question}
Agent response: {agent_response}
Evaluate this response."""
result = await Runner.run(evaluator_agent, prompt)
return result.final_output
Il-qasam reason jistħoqqilu attenzjoni waqt ir-reviżjonijiet: hawnhekk l-imħallef jispjega għaliex ta 3 minn 5, u spiss din hija l-formulazzjoni ta’ difett li ma rnexxielekx isemmi.
Settijiet ta’ Testijiet Strutturati
Evalwazzjoni li mhix riproduċibbli hija inutili. Organizza l-każijiet tat-test tiegħek f’format stabbli fejn kull entrata ġġorr ID, kategorija, il-mistoqsija, it-tweġiba mistennija, l-għodod mistennija, u kriterji kwalitattivi. Il-kategorija tagħmel ix-xogħol kollu hawn: punteġġ ġenerali ta’ 4.2 minn 5 huwa qarrieqi u jisseddaq, filwaqt li punteġġ dettaljat jiżvela li l-kategorija “stock” tinżel għal 2.8 filwaqt li “price” tiġbed il-medja ‘l fuq.
import json
# evaluation_dataset.json
DATASET = [
{
"id": "test_001",
"category": "price",
"question": "What is the price of the Pro laptop?",
"expected_answer": "€1,299",
"expected_tools": ["search_product"],
"criteria": ["contains_price", "professional_tone"],
},
{
"id": "test_002",
"category": "stock",
"question": "Is the Tablet Air in stock?",
"expected_answer": "yes",
"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,
})
# Rapport
average_score = sum(r["score"] for r in results) / len(results)
print(f"\nAverage score: {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
Ħaddem din l-evalwazzjoni fil-pipeline tal-integrazzjoni kontinwa tiegħek, eżattament bħat-testijiet tal-unità tiegħek, u stabbilixxi limitu li taħtu l-konsenja tiġi mblukkata. Minn dak il-mument ‘il quddiem, kull bidla—mudell ġdid, istruzzjonijiet aġġustati, għodda miżjuda—titqabbel ma’ dik ta’ qabilha fuq l-istess każijiet, u d-diskussjoni tieqaf iddur madwar l-impressjonijiet.
Punti Ewlenin
- Evalwa l-preċiżjoni, l-użu tal-għodod, il-latenza u l-ispiża
- L-evalwazzjoni permezz ta’ LLM (LLM-as-Judge) tittratta risposti miftuħa
- Oħloq settijiet ta’ testijiet strutturati u riproduċibbli
- Awtomatizza l-evalwazzjoni fil-CI/CD tiegħek biex tiskopri regrezzjonijiet
- Qabbel sistematikament il-bidliet (mudell, istruzzjonijiet, għodod)