Skip to content

標註引擎的命令列、REST API、MCP 工具和 SDK

通過 potato label、/api/engine/v1 REST 路由、五個引擎 MCP 工具或 Python 的 Study 類來驅動標註引擎，它們共用同一個 engine.sqlite 檔案。

標註伺服器、命令列、REST API、MCP 工具和 Python SDK 都通過任務目錄裡同一個 engine.sqlite 檔案，驅動同一個標註引擎。你可以從命令列啟動一項研究，用伺服器提供人工請求，再在筆記本里完成認證。

同一時間只有一個程序驅動一項研究。執行中的伺服器的規劃器持有研究的寫入鎖，在它持有期間，potato label run、potato label certify 和 Study.run() 會拒絕執行並說明原因。這時請改為通過伺服器認證，使用 POST /api/engine/v1/certify 或管理頁面。之所以要有這把鎖，是因為兩個驅動方會抽取兩份校準樣本，並拿對方的標籤來認證。持有者退出時鎖會釋放。同一臺機器上被終止的持有者，其鎖會被立即接管；另一臺機器上的持有者，則在兩分鐘沒有心跳後被接管。只讀命令（status、certificate、calls、export）隨時都能使用。

命令列

每條引擎命令都接受研究的配置檔案：

bash
potato label <command> <config.yaml> [options]

這九條命令覆蓋了一項研究從第一次模型呼叫到匯出資料集的全過程：

命令作用
run用級聯為每個條目打標籤，抽取盲態校準樣本，認證，定案。--until predicted（預設）執行一輪後停止，--until met 會一直執行，直到每份契約都滿足，或者引擎在等待人工。還接受 --max-items N、--budget-usd X（本次執行覆蓋 budgets.model_usd）、--max-ticks N（預設 20）和 --json。被終止的執行會從停下的地方繼續，不會重複模型呼叫。當某個來源上次執行失敗或它給出的每個答案都是錯誤，或者沒有任何來源能標註契約指定的方案時，以狀態碼 1 退出，並指出該來源。
status條目、預測、按用途分列的請求、契約、花費、尚無標籤的條目，以及每個出錯或執行失敗、暫停的來源各佔一行。--json。
certify在新的 cert 標籤和新的預測上檢驗每份契約。如果只有 dev 標籤變了，會返回儲存的結果並附一條說明；--retest 會在下一次檢視時檢驗 dev 現在選出的規則（參見檢視次數）。--json。
certificate品質證書。--format md（預設）、html 或 json，以及 --out FILE。
export把帶來源記錄的標籤、證書（JSON、Markdown、HTML）、資料集卡片和呼叫日誌寫入 --out DIR（預設 <output_annotation_dir>/labeling_engine）。
calls以 JSON lines 格式輸出模型呼叫審計日誌。--out FILE。
distill用目前的標籤訓練一個模型，並把它放在級聯的第一位。
optimize在 dev 標籤上為級聯的每個子集打分，報告保持覆蓋率的最便宜子集。如果沒有任何子集能保持覆蓋率，它就不推薦任何子集。--prompts N 還會請某個 LLM 層為它的提示詞生成 N 個改寫版本，並在 dev 條目上為每個版本打分。這些都是模型呼叫，會記入日誌、計入預算，並以各自的來源版本儲存，而當前提示詞則用它儲存的預測來打分。級聯和證書都不會被修改。
migrate-config寫出配置的一份副本，其中帶有與舊 AI 鍵等價的 labeling_engine 塊。--out FILE。參見遷移到標註引擎。

檢視進度不消耗任何預算，因為 status、certificate 和管理頁面讀取的是儲存的結果。每一次新的檢驗，無論來自對新標籤執行 certify，還是來自 certify --retest，都會消耗契約的一部分誤差預算。

匯出寫出的檔案

potato label export 向輸出目錄寫入四類檔案：

檔案內容
labels.jsonl, labels.csv每個條目和方案一行，無論是否已有標籤，包含 id、schema、label、label_origin（auto、human、adjudicated……）、status（accepted、threshold_legacy 下的 accepted_uncertified、pending、pending_recert）、source、model、source_version、confidence、contract_version 和 request_ids。如果某個機器標籤的來源在它被接受後發生了變化，它會顯示為 pending_recert，直到下一輪重新認證它。
certificate.json, .md, .html證書。
README.md根據證書生成的資料集卡片，帶有 Hugging Face 前置後設資料。
model_calls.jsonl每一次模型呼叫，包含模型、提示詞和回覆的雜湊值、token 數、延遲、成本、快取命中和遮蓋類別。

