Potatoのモデルトレーナー（タスク別）

v2.14.0の新機能

Potatoのモデル学習には38のトレーナーがあり、各トレーナーは、1種類のアノテーションスキームの答えに、1種類のモデルを当てはめます。このページの表は、すべてのトレーナーをタスク別に並べ、トレーナーが学習元とするスキーム、読み込む項目、必要なインストール、書き戻す事前ラベル、各実行が報告するホールドアウトスコアを示します。対象は、最初の実行の前にトレーナーを選ぶ研究の担当者と、あるスキームを学習できるかどうかを確かめたい担当者です。設定のキー、バックエンド、書き戻しの規則は設定ページにあります。各トレーナーのパラメーターの完全な表は、アップストリームのリファレンスのトレーナーごとのセクションにあり、以下の各トレーナー名はそのセクションにリンクしています。

スキームごとに提示されるトレーナー

/admin/trainingのTrainingページは、各スキームに対して、スキームの種類と、スキームの項目のモダリティ（テキスト、画像、音声など）に合うトレーナーだけを提示します。プロジェクトで実行できないトレーナーは、理由とともにリストに残ります。たとえばdecision-calibrateは、プロジェクトに判断モデルができるまで「no decision model is configured」と表示されます。パッケージが足りないトレーナーは「not installed」と表示され、パッケージをインストールするコマンドが添えられます。トレーナーを選ぶまでは、sklearn-textが使える場所ではどこでもsklearn-textが選択されています。存在しないスキーム、またはトレーナーが学習できないスキームに対して開始した実行は、何かが作られる前にHTTP 400で拒否されます。

各実行は1つのスキームで学習します。Trainingページが送るスキームは1つで、学習用APIはスキームのリストを受け取りますが、どのトレーナーもリストの最初のスキームしか学習しません。2つのスキームを学習するには、実行を2回開始します。

以下の表の「事前ラベル」列は、スキームがwriteback.schemasに挙がっているときに、実行が項目に書き込む内容を示しています。実行のtrain分割の項目に事前ラベルは付かず、事前ラベルがアノテーターの答えになるのは、アノテーターが事前ラベルを編集するか、次に進んだときだけです。「ホールドアウトスコア」列は、実行の代表の指標を示し、アノテーターが統合したラベルに対して、valとtestの項目で計算されます。ラベルがあって予測がない項目は、不正解として数えられます。そのため、トレーナーは難しい項目を飛ばしてスコアを上げることはできません。アップストリームのリファレンスのホールドアウトスコアに、すべての指標の定義があります。

トレーナーのインストール

sklearn-textは、scikit-learnがコア依存関係なので、通常のPotatoのインストール以外に何も必要ありません。テキスト、画像、音声、LLMのトレーナーにはPyTorchとtransformersが必要です。1つのextraで、4グループすべてのパッケージがインストールされます。

pip install "potato-annotation[train]"

より範囲の狭いextraの[train-text]、[train-vision]、[train-audio]、[train-llm]は、それぞれ1グループをインストールします。以下の「インストール」列には、pip install "potato-annotation[train-vision]"のように、各トレーナーをカバーする最も範囲の狭いextraが書かれています。PyTorchは数ギガバイトのインストールになるため、学習用のextraはpotato-annotation[all]には含まれません。[train]の外のパッケージが必要なトレーナーもあります。

• ultralytics-detectとultralytics-segmentにはpip install ultralyticsが必要です。
• cellposeにはpip install cellposeが必要で、Cellpose 3でもCellpose 4でも動作します。
• laya-finetuneには[decision]が、openjev-finetuneにはpip install wev-aiが必要です。
• rdkit-propertyには[chemistry]、volume-unetには[volumes]、video-trackにはopencv-pythonが必要で、WFDBまたはParquetの信号には[signals]が必要です。全スライド画像には、openslide用の[wsi]が必要です。
• hf-text-classificationとhf-image-classificationのdpオプションにはpip install opacusが必要です。

ultralytics-detect、ultralytics-segment、layoutlmv3は、最初の実行の前にライセンスの確認を求めます。UltralyticsはAGPL-3.0なので、どちらかのYOLOトレーナーで学習して配布したモデルはAGPLの条件に従うことになり、クローズドな用途には、Ultralyticsが別のライセンスを販売しています。LayoutLMv3の重みはCC BY-NC-SA 4.0で、商用利用はできません。この3つのトレーナーでは、Trainingページが確認を求め、APIからの実行にはaccept_licence: trueが必要で、自動再学習にはauto_retrain.accept_licence: trueが必要です。CellposeのコードのライセンスはBSD-3-Clauseで、Cellposeの事前学習済みの重みは、Cellposeの作者が独自の条件で公開しています。model_nameに指定するチェックポイントによっても、ライセンスは異なります。たとえば、Qwen2.5-VL-3BはQwen研究ライセンスで、Qwen2.5-VL-7BはApache-2.0です。

