Anotação de Recompensa de Processo

Colete sinais de recompensa por etapa para treinar modelos de recompensa de processo com os modos de anotação de primeiro erro e por etapa. Exporte diretamente para os formatos de treinamento PRM, DPO e SWE-bench.

Novidade na v2.4.0

Os Modelos de Recompensa de Processo (PRMs) exigem rótulos de correção por etapa, em vez de uma única pontuação no nível do resultado. Treinar um PRM eficaz significa coletar anotações que identifiquem exatamente em que ponto de um trace de múltiplas etapas o agente errou, que tipo de erro ocorreu e se a recuperação era possível. Isso é fundamentalmente diferente da anotação baseada em resultado, em que você julga apenas o resultado final.

O Potato oferece dois modos de anotação otimizados para diferentes compensações entre velocidade e detalhe ao coletar dados de recompensa de processo. O modo de primeiro erro é projetado para rotulagem binária rápida: o anotador clica na primeira etapa incorreta, e todas as etapas subsequentes são marcadas automaticamente como comprometidas. O modo por etapa pede que o anotador avalie cada etapa de forma independente, produzindo sinais mais ricos ao custo de mais tempo de anotação.

Ambos os modos se integram à exibição de trace de código, à exibição de trace de agente e à exibição de agente web, de modo que você pode coletar recompensas de processo para qualquer tipo de trace de agente.

Modo de primeiro erro

No modo de primeiro erro, o anotador lê o trace sequencialmente e clica na primeira etapa em que o agente cometeu um erro. Todas as etapas anteriores à etapa clicada são rotuladas automaticamente como corretas. A etapa clicada e todas as subsequentes são rotuladas como incorretas (a etapa clicada como o "primeiro erro" e as demais como "posteriores ao erro").

Isso produz o formato exato de rótulo necessário para treinar PRMs binários: uma sequência de rótulos +1 seguida de um -1 no ponto do erro e -1 para todas as etapas restantes.

Configuração

yaml

annotation_schemes:
  - name: process_reward
    annotation_type: process_reward
    mode: first_error
    description: "Click the first step where the agent made a mistake"
 
    first_error:
      # Visual styling
      correct_color: "#22c55e"     # green for steps before the error
      error_color: "#ef4444"       # red for the first error step
      downstream_color: "#f97316"  # orange for steps after the error
      unmarked_color: "#6b7280"    # gray for steps not yet reviewed
 
      # Behavior
      require_confirmation: true   # ask "Are you sure?" before marking
      allow_no_error: true         # allow annotator to mark all steps correct
      show_step_content: true      # show step content in the annotation panel
 
      # Labels applied automatically
      labels:
        correct: "+1"
        first_error: "-1 (first error)"
        downstream: "-1 (downstream)"
        all_correct: "+1 (all correct)"

Fluxo de anotação

O anotador lê o trace de cima para baixo
As etapas começam não marcadas (cinza)
O anotador clica na primeira etapa incorreta
As etapas 0 a N-1 ficam verdes (corretas)
A etapa N fica vermelha (primeiro erro)
As etapas N+1 até o fim ficam laranja (posteriores)
Se o trace inteiro estiver correto, o anotador clica em "All Steps Correct"

Formato de saída

json

{
  "id": "trace_042",
  "annotations": {
    "process_reward": {
      "mode": "first_error",
      "first_error_step": 4,
      "total_steps": 8,
      "labels": [1, 1, 1, 1, -1, -1, -1, -1]
    }
  }
}

Quando o anotador marca todas as etapas como corretas, first_error_step é null e o array de rótulos contém apenas valores 1.

Modo por etapa

No modo por etapa, o anotador avalia cada etapa do trace de forma independente. Isso produz sinais mais ricos -- uma etapa pode ser "parcialmente correta" ou "desnecessária", em vez de apenas correta/incorreta. Também captura casos em que o agente se recupera de um erro, algo que o modo de primeiro erro não consegue representar.

Configuração

yaml

