tao-train-oneformer

OneFormer

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

OneFormer は、汎用画像セグメンテーションに対応します。タスク条件付きクエリを使用する単一のアーキテクチャで、パノプティック、インスタンス、セマンティックセグメンテーションを統合します。

train.pretrained_backbone および／または train.pretrained_model を設定します。

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

データクラススキーマ

生成された TAO Core スキーマは schemas/<action>.schema.json にパッケージされ、利用可能なアクションは schemas/manifest.json に記載されています。生成された各スキーマから、スキーマのトップレベルの default フィールドを基に references/spec_template_<action>.yaml も生成されます。AutoML の有効化は、モデルレイヤーの references/skill_info.yaml で automl_enabled を通じて宣言されます。アクションで 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 が両方パッケージされている場合、デフォルトでは tao-skill-bank:tao-run-automl にこのモデルの skill_dir を渡して train アクションを実行してください。データセット、仕様、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に関するワークフロー／アプリケーションのオーバーライドは保持してください。直接モデルをトレーニングするのは、automl_policy: off の場合、またはパッケージされた train スキーマ／テンプレートがない場合に限ります。スキーマがない場合は、AutoML は有効ですが、スキーマが生成されるまではこのモデルで実行できないことを報告してください。

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

トレーニング要件

• データセットの種類： セグメンテーション
• 形式： coco_panoptic、coco
• AutoML トレーニング指標： mIoU、direction=maximize
• 単独評価指標： test_mIoU、direction=maximize

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

アクション	仕様キー	ソース	ファイル	リスト？
評価	dataset.train.images	train_datasets	images.tar.gz	いいえ
評価	dataset.label_map	train_datasets	label_map.json	いいえ
評価	dataset.train.annotations	train_datasets	annotations.json	いいえ
評価	dataset.train.panoptic	train_datasets	images_panoptic.tar.gz	いいえ
評価	dataset.val.images	eval_dataset	images.tar.gz	いいえ
評価	dataset.val.annotations	eval_dataset	annotations.json	いいえ
評価	dataset.val.panoptic	eval_dataset	images_panoptic.tar.gz	いいえ
評価	dataset.test.images	eval_dataset	images.tar.gz	いいえ
評価	dataset.test.annotations	eval_dataset	annotations.json	いいえ
評価	dataset.test.panoptic	eval_dataset	images_panoptic.tar.gz	いいえ
推論	dataset.train.images	train_datasets	images.tar.gz	いいえ
推論	dataset.label_map	train_datasets	label_map.json	いいえ
推論	dataset.train.annotations	train_datasets	annotations.json	いいえ
推論	dataset.train.panoptic	train_datasets	images_panoptic.tar.gz	いいえ
推論	dataset.val.images	eval_dataset	images.tar.gz	いいえ
推論	dataset.val.annotations	eval_dataset	annotations.json	いいえ
推論	dataset.val.panoptic	eval_dataset	images_panoptic.tar.gz	いいえ
推論	dataset.test.images	inference_dataset	images.tar.gz	いいえ
量子化	dataset.train.images	train_datasets	images.tar.gz	いいえ
量子化	dataset.train.annotations	train_datasets	annotations.json	いいえ
量子化	dataset.label_map	train_datasets	label_map.json	いいえ
量子化	dataset.train.panoptic	train_datasets	images_panoptic.tar.gz	いいえ
量子化	dataset.val.images	eval_dataset	images.tar.gz	いいえ
量子化	dataset.val.annotations	eval_dataset	annotations.json	いいえ
量子化	dataset.val.panoptic	eval_dataset	images_panoptic.tar.gz	いいえ
量子化	dataset.test.images	eval_dataset	images.tar.gz	いいえ
量子化	dataset.quant_calibration_dataset.images_dir	calibration_dataset	images.tar.gz	いいえ
トレーニング	dataset.train.images	train_datasets	images.tar.gz	いいえ
トレーニング	dataset.train.annotations	train_datasets	annotations.json	いいえ
トレーニング	dataset.label_map	train_datasets	label_map.json	いいえ
トレーニング	dataset.train.panoptic	train_datasets	images_panoptic.tar.gz	いいえ
トレーニング	dataset.val.images	eval_dataset	images.tar.gz	いいえ
トレーニング	dataset.val.annotations	eval_dataset	annotations.json	いいえ
トレーニング	dataset.val.panoptic	eval_dataset	images_panoptic.tar.gz	いいえ
トレーニング	dataset.test.images	eval_dataset	images.tar.gz	いいえ