常規匯出器（python -m potato.export 和管理端匯出）匯出的是人的標註，匯出格式頁面列出了它們。其中，labeling_engine 格式寫出的檔案與 potato label export 相同，引擎未啟用時它會拒絕執行。開啟引擎時，CSV、Parquet 和 Hugging Face 匯出會多出兩列，說明每條標註回答的是引擎的哪個請求。engine_purpose 存放用途，例如 calibration；engine_request 存放 JSON，包含用途、入樣機率、可見性、劃分和請求 id。用這兩列可以把盲態隨機樣本與核驗答案分開。

REST API

所有引擎路由都位於 /api/engine/v1 下，返回 JSON。認證方式是在 X-API-Key 頭中提供管理員金鑰，或使用管理員會話。讀取需要管理面板許可權，certify 和 plan 需要分配管理許可權，證書需要匯出許可權。

方法和路徑返回
GET /status條目、預測、請求、呼叫總數、預算，以及每個方案的級聯、契約和已定案標籤數
GET /schemes/<name>/contracts該方案上每份契約的最新結果，如果級聯變了則標為 stale
GET /schemes/<name>/risk_coverage在 cert 標籤上，最後一層每個閾值的接受比例、觀測錯誤率和保證的上界
GET /schemes/<name>/reliability在校準標籤上，每一層的可靠性分箱、ECE 和 Brier 分數
GET /schemes/<name>/drift每份選擇性風險契約的抽查監控
GET /schemes/<name>/optimize在 dev 標籤上打分的更便宜級聯報告
GET /requests按用途和狀態分列的請求數，以及請求本身。過濾參數為 purpose、status（重複該參數，或用逗號分隔多個值）、schema 和 limit（最大 1000）
GET /calls呼叫日誌，最新的在前，以及按來源彙總的總數。limit（最大 500）、offset
GET /certificate證書。format=json（預設）、md 或 html，save=1 還會把它儲存下來
GET /crowd規劃器最近一次的眾包計劃，除非開啟實際花費，否則是演練
POST /certify立即檢驗每份契約。?retest=1（或 {"retest": true}）還會檢驗只有 dev 標籤發生變化的規則
POST /plan立即執行一次規劃器

研究未開啟引擎時，這些路由返回 404。對於無效的參數，例如不是數字的 limit、未知的 purpose 或 status，或者 json、md、html 以外的 format，它們返回 400 和一個 JSON 錯誤。

例如，下面的請求從執行在 8000 埠的伺服器上以 Markdown 格式獲取當前證書：

bash
curl -H "X-API-Key: $ADMIN_API_KEY" \
  "http://localhost:8000/api/engine/v1/certificate?format=md"

MCP 工具

MCP 伺服器提供五個引擎工具，許可權與 REST 路由相同：

  • engine_status
  • engine_requests
  • engine_run，執行一次規劃器
  • engine_certify，接受 retest
  • engine_certificate，格式為 json、md 或 html

在引擎關閉時授予這些工具，會產生校驗警告。通過 potato mcp connect 呼叫時，被拒絕的呼叫（缺少許可權、參數錯誤）會作為工具錯誤返回，並帶上伺服器的訊息。MCP 伺服器文件介紹瞭如何授予工具和連線客戶端。

Python SDK

Study 類用於在 Python 中驅動引擎，例如在筆記本里：

python
from potato.labeling_engine.sdk import Study
 
study = Study("examples/labeling-engine/text-certified-sentiment/config.yaml")
study.run()                                   # label, sample, certify, resolve
for req in study.requests(status="open")[:5]:
    study.label(req.item_id, req.schema, "positive", user="me")
study.certify()
print(study.certificate(fmt="md"))
study.export("out/")

每個方法都對應一條命令或一個路由：

方法作用
Study(config_path)載入配置和條目
run(until="predicted", max_ticks=20)與 potato label run 相同，並獲取寫入鎖
label(item_id, scheme, value, user, request_id=None)記錄一個人的標籤。它會關閉 request_id，否則關閉這個人在該條目上持有的請求，如果都沒有，就保留為自發標籤，自發標籤永遠不用於認證。同一個人在同一條目上的第二個標籤會更新他的第一個標籤
status()與 GET /status 相同
requests(status=None, purpose=None, ...)請求臺賬
certify(retest=False)與 potato label certify 相同
certificate(fmt="json")json、md 或 html
export(out_dir)與 potato label export 相同

示例把每個未關閉的請求都標為 "positive"，只是為了演示這些呼叫。通過 Study.label 記錄、但不回答任何請求的標籤會被保留為自發標籤，而自發標籤永遠不用於認證，所以一個為引擎沒有請求的條目打標籤的指令碼，新增的是任何契約都不會讀取的標籤。

延伸閱讀

實現細節見源文件。