tao-train-mask2former

Mask2Former

ユニバーサル画像セグメンテーション（パノプティック、インスタンス、セマンティック）向けの Mask2Former です。マスク付きアテンションを用いた Transformer ベースのモデルで、高品質なセグメンテーション結果を実現します。

Swin バックボーンの重みには、model.backbone.pretrained_weights を設定してください。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT evaluate、TensorRT inference）では、まず references/tao-deploy-mask2former.md をお読みください。Deploy 仕様テンプレートは、このスキルの references/ フォルダーにあり、spec_template_deploy_*.yaml というプレフィックスが付いています。

データクラススキーマ

生成された TAO Core スキーマは schemas/.schema.json にパッケージ化されており、schemas/manifest.json に利用可能なアクションが一覧表示されています。生成された各スキーマから、スキーマのトップレベルの default フィールドに基づいて references/spec_template_.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 経由で実行してください。データセット、仕様、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に対するワークフロー／アプリケーションのオーバーライドは維持してください。automl_policy: off の場合、またはパッケージ化された train スキーマ／テンプレートがない場合に限り、モデルの直接トレーニングを使用してください。スキーマが不足している場合は、AutoML は有効ですが、スキーマが生成されるまではこのモデルで実行できないことを報告してください。

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

トレーニング要件

• データセットの種類： セグメンテーション
• 形式： coco_panoptic、coco
• 監視指標： mIoU

Per-Action Dataset Requirements

Action	Spec Key	Source	Files	List?
evaluate	dataset.train.img_dir	train_datasets	images.tar.gz	No
evaluate	dataset.label_map	train_datasets	coco_panoptic: label_map_panoptic.json; *: label_map.json	No
evaluate	dataset.train.instance_json	train_datasets	annotations.json	No
evaluate	dataset.train.panoptic_json	train_datasets	annotations_panoptic.json	No
evaluate	dataset.train.panoptic_dir	train_datasets	images_panoptic.tar.gz	No
evaluate	dataset.val.img_dir	eval_dataset	images.tar.gz	No
evaluate	dataset.val.instance_json	eval_dataset	annotations.json	No
evaluate	dataset.val.panoptic_json	eval_dataset	annotations_panoptic.json	No
evaluate	dataset.val.panoptic_dir	eval_dataset	images_panoptic.tar.gz	No
evaluate	dataset.test.img_dir	eval_dataset	images.tar.gz	No
inference	dataset.train.img_dir	train_datasets	images.tar.gz	No
inference	dataset.label_map	train_datasets	coco_panoptic: label_map_panoptic.json; *: label_map.json	No
inference	dataset.train.instance_json	train_datasets	annotations.json	No
inference	dataset.train.panoptic_json	train_datasets	annotations_panoptic.json	No
inference	dataset.train.panoptic_dir	train_datasets	images_panoptic.tar.gz	No
inference	dataset.val.img_dir	eval_dataset	images.tar.gz	No
inference	dataset.val.instance_json	eval_dataset	annotations.json	No
inference	dataset.val.panoptic_json	eval_dataset	annotations_panoptic.json	No
inference	dataset.val.panoptic_dir	eval_dataset	images_panoptic.tar.gz	No
inference	dataset.test.img_dir	eval_dataset	images.tar.gz	No
quantize	dataset.train.img_dir	train_datasets	images.tar.gz	No
quantize	dataset.label_map	train_datasets	coco_panoptic: label_map_panoptic.json; *: label_map.json	No
quantize	dataset.train.instance_json	train_datasets	annotations.json	No
quantize	dataset.train.panoptic_json	train_datasets	annotations_panoptic.json	No
quantize	dataset.train.panoptic_dir	train_datasets	images_panoptic.tar.gz	No
quantize	dataset.val.img_dir	eval_dataset	images.tar.gz	No
quantize	dataset.val.instance_json	eval_dataset	annotations.json	No
quantize	dataset.val.panoptic_json	eval_dataset	annotations_panoptic.json	No
quantize	dataset.val.panoptic_dir	eval_dataset	images_panoptic.tar.gz	No
quantize	dataset.test.img_dir	eval_dataset	images.tar.gz	No
quantize	dataset.quant_calibration_dataset.images_dir	train_datasets	images.tar.gz	No
train	dataset.train.img_dir	train_datasets	images.tar.gz	No
train	dataset.label_map	train_datasets	coco_panoptic: label_map_panoptic.json; *: label_map.json	No
train	dataset.train.instance_json	train_datasets	annotations.json	No
train	dataset.train.panoptic_json	train_datasets	annotations_panoptic.json	No
train	dataset.train.panoptic_dir	train_datasets	images_panoptic.tar.gz	No
train	dataset.val.img_dir	eval_dataset	images.tar.gz	No
train	dataset.val.instance_json	eval_dataset	annotations.json	No
train	dataset.val.panoptic_json	eval_dataset	annotations_panoptic.json	No
train	dataset.val.panoptic_dir	eval_dataset	images_panoptic.tar.gz	No
train	dataset.test.img_dir	eval_dataset	images.tar.gz	No

