Trace grading: vykdymų vertinimas
Šiame puslapyje
Trace grading: vykdymų vertinimas
„Trace“ (vykdymo žurnalas) fiksuoja tai, ką daro tavo agentas. Tai būtina, tačiau nepakanka: niekas neperskaito dešimties tūkstančių žurnalų per dieną, o problemos slepiasi būtent tuose, kurių niekada neatidarai. Trace grading (vykdymų vertinimas) žengia dar toliau: jis automatiškai įvertina kiekvieną vykdymą, kad pastebėtum problemas, išmatuotum kokybės pokyčius laikui bėgant ir maitintum nuolatinio tobulinimo ciklą.
Trace grading koncepcija
Kiekviename tavo agento sugeneruotame žurnale yra visa vykdymo istorija: naudotojo žinutė, įrankių kvietimai, tarpiniai atsakymai ir galutinis atsakymas. Trace grading analizuoja šiuos žurnalus ir priskiria balus pagal tavo nustatytus kriterijus. Tu pereini nuo žurnalo, kurį peržiūri post factum, prie metrikos, kurią stebi nuolat, ir klausimas „Kaip agentui sekasi šiuo metu?“ nustoja būti spėjimas.
Automatinis vertinimas naudojant taisykles
Paprastiausias lygmuo naudoja programines taisykles kiekvienam žurnalui įvertinti. Kiekviena taisyklė pradeda nuo maksimalaus 1,0 balo ir atima taškus priklausomai nuo to, ką pastebi. Vykdymas, trunkantis ilgiau nei dešimt sekundžių, praranda 0,2 balo – ne todėl, kad rezultatas neteisingas, o todėl, kad naudotojas greičiausiai jau pasitraukė. Daugiau nei penkiolika ciklų kainuoja 0,3 balo: tai agento, besisukančio rate tarp dviejų įrankių, požymis. Kiekviena įrankio klaida atima 0,1 balo. Suaktyvintos apsaugos taisyklės (guardrails) pažymimos be baudos – jos atliko savo darbą – tačiau atsakymas, trumpesnis nei dešimt simbolių, vienas pats kainuoja pusę balo, nes tylus agentas yra nenaudingas agentas.
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,
)
Žodynas details visada lydi balą: be jo žinotum, kad vykdymas gavo 0,5 balo, bet nežinotum kodėl. Šios ribos yra tavo, o ne universalios konstantos – tyrimų agentas toleruoja penkiolika ciklų, tuo tarpu atsiskaitymo asistentas privalo atsakyti per tris.
Vertinimas naudojant LLM
Taisyklės nemato turinio. Greitas, trumpas, mandagus atsakymas, kuris visiškai nepataiko į esmę, gaus 1,0 balo. Tiksliau įvertinti gali modelis, vertinantis žurnalus pagal esmę: aktualumą, tikslumą ir toną, kiekvieną nuo 1 iki 5, kartu nustatydamas problemas ir siūlydamas patobulinimus. Vėlgi, struktūruota išvestis naudojant „Pydantic“ leidžia agreguoti balus, užuot generavus laisvos formos komentarus.
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
Užklausa taip pat perduoda iškviestus įrankius ir trukmę: taip vertintojas gali nubausti agentą už atsakymą nepasitikrinus katalogo, ko vien tik skaitant atsakymą nustatyti nebūtų galima.
Vertinimo vamzdynas gamyboje
Dabar derink abu metodus neiššvaistydamas biudžeto. Kiekvieno žurnalo vertinimas naudojant LLM gamybos apimtimis daugina tavo išvadų sąskaitą; naudojant tik taisykles lieki aklas esmei. Toliau pateiktas vamzdynas taiko filtrą: visi žurnalai praeina programinį vertinimą, kuris yra greitas ir nemokamas, o tik tie, kurių rezultatas mažesnis nei 0,7, siunčiami vertintojui. Vertintojo balas, sudarytas iš trijų 1–5 įverčių sumos, normalizuojamas į 0–1 diapazoną padalijus iš 15, kad būtų palyginamas su pirmuoju. Jei balas mažesnis nei 0,5, žurnalas patenka į kritinių įspėjimų sąrašą.
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())
Ataskaitoje išlaikomas minimalus balas ir dešimties blogiausių žurnalų imtis: būtent čia prasideda tyrimas, niekada – nuo vidurkio.
Kokybės skydelis
Vienas balas nieko nereiškia; svarbi jo trajektorija. Kasdienę ataskaitą rašydamas į JSONL failą, sukuri laiko eilutę, kurią gali skaityti bet kuris vizualizacijos įrankis, ir gali automatiškai palyginti naujausią tašką su ankstesniu. Kritimas daugiau nei 0,1 sukelia regresijos įspėjimą – ir susiejus jį su tos dienos diegimais, kaltininkas paprastai nustatomas per kelias minutes.
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
Dviejų iš eilės einančių dienų palyginimas lieka jautrus triukšmui: esant mažam srautui, prieš skelbiant regresiją, geriau naudoti slankųjį vidurkį, kitaip gaudysi statistinius šuolius.
Svarbiausi punktai
- Trace grading automatiškai įvertina kiekvieną tavo agento vykdymą
- Programinės taisyklės (vėlavimas, klaidos, ilgis) yra greitos ir patikimos
- LLM vertinimas analizuoja aktualumą, tikslumą ir toną
- Derink abu metodus: greitos taisyklės filtravimui, LLM – ribiniams atvejams
- Stebėk balus laikui bėgant, kad aptiktum regresijas
- Kritiniai įspėjimai (balas < 0,5) privalo inicijuoti tyrimą