標註引擎契約

契約是關於最終標籤的一項陳述，標註引擎在隨機樣本上用人工標籤檢驗它。每份契約指定一個標註方案（schema），並帶有一個 confidence（預設 0.9），即該陳述成立的機率。因此 confidence 為 0.9 時，已滿足的契約有 10% 的可能是錯的。

六種契約作出的陳述各不相同，適合不同的研究：

這些契約都不保證標籤沒有錯誤。selective_risk 限定的是被接受標籤中的錯誤率，而每份檢驗機器的契約，衡量的都是機器與標註樣本的那些人之間的一致程度。

契約狀態

每份契約都處於五種狀態之一，顯示在管理頁面、potato label status 的輸出和證書中：

只有當某方案上的每一份 selective_risk 和 threshold_legacy 契約都已滿足並接受某個機器標籤時，這個標籤才會被接受。契約陳述的是標籤必須滿足的條件，所以未滿足的契約會阻止接受，而不是被跳過；狀態、管理頁面和證書都會指出哪份契約沒有滿足。當任何規則都無法生效、也不再抽取樣本時（某份契約 infeasible、校準樣本已經抽完，或者無法作出任何預估），仍沒有標籤的條目會在 budgets.human_labels 的範圍內交給人來標註。

dev 劃分和 cert 劃分

引擎把用來選定規則的標籤和用來檢驗規則的標籤分開儲存。校準請求隨機抽取，並記錄入樣機率，始終是盲態的，每個請求隨機歸入以下兩個劃分之一：

• dev（humans.dev_fraction，預設一半）用來擬合校準器並選定閾值；
• cert 用來檢驗選定的規則，除此之外沒有任何東西讀取它。

檢視次數

對一份契約的每一次新檢驗都使用更嚴格的水平，所以隨著標籤陸續到來反覆檢驗，並不會抬高置信度。第 k 次檢視分到誤差預算的 (1 - confidence) * 6 / (pi^2 k^2)，對所有可能的檢視求和恰好是整個預算，第一次檢視分到其中的 61%。

• 檢視次數按契約計算，涵蓋這份契約曾在其下檢驗過的每一個級聯，改名的契約保留舊 id 的檢視次數。不斷嘗試提示詞或模型直到有一個通過，每試一次都算一次檢視。回到之前的某個級聯也算一次新的檢視，它之前的結果不會恢復。
• 對同一份資料重新檢驗不算新的檢視。 同樣的 cert 標籤、同樣的預測、在 dev 上選定的同一條規則，會返回儲存的結果。無法進行的檢驗（例如某個類別沒有 cert 標籤）不消耗任何預算。
• potato label certify 會一次性檢驗新的 cert 標籤和新的預測，對應的 REST、MCP 和 SDK 操作也一樣。如果只有 dev 標籤變了，它會返回儲存的結果，並附一條說明，指出 dev 現在會選另一條規則；--retest 會在下一次檢視時檢驗那條規則。
• 規劃器會隨著標籤到來自動認證。 已滿足的 selective_risk 契約在其級聯下保持滿足，由抽查來監控。未滿足的契約在其標籤增長四分之一、且至少增加 10 條時會再次檢驗。ppi、distributional 和 no_worse_than_human 的結果是估計值，而不是通過與否的檢驗，所以規劃器會在同樣的節點重新估計，並在校準樣本完整時再估計一次。
• 修改過的 cert 標籤算作新資料。 標註者修改答案時，這次修改的代價不會超過一條新標籤。如果改回到已經檢驗過的狀態，那次檢驗的結果會恢復。如果儲存結果中的每一項檢驗在修改後都沒有看到更多錯誤，結果和它的檢視次數保持不變。否則，規劃器會等到標籤從第一次修改起增長四分之一，這樣一連串更正只算作一次檢驗，在此期間已接受的標籤仍保持接受，契約上會附一條說明。當不會再有更多標籤時，它會立即檢驗，而顯式的認證操作會在下一次檢視時檢驗。

人們在看過機器答案之後給出的標籤（核驗請求）以及在引擎請求之外給出的標籤，永遠不會用於認證或估計任何東西。它們可以用來訓練蒸餾模型。

selective_risk

selective_risk 限定被接受的機器標籤中出錯的比例。error 鍵是被接受標籤中能容忍的最大錯誤率，必須設定：

- id: accuracy
  kind: selective_risk
  schema: sentiment
  error: 0.05          # required: largest tolerated error among accepted labels
  confidence: 0.9
  per_class: true      # test each predicted class separately
  tolerance: 0.5       # graded families only: loss at or below this counts as correct

