Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Gradazzjoni tat-traċċi: punteġġ tal-eżekuzzjonijiet

Lezzjoni 23 / 25 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Gradazzjoni tat-traċċi: punteġġ tal-eżekuzzjonijiet
  2. Il-kunċett tal-gradazzjoni tat-traċċi
  3. Gradazzjoni awtomatika bir-regoli
  4. Gradazzjoni bbażata fuq LLM
  5. Pipeline tal-gradazzjoni fil-produzzjoni
  6. Dashboard tal-kwalità
  7. Punti Ewlenin

Gradazzjoni tat-traċċi: punteġġ tal-eżekuzzjonijiet

It-traċċar jirreġistra x’jagħmel l-aġent tiegħek. Dan huwa essenzjali, iżda mhux biżżejjed: ħadd ma jaqra għaxart elef traċċa kuljum, u l-problemi jinħbew eżattament f’dawk li qatt ma tiftaħ. Il-gradazzjoni tat-traċċi tmur lil hinn: tivvaluta awtomatikament kull eżekuzzjoni biex tindividwa problemi, tkejjel il-kwalità matul iż-żmien, u titma’ ċiklu kontinwu ta’ titjib.

Il-kunċett tal-gradazzjoni tat-traċċi

Kull traċċa li jipproduċi l-aġent tiegħek fiha l-eżekuzzjoni sħiħa: il-messaġġ tal-utent, is-sejħiet tal-għodod, ir-risponsi intermedjarji, u t-tweġiba finali. Il-gradazzjoni tat-traċċi tanalizza dawn it-traċċi u taħtri punteġġi bbażati fuq il-kriterji tiegħek. Inti timxi minn reġistru li tikkonsulta wara l-fatt għal metrika li timmonitorja kontinwament, u l-mistoqsija “Kif qed jaħdem l-aġent bħalissa?” tieqaf tkun suppożizzjoni.

Gradazzjoni awtomatika bir-regoli

Il-livell l-aktar sempliċi juża regoli programmatiċi biex jivvaluta kull traċċa. Kull regola tibda minn punteġġ perfett ta’ 1.0 u tnaqqas punti abbażi ta’ dak li tosserva. Eżekuzzjoni li tieħu aktar minn għaxar sekondi titlef 0.2 punti, mhux għax ir-riżultat huwa żbaljat iżda għax l-utent x’aktarx irriżenja. Aktar minn ħmistax-il dawra tispiċċa bi tnaqqis ta’ 0.3 punti: din hija s-sinjal ta’ aġent idur f’ċirku bejn żewġ għodod. Kull żball fl-għodda jnaqqas 0.1 punti. Il-guardrails attivati jiġu mmarkati mingħajr penali—huma għamlu xogħolhom—iżda tweġiba iqsar minn għaxar karattru waħedha tispiċċa b’nofs punt, għax aġent sieket huwa aġent inutli.

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

Id-dizzjunarju details dejjem jakkumpanja l-punteġġ: mingħajru, tkun taf li eżekuzzjoni skurjat 0.5 iżda mhux għaliex. Dawn il-limiti huma tiegħek, mhux kostanti universali—aġent tar-riċerka jittollera ħmistax-il dawra fejn assistent tal-ħlas irid iwieġeb fi tlieta.

Gradazzjoni bbażata fuq LLM

Ir-regoli ma jarawx il-kontenut. Tweġiba mgħaġġla, qasira u polite li titlef il-punt kompletament se tiskurja 1.0. Għal evalwazzjoni aktar fina, uża mudell biex tivvaluta t-traċċi fuq is-sustanza: rilevanza, preċiżjoni u ton, kull waħda minn 1 sa 5, flimkien ma’ problemi identifikati u suġġerimenti għat-titjib. Mill-ġdid, output strutturat permezz ta’ Pydantic jagħmel il-punteġġi aggregabbli minflok ma jipproduċi kummentarju f’forma ħielsa.

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

Il-prompt jgħaddi wkoll l-għodod imsejħa u d-durata: b’hekk il-ġudiku jista’ jilmenta li l-aġent wieġeb mingħajr ma kkonsulta l-katalgu, ħaġa li l-qari tat-tweġiba waħedha ma kienx jippermetti.

Pipeline tal-gradazzjoni fil-produzzjoni

Issa għaqqad iż-żewġ approċċi mingħajr ma tinfaqa’ l-baġit tiegħek. Il-punteġġ ta’ kull traċċa b’LLM f’volum ta’ produzzjoni jimmultiplika l-kont tal-inferenza tiegħek; l-użu ta’ regoli biss iħallik għami għas-sustanza. Il-pipeline hawn taħt tapplika filtru: it-traċċi kollha jgħaddu mill-gradazzjoni programmatika, li hija mgħaġġla u bla ħlas, u dawk biss li jaqgħu taħt 0.7 jmorru għand il-ġudiku. Il-punteġġ tal-ġudiku, is-somma ta’ tliet klassifikazzjonijiet ta’ 1–5, jiġi skalat għal 0–1 billi jiġi diviż b’15 biex jibqa’ komparabbli mal-ewwel wieħed. Taħt 0.5, it-traċċa tidħol fil-lista tal-allerti kritiċi.

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

Ir-rapport iżomm l-inqas punteġġ u kampjun tal-għaxar traċċi l-agħar: hemmhekk tibda investigazzjoni, qatt mhux bil-medja.

Dashboard tal-kwalità

Punteġġ wieħed ma jfisser xejn; it-traċċatorja tiegħu hija li tinforma. Billi tikteb ir-rapport ta’ kuljum f’fajl JSONL, tibni serje temporali li kwalunkwe għodda ta’ viżwalizzazzjoni tista’ taqra, u tista’ tqabbel awtomatikament l-aħħar punt ma’ dak ta’ qablu. Tnaqqis ta’ aktar minn 0.1 jattiva allert ta’ regrezzjoni—u l-korrelazzjoni tiegħu mad-deployments tal-ġurnata tiegħek ħafna drabi turi l-ħati fi żmien minuti.

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

It-tqabbil ta’ żewġ ijiem konsekuttivi jibqa’ sensittiv għall-istorbju: fuq volum baxx, ippreferi medja li tiċċaqlaq qabel ma tgħajjat regrezzjoni, inkella se tkun qed tfittex anomalija statistika.

Punti Ewlenin

  • Il-gradazzjoni tat-traċċi tivvaluta awtomatikament kull eżekuzzjoni tal-aġent tiegħek
  • Ir-regoli programmatiċi (latenza, żbalji, tul) huma mgħaġġla u affidabbli
  • Il-gradazzjoni b’LLM tevalwa r-rilevanza, il-preċiżjoni u t-ton
  • Għaqqad iż-żewġ metodi: regoli mgħaġġla għall-filtrar, LLM għall-każijiet limitrofi
  • Segwi l-punteġġi matul iż-żmien biex tindividwa regrezzjonijiet
  • Allerti kritiċi (punteġġ < 0.5) iridu jattivaw investigazzjoni