Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Trace grading: suoritusten pisteytys

Oppitunti 23 / 25 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Trace grading: suoritusten pisteytys
  2. Trace gradingin käsite
  3. Automaattinen pisteytys sääntöjen avulla
  4. LLM-pohjainen pisteytys
  5. Pisteytysputki tuotannossa
  6. Laatu-dashboard
  7. Keskeiset asiat

Trace grading: suoritusten pisteytys

Jäljitys (tracing) tallentaa, mitä agenttisi tekee. Se on välttämätöntä, mutta ei riittävää: kukaan ei lue kymmentätuhatta jäljitystä päivässä, ja ongelmat piilevät nimenomaan niissä, joita et koskaan avaa. Trace grading menee pidemmälle: se pisteyttää automaattisesti jokaisen suorituksen tunnistaakseen ongelmia, mitatakseen laatua ajan myötä ja ruokkiakseen jatkuvan parantamisen kiertoa.

Trace gradingin käsite

Jokainen agenttisi tuottama jäljitys sisältää koko suorituksen: käyttäjän viestin, työkalukutsut, välivastaukset ja lopullisen vastauksen. Trace grading analysoi nämä jäljitykset ja määrittää pisteet kriteeriesi perusteella. Siirryt lokista, jota tarkastelet jälkikäteen, mittariin, jota valvot jatkuvasti, ja kysymys “Miten agentti suoriutuu juuri nyt?” lakkaa olemasta arvaus.

Automaattinen pisteytys sääntöjen avulla

Yksinkertaisin taso käyttää ohjelmallisia sääntöjä jokaisen jäljityksen pisteyttämiseen. Jokainen sääntö lähtee täydestä 1,0:n pisteestä ja vähentää pisteitä havaintojensa perusteella. Suoritus, joka kestää yli kymmenen sekuntia, menettää 0,2 pistettä, ei siksi että tulos olisi väärä, vaan koska käyttäjä todennäköisesti luovutti. Yli viisitoista kierrosta maksaa 0,3 pistettä: se on merkki agentista, joka pyörii kehää kahden työkalun välillä. Jokainen työkaluvirhe vähentää 0,1 pistettä. Laukaistut suojakaiteet (guardrails) merkitään ilman sakkoa – ne tekivät tehtävänsä – mutta alle kymmenen merkin pituinen vastaus maksaa yksinään puoli pistettä, sillä vaikenava agentti on hyödytön agentti.

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

details-sanakirja seuraa aina pistemäärää: ilman sitä tietäisit suorituksen saaneen 0,5 pistettä, mutta et tietäisi miksi. Nämä kynnykset ovat sinun, eivät universaaleja vakioita – tutkimusagentti sietää viisitoista kierrosta, kun taas kassan avustajan on vastattava kolmessa.

LLM-pohjainen pisteytys

Säännöt eivät näe sisältöä. Nopea, lyhyt ja kohtelias vastaus, joka menee täysin ohi asian, saa 1,0 pistettä. Tarkempaa arviointia varten käytä mallia pisteyttämään jäljitykset substanssin perusteella: relevanssi, tarkkuus ja sävy, kukin asteikolla 1–5, yhdessä tunnistettujen ongelmien ja parannusehdotusten kanssa. Jälleen kerran strukturoitu tuloste Pydanticin kautta tekee pisteistä yhdisteltäviä vapaan muotoisen kommentoinnin sijaan.

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

Kehote välittää myös käytetyt työkalut ja keston: tuomari voi näin moittia agenttia vastaamisesta ilman katalogin konsultointia, mikä pelkän vastauksen lukeminen ei mahdollistaisi.

Pisteytysputki tuotannossa

Yhdistä nyt molemmat lähestymistavat räjäyttämättä budjettiasi. Jokaisen jäljityksen pisteyttäminen LLM:llä tuotantomäärillä kertoo inferenssilaskusi; pelkkien sääntöjen käyttö jättää sinut sokeaksi substanssille. Alla oleva putki käyttää suodatinta: kaikki jäljitykset käyvät läpi ohjelmallisen pisteytyksen, joka on nopeaa ja ilmaista, ja vain alle 0,7:n tuloksen saaneet menevät tuomarille. Tuomarin pisteet, kolmen 1–5-arvosanan summa, skaalataan jakamalla 15:llä välille 0–1, jotta ne pysyvät vertailukelpoisina ensimmäisen kanssa. Alle 0,5:n jäljitys siirtyy kriittisten hälytysten listalle.

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

Raportti säilyttää minimipistemäärän ja otoksen kymmenestä huonoimmasta jäljityksestä: siitä tutkimus alkaa, ei koskaan keskiarvosta.

Laatu-dashboard

Yksittäinen piste ei merkitse mitään; sen kehityssuunta kertoo oleellista. Kirjoittamalla päivittäisen raportin JSONL-tiedostoon rakennat aikasarjan, jonka mikä tahansa visualisointityökalu voi lukea, ja voit automaattisesti verrata viimeisintä pistettä edelliseen. Yli 0,1:n pudotus laukaisee regressiohälytyksen – ja sen korrelointi päivän käyttöönottojen (deployments) kanssa osoittaa yleensä syyllisen minuuteissa.

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

Kahden peräkkäisen päivän vertaaminen on herkkää kohinalle: pienillä volyymeillä suosii liukuvaa keskiarvoa ennen kuin julistat regression, muuten jahtastat tilastollista harhaa.

Keskeiset asiat

  • Trace grading pisteyttää automaattisesti jokaisen agenttisi suorituksen
  • Ohjelmalliset säännöt (viive, virheet, pituus) ovat nopeita ja luotettavia
  • LLM-pisteytys arvioi relevanssia, tarkkuutta ja sävyä
  • Yhdistä molemmat: nopeat säännöt suodatukseen, LLM rajatapauksiin
  • Seuraa pisteitä ajan myötä havaitaksesi regressiot
  • Kriittiset hälytykset (pisteet < 0,5) vaativat tutkimusta