規則是每一層級聯的一個置信度閾值，開啟 per_class 時則是每個預測類別各一個閾值。除最後一層外，每一層的閾值都在 dev 上選定，並在 cert 上檢驗一次。最後一層從 dev 選定的閾值開始，逐步嘗試更寬鬆的閾值，依次檢驗，在第一個不通過的閾值處停止。這個過程就是固定順序的 Learn-then-Test（Angelopoulos 等，2025）。每一次檢驗都是單側二項檢驗，檢驗被接受標籤中的錯誤率是否高於 error，顯著性水平在各層和各類別之間分配。不通過的那一層不接受任何標籤，它的條目交給人。

什麼算“正確”取決於方案族。每個方案族的損失見下表，損失不超過 tolerance 時標籤算作正確：

區域、片段、3D 物體和軌跡的損失，與 /admin/iaa 上的一致性報告所用的相同，所以機器與人之間的評分方式，和兩個人之間的評分方式一樣。自由文本和成對比較方案目前還沒有對應的方案族，證書會把它們列為不支援。

檢驗要求每一組被檢驗的 cert 條目是均勻樣本。如果某一組條目是以不等的機率抽取的，就不會檢驗這一組，結果中會指出這一點。

在最後一層，只有當 dev 上的錯誤率不超過目標的一半、並且預計有足夠多的 cert 標籤能通過第一次檢驗時，才會在 dev 上選定閾值。對還需要多少標籤的預估，只計入能以這種方式選定的閾值。如果 cert 已經有了預估所要求的標籤數，檢驗卻仍不通過，下一次預估就會使用 dev 和 cert 合起來顯示的錯誤率，而不只是 dev 的。如果 dev 上的最低錯誤率低於目標、但高於目標的一半，就既不檢驗也不預估。結果會說明這一點並給出該錯誤率，因為只有在錯誤率最終更低時，更多標籤才有幫助。

metrics.accepted_by_tier 是規則對整個總體（包括校準條目）的覆蓋率，而不是交付的機器標籤數量。證書中 "Machine labels accepted, by source" 一行統計的才是這個數量。

軌跡損失只比較雙方都標註了的步驟，所以只標註了部分步驟的人，只在那些步驟上比較。沒有人標註的步驟不會被檢查；一個人如果只標註了第 0 步，並且在那一步與評審一致，就算作與整條軌跡的標籤一致。在每一步都必須檢查的場合，請要求人們標註每一步。

ppi

ppi 報告每個標籤的流行率區間，或者某個平均分的區間，並對機器的錯誤作了校正：

- id: prevalence
  kind: ppi
  schema: sentiment
  estimand: prevalence   # or mean, for numeric scores
  by: language           # optional: an interval per value of this item field
  confidence: 0.95
  max_width: 0.05        # optional: met once every interval is at most this wide

預測驅動推斷（prediction-powered inference，Angelopoulos 等，2023）用機器在人工標註樣本上的誤差來校正機器的估計。無論機器品質如何，這個區間都有效。好的機器能讓區間比只靠人更窄，差的機器也不會讓它更寬。入樣機率相等時，引擎使用帶調優權重的 PPI++；入樣機率不等時（分層抽樣或不確定性驅動的抽樣），使用 Horvitz-Thompson 差分估計量。它所用的機器標籤，就是級聯會交付的那個標籤。by 欄位在條目註冊時從條目中複製過來。沒有 max_width 時，契約只要有足夠的標籤可以報告就算滿足。

no_worse_than_human

no_worse_than_human 檢驗的是，機器與人一致的頻率是否至少和一個人與其他人一致的頻率一樣高：

- id: replaces-a-person
  kind: no_worse_than_human
  schema: verdict
  epsilon: 0.1

這份契約執行替代標註者檢驗（alternative annotator test，Calderon 等，2025）。它依次留出每一個人，檢驗機器與其餘人一致的頻率是否至少和被留出的那個人一樣高，允許 epsilon 的差距。當機器勝過至少一半的人時就算通過，並控制跨人的錯誤發現率。

這項檢驗需要由多人標註的條目。請設定 humans.overlap（樣本中被標註不止一次的比例）和 humans.overlap_k（每個條目的標註人數，至少 3），而檢驗還需要至少 3 名標註者、每人 30 個條目。在湊齊之前，契約一直是 insufficient。當固定的準確率目標主要測到的是標註者噪聲時，就用這份契約。如果兩個認真的人只有 85% 的時候意見一致，那麼任何標註者都無法被證明有 95% 是“對”的。

budget_first

budget_first 在你花錢之前預估一筆人工標註預算能換來什麼：

- id: plan
  kind: budget_first
  schema: sentiment
  human_labels: 500      # or human_usd, priced at the crowd reward

