Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Betygssättning av spår: poängsättning av körningar

Lektion 23 av 25 Uppdaterad 29 juli 2026 Utvecklare
På denna sida
  1. Betygssättning av spår: poängsättning av körningar
  2. Konceptet med betygssättning av spår
  3. Automatisk betygssättning med regler
  4. LLM-baserad betygssättning
  5. Betygssättningspipeline i produktion
  6. Kvalitetsdashboard
  7. Viktiga punkter

Betygssättning av spår: poängsättning av körningar

Spårning registrerar vad din agent gör. Det är avgörande, men det räcker inte: ingen läser tiotusen spår om dagen, och problemen gömmer sig just i de du aldrig öppnar. Betygssättning av spår går ett steg längre: den poängsätter automatiskt varje körning för att upptäcka problem, mäta kvalitet över tid och mata en loop för kontinuerlig förbättring.

Konceptet med betygssättning av spår

Varje spår din agent producerar innehåller hela körningen: användarens meddelande, verktygsanrop, mellanliggande svar och det slutgiltiga svaret. Betygssättning av spår analyserar dessa spår och tilldelar poäng baserat på dina kriterier. Du går från en logg du konsulterar i efterhand till en metrik du övervakar kontinuerligt, och frågan “Hur presterar agenten just nu?” slutar vara ett gissningsspel.

Automatisk betygssättning med regler

Den enklaste nivån använder programmatiska regler för att poängsätta varje spår. Varje regel utgår från en perfekt poäng på 1,0 och drar av poäng baserat på vad den observerar. En körning som tar längre tid än tio sekunder förlorar 0,2 poäng, inte för att resultatet är fel utan för att användaren sannolikt gav upp. Fler än femton turer kostar 0,3 poäng: det är signaturerna för en agent som snurrar i cirklar mellan två verktyg. Varje verktygsfel drar av 0,1 poäng. Aktiverade skyddsräcken flaggas utan straff – de gjorde sitt jobb – men ett svar kortare än tio tecken kostar ensam en halv poäng, för en tyst agent är en värdelös 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,
    )

Ordboken details följer alltid med poängen: utan den skulle du veta att en körning fick 0,5 men inte varför. Dessa tröskelvärden är dina, inte universella konstanter – en forskningsagent tolererar femton turer där en kassaassistent måste svara inom tre.

LLM-baserad betygssättning

Regler ser inte innehållet. Ett snabbt, kort, artigt svar som helt missar poängen kommer att få 1,0. För finare utvärdering använder du en modell för att poängsätta spår efter substans: relevans, noggrannhet och ton, vardera från 1 till 5, tillsammans med identifierade problem och förbättringsförslag. Återigen gör strukturerad utmatning via Pydantic poängen aggregerbara istället för att producera fri text-kommentarer.

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

Prompten skickar också de anropade verktygen och varaktigheten: domaren kan därmed fälla agenten för att svara utan att konsultera katalogen, vilket att bara läsa svaret inte skulle tillåta.

Betygssättningspipeline i produktion

Kombinera nu båda metoderna utan att spränga din budget. Att poängsätta varje spår med en LLM i produktionsvolym multiplicerar din inferensräkning; att bara använda regler lämnar dig blind för substans. Pipelinen nedan applicerar ett filter: alla spår går igenom programmatisk betygssättning, vilket är snabbt och gratis, och endast de som hamnar under 0,7 skickas till domaren. Domarens poäng, summan av tre betyg på 1–5, skalas till 0–1 genom division med 15 för att förbli jämförbar med den första. Under 0,5 hamnar spåret på listan över kritiska varningar.

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

Rapporten behåller minimipoängen och ett urval av de tio sämsta spåren: det är där en undersökning börjar, aldrig med medelvärdet.

Kvalitetsdashboard

En ensam poäng betyder ingenting; dess utveckling informerar. Genom att skriva den dagliga rapporten till en JSONL-fil bygger du en tidsserie som alla visualiseringsverktyg kan läsa, och du kan automatiskt jämföra den senaste punkten med den föregående. Ett fall på mer än 0,1 utlöser en regressionsvarning – och att korrelera den med dagens distributioner pekar oftast ut boven inom minuter.

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

Att jämföra två på varandra följande dagar förblir känsligt för brus: vid låg volym, föredra ett glidande medelvärde innan du skriker regression, annars jagar du en statistisk tillfällighet.

Viktiga punkter

  • Betygssättning av spår poängsätter automatiskt varje körning av din agent
  • Programmatiska regler (latens, fel, längd) är snabba och tillförlitliga
  • LLM-betygssättning utvärderar relevans, noggrannhet och ton
  • Kombinera båda: snabba regler för filtrering, LLM för gränsfall
  • Spåra poäng över tid för att upptäcka regressioner
  • Kritiska varningar (poäng < 0,5) måste utlösa en undersökning