標註引擎配置

labeling_engine 塊中的每一個鍵，涵蓋來源和置信度方法、人工標註池、眾包花費、預算、執行時限制、功能開關，以及校驗會拒絕哪些寫法。

標註引擎所做的一切都在一個 labeling_engine 塊中設定。無效的塊會讓伺服器在啟動時停下，並一次性列出所有問題。要讓標註者拿到引擎的請求，還需要設定 assignment_strategy: engine。設定了這個策略卻沒有啟用引擎，屬於校驗錯誤。

這個塊包含以下幾個部分，下文逐一說明：

yaml

assignment_strategy: engine
 
labeling_engine:
  enabled: true
  schemas: [sentiment]            # default: every scheme a source can label
  sources: []
  cascade: [laya, gemma]          # default: the first source alone
  contracts: []
  humans: {}
  crowd: {}
  budgets: {}
  runtime: {}
  features: {}
  redaction: {}
  distill: {}

頂層鍵

直接位於 labeling_engine 下的鍵有五個：

鍵	預設值	含義
`enabled`	`false`	開啟引擎。啟用的引擎至少需要一個來源。
`schemas`	全部	引擎負責標註的標註方案。在 `assignment_strategy: engine` 下，沒有列入的方案只會在引擎為自己的方案交給人的那些條目上得到回答，而不是在每個條目上，校驗會對此發出警告。沒有任何來源能標註的方案（例如自由文本）不能放進引擎，所以在這個策略下它永遠不會在每個條目上得到回答。如果必須如此，請改用其他分配策略。
`sources`	`[]`	模型。參見來源。
`cascade`	第一個來源	按嘗試順序排列的來源 id。最後一個之後是人。
`contracts`	`[]`	標籤必須滿足的條件。參見契約。

來源

來源是一個模型或一組已有標籤，它為每個條目提出一個標籤和一個置信度。每個來源都有唯一的 id 和一個 kind，來源上出現未知的鍵屬於錯誤：

鍵	預設值	含義
`id`	必填	在 `cascade`、呼叫日誌和證書中使用的名稱。
`kind`	必填	`llm`、`vlm`、`decision`、`detector`、`judge`、`jury`、`trained`、`static`、`fixture`、`asr`、`lf`、`simulator` 之一。
`endpoint_type`	`llm`、`vlm`、`decision`、`judge` 必填	AI 端點，例如 `vllm`、`openai`、`anthropic`、`gemini`、`ollama`、`openrouter`、`openai_vision`、`ollama_vision`、`laya` 或 `systemone`。`detector` 預設為 `yolo`。
`model`	端點預設值	模型名稱。
`base_url`	無	自託管或相容 OpenAI 的端點的伺服器 URL。
`api_key`	無	永遠不會被雜湊進版本，也永遠不會被匯出。`${ENV_VAR}` 會被替換。
`temperature`	`0.0`	0 到 2。
`max_tokens`	`256`	每次呼叫的輸出 token 上限。
`timeout`	端點預設值	每次呼叫的秒數。
`prompt`	根據方案生成	提示詞模板。更改它會產生一個新的來源版本。
`confidence`	`{method: auto}`	來源如何給出置信度。參見置信度方法。
`concurrency`	`runtime.concurrency`	對這個來源的並行呼叫數。
`schemas`	引擎的全部方案	把來源限定在這些方案上。
`options`	`{}`	特定類型的選項，見下文。
`judge`	`{}`	僅限 `judge`。與 `options` 相同的選項，放在自己的鍵下；兩處都設定了同一選項時以 `options` 為準。
`members`	無	僅限 `jury`。至少兩個其他來源的 id。
`aggregation`	`plurality`	僅限 `jury`。相對多數是唯一的規則。
`field` / `predictions_file`	無	僅限 `static`。已有標籤所在的位置。該欄位存放 `{scheme: label}`，來源只標註一個方案時也可以是單獨的標籤。如果每個條目上的該欄位形狀都不對，執行會失敗，並給出指明該欄位的訊息。
`error_rate`, `seed`	無	僅限 `fixture`。一個已知錯誤率的合成來源，用於測試。
`revision`	無	要記錄進版本的模型修訂號，例如檢查點的雜湊值。

凡是可能改變答案的東西（模型、提示詞、溫度、選項）都會計入來源的版本雜湊。新版本會讓依賴該來源的每份契約變為 stale。

不是方案可取值的答案，例如不在列表中的標籤、不是數字的數值欄位，或單選方案上的一個列表，會被記錄為錯誤，永遠不會被當作標籤，執行的訊息會統計這些錯誤。呼叫失敗的條目會在之後的執行中再次請求，每個來源版本最多三次，之後它會等待來源發生變化（修好的金鑰或提示詞就是一個新版本）。某個來源失敗的執行不會讓其他層停下。下一層會為每個條目打標籤，potato label run 以狀態碼 1 退出，並指出失敗的來源。

置信度方法

