Skip to content

Avaliadores programáticos

Pontue trajetórias de agente e saídas de texto automaticamente com a biblioteca de avaliadores do Potato, livre de Flask — correspondência determinística de trajetória, correção de uso de ferramentas, LLM-as-judge sem referência e heurísticas (correspondência exata, distância de edição, JSON, embeddings).

O Potato inclui uma biblioteca de avaliadores com poucas dependências que pontua trajetórias de agente e saídas de texto automaticamente: as verificações determinísticas e de LLM-as-judge que complementam a anotação humana. Os mesmos avaliadores rodam dentro de experimentos, do motor de automação e do plugin de CI, e também funcionam de forma independente.

Todo avaliador retorna um resultado normalizado — um score (por convenção 0.0–1.0, quanto maior melhor), um value, um comment e metadata — de modo que avaliadores determinísticos, heurísticos e de LLM-judge são intercambiáveis. As trajetórias podem ser passadas como listas de mensagens no estilo OpenAI, como turnos conversation canônicos do Potato ou como um CanonicalTrace; a normalização é automática.

Correspondência de trajetória (determinística)

Compara a sequência de chamadas de ferramenta de um agente com uma referência.

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…
strictchamadas de ferramenta idênticas, na mesma ordem
unorderedmesmo multiconjunto de chamadas de ferramenta, em qualquer ordem
subseto agente chamou apenas ferramentas que aparecem na referência
superseto agente chamou pelo menos as ferramentas da referência (extras permitidos)

A comparação de argumentos é configurável de forma independente (exact / ignore / subset / superset), com substituições por ferramenta.

Correção de uso de ferramentas

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 (sem referência)

Pontua a qualidade da trajetória sem uma referência ouro, já que existem muitos caminhos de agente válidos. Reutiliza a mesma configuração de endpoint ai_support do restante do 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)

Avaliadores heurísticos / de código

ExactMatch, Contains, RegexMatch, EditDistance, JSONValid, JSONSchemaMatch e EmbeddingDistance (importação preguiçosa de ML ou uma função de embedding injetada). Importar a biblioteca nunca puxa a pilha de ML.

Avaliação de trajetória em grafo (LangGraph)

Para avaliação de nós/transições do LangGraph, o Potato reutiliza o pacote agentevals, sob licença MIT, por meio de um adaptador preguiçoso — instale-o apenas se precisar.

Configurando avaliadores de forma declarativa

Um registro mapeia nomes → avaliadores para que possam ser configurados em YAML (usado pelo executor de experimentos e pelo motor de automação):

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

Relacionados