tao-train-mask-grounding-dino

Mask Grounding DINO

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

グラウンディングされたインスタンスセグメンテーションを行う Mask Grounding DINO です。Grounding DINO を拡張し、テキストプロンプトで誘導するオープンセットセグメンテーション用のマスク予測ヘッドを追加します。

完全なモデルの重みには train.pretrained_model_path を設定します。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）については、まず references/tao-deploy-mask-grounding-dino.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 を通じて train アクションを実行し、このモデルの skill_dir を指定します。データセット、仕様、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に関するワークフロー／アプリケーションのオーバーライドは保持します。直接モデルをトレーニングするのは、automl_policy: off の場合、またはパッケージ化された train スキーマ／テンプレートがない場合に限ります。スキーマがない場合は、AutoML は有効ですが、スキーマが生成されるまではこのモデルで実行できないことを報告します。

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

トレーニング要件

• データセットの種類： セグメンテーション
• 形式： odvg、coco、coco_raw
• モニタリング指標： val_loss
• AutoML 指標の規約： トレーニング中に出力される val_loss を使用し、 最小化します。単独評価の指標はチェックポイント検証用 KPI であり、 推奨候補を選択する目的関数ではありません。
• 評価チェックポイント指標： チェックポイントでクラス予測が生成される場合は、[segm] test_mAP50 と [bbox] test_mAP50。ごく短時間のスモークトレーニングで生成されたチェックポイントは、 KPI の辞書が空でも評価が正常に完了する場合があります。その場合は、 評価アクションと結果アーティファクトを確認してください。train ステージの AutoML における選択は、引き続き val_loss に基づきます。

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

アクション	Spec キー	ソース	ファイル	リスト？
評価	dataset.test_data_sources	eval_dataset	image_dir: images.tar.gz, json_file: annotations.json	いいえ
評価	dataset.test_data_sources.data_type	eval_dataset	OD	いいえ
推論	dataset.infer_data_sources	inference_dataset	image_dir: images.tar.gz, captions: text prompts	いいえ
推論	dataset.infer_data_sources.data_type	inference_dataset	OD	いいえ
量子化	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations_odvg.jsonl, label_map: annotations_odvg_labelmap.json	はい
量子化	dataset.val_data_sources	eval_dataset	image_dir: images.tar.gz, json_file: annotations.json	いいえ
量子化	dataset.val_data_sources.data_type	eval_dataset	OD	いいえ
量子化	dataset.quant_calibration_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations_odvg.jsonl, label_map: annotations_odvg_labelmap.json	いいえ
学習	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations_odvg.jsonl, label_map: annotations_odvg_labelmap.json	はい
学習	dataset.val_data_sources	eval_dataset	image_dir: images.tar.gz, json_file: annotations.json	いいえ
学習	dataset.val_data_sources.data_type	eval_dataset	OD	いいえ

典型的な Spec のオーバーライド

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

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

学習（必須のデータソース）：

{
    "train.num_gpus": 1,
    "train.num_epochs": 10,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "dataset.val_data_sources.data_type": "OD",
    "model.num_region_queries": 100,
    "dataset.train_data_sources": [{"image_dir": f"{S3_TRAIN}/images.tar.gz", "json_file": f"{S3_TRAIN}/annotations_odvg.jsonl", "label_map": f"{S3_TRAIN}/annotations_odvg_labelmap.json"}],
    "dataset.val_data_sources": {"image_dir": f"{S3_EVAL}/images.tar.gz", "json_file": f"{S3_EVAL}/annotations.json"},
}

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

{
    "evaluate.checkpoint": "<selected train/AutoML checkpoint>",
    "dataset.test_data_sources.data_type": "OD",
    "dataset.test_data_sources": {"image_dir": f"{S3_EVAL}/images.tar.gz", "json_file": f"{S3_EVAL}/annotations.json"},
}

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

{
    "inference.checkpoint": "<selected train/AutoML checkpoint>",
    "dataset.infer_data_sources.data_type": "OD",
    "dataset.infer_data_sources": {"image_dir": f"{S3_EVAL}/images.tar.gz", "captions": ["person", "bicycle", "car"]},
}

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

{
    "dataset.train_data_sources": [{"image_dir": f"{S3_TRAIN}/images.tar.gz", "json_file": f"{S3_TRAIN}/annotations_odvg.jsonl", "label_map": f"{S3_TRAIN}/annotations_odvg_labelmap.json"}],
    "dataset.val_data_sources": {"image_dir": f"{S3_EVAL}/images.tar.gz", "json_file": f"{S3_EVAL}/annotations.json"},
    "dataset.quant_calibration_data_sources": {"image_dir": f"{S3_TRAIN}/images.tar.gz", "json_file": f"{S3_TRAIN}/annotations_odvg.jsonl", "label_map": f"{S3_TRAIN}/annotations_odvg_labelmap.json"},
}