annotation_schemes:
  - name: process_reward
    annotation_type: process_reward
    mode: per_step
    description: "Rate each step independently"
 
    per_step:
      # Rating options
      labels:
        - value: "correct"
          display: "Correct"
          color: "#22c55e"
          score: 1.0
        - value: "partially_correct"
          display: "Partially Correct"
          color: "#eab308"
          score: 0.5
        - value: "incorrect"
          display: "Incorrect"
          color: "#ef4444"
          score: -1.0
        - value: "unnecessary"
          display: "Unnecessary"
          color: "#f97316"
          score: -0.5
        - value: "recovery"
          display: "Recovery from Error"
          color: "#3b82f6"
          score: 0.25
 
      # Optional error categorization for incorrect/partially correct steps
      error_categories:
        enabled: true
        categories:
          - "Wrong tool selected"
          - "Correct tool, wrong arguments"
          - "Hallucinated information"
          - "Repeated previous step"
          - "Logic error"
          - "Syntax error"
          - "Missed edge case"
          - "Unnecessary step"
          - "Other"
 
      # Behavior
      require_all_steps: true     # all steps must be rated before submission
      allow_notes: true           # optional text field per step
      show_running_score: true    # show cumulative reward score

Fluxo de anotação

Cada etapa do trace tem um widget de avaliação ao seu lado
O anotador seleciona um rótulo para cada etapa
Se a etapa for avaliada como "Incorrect" ou "Partially Correct" e as categorias de erro estiverem habilitadas, surge um menu suspenso para selecionar o tipo de erro
Um campo de notas opcional permite uma explicação em texto livre
Uma pontuação acumulada no topo mostra a recompensa corrente

Formato de saída

json

{
  "id": "trace_042",
  "annotations": {
    "process_reward": {
      "mode": "per_step",
      "total_steps": 6,
      "labels": [1.0, 1.0, -1.0, 0.25, 1.0, 1.0],
      "step_details": {
        "0": {"label": "correct"},
        "1": {"label": "correct"},
        "2": {
          "label": "incorrect",
          "error_category": "Wrong tool selected",
          "notes": "Agent used grep when it should have read the file directly"
        },
        "3": {
          "label": "recovery",
          "notes": "Agent recognized the mistake and tried a different approach"
        },
        "4": {"label": "correct"},
        "5": {"label": "correct"}
      },
      "cumulative_score": 2.75
    }
  }
}

Referência de configuração

Opções completas de configuração para o esquema de anotação de recompensa de processo:

yaml

annotation_schemes:
  - name: process_reward
    annotation_type: process_reward
    mode: first_error              # "first_error" or "per_step"
    description: "Process reward annotation"
 
    # Required for mode: first_error
    first_error:
      correct_color: "#22c55e"
      error_color: "#ef4444"
      downstream_color: "#f97316"
      unmarked_color: "#6b7280"
      require_confirmation: true
      allow_no_error: true
      show_step_content: true
 
    # Required for mode: per_step
    per_step:
      labels:
        - value: "correct"
          display: "Correct"
          color: "#22c55e"
          score: 1.0
        - value: "incorrect"
          display: "Incorrect"
          color: "#ef4444"
          score: -1.0
      error_categories:
        enabled: false
        categories: []
      require_all_steps: true
      allow_notes: false
      show_running_score: false
 
    # Common options
    target: agentic_steps          # bind to trace steps
    keyboard_shortcuts:
      enabled: true
      correct: "1"
      incorrect: "2"
      partially_correct: "3"
      unnecessary: "4"
      next_step: "j"
      prev_step: "k"

Exportação para formatos de treinamento

O Potato pode exportar anotações de recompensa de processo diretamente para os formatos usados por pipelines comuns de treinamento de PRM.

Formato de treinamento PRM

Exporte rótulos binários no nível de etapa para o treinamento de PRM:

bash

python -m potato.export \
  -i output/ \
  -f prm \
  -o results/prm_training_data.jsonl

Formato de saída:

json

{
  "trace_id": "trace_042",
  "steps": [
    {"content": "Search for Tokyo population", "label": 1},
    {"content": "Parse search results", "label": 1},
    {"content": "Search for NYC population", "label": -1},
    {"content": "Compare populations", "label": -1}
  ]
}

Pares de preferência DPO / RLHF

Quando você tem vários traces anotados para a mesma tarefa, exporte preferências par a par para treinamento DPO ou RLHF. O exportador emparelha traces em que um tem recompensa acumulada maior do que o outro:

bash

