Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Jälituse hindamine: käivituste skoorimine

Õppetund 23 / 25 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Jälituse hindamine: käivituste skoorimine
  2. Jälituse hindamise kontseptsioon
  3. Automaatne hindamine reeglitega
  4. LLM-põhine hindamine
  5. Hindamistorustik tootmises
  6. Kvaliteedi armatuurlaud
  7. Peamised punktid

Jälituse hindamine: käivituste skoorimine

Jälitamine salvestab sinu agendi tegevuse. See on hädavajalik, kuid mitte piisav: keegi ei loe päevas kümme tuhat jälitust ja probleemid peituvad täpselt nendes, mida sa kunagi ei ava. Jälituse hindamine läheb kaugemale: see skoorib automaatselt iga käivituse, et tuvastada probleeme, mõõta kvaliteeti ajas ja toita pideva täiustamise tsüklit.

Jälituse hindamise kontseptsioon

Iga sinu agendi loodud jälitus sisaldab kogu käivitust: kasutaja sõnumit, tööriistakutseid, vahevastuseid ja lõplikku vastust. Jälituse hindamine analüüsib neid jälitusi ja omab skoorid sinu kriteeriumide põhjal. Sa liigud logilt, mida konsulteerid tagantjärele, mõõdikule, mida jälgid pidevalt, ja küsimus „Kuidas agent praegu toimib?“ lõpetab arvamise.

Automaatne hindamine reeglitega

Lihtsaim tase kasutab iga jälituse skoorimiseks programmeeritavaid reegleid. Iga reegel algab täiusliku skooriga 1,0 ja lahutab punkte selle põhjal, mida ta täheldab. Käivitus, mis võtab aega üle kümne sekundi, kaotab 0,2 punkti, mitte sellepärast, et tulemus oleks vale, vaid sest kasutaja tõenäoliselt loobus. Üle viieteistkümne pöörde maksab 0,3 punkti: see on agendi märk, mis pöörleb kahe tööriista vahel ringe. Iga tööriistaviga lahutab 0,1 punkti. Käivitatud kaitseraudteed märgistatakse ilma trahvita – nad tegid oma töö –, kuid vastus, mis on lühem kui kümme tähemärki, maksab üksi pool punkti, sest vaikiv agent on kasutu 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,
    )

Sõnastik details kaasneb alati skooriga: ilma selleta teaksid, et käivitus sai skooriga 0,5, kuid mitte miks. Need läved on sinu omad, mitte universaalsed konstandid – uurimisagent talub viieteistkümnet pööret, kusjuures kassaabi peab vastama kolmega.

LLM-põhine hindamine

Reeglid ei näe sisu. Kiire, lühike ja viisakas vastus, mis jätab sisu täiesti kõrvale, saab skooriga 1,0. Peenemaks hindamiseks kasuta mudelit jälituste skoorimiseks sisu põhjal: asjakohasus, täpsus ja toon, igaüks skaalal 1–5, koos tuvastatud probleemide ja parandusettepanekutega. Jällegi muudab struktureeritud väljund Pydanticu kaudu skoorid agregeeritavaks, mitte ei tooda vabas vormis kommentaare.

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

Viip sisaldab ka kutsutud tööriistu ja kestust: kohtunik saab seega süüdistada agenti vastamises ilma kataloogi konsulteerimata, mida ainult vastuse lugemine ei võimaldaks.

Hindamistorustik tootmises

Nüüd ühenda mõlemad lähenemised ilma eelarvet lõhkumata. Iga jälituse skoorimine LLM-iga tootmismahus korrutab sinu järeldusarve; ainult reeglite kasutamine jätab sind sisu suhtes pimedaks. Allpool olev torustik rakendab filtrit: kõik jälitused läbivad programmeeritava hindamise, mis on kiire ja tasuta, ja ainult need, mis jäävad alla 0,7, lähevad kohtunikule. Kohtuniku skoor, kolme 1–5 hinnangu summa, skaalitakse 0–1-ni, jagades 15-ga, et jääda võrreldavaks esimesega. Alla 0,5 liitub jälitus kriitiliste häirete loendisse.

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())

Aruanne hoiab minimaalset skoori ja proovi kümnest halvimast jälitusest: sealt algab uurimine, mitte kunagi keskmisest.

Kvaliteedi armatuurlaud

Üksik skoor ei tähenda midagi; selle trajektoor annab informatsiooni. Kirjutades päevase aruande JSONL-faili, ehidad ajaread, mida iga visualiseerimistööriist saab lugeda, ja saad automaatselt võrrelda viimast punkti eelmisega. Langus üle 0,1 käivitab taandarengu hoiatuse – ja selle korreleerimine päeva kasutuselevõttudega osutab süüdlasele tavaliselt minutitega.

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

Kahe järjestikuse päeva võrdlemine jääb müra suhtes tundlikuks: väikese mahu korral eelista liikuvat keskmist enne taandarengu karjumist, muidu jahid statistilist hälvet.

Peamised punktid

  • Jälituse hindamine skoorib automaatselt iga sinu agendi käivituse
  • Programmeeritavad reeglid (latentsus, vead, pikkus) on kiired ja usaldusväärsed
  • LLM-hindamine hindab asjakohasust, täpsust ja tooni
  • Kombineeri mõlemat: kiired reeglid filtreerimiseks, LLM piirjuhtumite jaoks
  • Jälgi skoorid ajas, et tuvastada taandarenguid
  • Kriitilised häired (skoor < 0,5) peavad käivitama uurimise