パラメーター

実行のパラメーターは3か所から来ており、後のものが前のものを上書きします。

1. トレーナーの既定値。トレーナーのアップストリームのセクションに載っています。
2. 設定のmodel_training.trainer_params.<trainer>。
3. 実行自身のparams。つまり、TrainingページのParameters欄、APIの実行のparams、またはauto_retrain.paramsです。

model_trainingブロックにtrainer_paramsを追加すると、使うトレーナーごとに既定値を設定できます。

model_training:
  enabled: true
  trainer_params:
    hf-text-classification:
      model_name: answerdotai/ModernBERT-base
      epochs: 4
    torchvision-detect:
      model_name: fasterrcnn_resnet50_fpn_v2
      score_threshold: 0.4

TrainingページのParameters欄はJSONで、選んだトレーナーのtrainer_paramsから入力されます。トレーナーが受け取らないパラメーター名はエラーになります。trainer_paramsの下の名前はサーバーの起動時に、実行のparamsの中の名前は実行が始まる前に、それぞれ停止させます。どちらのエラーも、トレーナーが受け取る名前を一覧で示します。たとえば、torchvision-detectの下でscore_threshと綴りを誤ると、score_thresholdを含む一覧とともに報告されます。Potatoは、各値をパラメーターの型と範囲に照らして検査します。

テキストと画像の分類器

分類器は、選択型のスキームradio、select、likert、multiselectから学習します。radio、select、likertの事前ラベルは1つの答えを選択し、multiselectの事前ラベルはラベルの集合にチェックを付けます。sklearn-textは追加のインストールなしでCPUで動き、最初のモデルのチュートリアルでは、sklearn-textでの実行を通しで説明しています。画像コーパスでは、sklearn-textは、CLIPの画像埋め込みに分類器を当てはめます。setfitはプロジェクトの初期のために作られており、ラベル1つあたり8項目ほどのラベル付き項目から動作します。アノテーション側については、radioとmultiselect、select、リッカート尺度のスキームのページを参照してください。

hf-text-classificationはトランスフォーマーをファインチューニングし、lora: trueを指定すると、QwenやLlamaのようなデコーダーLLMもファインチューニングします。soft_targets: trueを指定すると、hf-text-classificationは、統合した1つのラベルではなく、アノテーターの投票の割合に向けて学習します。hf-text-classificationとhf-image-classificationはacquisitionパラメーターを受け取り、単一ラベルのスキームで次にラベルを付ける項目を、マージン、エントロピー、BALD、コアセット距離で並べます。使い方はループの中のモデルのチュートリアルに示されています。どちらのトレーナーも、Opacusを通じたDP-SGDでの学習のためのdpを受け取り、差分プライバシーのチュートリアルでdpの実行を通しで説明しています。

スパン、関係、構造

このグループのトレーナーは、文字オフセットつきのスパン、スパン間のリンク、会話ツリーのノードへの答え、行間グロスを学習します。hf-relationは、1つのエンコーダーに、スパンのタグ付けとスパンのペアの分類を学習させます。予測されたリンクが見つかったと数えられるのは、タガーがそのリンクの2つのスパンの両方を正しい境界で見つけたときだけです。span_linkスキームの学習用の答えがすべて係り受け木のとき、hf-relationは木をデコードし、スコアにUASとLASを加えます。実行は最初のモデルのチュートリアルと同じ手順で進み、選ぶトレーナーとスキームだけが異なります。

LLMと報酬モデル

LLMのトレーナーは、自由記述の答え、選好、ランキング、修正されたエージェントのトレースから学習します。llm-sftとllm-dpoは既定でLoRAアダプターを学習し、lora: {quantize: 4bit}を指定すると、ベースモデルが4ビットで読み込まれます。これはQLoRAです。reward-modelは、ペア比較、ランキング、best-worstの答えからスカラーの報酬モデルを学習し、各予測は、スキームの答えと並べて選択肢ごとの報酬を保持します。prm-rewardは、エージェントのトレースの各ステップを、正しい、中立、誤りのいずれかで評価します。max_length（既定は1,024トークン）を超えたステップは、学習にも評価にも使われません。trajectory_editの予測はスコアが測られて保存されますが、事前ラベルとして表示されることはなく、writeback.schemasの下にtrajectory_editスキームがあると、サーバーは起動を拒否します。LLMファインチューニングのチュートリアルでは、SFT、DPO、報酬モデル、プロセス報酬モデル、QLoRAを扱います。

画像の検出とセグメンテーション

