Potato 2.11：標註引擎與經過認證的機器標籤

Potato 2.11 新增了標註引擎。它用模型為資料集打標籤，再用一份盲態隨機抽取的人工標籤樣本來衡量模型出錯的頻率。你宣告最終標籤必須滿足的條件，例如被接受的機器標籤中至多 10% 是錯的，置信度為 90%。引擎接受統計檢驗所支援的機器標籤，把其餘條目交給人來標註，並寫出一份證書，記錄檢驗了什麼、用了多少條人工標籤。這個版本還把一致性報告擴充套件到 3D 物體、時間定位、分層標註和智慧體軌跡，並修復了一個影像缺陷，它可能把沒人動過的條目算作已作答。

bash

pip install --upgrade potato-annotation

升級說明

閒置會話現在會被登出，預設是 8 小時之後。 在 2.11 之前，session_timeout_minutes 對正在執行的應用不起作用，因為這項檢查註冊在一個會被 potato start 丟棄的應用物件上。現在，閒置時間超過這一設定的會話會被清除，它的下一個請求會轉到登入頁面。整夜保持登入的自助終端和實驗室共用電腦會開始遇到登出，所以如果某項研究依賴於保持登入，請調高 session_timeout_minutes。已經儲存的標註不受影響。

三個舊鍵會在啟動時列印一條提示。 icl_labeling、judge_calibration 和 pre_annotation 的行為和以前完全一樣，只是每個都會向 stderr 列印一行以 NOTE: 開頭的文字，指出它在引擎中的對應項。這些提示僅供參考，所以 potato validate --strict 不會因此失敗。這些鍵計劃在 3.0 中移除，potato label migrate-config 會替你寫出等價的 labeling_engine 配置塊。

標註引擎

引擎適用於條目多到人標不完、而模型大多數時候都對的研究。它把模型當作來源，按你列出的順序以級聯方式逐個嘗試，在最後一個來源之後把條目交給人。來源可以是 LLM、視覺語言模型、Laya 這樣的決策模型、YOLO 檢測器、LLM 評審、評審團、用本研究自身標籤訓練的模型，或者你已有的標籤。

契約是引擎要檢驗的東西。最主要的一種是 selective_risk，它限定被接受的機器標籤中出錯的比例。引擎在盲態樣本的一半上選定置信度閾值，在另一半上用單側二項檢驗來檢驗它，採用固定序列的 Learn-then-Test。每一次新檢驗都使用更嚴格的水平，所以反覆認證直到檢驗通過並不會抬高置信度。ppi 契約報告每個標籤的流行率，並附上一個用預測驅動推斷（prediction-powered inference）構造的區間，無論模型品質如何，這個區間都有效。no_worse_than_human 執行替代標註者檢驗，用於判斷能否替換一個人或一個評審；distributional 則在主觀條目上，把模型的標籤分佈與人們的意見分佈作比較。

在一份普通研究的配置里加上兩個鍵，就能在一個情感方案上認證一個 LLM：

yaml

assignment_strategy: engine
 
labeling_engine:
  enabled: true
  sources:
    - id: gemma
      kind: llm
      endpoint_type: vllm
      model: google/gemma-4-12B-it-qat-w4a16-ct
      base_url: http://localhost:8001/v1
      confidence: {method: logprob}
  contracts:
    - id: accuracy
      kind: selective_risk
      schema: sentiment
      error: 0.1
      confidence: 0.9
  budgets:
    human_labels: 400

confidence: {method: logprob} 根據模型的 token 機率讀出置信度，每個條目只需一次呼叫，而且通常是引擎各種置信度方法中校準得最好的。這份契約允許被接受的標籤中至多 10% 是錯的，90% 的置信度是 Potato 的預設值。budgets.human_labels 限定引擎最多能發出多少個人工請求，400 是隨附文本示例所用的上限。

Potato 隨附的文本示例讓 481 條評論經過一個 Laya 在前、Gemma 12B 在後的級聯。在那次執行中，10% 的契約用 165 條人工標籤得到滿足，引擎接受了 316 條機器標籤，全部來自 Gemma，因為 Laya 的閾值始終沒有定下來。對照參考標籤，這些標籤實測的錯誤率為 7.6%。智慧體軌跡示例有 288 條帶參考結果的合成軌跡。評審在其中 80% 上判斷正確，但它給每個判定的置信度都是 1.0，所以 selective_risk 沒有可以設閾值的依據，一直處於不可行狀態。用同一份資料算出的任務成功率 PPI 區間 [0.57, 0.76] 覆蓋了 0.60 的參考比率，而評審單獨給出的是 0.76。

已滿足的契約有哪些侷限