評価データセット

任意です。学習に ODVG を使用する場合でも、検証では COCO 形式のアノテーションを使用します。

重要なパラメーター

• model.backbone：デフォルトは swin_tiny_224_1k です。Grounding DINO と同じバックボーンの選択肢を使用できます。
• train.optim.lr：学習率です。デフォルトは 2e-4 です。lr_backbone は 2e-5 です。GDINOTrainExpConfig を再利用し、Grounding DINO と同じ学習設定を使用します。
• model.num_queries：オブジェクトクエリ数です。デフォルトは 900 です。
• model.enc_layers / model.dec_layers：train/AutoML の実行では、両方とも 6 のままにしてください。 検証時、マスクヘッドはデコーダー出力が 6 個であることをアサートするため、トランスフォーマー層を減らす Grounding DINO のスモークテスト用オーバーライドをコピーすると、 即座に失敗します。
• AutoML のメトリックに関する注意：train ステージの AutoML では、metric="val_loss" と direction="minimize" を使用してください。パッケージに含まれる train ループは 検証損失のスカラー値をログに記録しますが、train ジョブ中に [bbox] val_mAP@50 は出力しません。単独の評価では、予測がしきい値を超えた場合に限り [segm] test_mAP50 と [bbox] test_mAP50 が出力されます。AutoML の推奨順位付けに使用する学習損失の代わりに、これらの条件付きテストメトリックを使用しないでください。
• model.has_mask：マスク予測ヘッドを有効にします。デフォルトは True です。マスク／Dice／関係性の損失係数が追加されます。
• model.num_region_queries：マスク予測用の領域クエリ数です。デフォルトは 100 です。
• model.loss_types：損失の構成要素です。デフォルトは [labels, boxes, masks] です。mask_loss_coef、dice_loss_coef、rela_loss_coef が含まれます。
• evaluate.ioi_threshold：マスク評価の IoI しきい値です。デフォルトは 0.5 です。
• evaluate.nms_threshold：NMS しきい値です。デフォルトは 0.2 です。
• evaluate.text_threshold：テキストマッチングのしきい値です。デフォルトは 0.3 です。
• dataset.has_mask：データセットにマスクのアノテーションが含まれるかを指定します。デフォルトは True です。val_data_sources のデフォルトの data_type は "VG" です。

マルチ GPU／マルチノード

起動方法： Lightning による管理です。Grounding DINO と同じ DDP/FSDP の動作になります。

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

ハードウェア

GPU は最低 1 基、推奨 4 基です。GPU あたり 24GB 以上（A100 推奨）の VRAM が必要です。マスク予測ヘッドがあるため、Grounding DINO より負荷が高くなります。GPU メモリは 24GB 以上を推奨します。

エラーパターン

CUDA のメモリ不足：batch_size を減らしてください。マスク予測により、Grounding DINO に加えてオーバーヘッドが発生します。

test_threshold のデプロイスキーマエラー：TAO Deploy では evaluate.text_threshold と inference.text_threshold を使用します。デプロイ設定では test_threshold を使用しないでください。

デプロイモデルの形状不一致：エクスポート時の Transformer とマスク構造のフィールドを、デプロイの evaluate／inference 設定に引き継いでください。対象には model.num_queries、 model.num_select、model.max_text_len、model.num_region_queries、model.has_mask が含まれます。これらの値は、TensorRT エンジンのビルドに使用する ONNX モデルと一致している必要があります。

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

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

TAO Core の mask_grounding_dino.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	model.pretrained_backbone_path	ptm_if_no_resume_model	再開チェックポイントがない場合の PTM
train	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	train.pretrained_model_path	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 に戻したり、チェックポイントのパスを推測するように生成済みのランナースクリプトを修正したりしないでください。

SDK のリゾルバーを使わずに Mask Grounding DINO のチェックポイントを選択する場合は、対象のエポック／ステップのアーティファクトと正確に一致させてください。たとえば、model_epoch_000_step_00049.pth です。mask_gdino_model_latest.pth シンボリックリンクが有効なのは、latest が明示的に要求された場合に限ります。親の PyTorch mask_grounding_dino CLI は train、evaluate、inference、export、quantize をサポートします。TensorRT エンジンの生成、TensorRT 推論、TensorRT 評価は、references/tao-deploy-mask-grounding-dino.md を通じて実行してください。

デプロイ

• tao-deploy-mask-grounding-dino