Anotación de Recompensa de Proceso

Recopila señales de recompensa por paso para entrenar modelos de recompensa de proceso con los modos de primer error y por paso. Exporta directamente a formatos de entrenamiento PRM, DPO y SWE-bench.

Novedad en la v2.4.0

Los modelos de recompensa de proceso (PRM) necesitan etiquetas de corrección por paso, no una única puntuación a nivel de resultado. Entrenar un PRM que funcione implica recopilar anotaciones que identifiquen en qué punto exacto de una traza de varios pasos se equivocó el agente, qué tipo de error cometió y si era posible recuperarse. Esto se diferencia de la anotación basada en el resultado, donde solo juzgas el desenlace final.

Potato ofrece dos modos de anotación optimizados para distintos equilibrios entre velocidad y detalle a la hora de recopilar datos de recompensa de proceso. El modo de primer error está pensado para un etiquetado binario rápido: el anotador hace clic en el primer paso incorrecto y todos los pasos siguientes quedan marcados automáticamente como contaminados. El modo por paso pide al anotador que valore cada paso de forma independiente, lo que produce señales más ricas a costa de más tiempo de anotación.

Ambos modos se integran con la vista de trazas de coding, la vista de trazas de agente y la vista de agente web, así que puedes recopilar recompensas de proceso para cualquier tipo de traza de agente.

Modo de Primer Error

En el modo de primer error, el anotador lee la traza en orden y hace clic en el primer paso en el que el agente cometió un error. Todos los pasos anteriores al clic se etiquetan automáticamente como correctos. El paso señalado y todos los siguientes se etiquetan como incorrectos (el paso señalado como «primer error» y el resto como «posterior al error»).

Esto produce exactamente el formato de etiquetas que hace falta para entrenar PRM binarios: una secuencia de etiquetas +1 seguida de un -1 en el punto del error y -1 para todos los pasos restantes.

Configuración

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)"

Flujo de Anotación

El anotador lee la traza de arriba abajo
Los pasos empiezan sin marcar (gris)
El anotador hace clic en el primer paso incorrecto
Los pasos 0 a N-1 se ponen en verde (correctos)
El paso N se pone en rojo (primer error)
Los pasos N+1 hasta el final se ponen en naranja (posteriores al error)
Si toda la traza es correcta, el anotador pulsa «All Steps Correct»

Formato de Salida

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]
    }
  }
}

Cuando el anotador marca todos los pasos como correctos, first_error_step es null y el array de etiquetas contiene solo valores 1.

Modo por Paso

En el modo por paso, el anotador valora de forma independiente cada paso de la traza. Esto produce señales más ricas: un paso puede ser «parcialmente correcto» o «innecesario» en lugar de solo correcto o incorrecto. También recoge los casos en los que el agente se recupera de un error, algo que el modo de primer error no puede representar.

Configuración

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

Flujo de Anotación

Cada paso de la traza tiene junto a él un control de valoración
El anotador selecciona una etiqueta para cada paso
Si el paso se valora como «Incorrect» o «Partially Correct» y las categorías de error están activadas, aparece un desplegable para elegir el tipo de error
Un campo de notas opcional permite explicarlo en texto libre
Una puntuación acumulada en la parte superior muestra la recompensa total

Formato de Salida

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
    }
  }
}

Referencia de Configuración

Todas las opciones de configuración del esquema de anotación de recompensa de proceso:

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"

Exportar a Formatos de Entrenamiento

Potato puede exportar las anotaciones de recompensa de proceso directamente a los formatos que usan los pipelines habituales de entrenamiento de PRM.

Formato de Entrenamiento PRM

Exporta etiquetas binarias por paso para entrenar un PRM:

bash

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

Formato de salida:

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 Preferencia para DPO / RLHF

Cuando tienes varias trazas anotadas para la misma tarea, exporta preferencias por pares para entrenamiento con DPO o RLHF. El exportador empareja trazas en las que una tiene mayor recompensa acumulada que la otra:

bash

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

Formato de salida:

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 Compatibles con SWE-bench

Exporta los resultados de evaluación en un formato compatible con los envíos a la clasificación de SWE-bench:

bash

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

Esto genera el JSON de evaluación estándar de SWE-bench con los identificadores de instancia, los parches del modelo y el estado de resolución derivado de los juicios de los anotadores.

Análisis

Potato incluye funciones de utilidad para analizar las anotaciones de recompensa de proceso:

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}")

Visualización

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 Investigación

La anotación de recompensa de proceso en Potato está pensada para dar soporte a la investigación sobre entrenamiento y evaluación de modelos de recompensa para sistemas agénticos. Varias líneas de trabajo recientes motivan esta funcionalidad:

AgentPRM muestra que los modelos de recompensa de proceso entrenados con etiquetas por paso superan con claridad a los modelos de recompensa de resultado a la hora de guiar agentes de coding durante la búsqueda.
ToolRM y ToolRL muestran que los modelos de recompensa especializados en pasos de uso de herramientas pueden mejorar el rendimiento del agente en tareas de llamada a API y generación de código.
DeepSWE aplica modelos de recompensa de proceso a tareas de ingeniería de software a escala SWE-bench, usando etiquetas por paso para entrenar verificadores que guían la búsqueda en árbol del agente.
La investigación en RLHF a nivel de paso muestra que la realimentación humana por paso produce modelos de recompensa más eficientes en muestras que la realimentación a nivel de episodio.

Los modos de primer error y por paso de Potato se corresponden directamente con los formatos de etiquetas que usan estos enfoques. El pipeline de exportación produce datos listos para entrenar sin preprocesamiento adicional.

Véase También

Anotación de Agentes de Coding -- muestra y anota trazas de agentes de coding
Anotación Agéntica -- anotación de trazas de agente de propósito general con valoraciones por turno
Formatos de Exportación -- todos los formatos de exportación admitidos
Control de Calidad -- acuerdo entre anotadores y adjudicación

Para los detalles de implementación, consulta la documentación fuente.