Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Grádú lorg: scóráil feidhmithe

Ceacht 23 as 25 Nuashonraithe 29 Iúil 2026 Forbróir
Ar an leathanach seo
  1. Grádú lorg: scóráil feidhmithe
  2. Coincheap an ghrádaithe lorg
  3. Grádú uathoibríoch le rialacha
  4. Grádú bunaithe ar LLM
  5. Píblíne grádaithe i léiriú
  6. Deasc bhord cáilíochta
  7. Príomhphointí

Grádú lorg: scóráil feidhmithe

Taifeadann lorgú cad a dhéanann do ghníomhaire. Tá sé sin riachtanach, ach ní leor é: ní léann aon duine deich míle lorg in aghaidh an lae, agus folaithe go díreach sna cinn nach osclaíonn tú riamh atá na fadhbanna. Téann grádú lorg níos faide: déanann sé scóráil uathoibríoch ar gach feidhmiú chun fadhbanna a aimsiú, cáilíocht a thomhas le himeacht ama, agus lúb feabhsaithe leanúnaigh a chothú.

Coincheap an ghrádaithe lorg

Bíonn an feidhmiú iomlán i ngach lorg a tháirgeann do ghníomhaire: teachtaireacht an úsáideora, glaonna uirlisí, freagraí idirmheánacha, agus an freagra deiridh. Déanann grádú lorg anailís ar na lorg seo agus sannann sé scóir bunaithe ar do chritéir féin. Bogann tú ó loga a chuireann tú i gcomhairle tar éis na himeachta go méadracht a dhéanann tú monatóireacht air go leanúnach, agus stopann an cheist “Conas atá an gníomhaire ag feidhmiú faoi láthair?” bheith ina thuar.

Grádú uathoibríoch le rialacha

Úsáideann an leibhéal is simplí rialacha cláraithe chun scóráil a dhéanamh ar gach lorg. Tosaíonn gach riail le scór foirfe 1.0 agus baintear pointí de bhunaithe ar an méid a fheiceann sí. Cailleann feidhmiú a thógann níos mó ná deich soicind 0.2 pointe, ní mar gheall go bhfuil an toradh mícheart ach toisc gur dócha gur éirigh an t-úsáideoir as. Costas 0.3 pointe a bheith níos mó ná cúig throinn déag: sin an comhartha ar ghníomhaire ag casadh i gciorcail idir dhá uirlis. Bainear 0.1 pointe de gach earráid uirlise. Cuirtear bratach ar ráillí cosanta a spreagtar gan pionós—rinne siad a gcuid oibre—ach costálann freagra níos giorra ná deich gcarachtar leathphointe ina aonar, mar is gníomhaire gan úsáid é gníomhaire ciúin.

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

Bíonn an foclóir details i gcomhpháirt leis an scór i gcónaí: gan é, bheadh a fhios agat go bhfuair feidhmiú scór 0.5 ach ní bheadh a fhios agat cén fáth. Is leatsa na tairseacha seo, ní tairisigh uilíocha iad—fuilingíonn gníomhaire taighde cúig throinn déag nuair a chaithfidh cúntóir seiceála freagra a thabhairt i dtrí cinn.

Grádú bunaithe ar LLM

Ní fheiceann rialacha ábhar. Scórálfadh freagra tapa, gairid, cúirtéil a chailleann an pointe go hiomlán 1.0. Chun meastóireacht níos mine a dhéanamh, úsáid samhail chun lorg a scóráil ar ábhar: ábharthacht, cruinneas, agus tón, gach ceann ó 1 go 5, mar aon le fadhbanna a aithníodh agus moltaí feabhsaithe. Arís, déanann aschur struchtúrtha trí Pydantic na scóir in-ghrúpáilte seachas trácht saorchruth a tháirgeadh.

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

Cuireann an leid na huirlisí a glaodh agus an fad ama ar fáil freisin: mar sin is féidir leis an mbreitheamh locht a chur ar an ngníomhaire as freagra a thabhairt gan dul i gcomhairle leis an gcatagóir, rud nach ligfeadh léamh na freagra amháin.

Píblíne grádaithe i léiriú

Anois comhcheangail an dá chur chuige gan do bhuiséad a shéideadh. Méadaíonn scóráil gach lorg le LLM ag toirt léirithe do bhille infearaince; fágann úsáid rialacha amháin dall thú ar ábhar. Cuirtear scagaire i bhfeidhm sa phíblíne thíos: téann gach lorg trí ghrádú cláraithe, atá tapa agus saor in aisce, agus ní théann ach iad siúd a thiteann faoi 0.7 chuig an mbreitheamh. Scálaítear scór an bhreithimh, suim trí ráta 1–5, go 0–1 trí roinnt ar 15 chun fanacht inchomparáide leis an gcéad cheann. Faoi 0.5, téann an lorg isteach sa liosta foláirimh chriticiúla.

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

Coinníonn an tuarascáil an scór íosta agus sampla de na deich lorg is measa: sin áit a dtosaíonn imscrúdú, riamh leis an meán.

Deasc bhord cáilíochta

Ní chiallaíonn scór amháin dada; is é a threocht a chuireann ar an eolas tú. Trí thuairisc laethúil a scríobh chuig comhad JSONL, tógann tú sraith ama is féidir le haon uirlis amhairc a léamh, agus is féidir leat an pointe is déanaí a chur i gcomparáid go huathoibríoch leis an gceann roimhe. Spreagann titim níos mó ná 0.1 foláireamh cúlaithe—agus de ghnáth léiríonn comhcheangal leis na himpleálacha a rinneadh an lá sin an lochtach laistigh de nóiméid.

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

Fanann comparáid idir dhá lá as a chéile íogair do thorann: ar thoirt íseal, is fearr meán gluaiseachta a úsáid sula nglaofar cúlú ort, nó beidh tú ag saothrú blip staitistiúil.

Príomhphointí

  • Déanann grádú lorg scóráil uathoibríoch ar gach feidhmiú de do ghníomhaire
  • Tá rialacha cláraithe (moill, earráidí, fad) tapa agus iontaofa
  • Déanann grádú LLM meastóireacht ar ábharthacht, cruinneas, agus tón
  • Comhcheangail an dá cheann: rialacha tapa le haghaidh scagtha, LLM do chásanna teorann
  • Rianaigh scóir le himeacht ama chun cúluithe a bhrath
  • Caithfidh foláirimh chriticiúla (scór < 0.5) imscrúdú a spreagadh