Ocenjevanje sledi: točkovanje izvedb
Na tej strani
Ocenjevanje sledi: točkovanje izvedb
Sledenje beleži, kaj tvoj agent počne. To je nujno, a ni dovolj: nihče ne prebere deset tisoč sledi na dan, težave pa se skrivajo prav v tistih, ki jih nikoli ne odpreš. Ocenjevanje sledi gre korak dlje: samodejno oceni vsako izvedbo, da odkrije težave, skozi čas meri kakovost in napaja zanko stalnega izboljševanja.
Koncept ocenjevanja sledi
Vsaka sled, ki jo ustvari tvoj agent, vsebuje celotno izvedbo: uporabniško sporočilo, klice orodij, vmesne odgovore in končni odgovor. Ocenjevanje sledi analizira te sledi in dodeljuje ocene na podlagi tvojih meril. Preideš od dnevnika, ki ga pregledaš naknadno, do metrike, ki jo spremljaš neprekinjeno, vprašanje „Kako se agent trenutno obnaša?” pa preneha biti ugibanje.
Samodejno ocenjevanje s pravili
Najpreprostejša raven uporablja programska pravila za točkovanje vsake sledi. Vsako pravilo izhaja iz popolne ocene 1,0 in odbija točke glede na to, kaj opazi. Izvedba, ki traja dlje kot deset sekund, izgubi 0,2 točke, ne zato, ker je rezultat napačen, ampak zato, ker je uporabnik verjetno odnehal. Več kot petnajst krogov stane 0,3 točke: to je znak agenta, ki se vrti v krogu med dvema orodjema. Vsaka napaka orodja odšteje 0,1 točke. Sprožene varovalke so označene brez kazni – opravile so svoje delo – toda odgovor, krajši od desetih znakov, sam po sebi stane pol točke, kajti tihi agent je neuporaben agent.
from dataclasses import dataclass
@dataclass
class GradeTrace:
trace_id: str
score: float # 0.0 to 1.0
details: dict
alerts: list[str]
def grade_trace(trace_data: dict) -> GradeTrace:
"""Scores a trace based on business rules."""
score = 1.0
alerts = []
details = {}
# Rule 1: Latency
duration = trace_data.get("duration_ms", 0)
if duration > 10000:
score -= 0.2
alerts.append(f"High latency: {duration}ms")
details["latency_ms"] = duration
# Rule 2: Number of turns
num_turns = trace_data.get("num_turns", 0)
if num_turns > 15:
score -= 0.3
alerts.append(f"Too many turns: {num_turns}")
details["num_turns"] = num_turns
# Rule 3: Tool errors
tool_errors = trace_data.get("tool_errors", 0)
if tool_errors > 0:
score -= 0.1 * tool_errors
alerts.append(f"{tool_errors} tool error(s)")
details["tool_errors"] = tool_errors
# Rule 4: Triggered guardrails
guardrails = trace_data.get("guardrails_triggered", 0)
if guardrails > 0:
alerts.append(f"{guardrails} guardrail(s) triggered")
details["guardrails"] = guardrails
# Rule 5: Empty response
response = trace_data.get("final_output", "")
if not response or len(response) < 10:
score -= 0.5
alerts.append("Empty or too short response")
details["response_length"] = len(response)
return GradeTrace(
trace_id=trace_data["trace_id"],
score=max(0.0, score),
details=details,
alerts=alerts,
)
Slovar details vedno spremlja oceno: brez njega bi vedel, da je izvedba dosegla 0,5, ne bi pa vedel zakaj. Ti pragovi so tvoji, niso univerzalne konstante – raziskovalni agent prenese petnajst krogov, medtem ko mora asistent za odjavo odgovoriti v treh.
Ocenjevanje z LLM
Pravila ne vidijo vsebine. Hiter, kratek, vljuden odgovor, ki popolnoma zgreši bistvo, bo dosegel 1,0. Za natančnejšo evalvacijo uporabi model za ocenjevanje sledi glede na vsebino: ustreznost, točnost in ton, vsakega od 1 do 5, skupaj z identificiranimi težavami in predlogi za izboljšave. Tudi tu strukturiran izhod prek Pydantic omogoča združevanje ocen namesto ustvarjanja komentarjev proste oblike.
from pydantic import BaseModel
from agents import Agent, Runner
class GradeLLM(BaseModel):
relevance_score: int # 1-5
accuracy_score: int # 1-5
tone_score: int # 1-5
issues: list[str]
suggestions: list[str]
grader_agent = Agent(
name="Trace Grader",
instructions="""You score executions of a sales agent.
Analyze the full trace (question, tools called, response) and score:
- Relevance (1-5): Does the response answer the question?
- Accuracy (1-5): Is the information correct?
- Tone (1-5): Is the tone professional and appropriate?
Identify issues and propose improvements.""",
model="gpt-5.6-sol",
output_type=GradeLLM,
)
async def grade_trace_llm(trace: dict) -> GradeLLM:
prompt = f"""Execution trace to score:
User question: {trace['user_message']}
Tools called: {trace['tools_called']}
Final response: {trace['final_output']}
Duration: {trace['duration_ms']}ms
Number of turns: {trace['num_turns']}"""
result = await Runner.run(grader_agent, prompt)
return result.final_output
Poziv posreduje tudi poklicana orodja in trajanje: sodnik lahko tako ošteje agenta, ker je odgovoril brez posvetovanja s katalogom, česar samo branje odgovora ne bi omogočilo.
Cevovod za ocenjevanje v proizvodnji
Zdaj združi oba pristopa, ne da bi razstrelil svoj proračun. Točkovanje vsake sledi z LLM pri obsegu proizvodnje pomnoži tvoj račun za sklepanje; uporaba samo pravil te pušča slepega za vsebino. Spodnji cevovod uporablja filter: vse sledi gredo skozi programsko ocenjevanje, ki je hitro in brezplačno, le tiste z oceno pod 0,7 pa gredo k sodniku. Sodnikova ocena, vsota treh ocen od 1 do 5, je skalirana na 0–1 z deljenjem s 15, da ostane primerljiva s prvo. Pod 0,5 se sled pridruži seznamu kritičnih opozoril.
import asyncio
from collections import defaultdict
class GradingPipeline:
def __init__(self):
self.scores = defaultdict(list)
self.critical_alerts = []
async def grade_batch(self, traces: list[dict]):
"""Scores a batch of traces."""
for trace in traces:
# Programmatic grading (fast)
rule_grade = grade_trace(trace)
# LLM grading for borderline cases
if rule_grade.score < 0.7:
llm_grade = await grade_trace_llm(trace)
final_score = (
llm_grade.relevance_score +
llm_grade.accuracy_score +
llm_grade.tone_score
) / 15.0 # Normalize to 0-1
else:
final_score = rule_grade.score
self.scores["global"].append(final_score)
# Alerts
if final_score < 0.5:
self.critical_alerts.append({
"trace_id": trace["trace_id"],
"score": final_score,
"alerts": rule_grade.alerts,
})
def report(self):
"""Generates a quality report."""
scores = self.scores["global"]
if not scores:
return "No traces evaluated."
import statistics
return {
"num_traces": len(scores),
"avg_score": statistics.mean(scores),
"median_score": statistics.median(scores),
"min_score": min(scores),
"pct_critical": len(self.critical_alerts) / len(scores),
"critical_alerts": self.critical_alerts[:10],
}
# Usage
pipeline = GradingPipeline()
await pipeline.grade_batch(traces_of_the_day)
print(pipeline.report())
Poročilo ohrani najnižjo oceno in vzorec desetih najslabših sledi: tam se začne preiskava, nikoli s povprečjem.
Nadzorna plošča za kakovost
Ena sama ocena ne pomeni nič; poučna je njena potek. Z zapisovanjem dnevnega poročila v datoteko JSONL gradiš časovno vrsto, ki jo lahko prebere katero koli orodje za vizualizacijo, in samodejno lahko primerjaš zadnjo točko s prejšnjo. Padec za več kot 0,1 sproži opozorilo o regresiji – in če ga povežeš s tvojimi dnevnimi uvedbami, običajno v nekaj minutah kaže na krivca.
import json
from datetime import datetime
def log_metrics(report: dict, file: str = "agent_metrics.jsonl"):
"""Logs daily metrics."""
entry = {
"date": datetime.now().isoformat(),
**report,
}
with open(file, "a") as f:
f.write(json.dumps(entry) + "\n")
def detect_regression(recent_metrics: list[dict], threshold: float = 0.1):
"""Detects a significant quality drop."""
if len(recent_metrics) < 2:
return False
latest = recent_metrics[-1]["avg_score"]
previous = recent_metrics[-2]["avg_score"]
drop = previous - latest
if drop > threshold:
print(f"REGRESSION DETECTED: score dropped from {previous:.2f} to {latest:.2f}")
return True
return False
Primerjava dveh zaporednih dni ostaja občutljiva na šum: pri majhnem obsegu raje uporabi drseče povprečje, preden zavpiješ o regresiji, sicer boš lovil statistični šum.
Ključne ugotovitve
- Ocenjevanje sledi samodejno točkuje vsako izvedbo tvojega agenta
- Programska pravila (zakasnitev, napake, dolžina) so hitra in zanesljiva
- Ocenjevanje z LLM evalvira ustreznost, točnost in ton
- Združi oboje: hitra pravila za filtriranje, LLM za mejne primere
- Spremljaj ocene skozi čas za odkrivanje regresij
- Kritična opozorila (ocena < 0,5) morajo sprožiti preiskavo