Skip to content

ラベリングエンジンのCLI、REST API、MCPツール、SDK

potato label、/api/engine/v1のRESTルート、5つのエンジン用MCPツール、PythonのStudyクラスからラベリングエンジンを操作します。いずれも1つのengine.sqliteファイルを通して動作します。

アノテーションサーバー、コマンドライン、REST API、MCPツール、Python SDKはいずれも、タスクディレクトリにある同じengine.sqliteファイルを通して、同じラベリングエンジンを操作します。研究をコマンドラインで始め、人への依頼をサーバーで提示し、ノートブックから証明することもできます。

1つの研究を同時に操作できるプロセスは1つだけです。実行中のサーバーのプランナーが研究の書き込みロックを持っている間は、potato label run、potato label certify、Study.run()はその旨を示して実行を拒否します。その場合はPOST /api/engine/v1/certifyまたは管理ページを使い、サーバー経由で証明してください。このロックがあるのは、2つのプロセスが操作すると2つのキャリブレーションサンプルが抽出され、互いのラベルに対して証明してしまうためです。ロックは保持者が終了すると解放されます。同じマシン上で強制終了された保持者のロックはすぐに引き継がれ、別のマシン上の保持者のロックはハートビートが2分間途絶えた後に引き継がれます。読み取り専用のコマンド（status、certificate、calls、export）はいつでも使えます。

コマンドライン

エンジンのコマンドはすべて研究の設定ファイルを取ります。

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

9つのコマンドで、最初のモデル呼び出しからデータセットのエクスポートまで、研究全体をカバーします。

コマンド動作
runカスケードですべての項目にラベルを付け、ブラインドのキャリブレーションサンプルを抽出し、証明し、解決します。--until predicted（デフォルト）は1回の処理で止まり、--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でも、新たな検定を行うたびにコントラクトの誤りの予算の一部を消費します。

exportが書き出すファイル

potato label exportは、出力ディレクトリに4種類のファイルを書き出します。

ファイル内容
labels.jsonl, labels.csvラベルの有無にかかわらず、項目とスキーマの組ごとに1行。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すべてのモデル呼び出し。モデル、プロンプトと返答のハッシュ、トークン数、レイテンシ、コスト、キャッシュヒット、マスクのカテゴリを含みます。

通常のエクスポーター（python -m potato.exportと管理画面のエクスポート）は人のアノテーションをエクスポートするもので、エクスポート形式のページに一覧があります。その中のlabeling_engine形式はpotato label exportと同じファイルを書き出し、エンジンが有効でない場合は実行を拒否します。エンジンが有効な場合、CSV、Parquet、Hugging Faceのエクスポートには、各アノテーションがどのエンジンの依頼に答えたものかを示す2つの列が加わります。engine_purposeは目的（たとえばcalibration）を、engine_requestは目的、包含確率、表示の有無、分割、依頼のidを含むJSONを保持します。ブラインドのランダムサンプルを検証の答えと区別するには、これらの列を使ってください。

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、ブライアースコア
GET /schemes/<name>/drift選択的リスクのコントラクトごとの監査モニター
GET /schemes/<name>/optimizedevラベルでスコア付けした、より安価なカスケードのレポート
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プランナーの処理を今すぐ1回実行します

研究でエンジンが無効な場合、ルートは404を返します。limitが数値でない、purposeやstatusが未知である、formatがjson、md、htmlのいずれでもない、といった無効なパラメーターには、JSONのエラーとともに400を返します。

たとえば、次のリクエストはポート8000のサーバーから現在の証明書をMarkdownで取得します。

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

MCPツール

MCPサーバーは、RESTルートと同じ権限で5つのエンジン用ツールを公開します。

  • engine_status
  • engine_requests
  • engine_run：プランナーの処理を1回実行します
  • 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の依頼を閉じ、それがなければその人がその項目で受け持っている依頼を閉じます。どちらもなければ自発的なラベルとして保持され、証明には使われません。同じ人が同じ項目に2つ目のラベルを付けると、最初のラベルが更新されます
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で記録したラベルがどの依頼にも答えていない場合は自発的なラベルとして保持され、自発的なラベルは証明に使われません。そのため、エンジンが依頼していない項目にラベルを付けるスクリプトは、どのコントラクトも読まないラベルを増やすことになります。

参考資料

実装の詳細については、ソースドキュメントを参照してください。