Skip to content

Valutatori programmatici

Assegna punteggi automatici a traiettorie di agenti e output testuali con la libreria di valutatori di Potato, indipendente da Flask: corrispondenza deterministica di traiettoria, correttezza dell'uso degli strumenti, LLM-as-judge senza riferimento ed euristiche (corrispondenza esatta, distanza di edit, JSON, embedding).

Potato include una libreria di valutatori con poche dipendenze che assegna punteggi automatici a traiettorie di agenti e output testuali: i controlli deterministici e LLM-as-judge che completano l'annotazione umana. Gli stessi valutatori girano dentro gli esperimenti, il motore di automazione e il plugin CI, e funzionano anche da soli.

Ogni valutatore restituisce un risultato normalizzato — uno score (per convenzione 0.0–1.0, più alto è meglio), un value, un comment e metadata — così i valutatori deterministici, euristici e LLM-judge sono intercambiabili. Le traiettorie possono essere passate come elenchi di messaggi in stile OpenAI, come turni conversation canonici di Potato o come una CanonicalTrace; la normalizzazione è automatica.

Corrispondenza di traiettoria (deterministica)

Confronta la sequenza di chiamate agli strumenti di un agente con un riferimento.

python
from potato.evaluators import TrajectoryMatchEvaluator
 
ev = TrajectoryMatchEvaluator(
    mode="unordered",               # strict | unordered | subset | superset
    tool_args_match_mode="subset",  # exact | ignore | subset | superset
    tool_args_match_overrides={"search": "ignore"},
)
result = ev.evaluate(outputs=agent_trace, reference_outputs=gold_trace)
modePassa quando…
strictchiamate agli strumenti identiche, stesso ordine
unorderedstesso multinsieme di chiamate agli strumenti, in qualsiasi ordine
subsetl'agente ha chiamato solo strumenti presenti nel riferimento
supersetl'agente ha chiamato almeno gli strumenti del riferimento (extra ammessi)

Il confronto degli argomenti è configurabile in modo indipendente (exact / ignore / subset / superset), con override per singolo strumento.

Correttezza dell'uso degli strumenti

python
from potato.evaluators import ToolUseEvaluator, ToolCallAccuracyEvaluator
 
# Did the agent call a specific tool (optionally with expected args)?
ToolUseEvaluator(expected_tool="submit", expected_args={"id": 1}).evaluate(outputs=trace)
 
# What fraction of reference tool calls did the agent reproduce? (partial credit)
ToolCallAccuracyEvaluator(args_match_mode="exact").evaluate(outputs=trace, reference_outputs=gold)

LLM-as-judge (senza riferimento)

Valuta la qualità della traiettoria senza un riferimento gold, dato che esistono molti percorsi validi per un agente. Riutilizza la stessa configurazione di endpoint ai_support del resto di Potato (OpenAI, Anthropic, Ollama, vLLM, …).

python
from potato.evaluators import LLMTrajectoryJudge
 
judge = LLMTrajectoryJudge(config=task_config, continuous=True)  # 0.0–1.0 score
result = judge.evaluate(outputs=agent_trace, inputs=task_prompt)

Valutatori euristici / di codice

ExactMatch, Contains, RegexMatch, EditDistance, JSONValid, JSONSchemaMatch ed EmbeddingDistance (import ML pigro o una funzione di embedding iniettata). Importare la libreria non carica mai lo stack ML.

Valutazione di traiettorie a grafo (LangGraph)

Per la valutazione di nodi/transizioni di LangGraph, Potato riutilizza il pacchetto agentevals con licenza MIT tramite un adattatore pigro: installalo solo se ti serve.

Configurare i valutatori in modo dichiarativo

Un registro mappa i nomi ai valutatori così da poterli configurare in YAML (usato dall'esecutore degli esperimenti e dal motore di automazione):

python
from potato.evaluators import build_evaluator, list_evaluators
 
ev = build_evaluator("trajectory_match", {"mode": "unordered"})
result = ev.evaluate(outputs=trace, reference_outputs=gold)

Correlati