引擎的接受規則是對每條預測的置信度設閾值，所以來源如何給出置信度，決定了引擎能接受多少。confidence.method 取以下五個值之一：

`confidence.method`	適用於	作用
`verbalized`	`llm`、`vlm`、`judge`	模型在回覆中給出 0-100 的數值。一次呼叫，是最不可靠的方法。
`k_sample`	`llm`	以 `sample_temperature`（預設 0.7）取得 `samples` 個回覆（預設 5 個）。標籤是最常見的答案，置信度是它所佔的比例。花費 k 次呼叫。
`logprob`	`llm`	給標籤編上字母，模型用一個字母作答，置信度從第一個 token 的機率中讀出。一次呼叫，通常校準得最好。需要能返回 logprob 的後端（vLLM、相容 OpenAI 的服務），並且標籤不超過 20 個，標籤更多的方案屬於校驗錯誤。
`native`	`decision`、`detector`、`trained`	模型自身的機率。用在 `llm` 來源上屬於校驗錯誤。
`auto`	全部	來源支援時用 `native`，否則用 `verbalized`。

特定類型的選項

有五種來源類型讀取自己的選項：

decision 涵蓋程序內的 Laya，或任何 /v1/systemone 伺服器，例如託管的 Jev 或 OpenJev。一次前向計算就為每個選項返回一個機率，適用於 radio、select、likert 和 slider 方案。endpoint_type 必須是 laya 或 systemone，systemone 需要 base_url，即伺服器根地址（以 /v1/systemone 結尾的 URL 也可以）。兩種情況下狀態都以 {"text": ...} 傳送，所以同一個檢查點在程序內和在 laya-serve 後面給出的答案相同；options: {state_key: ""} 則改為傳送裸字串。在評分量表（likert、slider）上，Laya 的分數幾乎跟不上量表，所以在依賴它之前先檢查幾個條目。程序內的 laya 端點需要 pip install 'potato-annotation[decision]'。
detector 在 image_annotation 方案上讀取目標檢測器給出的邊界框。keep_threshold（0.35）設定分數達到多少的框才算作預測的一部分。分數介於 candidate_threshold（0.05）和 keep_threshold 之間的框會降低這張影像的置信度。label_map 把檢測器的類別對映到方案的標籤，未對映的類別會被忽略。image_field 指定存放影像路徑或 URL 的條目欄位。路徑的解析方式與標註頁面相同：/media/x.jpg 位於任務的 media_directory 下，相對路徑位於 task_dir 下。
judge 接受 rubric（預設為方案的描述）、fields（按順序展示給評審的條目欄位）和 swap_order，後者會把標籤順序反過來再問一次，前後翻轉的判定變為棄權。在智慧體軌跡方案（process_reward、trajectory_eval……）上，評審為每一步打標籤。
vlm 使用視覺端點（openai_vision、anthropic_vision、ollama_vision）。對於部署在相容 OpenAI 的伺服器後面的自託管模型，使用 openai_vision 並設定 base_url。
trained 接受 artifact_dir、trainer（預設 sklearn-text）和 run_id。這個來源通常由蒸餾生成，而不是手寫配置。

humans

humans 塊設定由誰來標註，以及引擎如何向他們抽樣：

鍵	預設值	含義
`pools`	`[team]`	由誰標註：`team`、`crowd`、`solo`。
`calibration_rate`	`auto`	抽取用於盲態校準的條目比例。`auto` 根據契約的預估選擇比例，保證每個類別有足夠的標籤可供檢驗，小型研究最多一半，超過 1,000 個條目的研究最多五分之一。
`dev_fraction`	`0.5`	用於選定閾值的校準標籤比例。其餘的用來檢驗。
`min_calibration_per_class`	`10`	檢驗按類別的契約之前，每個類別的最低數量。
`audit_rate`	`0.02`	新接受的機器標籤中以盲態送回給人、用於監控漂移的比例。
`overlap`	`0.0`	由多人標註的校準條目比例。
`overlap_k`	`3`	每個重疊條目的標註人數。`no_worse_than_human` 契約需要 3 人。
`distribution_k`	`5`	`distributional` 契約中每個條目的標註人數。
`truth`	`majority`	多人在同一條目上的標籤如何合成為契約用來檢驗的標籤，取 `majority` 或 `dawid_skene`。
`verify_visibility`	`shown`	核驗請求顯示機器的答案（`shown`）還是不顯示（`blind`）。

crowd

當 crowd 在 humans.pools 中時，crowd 塊才生效，Prolific 是引擎唯一能驅動的眾包平臺：

鍵	預設值	含義
`provider`	`prolific`	眾包平臺。
`study_id`	無	要調整規模的 Prolific 研究。
`reward_usd`	無	每個名額的報酬，用於成本預估。
`per_worker_quota`	`20`	每位工作者的請求數。名額數為 `ceil(open requests / quota)`。

