tao-train-mask2former

Mask2Former

スタンドアロンでインストールする場合 このセッションが TAO スキルバンクプラグインによって初期化されていない場合は、まず tao-setup スキルを実行してください（ホストの事前確認、認証情報、スキル間の検出）。

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

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

Train アクションのポリシー

このモデルでは、モデルレイヤーで AutoML が有効になっています。train ステージのリクエストに対応する前に、references/skill_info.yaml を読み、明示的な automl_policy の値、またはユーザーのワークフローリクエストから実行時のオーバーライドを判断してください。デフォルトでは automl_policy: on を使用し、新しい起動プロンプトでは on／off のみを提示してください。「AutoML をオフにする」「AutoML を無効にする」「HPO なし」「通常のトレーニング」などの表現は、この実行に限り automl_policy: off として扱ってください。automl_policy: on、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 オーバーライドによって、モデルのメタデータが変更されることはありません。

トレーニング要件

• データセットタイプ： segmentation
• 形式： coco_panoptic、coco
• 監視メトリック： mIoU
• AutoML メトリック： 出力された検証／評価の mIoU を最大化してください。トレーニング損失で代用しないでください。

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

Action	Spec Key	Source	Files	List?
evaluate	dataset.train.type	train_datasets	coco_panoptic	No
evaluate	dataset.val.type	eval_dataset	coco_panoptic	No
evaluate	dataset.test.type	eval_dataset	coco_panoptic	No
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.type	train_datasets	coco_panoptic	No
inference	dataset.val.type	eval_dataset	coco_panoptic	No
inference	dataset.test.type	eval_dataset	coco_panoptic	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.type	train_datasets	coco_panoptic	No
quantize	dataset.val.type	eval_dataset	coco_panoptic	No
quantize	dataset.test.type	eval_dataset	coco_panoptic	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.type	train_datasets	coco_panoptic	No
train	dataset.val.type	eval_dataset	coco_panoptic	No
train	dataset.test.type	eval_dataset	coco_panoptic	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 に含める必要があります。

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": 133,
    "dataset.contiguous_id": True,
    "dataset.train.type": "coco_panoptic",
    "dataset.val.type": "coco_panoptic",
    "dataset.test.type": "coco_panoptic",
    "dataset.train.img_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.label_map": f"{S3_TRAIN}/label_map_panoptic.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（必須データソース）：

{
    "evaluate.checkpoint": "<selected train/AutoML checkpoint>",
    "model.sem_seg_head.num_classes": 133,
    "dataset.contiguous_id": True,
    "dataset.train.type": "coco_panoptic",
    "dataset.val.type": "coco_panoptic",
    "dataset.test.type": "coco_panoptic",
    "dataset.train.img_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.label_map": f"{S3_TRAIN}/label_map_panoptic.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：

{
    "export.checkpoint": "<selected train/AutoML checkpoint>",
    "export.onnx_file": "<output ONNX path>",
    "model.sem_seg_head.num_classes": "<same value used for train>",
}

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

{
    "inference.checkpoint": "<selected train/AutoML checkpoint>",
    "model.sem_seg_head.num_classes": "<same value used for train>",
    "dataset.contiguous_id": True,
    "dataset.train.img_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.label_map": f"{S3_TRAIN}/label_map_panoptic.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（必須データソース）：

{
    "quantize.model_path": "<selected train/export artifact>",
    "dataset.train.img_dir": f"{S3_TRAIN}/images.tar.gz",
    "dataset.label_map": f"{S3_TRAIN}/label_map_panoptic.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 はピクセルごとの予測を行うため、メモリーを大量に消費します。
• dataset.contiguous_id：true の場合、model.sem_seg_head.num_classes にラベルマップのカテゴリ数を設定します。false の場合は、 model.sem_seg_head.num_classes を最大の生カテゴリ ID より大きく設定し、 evaluate、inference、export、deploy、quantize でも同じ設定を維持します。 COCO panoptic S3 サンプルには 133 個のカテゴリがあり、生 ID は最大 200 まであるため、 生 ID の検証では num_classes: 201 を使用します。

マルチ GPU／マルチノード

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

仕様キー	説明	デフォルト
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 はサポートされていません
• 親の PyTorch mask2former CLI は train、evaluate、 inference、export、quantize をサポートします。TensorRT エンジンの生成、 TensorRT 推論、TensorRT 評価は references/tao-deploy-mask2former.md を通じて実行してください。 TensorRT 評価の検証時は、現在のデプロイ用評価ツールがセマンティックエンジンを受け付けるため、 セマンティック ONNX（model.mode: semantic）をエクスポートしてください。
• エクスポートの入力寸法は、デプロイ用テンプレートと互換性を保ってください。 パッケージに含まれるデフォルトの export.input_width: 960 と export.input_height: 544 では、 正常にエクスポートして TensorRT エンジンをビルドできます。エクスポート寸法を 128x128 などの検証専用の小さなサイズに縮小すると、ONNX が生成される前に PyTorch ONNX の minus_one_pos != -1 形状推論アサーションに達することがあります。

ハードウェア

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

エラーパターン

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

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

トップレベルの dataset.type に関するデプロイスキーマエラー：TAO Deploy では dataset.val.type と dataset.test.type を使用します。Mask2Former のデプロイ仕様では、トップレベルに dataset.type を指定しないでください。

非常に小さい解像度での ONNX エクスポートの形状アサーション：PyTorch ONNX の形状推論で minus_one_pos != -1 が発生してエクスポートに失敗する場合は、デプロイ検証を再試行する前に、テンプレートの エクスポート寸法（960x544）に戻してください。簡単なスモークテストのため、必要に応じてトレーニングと評価の画像サイズは小さくして構いませんが、ターゲット形状が検証されていない場合は、エクスポート時に極端に小さい寸法を使用しないでください。

量子化時のチェックポイント読み込みエラー：古い PyTorch イメージでは、ランタイムの量子化スクリプトが必須の cfg 引数ではなく experiment_spec を Mask2formerPlModule.load_from_checkpoint に渡すため、チェックポイントベースの mask2former quantize が失敗することがあります。量子化の修正が適用されたイメージでは、デフォルトの torchao チェックポイントフローがサポートされています。ONNX の量子化には引き続き、 backend: modelopt.onnx、mode: static_ptq、固定された dataset.test.target_size、および modelopt.onnx.quantization を含むイメージが必要です。

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 に戻したり、チェックポイントパスを推測するために生成済みランナースクリプトを修正したりしないでください。

SDK のリゾルバーを使わずに Mask2Former のチェックポイントを選択する場合は、たとえば model_epoch_000_step_00100.pth のように、対象のエポック／ステップの成果物と正確に一致させてください。mask2former_model_latest.pth シンボリックリンクが有効なのは、latest が明示的に要求された場合に限ります。

デプロイ

• tao-deploy-mask2former