ラベリングエンジンの設定

ラベリングエンジンの動作はすべて、1つのlabeling_engineブロックで設定します。ブロックが無効な場合、サーバーは起動時に停止し、すべての問題をまとめて一覧表示します。アノテーターにエンジンの依頼を提示するには、assignment_strategy: engineも設定してください。エンジンを有効にせずにこの戦略を設定すると、検証エラーになります。

ブロックには次のセクションがあり、それぞれ以下で説明します。

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の直下には5つのキーがあります。

ソース

ソースとは、各項目に対してラベルと信頼度を提案するモデル、または既存のラベルの集合です。すべてのソースは一意のidとkindを持ち、ソースに未知のキーがあるとエラーになります。

答えを変えうるもの（モデル、プロンプト、temperature、オプション）はすべてソースのバージョンハッシュに含まれます。新しいバージョンになると、そのソースに依存するすべてのコントラクトがstaleになります。

スキーマが保持できない値の答え、たとえば一覧にないラベル、数値でない数値フィールド、N択の単一選択スキーマに対するリストなどは、エラーとして記録され、ラベルとして記録されることはありません。実行時のメッセージはこうしたエラーの数を示します。呼び出しが失敗した項目は、以後の実行で再び依頼されます。これはソースのバージョンごとに最大3回までで、その後はソースが変わるまで待機します（キーやプロンプトを修正すると新しいバージョンになります）。1つのソースが失敗した実行でも、他の段は止まりません。次の段がすべての項目にラベルを付け、potato label runはステータス1で終了し、失敗したソースの名前を示します。

信頼度の求め方

エンジンの受理ルールは各予測の信頼度にしきい値を設けるので、ソースが信頼度をどう示すかによって、エンジンがどれだけ受理できるかが決まります。confidence.methodは次の5つの値のいずれかを取ります。

種類ごとのオプション

5種類のソースが独自のオプションを読みます。

• **decision**は、プロセス内のLaya、またはホスト版のJevやOpenJevなど任意の/v1/systemoneサーバーを対象とします。1回のフォワードパスですべての選択肢の確率を返し、radio、select、likert、sliderのスキーマで動作します。endpoint_typeはlayaかsystemoneでなければならず、systemoneにはサーバーのルートであるbase_urlが必要です（/v1/systemoneで終わるURLも受け付けます）。どちらの場合も状態は{"text": ...}として送られるので、1つのチェックポイントはプロセス内でも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（ラベルの順序を逆にして2回尋ね、判定が入れ替わった場合は棄権扱いにする）を取ります。エージェントトレースのスキーマ（process_reward、trajectory_eval、...）では、判定者は各ステップにラベルを付けます。
• **vlm**は視覚エンドポイント（openai_vision、anthropic_vision、ollama_vision）を使います。OpenAI互換サーバーの背後にあるセルフホストのモデルには、base_urlを付けてopenai_visionを使ってください。
• **trained**は、artifact_dir、trainer（デフォルトはsklearn-text）、run_idを取ります。このソースは通常、手書きの設定ではなく蒸留によって作られます。

humans

humansブロックは、誰がラベルを付けるか、エンジンがそれをどうサンプリングするかを設定します。

crowd

crowdブロックはhumans.poolsにcrowdが含まれる場合に適用されます。エンジンが操作できるクラウドソーシングのプラットフォームはProlificだけです。

クラウドソーシングでの募集はデフォルトでドライランで、プランナーは何を行うかを報告します。実際にお金を使うにはfeatures.crowd_live_spend: trueとbudgets.human_usdの上限が必要で、上限なしで実際の支出を有効にした設定は拒否されます。Prolificの研究自体の設定はクラウドソーシングで説明しています。

budgets

budgetsブロックは、上限を超える前に支出を止めます。

runtime

runtimeブロックは、バッチ処理、並列度、人が依頼を受け持てる時間を制御します。

features

driftを除き、すべての機能はデフォルトで無効です。

redaction

redaction.categoriesは、email、url、ip、card、ssn、phone、handleのうちどれをマスクするかを列挙し、デフォルトはすべてです。マスクはfeatures.pii_redactionが有効な場合に、外部のAPIに対してのみ適用されます。セルフホスト型のエンドポイント（vllm、ollama、laya、yolo、...）は、どこで動いていてもマスクされず、base_urlが同じマシン上にあるエンドポイントもマスクされません。

distill

features.distillが有効な場合、エンジンは研究のラベルで安価なモデルを学習し、カスケードの先頭に置きます。

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

また、すべての機械の答えが正しかったとしてもselective_riskコントラクトを証明できないほどbudgets.human_labelsが小さい場合にも、検証で警告が出ます。その警告が消えるまで、予算を増やすかerrorを緩めてください。

参考資料

• ラベリングエンジン
• ラベリングエンジンのコントラクト
• コマンドライン、REST API、MCPツール、SDK
• ソースがPotatoの他の部分と共有するエンドポイントの種類については、AIサポート

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