Name: Potato
Author: Potato

**注意：**本文描述的是 Potato 2.3 釋出時的樣子。部分配置鍵和功能在後續版本中已經變了。最新的配置語法見當前文件。

我們很高興地宣佈 Potato 2.3.0 釋出，這是 Potato 歷史上規模最大的一次更新。本版本引入了兩大全新系統——智慧體標註和 Solo Mode——以及 Best-Worst Scaling、SSO/OAuth 認證、Parquet 匯出和 15 個新演示項目。

本次釋出的主題很簡單：我們需要標註的內容已經發生了變化，我們的工具也需要跟上。 研究人員不再只是標註文本情感和命名實體。他們正在評估多步驟 AI 智慧體 trace、大規模比較 LLM 輸出，併為日益複雜的任務構建資料集。Potato 2.3 正是為這一新現實而構建的。

智慧體標註

Potato 2.3 的核心功能是一套完整的通過人類標註評估 AI 智慧體的系統。

AI 智慧體——執行多步驟操作以完成任務的系統——正在迅速普及。但評估它們很困難。單次智慧體執行可能涉及數十個工具呼叫、推理步驟、網頁瀏覽和中間輸出。現有的標註工具將智慧體的輸出顯示為純文本，丟失了評估人員需要看到的豐富結構。

Potato 的智慧體標註系統通過三個元件來解決這個問題。

12 種 Trace 格式轉換器

智慧體 trace 的格式因框架不同而各異。Potato 將它們全部標準化為統一的表示形式：

轉換器	來源
`openai`	OpenAI Assistants API / 函式呼叫
`anthropic`	Anthropic Claude tool_use / Messages API
`swebench`	SWE-bench 任務 trace
`otel`	OpenTelemetry span 匯出
`mcp`	Model Context Protocol 會話
`multi_agent`	CrewAI / AutoGen / LangGraph
`langchain`	LangChain 回呼 trace
`langfuse`	LangFuse 觀測匯出
`react`	ReAct Thought/Action/Observation
`webarena`	WebArena / VisualWebArena
`atif`	Agent Trace Interchange Format
`web_agent`	原始瀏覽器錄製（HAR + 截圖）

配置非常簡單：

yaml

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

對於需要從多個來源匯入 trace 的項目，支援自動檢測：

yaml

agentic:
  enabled: true
  trace_converter: auto

三種顯示類型

不同的智慧體模態需要不同的視覺化方式。

Agent Trace 顯示 將使用工具的智慧體 trace 渲染為帶顏色編碼的步驟卡片，支援可摺疊的觀測結果、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 顯示 渲染瀏覽智慧體的 trace，包含完整截圖、顯示點選目標和輸入欄位的 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

互動式聊天顯示 支援 trace 回顧（評估已錄製的對話）和即時聊天（標註人員與智慧體即時互動，然後評估對話）兩種模式：

yaml

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

逐步評分

對於任何顯示類型，標註人員都可以在評估整體 trace 的同時對單個步驟進行評分：

yaml

annotation_schemes:
  - annotation_type: likert
    name: overall_quality
 
  - annotation_type: trajectory_eval
    name: step_correctness
    steps_key: agentic_steps
    correctness_options:
      - "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

Potato 2.3 的第二大功能是 Solo Mode：一個 12 階段的工作流，用單個人類專家與 LLM 的協作取代傳統的多標註者範式。

問題

傳統標註需要多個標註者來確保可靠性。但招聘、培訓和協調團隊既昂貴又耗時。對於許多研究項目來說，標註瓶頸不在於介面，而在於後勤工作。

解決方案

Solo Mode 讓一位領域專家標註資料中經過策略性選擇的一個子集。LLM 從這些標籤中學習，為剩餘實例提出標籤建議，人類只需稽核 LLM 不確定的案例。12 階段工作流自動編排這一過程。

在內部基準測試中，Solo Mode 達到了與完整多標註者流程 95% 以上的一致性，同時僅需 10-15% 的人工標註量。

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 新增了 Best-Worst Scaling（BWS），也稱為最大差異縮放。標註人員看到一組項目（通常 4 個），根據某個標準選擇最好和最差的項目。BWS 從簡單的二元判斷中生成可靠的標量分數，在相同統計效力下所需的標註量遠少於 Likert 量表。

yaml

annotation_schemes:
  - annotation_type: bws
    name: fluency
    description: "Select the BEST and WORST translation"
    tuple_size: 4
    best_description: "Most Fluent"
    worst_description: "Least Fluent"

提供三種評分方法：

計數法 -- 簡單的 (best_count - worst_count) / appearances
Bradley-Terry -- 成對比較模型（推薦預設選項）
Plackett-Luce -- 完整排名模型，最大化資料效率

通過命令列計算分數：

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 -- 每行對應一個標註的 span，包含偏移量、標籤和連結
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 智慧體 trace
web-agent-eval -- 帶截圖覆蓋層的 WebArena trace 評估
chatbot-eval -- 帶即時智慧體代理的互動式聊天評估
multi-agent-eval -- 評估 CrewAI 多智慧體系統
swebench-eval -- 編碼智慧體的 SWE-bench trace 評估

Solo Mode 演示

solo-sentiment -- 產品評論的 Solo Mode 情感分類
solo-ner -- Solo Mode 命名實體識別
solo-toxicity -- 帶邊緣案例合成的 Solo Mode 毒性檢測

Best-Worst Scaling 演示

bws-translation -- 機器翻譯品質排名
bws-summarization -- 摘要品質比較
bws-image-quality -- 影像生成品質排名

認證演示

google-oauth-demo -- Google OAuth 配置示例
github-oauth-demo -- 帶組織限制的 GitHub OAuth

匯出演示

parquet-export-demo -- 帶 DuckDB 分析指令碼的 Parquet 匯出
huggingface-upload -- 匯出為 Parquet 並推送到 Hugging Face Hub

每個演示都包含完整的 config.yaml、示例資料和包含設定說明的 README。啟動任意演示：

bash

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

安全加固

Potato 2.3 包含多項安全改進：

會話令牌 使用加密安全的隨機生成，支援可配置的過期時間
CSRF 保護 預設對所有表單提交啟用
速率限制 應用於認證端點（可配置，預設每分鐘 10 次嘗試）
輸入淨化 用於標註介面中顯示的所有使用者提供內容
依賴審計 -- 所有 Python 和 JavaScript 依賴已更新至最新安全版本
內容安全策略 頭已新增以防止 XSS

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]

未來展望

Potato 2.3 代表了標註工具能力的重大擴充套件。我們已經在開發下一批功能：

標註差異比較 -- 使用視覺化差異跨輪次和標註者比較標註
聯邦標註 -- 跨多個 Potato 實例協調標註
流式資料來源 -- 標註來自 Kafka、Pub/Sub 和其他流式系統的資料
移動端最佳化介面 -- 適用於平板和手機的響應式標註

我們期待聽到您的反饋。請在 GitHub 上提交 issue，加入 GitHub Discussions 中的討論，或直接聯絡團隊。

智慧體標註

12 種 Trace 格式轉換器

三種顯示類型

逐步評分

預置標註方案

Solo Mode

問題

解決方案

12 個階段

快速開始

多訊號實例優先順序

Best-Worst Scaling

SSO 與 OAuth 認證

Google OAuth

GitHub OAuth（帶組織限制）

通用 OIDC

Parquet 匯出

15 個新演示項目

智慧體標註演示

Solo Mode 演示

Best-Worst Scaling 演示

認證演示

匯出演示

安全加固

升級指南

從 Potato 2.2.x 升級

新增依賴

未來展望

連結