Note: This post describes Potato 2.3 as it was at release. Some configuration keys and features have been updated in later versions. See the current documentation for up-to-date configuration syntax.

Potato 2.3.0은 지금까지 우리의 가장 큰 릴리스입니다. 두 가지 새로운 시스템인 에이전트 어노테이션과 Solo Mode를 비롯해 Best-Worst Scaling, SSO/OAuth 인증, Parquet 내보내기, 그리고 15개의 새로운 데모 프로젝트를 제공합니다.

이 대부분의 이유는 사람들이 어노테이션하는 대상이 바뀌었기 때문입니다. 많은 연구자가 더 이상 단순히 감정과 개체명만 레이블링하지 않습니다. 그들은 다단계 에이전트 트레이스를 분석하고, LLM 출력을 대량으로 비교하며, 몇 년 전에는 존재하지 않았던 작업을 위한 데이터셋을 구축하고 있습니다. Potato 2.3은 바로 그런 작업을 정조준합니다.

에이전트 어노테이션

2.3의 대표 기능은 인간 어노테이션을 통해 AI 에이전트를 평가하는 완전한 시스템입니다.

무언가를 완수하기 위해 여러 단계를 거치는 시스템인 에이전트는 이제 어디에나 있으며, 진정으로 평가하기 어렵습니다. 한 번의 실행이 수십 개의 도구 호출, 추론 단계, 페이지 탐색, 중간 출력을 쌓을 수 있습니다. 대부분의 어노테이션 도구는 이 모든 것을 일반 텍스트로 평탄화하는데, 이는 평가자가 봐야 할 바로 그 구조를 버리는 것입니다.

Potato의 에이전트 어노테이션 시스템은 세 부분으로 이루어져 있습니다.

12개의 트레이스 형식 변환기

에이전트 트레이스는 그것을 생성한 프레임워크에 따라 모양이 다릅니다. Potato는 이를 하나의 표현으로 정규화합니다:

변환기	출처
`openai`	OpenAI Assistants API / function calling
`anthropic`	Anthropic Claude tool_use / Messages API
`swebench`	SWE-bench 작업 트레이스
`opentelemetry`	OpenTelemetry 스팬 내보내기
`mcp`	Model Context Protocol 세션
`multi_agent`	CrewAI / AutoGen / LangGraph
`langchain`	LangChain 콜백 트레이스
`langfuse`	LangFuse 관측 내보내기
`react`	ReAct Thought/Action/Observation
`webarena`	WebArena / VisualWebArena
`atif`	Agent Trace Interchange Format
`raw_web`	원시 브라우저 녹화 (HAR + 스크린샷)

설정은 짧습니다:

yaml

agentic:
  enabled: true
  trace_converter: react
  trace_file: "data/agent_traces.jsonl"

여러 출처에서 한 번에 트레이스를 가져오는 경우, 자동으로 감지하도록 두십시오:

yaml

agentic:
  enabled: true
  trace_converter: auto

세 가지 표시 유형

서로 다른 종류의 에이전트는 서로 다른 시각화를 필요로 합니다.

Agent Trace Display는 도구를 사용하는 에이전트 트레이스를 색상으로 구분된 단계 카드로 렌더링하며, 접을 수 있는 관측, 보기 좋게 출력된 JSON, 타임라인 사이드바를 제공합니다:

yaml

agentic:
  display_type: agent_trace
  agent_trace_display:
    colors:
      thought: "#6E56CF"
      action: "#3b82f6"
      observation: "#22c55e"
      error: "#ef4444"
    collapse_observations: true
    show_step_numbers: true

Web Agent Trace Display는 브라우징 에이전트를 처리합니다. 전체 스크린샷, 클릭 대상과 입력 필드를 표시하는 SVG 오버레이, 빠르게 이동할 수 있는 필름스트립을 제공합니다:

yaml

agentic:
  display_type: web_agent
  web_agent_display:
    screenshot_max_width: 900
    overlay:
      enabled: true
      click_marker: "circle"
      click_color: "#ef4444"
    filmstrip:
      enabled: true

Interactive Chat Display는 두 가지 경우를 다룹니다. 녹화된 대화를 평가하는 트레이스 검토와, 어노테이터가 에이전트와 실시간으로 대화한 뒤 그 대화를 평가하는 라이브 채팅입니다:

yaml

agentic:
  display_type: interactive_chat
  interactive_chat_display:
    mode: trace_review
    trace_review:
      show_token_counts: true
      show_latency: true

턴별 평가

어떤 표시 유형이든, 어노테이터는 트레이스 전체뿐만 아니라 개별 단계도 평가할 수 있습니다:

yaml

annotation_schemes:
  - annotation_type: likert
    name: overall_quality
    min: 1
    max: 5
 
  - annotation_type: per_turn_rating
    name: step_correctness
    target: agentic_steps
    rating_type: radio
    labels:
      - "Correct"
      - "Partially Correct"
      - "Incorrect"

사전 구축된 스킴

아홉 가지 기성 스킴이 일반적인 에이전트 평가 차원을 기본으로 제공합니다:

yaml

annotation_schemes:
  - preset: agent_task_success
  - preset: agent_step_correctness
  - preset: agent_error_taxonomy
  - preset: agent_safety

프리셋은 agent_task_success, agent_step_correctness, agent_error_taxonomy, agent_safety, agent_efficiency, agent_instruction_following, agent_explanation_quality, agent_web_action_correctness, agent_conversation_quality입니다.

에이전트 어노테이션 문서 읽기 →

Solo Mode

2.3의 두 번째 큰 기능은 Solo Mode로, 통상적인 다수의 어노테이터를 LLM과 함께 작업하는 한 명의 인간 전문가로 대체하는 12단계 워크플로입니다.

문제

신뢰할 수 있는 레이블을 얻으려면 보통 여러 명의 어노테이터가 필요합니다. 그 팀을 채용하고 교육하며 조율하는 일은 느리고 비용이 많이 듭니다. 많은 연구 프로젝트에서 병목은 어노테이션 인터페이스가 전혀 아니라, 팀을 운영하는 데 따르는 물류입니다.

Solo Mode가 이를 처리하는 방식

한 명의 도메인 전문가가 신중하게 선택된 데이터의 일부를 레이블링합니다. LLM은 그 레이블에서 학습하여 나머지 전부에 대한 레이블을 제안하고, 인간은 LLM이 확신하지 못하는 곳에서만 다시 개입합니다. 12단계 워크플로가 이 전체 루프를 실행합니다.

내부 벤치마크에서 Solo Mode는 인간 레이블의 10~15%만 사용하면서도 95% 이상의 일치도로 완전한 다중 어노테이터 파이프라인에 필적했습니다.

12단계

시드 어노테이션: 인간이 다양한 인스턴스 50개를 레이블링합니다.
초기 LLM 보정: LLM이 그 시드 예제를 사용하여 보정 배치를 레이블링합니다.
혼동 분석: 인간과 LLM이 체계적으로 불일치하는 패턴을 찾습니다.
가이드라인 정제: LLM이 더 나은 가이드라인을 제안하고 인간이 이를 승인합니다.
레이블링 함수 생성: 쉬운 인스턴스를 위한 ALCHEmist에서 영감을 받은 프로그래밍 규칙입니다.
능동 레이블링: 인간이 남아 있는 가장 유익한 인스턴스를 레이블링합니다.
자동화된 정제 루프: 가이드라인이 개선됨에 따라 반복적으로 다시 레이블링합니다.
불일치 탐색: 인간이 LLM과 레이블링 함수가 충돌하는 사례를 해결합니다.
엣지 케이스 합성: LLM이 인간이 레이블링할 모호한 예제를 만들어 냅니다.
단계적 신뢰도 에스컬레이션: 인간이 LLM의 가장 낮은 신뢰도 레이블을 검토합니다.
프롬프트 최적화: DSPy에서 영감을 받은 자동화된 프롬프트 탐색입니다.
최종 검증: 무작위 표본을 검토한 뒤 통과시키거나 다시 순환합니다.

빠른 시작

yaml

solo_mode:
  enabled: true
  llm:
    endpoint_type: openai
    model: "gpt-4o"
    api_key: ${OPENAI_API_KEY}
  seed_count: 50
  accuracy_threshold: 0.92
  confidence_threshold: 0.85
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    labels: [Positive, Neutral, Negative]

다중 신호 인스턴스 우선순위화

Solo Mode는 어떤 인스턴스가 인간의 시간을 들일 가치가 있는지 결정하기 위해 가중치가 부여된 여섯 개의 풀에서 추출합니다:

yaml

solo_mode:
  prioritization:
    pools:
      - name: uncertain
        weight: 0.30
      - name: disagreement
        weight: 0.25
      - name: boundary
        weight: 0.20
      - name: novel
        weight: 0.10
      - name: error_pattern
        weight: 0.10
      - name: random
        weight: 0.05

Solo Mode 문서 읽기 →

Best-Worst Scaling

