Potato 2.3：智慧體標註、Solo Mode 與 Best-Worst Scaling

**注意：**本文描述的是 Potato 2.3 在 2026 年 3 月釋出時的樣子。下文中的若干配置鍵在後續版本里被改名或替換，當前的語法見文件。不要把這些配置塊直接複製到運行當前版本 Potato 的項目裡。

Potato 2.3.0 帶來了 Solo Mode——一套貫穿十個書面階段的人機協同標註流程——以及帶十一個已註冊軌跡轉換器的智慧體軌跡標註、提供三種打分方法的 Best-Worst Scaling、面向 Google、GitHub 和通用 OIDC 提供商的 SSO 與 OAuth 登入、Parquet 匯出和 15 個演示項目。釋出說明記錄了自 2.2.0 以來 50 多次提交，以及橫跨 8 個模組的 12 個安全漏洞修復。

這次釋出跟隨的是人們標註物件的變化。兩年前還在標註情感和命名實體的研究者，現在在拆解多步驟的智慧體軌跡、批次比較模型輸出，併為 Potato 的方案集當初設計時還不存在的任務構建資料集。Solo Mode 和智慧體軌跡這兩塊工作，針對的都是這個轉變。

升級

pip install --upgrade potato-annotation==2.3.0

Parquet 匯出需要 PyArrow 12.0.0 或更新的版本，要單獨安裝：

pip install "pyarrow>=12.0.0"

智慧體軌跡標註

一次智慧體執行是一串工具呼叫、推理步驟和中間輸出，把它壓平成純文本，就丟掉了評估者需要看到的結構。Potato 2.3 改為通過顯示系統來渲染軌跡，於是軌跡被排布成一段對話，評分掛在單獨的輪次上。

顯示在 instance_display 中宣告，逐輪評分方案巢狀在存放對話的那個欄位下面：

instance_display:
  layout:
    direction: vertical
    gap: 16px
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: conversation
      type: dialogue
      label: "Agent Trace"
      span_target: true
      display_options:
        show_turn_numbers: true
        alternating_shading: true

2.3 中有兩種顯示類型承載智慧體的工作。dialogue 顯示把軌跡渲染成輪次並支援在其上做跨度標註，interactive_chat 則用於標註者親自參與而非事後回看的對話。設定 span_target: true 正是讓標註者能在一輪內部高亮某一段文字的開關，幻覺和無依據的說法就是這樣在它們出現的位置被標出來的。

其他框架的軌跡通過轉換器進入，本次釋出註冊了十一種格式：openai、anthropic、swebench、otel、mcp、multi_agent、langchain、langfuse、react、webarena 和 atif。

python -m potato.trace_converter -i traces.json -f react -o data/traces.jsonl

Solo Mode

多標註者標註需要招人、培訓、協調，在許多研究項目上，瓶頸是這套後勤而不是標註介面。Solo Mode 改為讓一位領域專家和一個大模型搭檔。人來標註，模型來提議，每一次糾正都反饋回提示詞裡，隨著兩者逐漸收斂，人把佇列裡越來越多的部分交給模型。

這套流程貫穿十個書面階段：初始設定、提示詞審查、邊緣案例合成、邊緣案例標註、提示詞驗證、並行標註、分歧解決、定期複查、自主標註和最終驗證。並不是每個項目都會經過每個階段。

solo_mode:
  enabled: true
 
  labeling_models:
    - endpoint_type: "ollama"
      model: "qwen3:4b"
      endpoint_url: "http://localhost:11434"
      max_tokens: 256
      temperature: 0.1
 
  revision_models:
    - endpoint_type: "ollama"
      model: "qwen3:4b"
      endpoint_url: "http://localhost:11434"
 
  uncertainty:
    strategy: "direct_confidence"
 
  thresholds:
    end_human_annotation_agreement: 0.90
    minimum_validation_sample: 20
    confidence_low: 0.5
    periodic_review_interval: 50
 
  instance_selection:
    low_confidence_weight: 0.4
    diversity_weight: 0.3
    random_weight: 0.2
    disagreement_weight: 0.1
 
  state_dir: "solo_state"

instance_selection 這四個權重決定哪些條目值得佔用人的注意力。把低置信度權重設為 0.4、多樣性設為 0.3，就把人的大部分時間送到模型沒把握的實例上，同時對分佈的其餘部分保持足夠覆蓋，好發現系統性錯誤。隨機取樣上的那 0.2，是讓 end_human_annotation_agreement 裡的一致性估計有意義的東西，因為只在困難實例上算出來的一致率，並不是你在整個語料上會得到的那個數。

Solo Mode 附帶 85 個整合測試和端到端測試、一份開發者指南，以及 examples/advanced/solo-mode/ 和 examples/advanced/simple-solo-mode/ 兩個示例項目。從簡單的那個開始，它跑在本地的 Ollama 模型上，不需要 API key，所以你首先評估的是這套流程適不適合你的任務，而不是這個模型值不值它的價錢。

Best-Worst Scaling