已滿足的契約是一項關於與標註樣本的那些人之間一致程度的陳述。引擎不會檢查這些人是否正確，所以用粗心的標註者檢驗的契約，認證的是與粗心標註者的一致。有三條規則保證這項陳述成立。校準請求是盲態的，所以當某人持有校準請求時，頁面不顯示任何預標註、評審判定或 AI 幫助。閾值在樣本的一半上選定，在另一半上檢驗。只有人工標籤能用於認證，對來源、提示詞或方案的任何改動，都會把受影響的契約標為 stale，直到它們再次被檢驗。

引擎的介面

每個介面背後都是同一個 engine.sqlite 檔案，所以你可以在一個接口裡開始研究，在另一個接口裡認證：

命令列上的 potato label run|status|certify|certificate|export|calls|distill|optimize|migrate-config；
位於 /api/engine/v1 下的 REST API；
MCP 伺服器中的五個 engine_* 工具；
Python 中的 potato.labeling_engine.sdk.Study；以及
位於 /admin/labeling-engine 的管理頁面，顯示契約狀態、錯誤率隨覆蓋率變化的曲線、每個來源的可靠性圖和模型呼叫日誌。

potato label export 會寫出帶來源資訊的標籤、JSON、Markdown 和 HTML 三種格式的證書、一份資料集卡片和呼叫日誌。標註引擎一頁帶你走完第一項研究，標註引擎契約說明每種契約檢驗什麼、在什麼情況下不成立。

Solo Mode

Solo Mode 現在可以隱藏它的建議。solo_mode.suggestions 會在所有條目上，或在一份隨機樣本上，扣下 LLM 給出的標籤。螢幕上的建議會把答案往它那邊拉，所以交接時讀取的是盲態條目上的一致性。決策模型（laya 以及任何提供 /v1/systemone 的伺服器）可以充當快速的第一層，Solo Mode 也會在標註開始前和每一批之前檢查項目的 ai_budget.cap_usd。黃金集、標註評審團和課程式排序也是新增的。開啟引擎時，Solo Mode 會把它的預測寫進引擎的儲存，這樣引擎就能校準並認證這些預測。配置見 Solo Mode。

一致性

/admin/iaa 現在會報告 spatial_annotation、temporal_grounding、tiered_annotation 以及五種智慧體軌跡方案上的一致性，以前它會把這些方案當作不受支援而跳過。3D 物體和時間片段得到的是平均匹配集一致性，它沒有做機會校正；智慧體軌跡的步驟則以每條軌跡的每一步為單位，得到 Krippendorff's alpha 和 Cohen's kappa。/admin/api/agreement 不再報告結構化方案，而是改為指向 /admin/iaa，因為這些方案被簡化為標籤名後，任意兩位標註者之間都顯示為完全一致。兩個相同的零長度片段現在算作一致。Publishing 和 Paper Mode 會把機器評分者排除在黃金標籤和一致性數字之外。

影響 2.10 研究的修復

有三項修復可能會改變你已經收集或報告的數字：

影像頁面會自行儲存預填的答案。 在帶有 pre_annotation 的 image_annotation 方案上，畫布在載入後重新佈局時，會把預填的形狀儲存為標註者的答案，於是一個沒人動過的條目被算作已作答。在一項帶預標註的 2.10 影像研究中，儲存的形狀與預標註完全一致的條目可能從未被人動過，所以除非你的計時資料表明並非如此，請把這些條目當作未稽核處理。
Paper Mode 用自己的程式碼計算 kappa。 Paper Mode 和一致性模組現在與 /admin/iaa 通過同一個函式計算 Cohen's kappa，所以對同一份資料，2.11 之前從 Paper Mode 報告的 kappa 可能與 /admin/iaa 顯示的不同。
仲裁和 Prolific 自動擴容把機器評分者也算了進去。 機器標註者可能把條目送去仲裁，min_human_annotations 被忽略，Prolific 自動擴容還把機器標註計入了每個條目的上限。

其餘修復改變的是研究能做什麼。來自不傳送 CORS 頭的主機（例如 cocodataset.org）的影像現在可以載入了。在這類影像上，泛洪填充、SAM 和文本提示分割現在會說明為什麼無法讀取它。沒有 color 的預標註形狀會採用其標籤的顏色，而不是被丟棄。Solo Mode 的 "Generate prompt" 現在會讓修訂模型來寫第一版提示詞。通過 potato mcp connect 發出的拒絕現在以工具錯誤的形式返回，而不是被當作成功。邊緣案例發現現在可以在 vLLM 上執行，此前 vLLM 不返回邊緣案例欄位，直到這些欄位被加入響應 schema。

安裝 2.11

用 pip install --upgrade potato-annotation 升級，或者拉取 ghcr.io/davidjurgens/potato:2.11.0。程序內執行的 Laya 決策模型需要新的 decision 附加依賴，即 pip install 'potato-annotation[decision]'；由於它會引入 torch，它不包含在 all 中。釋出說明列出了每一項改動，新功能彙總了每個 2.x 版本的內容。