眾包招募預設是演練，規劃器只報告它會做什麼。要真正花錢，需要 features.crowd_live_spend: true 和 budgets.human_usd 上限，開啟實際花費卻沒有上限的配置會被拒絕。眾包介紹瞭如何設定 Prolific 研究本身。

budgets

budgets 塊在超出限額之前停止花費：

鍵	含義
`model_usd`	花費達到這個數額後，停止呼叫計價模型。每次呼叫會先預留它的預估成本。沒有價格的模型以及 `localhost` 上的自託管模型不受此限制。
`human_usd`	眾包花費的上限。實際眾包花費必須設定。
`human_labels`	引擎最多可以發出的人工請求數，在每個請求發出時計數。

runtime

runtime 塊控制分批、併發，以及一個人可以持有請求多久：

鍵	預設值	含義
`batch_size`	`32`	每個提交塊的條目數。被終止的執行會從下一個塊繼續，不會重複呼叫。
`concurrency`	`4`	每個來源的並行呼叫數，可被來源自己的 `concurrency` 覆蓋。
`cache`	`true`	複用同一來源版本對相同請求的回覆。
`retries`	`2`	遇到超時、連線錯誤、429 或 5xx 後額外嘗試的次數。每次嘗試都會記入日誌。
`planner_interval`	`30`	伺服器中兩次規劃器執行之間的秒數。
`hold_minutes`	`60`	一個人持有請求而不作答的最長分鐘數，超過後請求回到池中。該條目也會從他的頁面上移除，所以開著不管的標籤頁之後無法再回答它。

features

除 drift 外，所有功能預設關閉：

鍵	開啟什麼
`drift`	預設開啟。根據抽查結果採取行動。當抽查顯示已接受標籤的錯誤率高於目標時，契約顯示為 `violated`，該方案上的機器標籤不再被接受，並抽取新的校準標籤。每次認證都會開始一個新的抽查序列，所以修復後重新認證就能恢復接受。設為 `false` 時只報告違規，契約顯示為 "met, audits breached"。
`distill`	用本研究的標籤訓練一個模型，並把它放在級聯的第一位（參見 distill）。
`optimize`	讓規劃器每次執行時在 dev 標籤上為級聯的每個子集打分，並在 `GET /api/engine/v1/schemes/<name>/optimize` 報告保持契約覆蓋率的最便宜子集。不會自動應用任何結果，因為採用一個級聯意味著修改配置並重新認證。
`crowd_recruit`	讓規劃器調整 Prolific 研究的規模，除非開啟 `crowd_live_spend`，否則只是演練。
`crowd_live_spend`	真正修改 Prolific 研究。需要 `crowd` 池和 `budgets.human_usd`。
`pii_redaction`	在文本發往第三方 API 之前，遮蓋電子郵件、URL、IP 地址、卡號、SSN、電話號碼和 @使用者名稱。呼叫日誌以類別和雜湊值記錄遮蓋了什麼，從不記錄文本本身。
`payload_capture`	在 `<task_dir>/engine_payloads/` 下保留完整的提示詞和回覆。預設關閉，呼叫日誌只保留雜湊值。

redaction

redaction.categories 列出要遮蓋 email、url、ip、card、ssn、phone 和 handle 中的哪些，預設全部遮蓋。只有開啟 features.pii_redaction 時才會遮蓋，並且只針對第三方 API。自託管的端點類型（vllm、ollama、laya、yolo……）無論在哪裡執行都不遮蓋，base_url 位於同一臺機器上的任何端點也不遮蓋。

distill

開啟 features.distill 後，引擎會用本研究的標籤訓練一個便宜的模型，並把它放在級聯的第一位：

鍵	預設值	含義
`trainer`	`sklearn-text`	來自 `potato/training` 的訓練器。
`min_labels`	`200`	標籤達到這個數量後才開始訓練。
`include_silver`	`true`	同時用契約認證過的機器標籤訓練，標記為銀標準。
`every`	`2.0`	標籤數量增長到這個倍數時重新訓練。

cert 和抽查劃分中的條目永遠不會進入訓練集，所以蒸餾模型永遠不會在它訓練過的標籤上接受檢驗。

校驗

potato validate config.yaml 會連同配置的其餘部分一起檢查 labeling_engine 塊，每條錯誤都會指出對應的鍵，例如 labeling_engine.sources[1].kind must be one of ... 或 labeling_engine.contracts[0].error is required for selective_risk。校驗還會拒絕：

契約類型不讀取的契約鍵，例如 error 的拼寫錯誤；
位於級聯中沒有任何來源能標註的方案上的契約，並給出每個來源的原因；
位於引擎無法評分的方案（自由文本、成對比較）上的契約；
endpoint_type 不是決策模型的 decision 來源，以及 endpoint_type 是決策模型的 llm、vlm 或 judge 來源；以及
humans.overlap_k 低於 3 的 no_worse_than_human。

當 budgets.human_labels 小到即使每個機器答案都正確也無法認證一份 selective_risk 契約時，校驗也會發出警告。請提高預算或放寬 error，直到這條警告消失。