一般的な spec_overrides

データソースのオーバーライドはすべてのアクションで必須です。エージェントは、上記の「アクションごとのデータセット要件」テーブルに基づいてデータソースのパスを構成し、spec_overrides に含める必要があります。

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

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

{
    "train.num_gpus": 1,
    "train.num_epochs": 10,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "model.sem_seg_head.num_classes": 90,
    "dataset.contiguous_id": True,
    "dataset.train.img_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.label_map": {"coco_panoptic": f"{S3_TRAIN}/label_map_panoptic.json; *: label_map.json"},
    "dataset.train.instance_json": f"{S3_TRAIN}/annotations.json",
    "dataset.train.panoptic_json": f"{S3_TRAIN}/annotations_panoptic.json",
    "dataset.train.panoptic_dir": f"{S3_TRAIN}/images_panoptic.tar.gz",
    "dataset.val.img_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.val.instance_json": f"{S3_EVAL}/annotations.json",
    "dataset.val.panoptic_json": f"{S3_EVAL}/annotations_panoptic.json",
    "dataset.val.panoptic_dir": f"{S3_EVAL}/images_panoptic.tar.gz",
    "dataset.test.img_dir": f"{S3_EVAL}/images.tar.gz",
}

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

{
    "model.sem_seg_head.num_classes": 90,
    "dataset.contiguous_id": True,
    "dataset.train.img_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.label_map": {"coco_panoptic": f"{S3_TRAIN}/label_map_panoptic.json; *: label_map.json"},
    "dataset.train.instance_json": f"{S3_TRAIN}/annotations.json",
    "dataset.train.panoptic_json": f"{S3_TRAIN}/annotations_panoptic.json",
    "dataset.train.panoptic_dir": f"{S3_TRAIN}/images_panoptic.tar.gz",
    "dataset.val.img_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.val.instance_json": f"{S3_EVAL}/annotations.json",
    "dataset.val.panoptic_json": f"{S3_EVAL}/annotations_panoptic.json",
    "dataset.val.panoptic_dir": f"{S3_EVAL}/images_panoptic.tar.gz",
    "dataset.test.img_dir": f"{S3_EVAL}/images.tar.gz",
}

export：

{
    "model.sem_seg_head.num_classes": 90,
}

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

{
    "model.sem_seg_head.num_classes": 90,
    "dataset.contiguous_id": True,
    "dataset.train.img_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.label_map": {"coco_panoptic": f"{S3_TRAIN}/label_map_panoptic.json; *: label_map.json"},
    "dataset.train.instance_json": f"{S3_TRAIN}/annotations.json",
    "dataset.train.panoptic_json": f"{S3_TRAIN}/annotations_panoptic.json",
    "dataset.train.panoptic_dir": f"{S3_TRAIN}/images_panoptic.tar.gz",
    "dataset.val.img_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.val.instance_json": f"{S3_EVAL}/annotations.json",
    "dataset.val.panoptic_json": f"{S3_EVAL}/annotations_panoptic.json",
    "dataset.val.panoptic_dir": f"{S3_EVAL}/images_panoptic.tar.gz",
    "dataset.test.img_dir": f"{S3_EVAL}/images.tar.gz",
}

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

{
    "dataset.train.img_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.label_map": {"coco_panoptic": f"{S3_TRAIN}/label_map_panoptic.json; *: label_map.json"},
    "dataset.train.instance_json": f"{S3_TRAIN}/annotations.json",
    "dataset.train.panoptic_json": f"{S3_TRAIN}/annotations_panoptic.json",
    "dataset.train.panoptic_dir": f"{S3_TRAIN}/images_panoptic.tar.gz",
    "dataset.val.img_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.val.instance_json": f"{S3_EVAL}/annotations.json",
    "dataset.val.panoptic_json": f"{S3_EVAL}/annotations_panoptic.json",
    "dataset.val.panoptic_dir": f"{S3_EVAL}/images_panoptic.tar.gz",
    "dataset.test.img_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.quant_calibration_dataset.images_dir": f"{S3_TRAIN}/images.tar.gz",
}

