Премини към основното съдържание
Български— Изберете език
Меню

Оценяване на следи: оценяване на изпълненията

Урок 23 от 25 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Оценяване на следи: оценяване на изпълненията
  2. Концепцията за оценяване на следи
  3. Автоматично оценяване с правила
  4. Оценяване, базирано на LLM
  5. Конвейер за оценяване в продукция
  6. Табло за качество
  7. Ключови изводи

Оценяване на следи: оценяване на изпълненията

Проследяването (tracing) записва какво прави Вашият агент. Това е от съществено значение, но не е достатъчно: никой не чете десет хиляди следи на ден, а проблемите се крият точно в тези, които никога не отваряте. Оценяването на следи (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 при обеми на продукция умножава сметката Ви за изводи (inference); използването само на правила Ви оставя слепи за същността. Конвейерът по-долу прилага филтър: всички следи минават през програмно оценяване, което е бързо и безплатно, и само тези, падащи под 0.7, отиват при съдията. Оценката на съдията, сумата от три рейтинга от 1 до 5, се мащабира до 0–1 чрез деление на 15, за да остане сравнима с първата. Под 0.5, следата се присъединява към списъка с критични предупреждения.

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

Сравняването на два последователни дни остава чувствително към шум: при нисък обем предпочитайте плъзгаща се средна стойност, преди да обявите регресия, в противен случай ще преследвате статистически случайност.

Ключови изводи

  • Оценяването на следи автоматично оценява всяко изпълнение на Вашия агент
  • Програмните правила (латентност, грешки, дължина) са бързи и надеждни
  • Оценяването чрез LLM оценява релевантността, точността и тона
  • Комбинирайте двете: бързи правила за филтриране, LLM за гранични случаи
  • Следете оценките във времето, за да откриете регресии
  • Критичните предупреждения (оценка < 0.5) трябва да задействат разследване