Potato 2.3은 때때로 Maximum Difference Scaling이라고도 불리는 Best-Worst Scaling(BWS)을 추가합니다. 어노테이터는 보통 네 개로 이루어진 항목 튜플을 보고 어떤 기준에 따라 가장 좋은 것과 가장 나쁜 것을 고릅니다. 이 단순한 이진 판단에서 BWS는 신뢰할 수 있는 스칼라 점수를 산출하며, 동일한 통계적 검정력을 위해 리커트 척도가 필요로 하는 것보다 훨씬 적은 어노테이션으로 이를 달성합니다.

yaml

annotation_schemes:
  - annotation_type: best_worst_scaling
    name: fluency
    description: "Select the BEST and WORST translation"
    items_key: "translations"
    tuple_size: 4
    best_label: "Most Fluent"
    worst_label: "Least Fluent"
    randomize_order: true
 
    tuple_generation:
      method: balanced_incomplete
      tuples_per_item: 5
 
    scoring:
      method: bradley_terry
      auto_compute: true
      include_confidence: true

세 가지 채점 방법이 있습니다. 카운팅이 가장 단순합니다: (best_count - worst_count) / 등장 횟수. Bradley-Terry는 쌍대 비교 모델이며 권장되는 기본값입니다. Plackett-Luce는 데이터에서 최대한을 짜내고 싶을 때 사용하는 완전한 순위 모델입니다.

CLI에서 점수를 매기십시오:

bash

python -m potato.bws score --config config.yaml --method bradley_terry --output scores.csv

관리자 대시보드에는 점수 분포, 수렴 차트, 절반 분할 신뢰도를 보여 주는 BWS 탭이 있습니다.

Best-Worst Scaling 문서 읽기 →

SSO 및 OAuth 인증

운영 환경의 어노테이션 배포에는 실제 인증이 필요합니다. Potato 2.3은 세 가지 OAuth 방식을 지원합니다.

Google OAuth

yaml

authentication:
  method: google_oauth
  google_oauth:
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
    redirect_uri: "https://annotation.example.com/auth/google/callback"
    allowed_domains:
      - "umich.edu"
    auto_register: true

조직 제한이 적용된 GitHub OAuth

yaml

authentication:
  method: github_oauth
  github_oauth:
    client_id: ${GITHUB_CLIENT_ID}
    client_secret: ${GITHUB_CLIENT_SECRET}
    redirect_uri: "https://annotation.example.com/auth/github/callback"
    allowed_organizations:
      - "my-research-lab"
    scopes:
      - "read:user"
      - "read:org"

일반 OIDC

Okta, Azure AD, Auth0, Keycloak 또는 OIDC를 지원하는 어떤 것에든 연결하십시오:

yaml

authentication:
  method: oidc
  oidc:
    discovery_url: "https://accounts.example.com/.well-known/openid-configuration"
    client_id: ${OIDC_CLIENT_ID}
    client_secret: ${OIDC_CLIENT_SECRET}
    redirect_uri: "https://annotation.example.com/auth/oidc/callback"

세 가지 모두 도메인 제한, 자동 등록, 그리고 여러 인증 방식이 하나의 로그인 페이지를 공유하는 혼합 모드를 지원합니다.

SSO 및 OAuth 문서 읽기 →

Parquet 내보내기

점점 더 어노테이션 데이터는 컬럼형 형식을 원하는 데이터 과학 도구로 흘러갑니다. Potato 2.3은 Apache Parquet로 세 개의 파일로 곧바로 내보낼 수 있습니다:

annotations.parquet, (인스턴스, 어노테이터, 스킴)당 한 행으로 값, 타임스탬프, 소요 시간을 담습니다
spans.parquet, 어노테이션된 스팬당 한 행으로 오프셋, 레이블, 링크를 담습니다
items.parquet, 어노테이션 수와 상태가 포함된 인스턴스 메타데이터

yaml

parquet_export:
  enabled: true
  output_dir: "output/parquet/"
  compression: zstd
  auto_export: true

pandas, DuckDB, PyArrow, Polars 또는 Hugging Face Datasets에서 직접 로드하십시오:

python

import pandas as pd
annotations = pd.read_parquet("output/parquet/annotations.parquet")
 
# Or with DuckDB for SQL queries
import duckdb
duckdb.sql("""
  SELECT instance_id, value, COUNT(*) as n
  FROM 'output/parquet/annotations.parquet'
  WHERE schema_name = 'sentiment'
  GROUP BY instance_id, value
""")

snappy, gzip, zstd, lz4, brotli 압축, 날짜 또는 어노테이터로 분할된 증분 내보내기, 그리고 문자열 컬럼에 대한 딕셔너리 인코딩을 처리합니다.

Parquet 내보내기 문서 읽기 →