検出器とセグメンターは、image_annotationスキームでアノテーターが描いた図形を学習し、検出器とセグメンターの多くは、顕微鏡画像、地図、スペクトログラムのスキームも読み込みます。検出器は各図形のバウンディングボックスで学習するため、ポリゴンやマスクの研究でも、学習されるのはボックスの検出器です。セグメンターは輪郭で学習してボックスは使わず、アノテーターが1点ずつ編集できる、最大64頂点のポリゴンを予測します。cellposeはクラスなしでセグメンテーションするため、予測された細胞にはすべて、labelパラメーターのラベルが付き、labelが未設定のときは、スキームで最も多いラベルが付きます。

sam-finetuneは、画像エンコーダーを固定したまま、Segment Anythingのマスクデコーダーをファインチューニングして、ボックスを輪郭に変えます。sam-finetuneの実行は、以前の検出の実行が書き戻したボックスの事前ラベルの輪郭を描くため、通常の順序は、writeback.include_unlabeled: trueで検出の実行をしてから、同じスキームでsam-finetuneの実行をすることです。Macでは、torchvision-detectとtorchvision-segmentはMetalではなくCPUで学習します。視覚モデルのチュートリアルでは、検出、セグメンテーション、スライド、顕微鏡画像、地図、Cellpose、SAMを通しで説明しています。

画像のトレーナーは、タスクディレクトリまたはmedia_directoryの中のローカルファイルを読み込みます。リモートのhttp(s)の画像はダウンロードされず、画像がリモートまたは欠けている行は、実行から除かれて予測も付きません。アップストリームのリファレンスの画像項目には、Potatoが画像パスを読み取るフィールドが示されています。

スライド、顕微鏡画像、地図、スペクトログラム

検出とセグメンテーションのトレーナーは、各画像を数百ピクセルにリサイズします。そのため、image_annotation、microscopy、geo_annotationのスキームでは、実行のバンドルを作るときに、Potatoが大きな画像をタイルに切ります。タイル化は、.svsや.ndpiなどのスライド形式と、長辺が4,096ピクセル以上の画像で、既定でオンです。1枚のスライドのタイルは、必ず1つの分割に入り、予測された図形は、ディープズームビューアーが保存する座標で、画像全体に対応づけられます。tilingの表にはすべてのキーが載っており、視覚モデルのチュートリアルでは、スライドのタイルサイズ、オーバーラップ、解像度を設定します。

microscopyスキームのROIは、検出とセグメンテーションのトレーナーとcellposeを学習させます。ROIのあるz平面と時点は、スキームの既定のチャンネルとコントラストで描画され、予測は、各ROIのzとtを持つROIとして戻ります。geo_annotationスキームは、項目のラスターのベースマップ、つまりGeoTIFFまたは範囲を持つ画像で学習し、予測は、地図に提案として表示される、EPSG:4326のGeoJSONとして戻ります。ベースマップがタイルサーバーから来る地図には学習に使えるラスターがなく、実行はそれらの項目を警告とともに除外します。spectrogram_annotationスキームは、スペクトログラムとして描画した各録音でtorchvision-detectとultralytics-detectを学習し、ボックスは秒とヘルツで戻ります。アップストリームのリファレンスの顕微鏡画像と地図とスペクトログラムに、描画の詳細があります。

文書と視覚言語モデル

layoutlmv3は、ページ上の単語と単語の位置から文書のレイアウトを学習し、vlm-sftは、画像についての答えで視覚言語モデルをファインチューニングします。PotatoはOCRを実行しないため、layoutlmv3の各項目には、各単語のテキストとボックスを持つwordsフィールドが必要です。regionsモードのPAGE XMLインポートがwordsを埋め、PDFのテキストレイヤーや別のOCRツールから得た単語も同じように使えます。vlm-sftは既定でLoRAアダプターを学習し、実際のチェックポイントにはGPUが必要です。region_captionの実行はスコアが測られますが、公開はされません。キャプションが説明する領域は、アノテーターの答えだからです。視覚モデルのチュートリアルでは2つのトレーナーを扱い、VLMのグラウンディングではgrounding_evalスキームを扱います。

音声と発話

音声のトレーナーは、soundfileが開けるローカルファイル（WAVやFLACなど）から録音を読み込み、音声がURLの項目は除かれます。hf-audio-taggerは、audio_annotationスキームで、ラベル付きの時間区間にタグを付けます。whisper-asrは、アノテーターが修正した書き起こしのターンでWhisperをファインチューニングし、既定では、potato transcripts --transcribeとfaster-whisper用に、モデルのCTranslate2コピーも書き出します。diarizationは、発話エンコーダー（既定はWavLM）をファインチューニングして、誰がいつ話しているかを見つけます。話者の名前は、各録音の中でだけ通用します。スペクトログラムのボックスは、画像の検出とセグメンテーションの検出器を学習します。音声モデルのチュートリアルでは、Whisper、ダイアライゼーション、スペクトログラムの検出、音声のタグ付けを通しで説明しています。

