프로세스 보상 주석
첫 오류 모드와 단계별 모드로 프로세스 보상 모델 학습을 위한 단계별 보상 신호를 수집합니다. PRM, DPO, SWE-bench 학습 포맷으로 바로 내보냅니다.
v2.4.0 신규 기능
프로세스 보상 모델(PRM)은 결과 수준의 단일 점수가 아니라 단계별 정확성 레이블을 필요로 합니다. 효과적인 PRM을 학습하려면 여러 단계로 이루어진 트레이스에서 에이전트가 정확히 어디서 잘못했는지, 어떤 종류의 오류가 발생했는지, 복구가 가능했는지를 식별하는 주석을 수집해야 합니다. 이는 최종 결과만 판단하는 결과 기반 주석과는 근본적으로 다릅니다.
Potato는 프로세스 보상 데이터를 수집할 때 속도와 상세도 사이의 서로 다른 균형에 맞춰 최적화된 두 가지 주석 모드를 제공합니다. 첫 오류 모드는 빠른 이진 레이블링을 위해 설계되었습니다. 주석자가 처음으로 잘못된 단계를 클릭하면 이후의 모든 단계는 오염된 것으로 자동 표시됩니다. 단계별 모드는 주석자에게 모든 단계를 개별적으로 평가하도록 요청하며, 주석 시간이 더 들지만 더 풍부한 신호를 만들어냅니다.
두 모드 모두 코딩 트레이스 표시, 에이전트 트레이스 표시, 웹 에이전트 표시와 통합되므로, 어떤 종류의 에이전트 트레이스에 대해서도 프로세스 보상을 수집할 수 있습니다.
첫 오류 모드
첫 오류 모드에서는 주석자가 트레이스를 순차적으로 읽으면서 에이전트가 오류를 범한 첫 번째 단계를 클릭합니다. 클릭한 단계 이전의 모든 단계는 자동으로 올바른 것으로 레이블링됩니다. 클릭한 단계와 그 이후의 모든 단계는 잘못된 것으로 레이블링됩니다(클릭한 단계는 "첫 오류", 나머지는 "오류 이후").
이는 이진 PRM 학습에 필요한 정확한 레이블 형식을 만들어냅니다. 즉, +1 레이블의 연속 뒤에 오류 지점의 -1과 이후 모든 단계의 -1이 이어집니다.
구성
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)"주석 작업 흐름
- 주석자가 트레이스를 위에서 아래로 읽습니다
- 단계는 처음에 표시되지 않은 상태(회색)입니다
- 주석자가 처음으로 잘못된 단계를 클릭합니다
- 0번부터 N-1번 단계가 초록색으로 바뀝니다(올바름)
- N번 단계가 빨간색으로 바뀝니다(첫 오류)
- N+1번부터 끝까지의 단계가 주황색으로 바뀝니다(오류 이후)
- 트레이스 전체가 올바르면 주석자는 "All Steps Correct"를 클릭합니다
출력 형식
{
"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]
}
}
}주석자가 모든 단계를 올바른 것으로 표시하면 first_error_step은 null이 되고 레이블 배열은 모두 1 값으로 채워집니다.
단계별 모드
단계별 모드에서는 주석자가 트레이스의 모든 단계를 개별적으로 평가합니다. 이는 더 풍부한 신호를 만들어냅니다. 단계는 단순히 올바름/잘못됨이 아니라 "부분적으로 올바름"이나 "불필요함"이 될 수 있습니다. 또한 에이전트가 오류에서 복구하는 경우도 포착하는데, 이는 첫 오류 모드로는 표현할 수 없습니다.
구성
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주석 작업 흐름
- 트레이스의 각 단계 옆에 평가 위젯이 있습니다
- 주석자가 각 단계에 레이블을 선택합니다
- 단계가 "Incorrect" 또는 "Partially Correct"로 평가되고 오류 범주가 활성화되어 있으면, 오류 유형을 선택하는 드롭다운이 나타납니다
- 선택적인 메모 필드를 통해 자유 텍스트로 설명할 수 있습니다
- 상단의 누적 점수가 현재까지의 보상을 보여줍니다
출력 형식
{
"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
}
}
}구성 참조
프로세스 보상 주석 스키마의 전체 구성 옵션입니다.
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"학습 포맷으로 내보내기
Potato는 프로세스 보상 주석을 일반적인 PRM 학습 파이프라인에서 사용하는 포맷으로 바로 내보낼 수 있습니다.
PRM 학습 포맷
PRM 학습을 위한 이진 단계별 레이블을 내보냅니다.
python -m potato.export \
-i output/ \
-f prm \
-o results/prm_training_data.jsonl출력 형식:
{
"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}
]
}DPO / RLHF 선호 쌍
동일한 작업에 대해 주석이 달린 여러 트레이스가 있는 경우, DPO 또는 RLHF 학습을 위한 쌍별 선호를 내보낼 수 있습니다. 내보내기 도구는 한 트레이스의 누적 보상이 다른 트레이스보다 높은 경우를 짝지어 줍니다.
python -m potato.export \
-i output/ \
-f dpo \
-o results/dpo_pairs.jsonl \
--min-score-gap 0.5출력 형식:
{
"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..."}
]
}SWE-bench 호환 결과
SWE-bench 리더보드 제출과 호환되는 형식으로 평가 결과를 내보냅니다.
python -m potato.export \
-i output/ \
-f swebench \
-o results/swebench_results.json이는 인스턴스 ID, 모델 패치, 주석자 판단에서 도출된 해결 상태를 담은 표준 SWE-bench 평가 JSON을 생성합니다.
분석
Potato는 프로세스 보상 주석을 분석하기 위한 유틸리티 함수를 제공합니다.
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}")시각화
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"
)연구 배경
Potato의 프로세스 보상 주석은 에이전트 시스템을 위한 보상 모델의 학습과 평가에 관한 연구를 지원하도록 설계되었습니다. 최근의 여러 연구 흐름이 이 기능의 동기가 됩니다.
- AgentPRM은 단계별 레이블로 학습된 프로세스 보상 모델이 탐색 중 코딩 에이전트를 안내하는 데 있어 결과 보상 모델을 크게 능가함을 보여줍니다.
- ToolRM과 ToolRL은 도구 사용 단계에 특화된 보상 모델이 API 호출 및 코드 생성 작업에서 에이전트 성능을 향상시킬 수 있음을 보여줍니다.
- DeepSWE는 프로세스 보상 모델을 SWE-bench 규모의 소프트웨어 엔지니어링 작업에 적용하며, 단계별 레이블로 에이전트 트리 탐색을 안내하는 검증기를 학습합니다.
- 단계별 RLHF 연구는 단계별 인간 피드백이 에피소드 수준 피드백보다 표본 효율이 높은 보상 모델을 만들어냄을 보여줍니다.
Potato의 첫 오류 모드와 단계별 모드는 이러한 접근 방식들이 사용하는 레이블 형식에 직접 대응합니다. 내보내기 파이프라인은 추가 전처리 없이 학습에 바로 쓸 수 있는 데이터를 생성합니다.
함께 보기
- 코딩 에이전트 주석 -- 코딩 에이전트 트레이스 표시 및 주석
- 에이전트 주석 -- 턴별 평가를 통한 범용 에이전트 트레이스 주석
- 내보내기 포맷 -- 지원되는 모든 내보내기 포맷
- 품질 관리 -- 주석자 간 일치도 및 판정
구현 세부 정보는 소스 문서를 참조하십시오.