一般的な仕様のオーバーライド

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

S3_TRAIN = "s3://bucket/data/train"
S3_EVAL = "s3://bucket/data/eval"
S3_INFERENCE = "s3://bucket/data/inference"
S3_CALIBRATION = "s3://bucket/data/calibration"

トレーニング（必須データソース）：

{
    "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,
    "train.precision": "32",
    "dataset.train.images": f"{S3_TRAIN}/images.tar.gz",
    "dataset.train.annotations": f"{S3_TRAIN}/annotations.json",
    "dataset.label_map": f"{S3_TRAIN}/label_map.json",
    "dataset.train.panoptic": f"{S3_TRAIN}/images_panoptic.tar.gz",
    "dataset.val.images": f"{S3_EVAL}/images.tar.gz",
    "dataset.val.annotations": f"{S3_EVAL}/annotations.json",
    "dataset.val.panoptic": f"{S3_EVAL}/images_panoptic.tar.gz",
    "dataset.test.images": f"{S3_EVAL}/images.tar.gz",
}

評価（必須データソース）：

{
    "evaluate.checkpoint": "<selected train/AutoML checkpoint>",
    "model.sem_seg_head.num_classes": 133,
    "dataset.contiguous_id": True,
    "dataset.train.images": f"{S3_TRAIN}/images.tar.gz",
    "dataset.label_map": f"{S3_TRAIN}/label_map.json",
    "dataset.train.annotations": f"{S3_TRAIN}/annotations.json",
    "dataset.train.panoptic": f"{S3_TRAIN}/images_panoptic.tar.gz",
    "dataset.val.images": f"{S3_EVAL}/images.tar.gz",
    "dataset.val.annotations": f"{S3_EVAL}/annotations.json",
    "dataset.val.panoptic": f"{S3_EVAL}/images_panoptic.tar.gz",
    "dataset.test.images": f"{S3_EVAL}/images.tar.gz",
    "dataset.test.annotations": f"{S3_EVAL}/annotations.json",
    "dataset.test.panoptic": f"{S3_EVAL}/images_panoptic.tar.gz",
}

エクスポート：

{
    "export.checkpoint": "<selected train/AutoML checkpoint>",
    "model.sem_seg_head.num_classes": 133,
    "model.export": True,
    "export.onnx_file": "/results/oneformer_export_640.onnx",
}

推論（必須データソース）：

{
    "inference.checkpoint": "<selected train/AutoML checkpoint>",
    "dataset.train.images": f"{S3_TRAIN}/images.tar.gz",
    "dataset.label_map": f"{S3_TRAIN}/label_map.json",
    "dataset.train.annotations": f"{S3_TRAIN}/annotations.json",
    "dataset.train.panoptic": f"{S3_TRAIN}/images_panoptic.tar.gz",
    "dataset.val.images": f"{S3_EVAL}/images.tar.gz",
    "dataset.val.annotations": f"{S3_EVAL}/annotations.json",
    "dataset.val.panoptic": f"{S3_EVAL}/images_panoptic.tar.gz",
    "dataset.test.images": f"{S3_INFERENCE}/images.tar.gz",
    "inference.images_dir": f"{S3_INFERENCE}/images.tar.gz",
}

量子化（必須データソース）：

{
    "quantize.model_path": "<selected train/AutoML checkpoint>",
    "dataset.train.images": f"{S3_TRAIN}/images.tar.gz",
    "dataset.train.annotations": f"{S3_TRAIN}/annotations.json",
    "dataset.label_map": f"{S3_TRAIN}/label_map.json",
    "dataset.train.panoptic": f"{S3_TRAIN}/images_panoptic.tar.gz",
    "dataset.val.images": f"{S3_EVAL}/images.tar.gz",
    "dataset.val.annotations": f"{S3_EVAL}/annotations.json",
    "dataset.val.panoptic": f"{S3_EVAL}/images_panoptic.tar.gz",
    "dataset.test.images": f"{S3_EVAL}/images.tar.gz",
    "dataset.quant_calibration_dataset.images_dir": f"{S3_CALIBRATION}/images.tar.gz",
}

チェックポイントの選択