ボリューム、点群、動画

3Dと動画のトレーナーは、ペイントされたボリューム、点群のキューボイド、動画のトラックから学習します。volume-unetは、CTとMRのボリュームにアノテーターがペイントしたマスクで、素のPyTorchの3D U-Netを学習し、フルサイズのCTには、実際にはGPUが必要です。external-3dは、train_commandとpredict_commandのパラメーターを通じて、自前の3D検出器を実行し、キューボイドを読み戻します。OpenPCDetとMMDetection3Dのどちらも使え、どちらもGPUホストでコンパイルしたCUDAオペレーターが必要です。video-trackは、アノテーションされたトラックからサンプリングしたフレームでFaster R-CNNをファインチューニングし、フレーム間の検出を結んでトラックにします。ボリューム、点群、動画のチュートリアルでは、3つのトレーナーすべてを通しで説明しています。

科学分野

科学分野のトレーナーは、化学、分光、生理信号、ロボットのエピソードから学習します。rdkit-propertyは、分子についての問いに、分子のMorganフィンガープリントとRDKitの記述子から答えます。選択肢にはscikit-learnの分類器を、スライダーには回帰器を使います。peak-cnnはスペクトル上のピークの位置を予測し、ピークのラベルや帰属は予測しません。signal-cnnは、EEG、ECGなどの信号で、固定エポックを段階づけたり、ラベル付きの区間を見つけたりします。episode-modelは、ロボットのエピソードの関節系列とセンサー系列から、フェーズ、結果、報酬曲線を予測します。エピソードの動画は読み込まれません。ピーク、区間、エピソードの答えは、答えそのものではなく、アノテーターが確認する提案として表示されます。科学分野のモデルのチュートリアルでは4つのトレーナーすべてを通しで説明し、アノテーション側については、化学構造、スペクトル、時系列、ロボットのエピソードのスキームのページを参照してください。

判断モデル

判断モデルは、質問の各選択肢に確率を返し、Potatoは判断モデルをラベリングエンジンのソースとして、またはSolo Modeのラベリングモデルとして使います。判断モデルのトレーナーは、radio、select、likert、sliderのスキームで、研究のラベルに判断モデルを当てはめ、ラベリングエンジンが質問するのと同じ形で各質問をします。sliderは、位置ごとに1つの選択肢を持つ評価として質問され、位置は最大21です。decision-calibrateは何も学習しません。このトレーナーは、Jev、OpenJev、laya-serve、Layaの確率に較正を当てはめ、エンジンのソースが適用できるように、較正をcalibration.jsonに書き出します。decision-calibrateはlocalバックエンドでしか動きません。laya-finetuneはLayaをファインチューニングし、openjev-finetuneはwevのLoRA学習で8BのOpenJevモデルをファインチューニングします。OpenJevのモデルカードには、OpenJevの学習データの一部が研究専用であると記されています。商用利用の前に、その条件を確認してください。

推論ブリッジ

推論ブリッジは、すでに別の場所で動いているモデルを使い、何も学習しません。ブリッジの実行は、ホールドアウトした項目をサービスに送り、答えを読み戻します。writeback.include_unlabeled: trueのときは、実行はラベルのない項目も送ります。その答えは、学習済みモデルの答えと同じように、アノテーターに対するホールドアウトスコア、書き戻し、レビューの対象になります。ブリッジは、設定にAPIキーを書くことを受け付けません。代わりに、パラメーターが、キーを保持するサーバー上の環境変数の名前を指定します。label-studio-mlは、Label Studio MLバックエンドの/predictを呼び出し、アノテーションのイベントをバックエンドの/webhookには送りません。hf-inferenceとroboflowはlocalバックエンドでしか動きません。openai-vlm-boxesのボックスには信頼度がありません。視覚言語モデルがスコアを返さないからです。手持ちのモデルのチュートリアルでは、各ブリッジを設定します。

関連ドキュメント

• モデル学習の概要では、アノテーションから事前ラベルまでのループとTrainingページを説明しています。
• 設定ページには、model_trainingのすべてのキー、バックエンド、書き戻し、ルートが記載されています。
• 最初のモデルのチュートリアルでは、GPUなしでsklearn-textを最初から最後まで実行します。
• リモート学習のチュートリアルでは、実行をsshのGPUサーバー、SLURMクラスター、問い合わせ型のエージェントに送ります。
• モデル支援ラベリングのガイドでは、自分のモデルの事前ラベルがアノテーターの助けになる場合と、アノテーターを引きずる場合を論じています。
• アップストリームのモデル学習リファレンスには、各トレーナーのパラメーター表がすべてあります。