預估依據的是目前已收集的 dev 標籤。對於網格上的每一個錯誤率目標，它給出在這筆預算下機器能被認證標註的語料比例，以及每個流行率區間會有多寬。只要有足夠的 dev 標籤可供預估，契約就是 met。它對標籤本身不作任何承諾，這要等標籤到齊後由 selective_risk 和 ppi 來做。

distributional

distributional 把機器的標籤分佈與人們的意見分佈進行比較，適用於人們出於本應保留在資料中的理由而意見分歧的主觀任務：

- id: disagreement
  kind: distributional
  schema: offensiveness
  max_distance: 0.15     # optional
  groups_by: age_band    # optional: a prestudy question whose answer groups the annotators

每個由多人標註的條目（humans.distribution_k，預設 5 人）都有一個人工標籤分佈。這份契約報告機器分佈與人們分佈之間的平均 Jensen-Shannon 距離，並附帶自助法區間。它還會報告一個噪聲上限，即每個條目上把人隨機分成兩半後兩半之間的同一距離。機器離人們的距離如果比人們彼此之間的距離還近，就已經接近到資料所能允許的程度了。

機器的分佈在來源提供機率時就是這些機率（決策模型、k_sample、logprob），否則就是把它的標籤表示成獨熱向量。當區間上端不超過 max_distance 時，契約滿足；沒有 max_distance 時，只要有 20 個由 3 人或更多人標註的條目，契約就滿足。當區間下端高於 max_distance 時，契約為 infeasible，因為更多條目只會把區間收窄到一個過大的距離周圍。

設定 groups_by 時，同樣的數字會按標註者分組報告。每組在某個條目上的分佈只由該組的人構成，分組依據是他們對指定研究前問題的回答；如果沒有人回答這個問題，契約會說明這一點。

threshold_legacy

threshold_legacy 接受高於固定置信度的機器標籤，不執行任何統計檢驗：

- id: old-rule
  kind: threshold_legacy
  schema: sentiment
  threshold: 0.8

potato label migrate-config 會為 icl_labeling 寫出這份契約，閾值取原來的 confidence_threshold，所以轉換後的配置行為與之前相同；你也可以手動編寫它。證書會把這些標籤標為未認證，並報告它們在校準標籤上測得的錯誤率，匯出時這些標籤的狀態為 accepted_uncertified。

示例研究的結果

examples/labeling-engine/ 下的三個示例研究在執行時，把 LLM、評審和視覺來源都指向了 vLLM 伺服器上的 Gemma 12B，而不是提交的配置中所用的 Ollama 模型。每個示例的 README 都列出了被修改的來源塊；使用 Ollama 預設設定時，數字會有所不同。

• 文本情感（481 條評論，最後一層是使用 logprob 置信度的 Gemma 12B）。10%、0.9 的 selective_risk 在 165 條人工標籤上滿足，316 條機器標籤被接受。它們相對於真實標籤測得的錯誤率是 7.6%，PPI 區間覆蓋了全部三個標籤的真實流行率。
• 影像（128 張 COCO 影像，YOLOv8n，視覺模型為 Gemma 12B）。“有人”標籤在 10% 上通過了認證。邊界框契約一直是 insufficient，因為在 IoU 0.5 下，YOLOv8n 的邊界框在 32% 的 dev 影像上是錯的。
• 智慧體軌跡（288 條軌跡，評審為 Gemma 12B）。評審在 80% 的軌跡上是對的，但它的置信度始終是 1.0，所以 selective_risk 為 infeasible。替代標註者檢驗為 insufficient，機器得分 0.82，人們為 0.93。PPI 估計的任務成功率為 0.66 [0.57, 0.76]，真實值是 0.60，而評審單獨給出的是 0.76，高了 16 個百分點。

延伸閱讀

• 標註引擎
• 標註引擎配置，包括這些契約讀取的 humans 鍵
• 標註者間一致性，以及幾何標註上的一致性，後者對區域、片段和 3D 物體使用相同的損失

實現細節見源文件。

參考文獻

1. Angelopoulos, A. N., Bates, S., Candès, E. J., et al. (2025). Learn then test: Calibrating predictive algorithms to achieve risk control. The Annals of Applied Statistics. https://doi.org/10.1214/24-AOAS1998
2. Angelopoulos, A. N., Bates, S., Fannjiang, C., et al. (2023). Prediction-powered inference. Science, 382(6671). https://doi.org/10.1126/science.adi6000
3. Angelopoulos, A. N., Duchi, J. C., and Zrnic, T. (2023). PPI++: Efficient prediction-powered inference. arXiv. https://arxiv.org/abs/2311.01453
4. Calderon, N., Reichart, R., and Dror, R. (2025). The alternative annotator test for LLM-as-a-judge: How to statistically justify replacing human annotators with LLMs. Proceedings of ACL 2025. https://aclanthology.org/2025.acl-long.782/