python -m potato.export \
  -i output/ \
  -f dpo \
  -o results/dpo_pairs.jsonl \
  --min-score-gap 0.5

Formato de saída:

json

{
  "prompt": "Fix the failing test in test_parser.py",
  "chosen": [
    {"role": "assistant", "content": "Step 1: Read the test file..."},
    {"role": "assistant", "content": "Step 2: Identify the bug..."}
  ],
  "rejected": [
    {"role": "assistant", "content": "Step 1: Run all tests..."},
    {"role": "assistant", "content": "Step 2: Edit a random file..."}
  ]
}

Resultados compatíveis com SWE-bench

Exporte resultados de avaliação em um formato compatível com as submissões ao leaderboard do SWE-bench:

bash

python -m potato.export \
  -i output/ \
  -f swebench \
  -o results/swebench_results.json

Isso gera o JSON de avaliação padrão do SWE-bench com IDs de instância, patches do modelo e status de resolução derivados dos julgamentos dos anotadores.

Análise

O Potato oferece funções utilitárias para analisar anotações de recompensa de processo:

python

from potato.analysis import load_annotations, process_reward_stats
 
# Load annotations
annotations = load_annotations("output/")
 
# Step-level accuracy statistics
stats = process_reward_stats(annotations)
 
print(f"Total traces annotated: {stats['total_traces']}")
print(f"Traces with no errors: {stats['all_correct_count']} ({stats['all_correct_pct']:.1f}%)")
print(f"Average first-error position: step {stats['avg_first_error_step']:.1f}")
print(f"Average steps before error: {stats['avg_correct_prefix_length']:.1f}")
 
# Error distribution by step position
for position, count in stats['error_by_position'].items():
    print(f"  Step {position}: {count} errors")
 
# Error category distribution (per-step mode only)
if 'error_categories' in stats:
    for category, count in stats['error_categories'].items():
        print(f"  {category}: {count}")
 
# Inter-annotator agreement on first-error step
if stats['multi_annotator']:
    print(f"First-error agreement (exact): {stats['first_error_exact_agreement']:.2f}")
    print(f"First-error agreement (within 1): {stats['first_error_near_agreement']:.2f}")

Visualização

python

from potato.analysis import plot_error_distribution
 
# Plot error position distribution across all traces
plot_error_distribution(
    annotations,
    output_path="figures/error_distribution.png",
    normalize_by_trace_length=True,
    title="Where Do Agents First Go Wrong?"
)
 
# Plot per-step reward curves
from potato.analysis import plot_reward_curves
 
plot_reward_curves(
    annotations,
    output_path="figures/reward_curves.png",
    group_by="agent_model",
    title="Cumulative Reward by Model"
)

Contexto de pesquisa

A anotação de recompensa de processo no Potato foi projetada para apoiar pesquisas sobre o treinamento e a avaliação de modelos de recompensa para sistemas agênticos. Várias linhas de trabalho recentes motivam esse recurso:

O AgentPRM demonstra que modelos de recompensa de processo treinados com rótulos no nível de etapa superam de forma significativa os modelos de recompensa de resultado ao guiar agentes de código durante a busca.
O ToolRM e o ToolRL mostram que modelos de recompensa especializados em etapas de uso de ferramentas podem melhorar o desempenho do agente em tarefas de chamada de API e geração de código.
O DeepSWE aplica modelos de recompensa de processo a tarefas de engenharia de software na escala do SWE-bench, usando rótulos por etapa para treinar verificadores que guiam a busca em árvore do agente.
A pesquisa em RLHF no nível de etapa mostra que o feedback humano por etapa produz modelos de recompensa mais eficientes em amostras do que o feedback no nível de episódio.

Os modos de primeiro erro e por etapa do Potato mapeiam diretamente para os formatos de rótulo usados por essas abordagens. O pipeline de exportação produz dados prontos para treinamento sem pré-processamento adicional.

Veja também

Anotação de agente de código -- exiba e anote traces de agentes de código
Anotação agêntica -- anotação de traces de agente de uso geral com avaliações por turno
Formatos de exportação -- todos os formatos de exportação suportados
Controle de qualidade -- concordância entre anotadores e adjudicação

Para detalhes de implementação, consulte a documentação de origem.