Best-Worst Scaling 給標註者看一組條目，通常是四個，只要求按某一個標準挑出最好的和最差的。這兩次選擇隱含了一批成對比較，而在許多互相重疊的組之間，分數會落在一個真實的量表上，且這些判斷比打分更快做出。

annotation_schemes:
  - annotation_type: bws
    name: sentiment_bws
    description: "Sentiment Intensity"
    best_description: "Which sentence expresses the MOST positive sentiment?"
    worst_description: "Which sentence expresses the LEAST positive sentiment?"
    tuple_size: 4
    sequential_key_binding: true

收集到的組上可以跑三種打分方法。counting 是透明的基線，演算法是 (best_count - worst_count) / appearances，不需要額外依賴，而且結果確定。bradley_terry 擬合一個成對比較模型，產出對數尺度的強度參數。plackett_luce 擬合完整的排序模型。兩種基於模型的方法都需要 pip install choix。

python -m potato.bws_scoring --config config.yaml --method bradley_terry

分數落在輸出目錄下的 bws_scores.tsv 裡，包含每個條目的分數、排名、最好和最差的次數，以及出現次數。管理面板有一個 BWS Scoring 標籤頁，可以用一個按鈕跑同樣的計算，並把結果顯示成表格。

SSO 與 OAuth

標註者要通過網際網路訪問的部署需要真正的賬號，2.3 加入了 OAuth 2.0 和 OpenID Connect，讓他們可以用已有的身份登入。支援 Google、GitHub 和任何通用 OIDC 提供商，並且可以按郵箱域名或 GitHub 組織限制訪問。

authentication:
  method: "oauth"
  providers:
    google:
      client_id: ${GOOGLE_CLIENT_ID}
      client_secret: ${GOOGLE_CLIENT_SECRET}
  user_identity_field: "email"
 
secret_key: ${POTATO_SECRET_KEY}

把這個配置塊加到你的配置裡。隨之而來有兩個要求。OAuth 需要 HTTPS 部署，開發時 localhost 除外；它還需要一個穩定的 secret_key，因為每次重啟都變的簽名金鑰會讓登入已經發出的會話全部失效。在你的提供商那裡把重定向 URI 註冊為 https://your-domain.com/auth/callback/google，其中的提供商名字按實際替換。

Parquet 匯出

標註資料越來越多地流向想要列式格式的分析工具，所以 2.3 把 Parquet 加進了匯出登錄檔。一次匯出最多產出三張表：annotations.parquet，每個實例、每個標註者一行；spans.parquet，每條跨度標註一行；以及 items.parquet，存放源資料。

python -m potato.export -c config.yaml -f parquet -o ./export/

選項在命令列上傳遞，而不是在項目裡配置，壓縮編碼可選 snappy（預設）、gzip、zstd、lz4 或 none：

python -m potato.export -c config.yaml -f parquet -o ./export/ \
    --option compression=gzip --option include_items=false

這三張表用 instance_id 連線，這也是為什麼不必先把任何東西讀進 pandas 就能從 DuckDB 裡用上這批匯出：

import duckdb
duckdb.sql("""
  SELECT i.item_id, a.user_id, a.*
  FROM './export/annotations.parquet' a
  JOIN './export/items.parquet' i ON a.instance_id = i.item_id
""")

安全修復

本次釋出修復了橫跨 8 個模組的 12 個安全漏洞，以及分佈在 25 個檔案裡的 XSS、健壯性和資料完整性問題，還有一處跨度刪除的級聯操作——它遍歷的是字典的鍵而不是值，因而留下了沒清掉的連結記錄。一次依賴審計把 Python 和 JavaScript 依賴都升到了當前版本。

其他修復裡有兩個可能影響到你已經收集的資料。一個 has_free_response 布林值崩潰（issue #111）和一個全階段導航迴圈都影響了標註是否按預期被記錄下來，而動態 multirate 的引號處理影響了這些值是怎麼寫出去的。如果你在 2.2 上跑過用到自由文本選項或 multirate 方案的研究，在把輸出當作最終結果之前先檢查一遍。

演示項目

本次釋出在 demo/ 下附帶 15 個演示項目，按彼此疊加的順序編號，從 01-sentiment-admin 到 15-agentic-chat，涵蓋跨度、自定義稽核佈局、影像分類、音訊情感、影片、多模態條目、裁定、滑塊、邊界框、依存樹、分層 ELAN 標註和智慧體聊天。每個演示目錄裡有一個 config.yaml 和它的 data/，整套演示共用一個指令碼，為基於媒體的那幾個演示生成所需的素材。

# From the repository root: generates the demo data, then starts all 15 servers
bash demo/launch.sh

完整的變更日誌，包括上面提到的每一項修復，見倉庫中的 v2.3.0 釋出說明。請到 GitHub 提 issue，或者在 GitHub Discussions 裡開個話題。

連結

• 安裝指南
• v2 新功能
• 智慧體標註
• Solo Mode
• Best-Worst Scaling
• SSO 與 OAuth
• Parquet 匯出
• GitHub 倉庫
• PyPI 包