Annotation de récompense de processus

Name: Potato
Author: Potato

Recueillez des signaux de récompense par étape pour entraîner des modèles de récompense de processus, en mode première erreur ou par étape. Exportez directement vers les formats d'entraînement PRM, DPO et SWE-bench.

Nouveau dans la v2.4.0

Les modèles de récompense de processus (PRM) demandent des étiquettes de justesse par étape, et non une note unique portant sur le résultat. Entraîner un PRM efficace suppose de recueillir des annotations qui indiquent exactement où, dans une trace à plusieurs étapes, l'agent a dérapé, quel type d'erreur s'est produit et si un rattrapage était possible. Cela diffère de l'annotation fondée sur le résultat, où vous ne jugez que l'issue finale.

Potato propose deux modes d'annotation optimisés pour des compromis vitesse/finesse différents lors de la collecte de données de récompense de processus. Le mode première erreur vise l'étiquetage binaire rapide : l'annotateur clique sur la première étape erronée, et toutes les étapes suivantes sont automatiquement marquées comme viciées. Le mode par étape demande à l'annotateur de noter chaque étape indépendamment, ce qui produit des signaux plus riches au prix d'un temps d'annotation plus long.

Les deux modes s'intègrent à l'affichage de traces de coding, à l'affichage de traces d'agents et à l'affichage d'agents web, si bien que vous pouvez recueillir des récompenses de processus pour n'importe quel type de trace d'agent.

Mode première erreur

En mode première erreur, l'annotateur parcourt la trace dans l'ordre et clique sur la première étape où l'agent a commis une erreur. Toutes les étapes antérieures sont automatiquement étiquetées comme correctes. L'étape cliquée et toutes les suivantes sont étiquetées comme erronées (l'étape cliquée comme « première erreur » et les autres comme « en aval de l'erreur »).

On obtient exactement le format d'étiquettes qu'il faut pour entraîner des PRM binaires : une suite d'étiquettes +1, puis un -1 au point d'erreur et -1 pour toutes les étapes restantes.

Configuration

yaml

annotation_schemes:
  - name: process_reward
    annotation_type: process_reward
    mode: first_error
    description: "Click the first step where the agent made a mistake"
 
    mode: first_error
 
      # 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)"

Déroulé de l'annotation

L'annotateur lit la trace de haut en bas
Les étapes sont d'abord non marquées (gris)
L'annotateur clique sur la première étape erronée
Les étapes 0 à N-1 passent au vert (correctes)
L'étape N passe au rouge (première erreur)
Les étapes N+1 jusqu'à la fin passent à l'orange (en aval)
Si toute la trace est correcte, l'annotateur clique sur « All Steps Correct »

Format de sortie

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

Quand l'annotateur marque toutes les étapes comme correctes, first_error_step vaut null et le tableau d'étiquettes ne contient que des 1.

Mode par étape

En mode par étape, l'annotateur note chaque étape de la trace indépendamment. Les signaux obtenus sont plus riches -- une étape peut être « partiellement correcte » ou « inutile » plutôt que simplement correcte ou erronée. Ce mode rend aussi compte des cas où l'agent se rattrape après une erreur, ce que le mode première erreur ne sait pas représenter.

Configuration

yaml

annotation_schemes:
  - name: process_reward
    annotation_type: process_reward
    mode: per_step
    description: "Rate each step independently"
 
    mode: per_step
 
      # 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

Déroulé de l'annotation

Chaque étape de la trace est accompagnée d'un widget de notation
L'annotateur choisit une étiquette pour chaque étape
Si l'étape est notée « Incorrect » ou « Partially Correct » et que les catégories d'erreur sont activées, une liste déroulante apparaît pour choisir le type d'erreur
Un champ de notes facultatif permet une explication en texte libre
Un score courant affiché en haut montre la récompense cumulée

Format de sortie

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

Référence de configuration

Options complètes du schéma d'annotation de récompense de processus :

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
    mode: first_error
 
    # Required for mode: per_step
    mode: per_step
 
    # Common options

Exportation vers les formats d'entraînement

Potato exporte les annotations de récompense de processus directement vers les formats utilisés par les pipelines d'entraînement de PRM courants.

Format d'entraînement PRM

Exportez des étiquettes binaires par étape pour l'entraînement d'un PRM :

bash

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

Format de sortie :

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

Paires de préférence DPO / RLHF

Quand plusieurs traces annotées portent sur la même tâche, exportez des préférences par paires pour l'entraînement DPO ou RLHF. L'exportateur apparie les traces dont l'une a une récompense cumulée supérieure à l'autre :

bash

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

Format de sortie :

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

Résultats compatibles SWE-bench

Exportez les résultats d'évaluation dans un format compatible avec les soumissions au classement SWE-bench :

bash

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

Cela produit le JSON d'évaluation SWE-bench standard, avec les identifiants d'instance, les patchs du modèle et l'état de résolution déduit des jugements des annotateurs.

Analyse

Potato fournit des fonctions utilitaires pour analyser les annotations de récompense de processus :

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

Visualisation

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

Contexte de recherche

L'annotation de récompense de processus dans Potato est conçue pour soutenir les travaux sur l'entraînement et l'évaluation de modèles de récompense pour les systèmes agentiques. Plusieurs travaux récents motivent cette fonctionnalité :

AgentPRM montre que les modèles de récompense de processus entraînés sur des étiquettes par étape surpassent nettement les modèles de récompense de résultat pour guider les agents de coding pendant la recherche.
ToolRM et ToolRL montrent que des modèles de récompense spécialisés dans les étapes d'usage d'outils améliorent les performances des agents sur les tâches d'appel d'API et de génération de code.
DeepSWE applique les modèles de récompense de processus à des tâches d'ingénierie logicielle à l'échelle de SWE-bench, en se servant d'étiquettes par étape pour entraîner des vérificateurs qui guident la recherche arborescente de l'agent.
Les travaux sur le RLHF au niveau des étapes montrent qu'un retour humain par étape produit des modèles de récompense plus économes en exemples qu'un retour au niveau de l'épisode.

Les modes première erreur et par étape de Potato correspondent directement aux formats d'étiquettes utilisés par ces approches. Le pipeline d'exportation produit des données prêtes pour l'entraînement, sans prétraitement supplémentaire.

Voir aussi

Annotation d'agent de coding -- afficher et annoter des traces d'agents de coding
Annotation agentique -- annotation générale de traces d'agents, avec notation par tour
Formats d'exportation -- tous les formats d'exportation pris en charge
Contrôle de la qualité -- accord inter-annotateurs et arbitrage

Pour les détails d'implémentation, consultez la documentation source.