Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Trace grading: vykdymų vertinimas

Paskaita 23 iš 25 Atnaujinta 2026 m. liepos 29 d. Kūrėjas
Šiame puslapyje
  1. Trace grading: vykdymų vertinimas
  2. Trace grading koncepcija
  3. Automatinis vertinimas naudojant taisykles
  4. Vertinimas naudojant LLM
  5. Vertinimo vamzdynas gamyboje
  6. Kokybės skydelis
  7. Svarbiausi punktai

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ą