tao-train-mask-auto-label

MAL

弱教師ありセグメンテーション向けの MAL（Mask Auto-Label）です。最小限のアノテーション（例：ポイントまたはボックスのアノテーション）からセグメンテーションマスクを生成します。ViT-MAE バックボーンを使用します。

ViT-MAE の事前学習済み重みを指定するには、train.pretrained_model_path を設定してください。

データクラスのスキーマ

生成された TAO Core スキーマは schemas/<action>.schema.json にパッケージ化されており、利用可能なアクションは schemas/manifest.json に記載されています。各生成スキーマから、スキーマのトップレベルの default フィールドを基に references/spec_template_<action>.yaml も生成されます。AutoML の有効化は、モデルレイヤーの references/skill_info.yaml で automl_enabled を使って宣言します。AutoML を実行するには、schemas/train.schema.json と references/spec_template_train.yaml が存在し、解析可能である必要があります。automl_default_parameters、automl_disabled_parameters、デフォルト値、最小値／最大値の範囲、列挙値、オプションの重み、数式条件、依存関係、よく使われるパラメーターには、パッケージ済みの train スキーマを使用してください。実行時に ~/tao-core が存在することを前提にしないでください。スキルバンクをパッケージ化する前に、メンテナーがスキーマとテンプレートを再生成してください。

Train アクションのポリシー

このモデルでは、モデルレイヤーで AutoML が有効になっています。train ステージのリクエストを処理する前に、references/skill_info.yaml を読み込み、明示的な automl_policy 値またはユーザーのワークフローリクエストから実行時の上書きを決定してください。「AutoML をオフにする」「AutoML を無効にする」「HPO なし」「通常のトレーニング」などの表現は、この実行に限り automl_policy: off として扱い、それ以外はデフォルトで auto とします。automl_policy: auto、automl_enabled: true が設定され、schemas/train.schema.json と references/spec_template_train.yaml の両方がパッケージ化されている場合は、デフォルトでこのモデルの skill_dir を指定して、train アクションを tao-skill-bank:tao-run-automl 経由で実行してください。データセット、spec、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に関するワークフロー／アプリケーションの上書きは保持してください。直接モデルをトレーニングするのは、automl_policy: off の場合、またはパッケージ済みの train スキーマ／テンプレートが欠落している場合に限ります。スキーマが欠落している場合は、AutoML は有効ですが、スキーマが生成されるまではこのモデルで実行できないことを報告してください。

evaluate、inference、export、deploy フローなど、train 以外のアクションはこのモデルのスキル内で実行します。実行ごとの automl_policy 上書きによって、モデルのメタデータが変更されることはありません。

トレーニング要件

• データセットの種類： セグメンテーション
• 形式： デフォルト
• モニタリング指標： mIoU

アクションごとのデータセット要件

アクション	Spec キー	ソース	ファイル	リスト？
evaluate	dataset.val_img_dir	eval_dataset	images.tar.gz	いいえ
evaluate	dataset.val_ann_path	eval_dataset	annotations.json	いいえ
inference	inference.img_dir	inference_dataset	images.tar.gz	いいえ
inference	inference.ann_path	inference_dataset	annotations.json	いいえ
train	dataset.train_img_dir	train_datasets	images.tar.gz	いいえ
train	dataset.train_ann_path	train_datasets	annotations.json	いいえ
train	dataset.val_img_dir	eval_dataset	images.tar.gz	いいえ
train	dataset.val_ann_path	eval_dataset	annotations.json	いいえ

一般的な Spec の上書き

すべてのアクションでデータソースの上書きは必須です。エージェントは、上記の「アクションごとのデータセット要件」表からデータソースのパスを構築し、spec_overrides に含める必要があります。

S3_TRAIN = "s3://bucket/data/train"
S3_EVAL = "s3://bucket/data/eval"

train（必須データソース）：

{
    "train.num_gpus": 1,
    "train.gpu_ids": [
        0
    ],
    "train.num_epochs": 5,
    "train.checkpoint_interval": 5,
    "train.validation_interval": 5,
    "dataset.train_img_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.train_ann_path": f"{S3_TRAIN}/annotations.json",
    "dataset.val_img_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.val_ann_path": f"{S3_EVAL}/annotations.json",
}

evaluate（必須データソース）：

{
    "dataset.val_img_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.val_ann_path": f"{S3_EVAL}/annotations.json",
}

inference（必須データソース）：

{
    "inference.img_dir": f"{S3_EVAL}/images.tar.gz",
    "inference.ann_path": f"{S3_EVAL}/annotations.json",
}

Eval データセット

任意です。検証用画像とアノテーションは、train のパスと合わせて設定します。

重要なパラメーター

• model.arch：ViT-MAE バックボーンのバリアントです。デフォルトは vit-mae-base/16 です。選択肢には vit-mae-large/16 やその他の ViT-MAE バリアントがあります。
• train.lr：学習率です。デフォルトは 1e-6 です（非常に低い値です。ViT のファインチューニング向け）。
• model.crop_size：トレーニング時のクロップサイズです。デフォルトは 512 です。
• train.warmup_epochs：学習率を最大にする前のウォームアップエポック数です。
• model.load_mask：事前計算済みマスクを読み込むかどうかを指定します。

マルチ GPU／マルチノード

起動方法： Lightning による管理（単一の python プロセスで、Lightning がワーカーを起動します）。

Spec キー	説明	デフォルト
train.num_gpus	GPU の数	1
train.gpu_ids	GPU デバイスのインデックス	[0]
train.num_nodes	ノードの数	1

• マルチ GPU 戦略：ddp_find_unused_parameters_true
• fsdp はサポートされていません
• LR の自動スケーリング： lr = lr * num_devices * batch_size（学習率はデバイス数とバッチサイズに応じて自動的にスケーリングされます）

マルチノード環境変数（オーケストレーターによって設定）：WORLD_SIZE、NODE_RANK、MASTER_ADDR、MASTER_PORT、NUM_GPU_PER_NODE。

ハードウェア

最低 1 GPU、推奨 2 GPU です。GPU ごとに 24GB 以上の VRAM が必要です（A100 を推奨）。crop_size=512 の ViT-MAE バックボーンには、24GB 以上の GPU メモリが必要です。

エラーパターン

CUDA のメモリ不足：model.crop_size を小さくする（512 -> 384 -> 256）か、より小さい ViT-MAE バリアント（base と large のうち base）を使用してください。

Spec パラメーター／親モデルの推論

モデル固有の推論マッピングは config.json ではなく、この MD ファイルに記述します。生成されたランナーはこのセクションを読み取り、create_job() の前に SDK ヘルパーを使ってマッピングを適用します。これは、以前のマイクロサービスの infer_params.py のフローに対応します。

TAO Core の mal.config.json からの推論マッピング：

アクション	Spec フィールド	推論関数	意味
評価	evaluate.checkpoint	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
評価	results_dir	output_dir	現在のジョブの結果ディレクトリ
推論	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
推論	inference.label_dump_path	create_inference_result_file_mal	MAL 推論 JSON パス
推論	results_dir	output_dir	現在のジョブの結果ディレクトリ
学習	results_dir	output_dir	現在のジョブの結果ディレクトリ

parent_model または parent_model_folder には、上流の train/export/AutoML 子ジョブ ID を parent_job_id として渡します。SDK は親の結果フォルダーを一覧表示し、チェックポイントのアーティファクトをフィルタリングして、選択されたモデルファイルまたはフォルダーを返します。これらのマッピングを config.json に戻したり、チェックポイントのパスを推測するよう生成されたランナースクリプトにパッチを適用したりしないでください。