15개의 새로운 데모 프로젝트

Potato 2.3은 project-hub/ 디렉터리에 15개의 새로운 데모를 제공하며, 각 새 기능마다 하나 이상이 있습니다.

에이전트 어노테이션용:

react-agent-eval, 단계 수준 평가로 ReAct 에이전트 트레이스를 평가
web-agent-eval, 스크린샷 오버레이를 사용한 WebArena 트레이스 평가
chatbot-eval, 라이브 에이전트 프록시를 사용한 대화형 채팅 평가
multi-agent-eval, CrewAI 멀티 에이전트 시스템 평가
swebench-eval, 코딩 에이전트를 위한 SWE-bench 트레이스 평가

Solo Mode용: 6. solo-sentiment, 제품 리뷰에 대한 감정 분류 7. solo-ner, 개체명 인식 8. solo-toxicity, 엣지 케이스 합성을 사용한 유해성 탐지

Best-Worst Scaling용: 9. bws-translation, 기계 번역 품질 순위화 10. bws-summarization, 요약 품질 비교 11. bws-image-quality, 이미지 생성 품질 순위화

인증용: 12. google-oauth-demo, Google OAuth 설정 예제 13. github-oauth-demo, 조직 제한이 적용된 GitHub OAuth

내보내기용: 14. parquet-export-demo, DuckDB 분석 스크립트와 함께하는 Parquet 내보내기 15. huggingface-upload, Parquet로 내보내고 Hugging Face Hub로 푸시

각 데모에는 완전한 config.yaml, 샘플 데이터, README가 함께 제공됩니다. 다음 명령으로 아무 데모나 시작하십시오:

bash

cd project-hub/react-agent-eval
potato start config.yaml

보안 강화

2.3에는 여러 가지 보안 개선이 적용되었습니다:

세션 토큰이 이제 구성 가능한 만료와 함께 암호학적으로 안전한 난수 생성을 사용합니다
모든 폼 제출에 대해 CSRF 보호가 기본으로 켜져 있습니다
인증 엔드포인트에 대한 속도 제한(구성 가능, 기본값은 분당 10회 시도)
어노테이션 인터페이스에 표시되는 사용자 제공 콘텐츠에 대한 입력 살균
모든 Python 및 JavaScript 의존성을 현재의 안전한 버전으로 끌어올린 의존성 감사
XSS를 차단하기 위한 Content Security Policy 헤더

yaml

security:
  csrf_protection: true
  rate_limiting:
    auth_attempts: 10            # per minute
    api_requests: 100            # per minute
  session:
    token_length: 64
    lifetime_hours: 24
  content_security_policy: true

업그레이드

Potato 2.2.x에서

bash

pip install --upgrade potato-annotation

v2.2 설정은 완전히 하위 호환되므로 아무것도 바꿀 필요가 없습니다.

새로운 의존성

Parquet 내보내기에는 PyArrow가 필요합니다:

bash

pip install potato-annotation[parquet]

Solo Mode에는 LLM 공급자 SDK가 필요합니다:

bash

pip install potato-annotation[solo]    # installs openai + anthropic SDKs

또는 전부 설치하십시오:

bash

pip install potato-annotation[all]

다음은 무엇일까요

다음 릴리스를 위해 이미 작업 중인 몇 가지입니다:

어노테이션 디핑, 라운드와 어노테이터 전반의 어노테이션을 시각적 diff로 비교
연합 어노테이션, 여러 Potato 인스턴스에 걸친 작업을 조율
스트리밍 데이터 소스, Kafka, Pub/Sub 등에서 어노테이션
태블릿과 휴대폰에서 어노테이션하기 위한 모바일 친화적 인터페이스

여러분의 생각을 진심으로 듣고 싶습니다. GitHub에 이슈를 등록하거나, GitHub Discussions에서 스레드를 시작하거나, 그냥 팀에 연락해 주십시오.

변경된 설정 키를 포함한 전체 changelog는 저장소의 v2.3.0 릴리스 노트를 참조하십시오.

에이전트 어노테이션

12개의 트레이스 형식 변환기

세 가지 표시 유형

턴별 평가

사전 구축된 스킴

Solo Mode

문제

Solo Mode가 이를 처리하는 방식

12단계

빠른 시작

다중 신호 인스턴스 우선순위화

Best-Worst Scaling

SSO 및 OAuth 인증

Google OAuth

조직 제한이 적용된 GitHub OAuth

일반 OIDC

Parquet 내보내기

15개의 새로운 데모 프로젝트

보안 강화

업그레이드

Potato 2.2.x에서

새로운 의존성

다음은 무엇일까요

링크