OneFormer のトレーニングでは、model_epoch_000_step_00017.pth のような エポック・ステップ形式のチェックポイントが書き出され、さらに oneformer_model_latest.pth というシンボリックリンクが書き出される場合もあります。チェックポイントに依存する操作では、 model-skill または SDK の親モデルリゾルバーを使い、選択したチェックポイントの正確なパスを evaluate.checkpoint、inference.checkpoint、export.checkpoint、 quantize.model_path、または train.resume_training_checkpoint_path に渡してください。ユーザーから最新のチェックポイントを使うよう明示的に依頼されていない限り、 oneformer_model_latest.pth という名前だけを見て選ばないでください。リゾルバーから最良のチェックポイントが報告された場合は、評価・エクスポート・推論にその最良のチェックポイントを使ってください。特定のエポックまたはステップをユーザーが指定した場合は、一致するエポック・ステップ形式のチェックポイントを使ってください。

評価データセット

任意です。トレーニングと併せてデータセット設定に検証データを設定します。

重要なパラメーター

• model.sem_seg_head.num_classes：ヘッドで使用できるセグメンテーションクラスのインデックス数です。dataset.contiguous_id: True によりラベルマップを介して元のカテゴリ ID が再マッピングされる場合、COCO パノプティックデータのデフォルトは 133 です。ラベルマップとアノテーションが実際にそのクラスセットに縮小されていない限り、これをワークフロー全体のクラス数に合わせて減らさないでください。
• model.one_former.hidden_dim：テキストエンコーダーの幅も同時に変更しない限り、ローカルのスモークテストでは 256 のままにしてください。hidden_dim だけを小さくすると、トレーニング中にテキスト特徴量とコンテキストの次元が一致しなくなります。
• model.backbone.name：デフォルトは D2SwinTransformer（Swin ベース）です。デフォルトの embed_dim は 192、depths は [2,2,18,2] です。
• train.num_epochs：デフォルトは 50 で、ほとんどの TAO モデルより大幅に多くなっています。OneFormer の収束には、より多くのエポックが必要です。
• train.optim.lr：学習率です。デフォルトは 1e-5 です。Mask2Former の 2e-4 より低い値です。
• model.task_toggling：特定のタスク（semantic_on、instance_on、panoptic_on）を有効または無効にします。
• export.task：エクスポートするタスクのモードです。選択肢は semantic、instance、panoptic です。デフォルトは semantic です。エクスポート入力のデフォルトサイズは 640x640 です。
• inference.mode：推論モードです。選択肢は semantic、instance、panoptic です。デフォルトは semantic です。image_size のデフォルトは [1024, 1024] です。
• evaluate.iou_per_class：評価でクラスごとの IoU をレポートします。デフォルトは True です。

マルチ GPU／マルチノード

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

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

• find_unused_parameters=True、gradient_as_bucket_view=True、process_group_backend="nccl" を指定した DDPStrategy を使用します
• sync_batchnorm は常に有効です
• fsdp はサポートされていません。DDP のみです

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

ハードウェア

GPU は最低 2 基、推奨 4 基です。各 GPU に 24GB 以上の VRAM が必要です（A100 を推奨）。OneFormer は Mask2Former と同様にメモリを大量に消費します。batch_size=1 がデフォルトです。妥当な速度でトレーニングするには、特に 50 エポックの場合、マルチ GPU が必要です。

エラーパターン

CUDA のメモリ不足: batch_size はすでに 1 です。画像解像度を下げるか、より小さい Swin 設定を使用してください。

抽出した S3 tarball のパスが1階層上を指している: ローカルで Docker を実行する場合、 images.tar.gz と images_panoptic.tar.gz は、images/ や images_panoptic/ などの ラッパーディレクトリに展開されることがあります。dataset.*.images、 dataset.*.panoptic、inference.images_dir、量子化のキャリブレーション用 パスには、ラッパーディレクトリではなく、画像ファイルまたはパノプティックファイルが 実際に格納されているフォルダーを指定してください。パスが1階層上すぎると、 再帰的なファイル数が正しく見えていても、最初のアノテーション画像で FileNotFoundError が発生します。

default_specs に results_dir がない: CLI の default_specs サブタスクは、 results_dir に対する -e の実験仕様を無視します。代わりに Hydra 形式の オーバーライドを渡してください： oneformer default_specs results_dir=/path/to/default_specs。

