Βαθμολόγηση ιχνών: αξιολόγηση εκτελέσεων
Σε αυτήν τη σελίδα
Βαθμολόγηση ιχνών: αξιολόγηση εκτελέσεων
Η ιχνηλάτηση καταγράφει τις ενέργειες του πράκτορά σας. Αυτό είναι απαραίτητο, αλλά δεν αρκεί: κανείς δεν διαβάζει δέκα χιλιάδες ίχνη την ημέρα, και τα προβλήματα κρύβονται ακριβώς σε αυτά που δεν ανοίγετε ποτέ. Η βαθμολόγηση ιχνών (trace grading) πηγαίνει ένα βήμα παραπέρα: βαθμολογεί αυτόματα κάθε εκτέλεση για να εντοπίσει ζητήματα, να μετρήσει την ποιότητα με την πάροδο του χρόνου και να τροφοδοτήσει έναν βρόχο συνεχούς βελτίωσης.
Η έννοια της βαθμολόγησης ιχνών
Κάθε ίχνος που παράγει ο πράκτοράς σας περιέχει την πλήρη εκτέλεση: το μήνυμα του χρήστη, τις κλήσεις εργαλείων, τις ενδιάμεσες απαντήσεις και την τελική απάντηση. Η βαθμολόγηση ιχνών αναλύει αυτά τα ίχνη και αναθέτει βαθμολογίες με βάση τα κριτήριά σας. Μεταβαίνετε από ένα αρχείο καταγραφής που συμβουλεύεστε εκ των υστέρων σε μια μετρική που παρακολουθείτε συνεχώς, και το ερώτημα «Πώς αποδίδει ο πράκτορας αυτή τη στιγμή;» παύει να είναι μια εικασία.
Αυτόματη βαθμολόγηση με κανόνες
Το απλούστερο επίπεδο χρησιμοποιεί προγραμματιστικούς κανόνες για τη βαθμολόγηση κάθε ίχνους. Κάθε κανόνας ξεκινά από την τέλεια βαθμολογία 1,0 και αφαιρεί πόντους με βάση ό,τι παρατηρεί. Μια εκτέλεση που διαρκεί περισσότερο από δέκα δευτερόλεπτα χάνει 0,2 πόντους, όχι επειδή το αποτέλεσμα είναι λάθος, αλλά επειδή ο χρήστης πιθανότατα εγκατέλειψε. Περισσότεροι από δεκαπέντε γύροι κοστίζουν 0,3 πόντους: αυτό είναι το σημάδι ενός πράκτορα που στριφογυρίζει άσκοπα μεταξύ δύο εργαλείων. Κάθε σφάλμα εργαλείου αφαιρεί 0,1 πόντους. Τα ενεργοποιημένα προστατευτικά όρια (guardrails) επισημαίνονται χωρίς ποινή—έκαναν τη δουλειά τους—αλλά μια απάντηση μικρότερη από δέκα χαρακτήρες κοστίζει από μόνη της μισό πόντο, επειδή ένας σιωπηλός πράκτορας είναι ένας άχρηστος πράκτορας.
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 συνοδεύει πάντα τη βαθμολογία: χωρίς αυτό, θα ξέρατε ότι μια εκτέλεση πήρε 0,5 αλλά όχι το γιατί. Αυτά τα κατώφλια είναι δικά σας, όχι καθολικές σταθερές—ένας ερευνητικός πράκτορας ανέχεται δεκαπέντε γύρους, ενώ ένας βοηθός ολοκλήρωσης αγοράς πρέπει να απαντήσει σε τρεις.
Βαθμολόγηση με βάση το LLM
Οι κανόνες δεν βλέπουν το περιεχόμενο. Μια γρήγορη, σύντομη, ευγενική απάντηση που χάνει εντελώς την ουσία θα πάρει βαθμολογία 1,0. Για λεπτομερέστερη αξιολόγηση, χρησιμοποιήστε ένα μοντέλο για να βαθμολογήσει τα ίχνη ως προς την ουσία: συνάφεια, ακρίβεια και τόνο, καθένα από 1 έως 5, μαζί με εντοπισμένα ζητήματα και προτάσεις βελτίωσης. Και πάλι, η δομημένη έξοδος μέσω του Pydantic καθιστά τις βαθμολογίες συγκεντρώσιμες αντί να παράγει σχόλια ελεύθερης μορφής.
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
Το prompt περνά επίσης τα εργαλεία που κλήθηκαν και τη διάρκεια: ο κριτής μπορεί έτσι να καταλογίσει σφάλμα στον πράκτορα για απάντηση χωρίς διαβούλευση με τον κατάλογο, κάτι που η ανάγνωση μόνο της απάντησης δεν θα επέτρεπε.
Αγωγός βαθμολόγησης σε παραγωγή
Τώρα συνδυάστε και τις δύο προσεγγίσεις χωρίς να εκτοξεύσετε τον προϋπολογισμό σας. Η βαθμολόγηση κάθε ίχνους με ένα LLM σε όγκο παραγωγής πολλαπλασιάζει τον λογαριασμό συμπερασμάτων σας· η χρήση μόνο κανόνων σας αφήνει τυφλούς ως προς την ουσία. Ο παρακάτω αγωγός εφαρμόζει ένα φίλτρο: όλα τα ίχνη περνούν από προγραμματιστική βαθμολόγηση, η οποία είναι γρήγορη και δωρεάν, και μόνο εκείνα που πέφτουν κάτω από 0,7 πηγαίνουν στον κριτή. Η βαθμολογία του κριτή, το άθροισμα τριών βαθμολογιών 1–5, κλιμακώνεται στο 0–1 διαιρώντας με το 15 για να παραμείνει συγκρίσιμη με την πρώτη. Κάτω από 0,5, το ίχνος joins τη λίστα κρίσιμων ειδοποιήσεων.
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())
Η αναφορά διατηρεί την ελάχιστη βαθμολογία και ένα δείγμα από τα δέκα χειρότερα ίχνη: εκεί ξεκινά μια διερεύνηση, ποτέ με τον μέσο όρο.
Πίνακας ελέγχου ποιότητας
Μια μεμονωμένη βαθμολογία δεν σημαίνει τίποτα· η τροχιά της είναι που ενημερώνει. Γράφοντας την ημερήσια αναφορά σε ένα αρχείο JSONL, χτίζετε μια χρονοσειρά που οποιοδήποτε εργαλείο οπτικοποίησης μπορεί να διαβάσει, και μπορείτε να συγκρίνετε αυτόματα το τελευταίο σημείο με το προηγούμενο. Μια πτώση μεγαλύτερη από 0,1 ενεργοποιεί μια ειδοποίηση παλινδρόμησης—και η συσχέτισή της με τις αναπτύξεις της ημέρας σας συνήθως δείχνει τον υπαίτιο μέσα σε λίγα λεπτά.
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
Η σύγκριση δύο διαδοχικών ημερών παραμένει ευαίσθητη στον θόρυβο: σε χαμηλό όγκο, προτιμήστε έναν κινητό μέσο όρο πριν φωνάξετε «παλινδρόμηση», διαφορετικά θα κυνηγάτε μια στατιστική anomalία.
Βασικά σημεία
- Η βαθμολόγηση ιχνών βαθμολογεί αυτόματα κάθε εκτέλεση του πράκτορά σας
- Οι προγραμματιστικοί κανόνες (λανθάνουσα κατάσταση, σφάλματα, μήκος) είναι γρήγοροι και αξιόπιστοι
- Η βαθμολόγηση με LLM αξιολογεί τη συνάφεια, την ακρίβεια και τον τόνο
- Συνδυάστε και τα δύο: γρήγοροι κανόνες για φιλτράρισμα, LLM για οριακές περιπτώσεις
- Παρακολουθήστε τις βαθμολογίες με την πάροδο του χρόνου για να εντοπίσετε παλινδρομήσεις
- Οι κρίσιμες ειδοποιήσεις (βαθμολογία < 0,5) πρέπει να ενεργοποιούν διερεύνηση