評価データセット

任意です。検証データソースは、train とともにデータセット設定の一部です。

重要なパラメーター

• model.sem_seg_head.num_classes：セグメンテーションクラスの数です。デフォルトは 200 です。アノテーションのカテゴリと一致している必要があります。
• model.backbone.swin.type：Swin Transformer のバリアントです。デフォルトは tiny です。tiny、small、base、large を指定できます。
• model.mode：セグメンテーションモードです。デフォルトは panoptic です。panoptic、instance、semantic を指定できます。
• train.optim.lr：学習率です。デフォルトは 2e-4（AdamW）です。
• dataset.train.batch_size：GPU あたりのバッチサイズです。デフォルトは 1 です。Mask2Former はピクセル単位で予測するため、メモリを大量に使用します。

マルチ GPU／マルチノード

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

spec キー	説明	デフォルト
train.num_gpus	GPU の数	1
train.gpu_ids	GPU デバイスのインデックス	[0]
train.num_nodes	ノードの数	1
train.distributed_strategy	ddp または fsdp	ddp

• DINO と同じ DDP／FSDP の動作です（アクティベーションチェックポイントに対応）。
• FAN バックボーンでは sync_batchnorm が自動的に有効になります。
• fsdp は FP16 を強制します。

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

エクスポート／TRT のデフォルト

• TRT のデータ型：FP32、FP16 のみ — INT8 はサポートされていません

TAO Deploy の完全なリファレンス：tao-deploy-mask2former。

ハードウェア

GPU は最低 1 基、推奨 4 基です。GPU あたり 24GB 以上（A100 を推奨）の VRAM が必要です。Mask2Former はメモリを大量に消費します。batch_size のデフォルトが 1 なのには理由があります。妥当な速度で学習するにはマルチ GPU を推奨します。

エラーパターン

CUDA のメモリ不足：batch_size はデフォルトですでに 1 です。拡張設定で画像の解像度を下げるか、より小さい Swin バリアントを使用してください。

パノプティック形式とインスタンス形式の不一致：model.mode の設定に合った正しいアノテーション形式を指定してください。

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

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

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

アクション	Spec フィールド	推論関数	意味
評価	encryption_key	key	暗号化キー
評価	evaluate.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
評価	evaluate.trt_engine	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
評価	results_dir	output_dir	現在のジョブの結果ディレクトリー
エクスポート	encryption_key	key	暗号化キー
エクスポート	export.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
エクスポート	export.onnx_file	create_onnx_file	出力 ONNX パス
エクスポート	results_dir	output_dir	現在のジョブの結果ディレクトリー
gen_trt_engine	encryption_key	key	暗号化キー
gen_trt_engine	gen_trt_engine.onnx_file	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
gen_trt_engine	gen_trt_engine.trt_engine	create_engine_file	出力 TensorRT エンジンのパス
gen_trt_engine	results_dir	output_dir	現在のジョブの結果ディレクトリー
推論	encryption_key	key	暗号化キー
推論	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
推論	inference.trt_engine	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
推論	results_dir	output_dir	現在のジョブの結果ディレクトリー
量子化	encryption_key	key	暗号化キー
量子化	quantize.model_path	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
量子化	results_dir	output_dir	現在のジョブの結果ディレクトリー
トレーニング	encryption_key	key	暗号化キー
トレーニング	model.backbone.pretrained_weights	{'link': 'https://github.com/SwinTransformer/storage/releases/download/v1.0.8/swin_tiny_patch4_window7_224_22k.pth', 'destination_path': '/ptm/mask2former/swin_tiny_patch4_window7_224_22k/swin_tiny_patch4_window7_224_22k.pth'}	{'link': 'https://github.com/SwinTransformer/storage/releases/download/v1.0.8/swin_tiny_patch4_window7_224_22k.pth', 'destination_path': '/ptm/mask2former/swin_tiny_patch4_window7_224_22k/swin_tiny_patch4_window7_224_22k.pth'}
トレーニング	results_dir	output_dir	現在のジョブの結果ディレクトリー
トレーニング	train.resume_training_checkpoint_path	resume_model	現在のジョブの結果フォルダーから推論されるモデルファイル

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