Lightning の精度設定 fp32 が無効: train/AutoML/evaluate/inference の仕様では、 train.precision: "32" を使用してください。現在の Lightning スタックは、 従来の fp32 文字列を拒否します。

PyTorch 2.6 でチェックポイントを読み込めず、後続アクションが失敗する: 現在の OneFormer チェックポイントには OmegaConf オブジェクトが含まれています。同じ信頼できる TAO の train/AutoML ワークフローで生成されたチェックポイントの場合は、 後続の evaluate、inference、export、quantize、または resume ジョブの環境変数に TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1 を設定すると、Lightning がチェックポイント全体を 読み込めるようになります。信頼できないチェックポイントには、この環境変数を 使用しないでください。

matcher/class cost で CUDA のデバイス側アサートが発生する: out_prob[:, tgt_ids] のインデックス処理中に oneformer/utils/matcher.py で学習が失敗する場合は、 有効なターゲット ID と model.sem_seg_head.num_classes を比較してください。 同梱の COCO panoptic サンプルには、dataset.contiguous_id: True の再マッピング後、133 個のコンパクトなクラスがあります。そのため、 より広範な検証ワークフローから汎用の num_classes に小さい値が渡される場合でも、 model.sem_seg_head.num_classes: 133 を使用してください。ラベルマップと アノテーションを、まったく同じ連続したクラスセットに削減した場合に限り、 より小さいクラス数を使用してください。

推論が予測なしで PASS を返す: OneFormer の予測では、 dataset.test.images ではなく inference.images_dir を読み込みます。 すべての推論実行で、画像フォルダーまたは tarball を inference.images_dir に指定して配置してください。dataset.test.images は 共有データセットのコンテキストに役立つ場合がありますが、PyTorch の predict データローダーには適用されません。

エクスポート出力パスがディレクトリとして事前作成される: export.onnx_file をファイル出力として宣言しないでください。OneFormer の エクスポーターは ONNX パスが既存でないことをアサートしますが、ローカルランナーは 宣言された出力パスを事前作成します。マウントされた results ツリー内にある 未作成のファイルパスを、仕様で export.onnx_file に明示的に設定してください。 スモーク検証ではデフォルトの 640x640 のエクスポート形状を維持してください。 エクスポート形状を小さくしすぎると、PyTorch の ONNX 形状推論が失敗することがあります。

AutoML チェックポイントから学習時のラベルマップを見つけられないため quantize が失敗する: OneFormer の Lightning チェックポイントには、保存された hparams に学習時の 絶対データセットパスが保持されています。AutoML の子チェックポイントから後続の アクションを実行する場合は、解決済みのチェックポイントパスを渡すだけでなく、 親 AutoML ジョブディレクトリにも、アクションコンテナ内で元の /results/<job_id> パスからアクセスできるようにしてください。そうしないと、 現在の仕様に有効な dataset.label_map が含まれていても、チェックポイントの hparams の読み込み時に quantize が失敗することがあります。

学習が遅い: デフォルトの 50 エポックを batch_size=1 で実行すると、単一 GPU では 時間がかかります。マルチ GPU 分散学習を使用してください。

Spec Param / 親モデルの推論

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

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

アクション	Spec フィールド	推論関数	意味
evaluate	encryption_key	key	暗号化キー
evaluate	evaluate.checkpoint	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
evaluate	evaluate.trt_engine	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
evaluate	results_dir	output_dir	現在のジョブの結果ディレクトリ
export	encryption_key	key	暗号化キー
export	export.checkpoint	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
export	export.onnx_file	create_onnx_file	出力 ONNX パス
export	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	現在のジョブの結果ディレクトリ
inference	encryption_key	key	暗号化キー
inference	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
inference	inference.trt_engine	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
inference	results_dir	output_dir	現在のジョブの結果ディレクトリ
quantize	encryption_key	key	暗号化キー
quantize	quantize.model_path	parent_model	親ジョブの結果フォルダーから推定されるモデルファイル
quantize	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	encryption_key	key	暗号化キー
train	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	train.pretrained_backbone	{'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'}
train	train.pretrained_model	ptm_if_no_resume_model	再開チェックポイントが存在しない場合の PTM
train	train.resume_training_checkpoint_path	resume_model	現在のジョブの結果フォルダーから推定されるモデルファイル

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

デプロイ

• tao-deploy-oneformer