tao-train-grounding-dino

Grounding DINO

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

オープンセット物体検出用の Grounding DINO です。DINO スタイルの検出と BERT テキストエンコーダーを組み合わせ、言語ガイド付きの検出を実現します。固定クラス語彙を使わず、テキストプロンプトで記述されたオブジェクトを検出します。

完全な Grounding DINO の重みには train.pretrained_model_path を、バックボーンのみの場合は model.pretrained_backbone_path を設定してください。

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

Dataclass スキーマ

生成された 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 オーバーライドによって、モデルのメタデータが変更されることはありません。

トレーニング要件

• データセットの種類： object_detection
• フォーマット： odvg、coco、raw
• トレーニング監視メトリック： val_mAP50
• AutoML メトリック契約： 評価に基づく選択では、最大化方向で test_mAP50 を使用してください。パッケージ化された evaluate アクションは test_mAP50 を出力します。AutoML の試行比較と最終選択には、トレーニング専用の val_mAP50 キーではなく、この評価指標を使用してください。

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

アクション	Spec Key	ソース	ファイル	リスト？
評価	dataset.test_data_sources	eval_dataset	image_dir: images.tar.gz, json_file: annotations.json	いいえ
推論	dataset.infer_data_sources.image_dir	inference_dataset	images.tar.gz	はい
推論	dataset.infer_data_sources.captions	ワークフローのプロンプト	プロンプトリスト	はい
量子化	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.quant_calibration_data_sources	キャリブレーション／評価データセット	image_dir: images.tar.gz, json_file: annotations.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	いいえ

ランナーは画像アーカイブを images.tar.gz としてソースにできますが、ローカルの Docker TAO CLI 仕様では、image_dir に展開済みの画像ディレクトリを指定する必要があります。 スキルのメタデータでは、これらのアーカイブを使用する画像ソースに runtime: extracted_folder を設定するため、新しいランナーは TAO を起動する前に アーカイブを展開できます。

一般的な Spec のオーバーライド

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

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

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

{
    "train.num_epochs": 10,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "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"},
}

deploy/gen_trt_engine（references/tao-deploy-grounding-dino.md を使用）：

{
    "gen_trt_engine.onnx_file": "<exported_onnx_uri>",
    "gen_trt_engine.trt_engine": "<output_engine_path>",
    "gen_trt_engine.tensorrt.data_type": "FP16",
}

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

{
    "inference.checkpoint": "<selected train/AutoML checkpoint>",
    "dataset.infer_data_sources.image_dir": [f"{S3_EVAL}/images.tar.gz"],
    "dataset.infer_data_sources.captions": [
        "fire extinguisher",
        "cone",
        "cart",
        "forklift"
    ],
}

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

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

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

{
    "quantize.model_path": "<selected train checkpoint or exported ONNX model>",
    "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_EVAL}/images.tar.gz", "json_file": f"{S3_EVAL}/annotations.json"},
}

評価データセット

任意です。トレーニングでは ODVG 形式を使用できますが、検証では mAP の計算に COCO 形式のアノテーションを使用します。

重要なパラメーター

• model.backbone：デフォルトは swin_tiny_224_1k です。resnet_50 やその他の Swin バリアントもサポートしています。Swin は一般にグラウンディングタスクでより高い性能を発揮します。
• model.text_encoder_type：テキストエンコーディング用の BERT モデルです。デフォルトは bert-base-uncased です。max_text_len のデフォルトは 256 です。
• model.max_text_len：データセットのラベル／トークン位置マップと一致させてください。対応するラベルマップを同じ長さで再生成しない限り、スモークテストのために値を小さくしないでください。そうしないと、トークン確率と位置マップの行列形状が一致せず、検証に失敗する場合があります。
• train.optim.lr：学習率です。デフォルトは 2e-4 です。lr_backbone は 2e-5 です。fp16／fp32 に加えて、bf16 精度もサポートしています。
• dataset.max_labels：トレーニング中の画像あたりの最大ラベル数です。デフォルトは 50 です。アノテーションが密なデータセットでは増やしてください。
• model.num_queries：オブジェクトクエリ数です。オープンボキャブラリーの性質上、デフォルトは DINO の 300 より多い 900 です。
• model.num_queries / model.num_select：バッチ内でマッチする ODVG ターゲット数に対して、num_queries を十分に大きくしてください。20 のような非常に小さいスモークテスト用の値では、オブジェクトが密集した画像でハンガリアンターゲットのインデックス処理に失敗する場合があります。1 画像あたりのオブジェクト数が少ないことが分かっているデータセットを除き、Grounding DINO の最小限のスモーク実行では少なくとも 100 を使用してください。
• train.optim.lr_steps：MultiStep 学習率スケジュールです。デフォルトは [10] です。

マルチ GPU／マルチノード

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

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

DINO と同じ DDP／FSDP の動作です。マルチノードでは、オーケストレーターによって WORLD_SIZE、NODE_RANK、MASTER_ADDR、MASTER_PORT の環境変数が設定されている必要があります。

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

• エクスポート入力：960x544（他の OD モデルより大きい）、opset 17。スモークテストでは、Grounding-DINO のエクスポート仕様をテンプレートのエクスポート解像度のままにしてください。エクスポート解像度を 128x128 などの非常に小さいサイズにすると、torch.onnx.export 中に contrastive text head で PyTorch ONNX の形状推論アサーションが発生することがあります。
• 親の PyTorch grounding_dino CLI は、train、evaluate、inference、export、quantize をサポートしています。TensorRT エンジンの生成、TensorRT 推論、TensorRT 評価は、references/tao-deploy-grounding-dino.md を参照して実行してください。
• TRT のデータ型：FP32、FP16 のみ — INT8 はサポートされていません
• TRT ワークスペース：8192 MB（他の OD モデルの 8 倍）
• TRT max_batch_size：4

ハードウェア

GPU は最低 1 台、推奨 4 台です。GPU あたり 24GB 以上（A100 を推奨）の VRAM が必要です。Grounding DINO はテキストエンコーダー（BERT）を使用するため、標準的な DINO より負荷が高くなります。GPU メモリは 24GB 以上を推奨します。16GB の GPU では batch_size を減らしてください。

エラーパターン

CUDA のメモリ不足：batch_size を減らします（4 -> 2 -> 1）。BERT テキストエンコーダーによって、ビジョンバックボーンに加えて大幅なメモリオーバーヘッドが発生します。

検証アノテーションのカテゴリ ID：損失を正しく計算するには、検証アノテーションのカテゴリ ID を 0 から始める必要があります。必要に応じて、アノテーション形式を変換してください。

テキストエンコーダーの読み込みエラー：コンテナから bert-base-uncased の重みをダウンロードできることを確認するか、ローカルパスを指定してください。

TAO Toolkit 7.0.0-rc-226 で PyTorch チェックポイントを使用した量子化に失敗する場合： コンテナの Grounding-DINO 量子化スクリプトは、チェックポイントの読み込み時に cap_lists=None を渡すため、post_process.py で失敗します。ONNX 量子化では エクスポート済みの ONNX アーティファクトと COCO キャリブレーションデータを使用しますが、デフォルトの rc-226 PyTorch イメージには modelopt.onnx.quantization モジュールもありません。この問題はチェックポイントリゾルバーではなく、イメージ／SDK の問題として扱ってください。

post_process.py で mat1 と mat2 の形状を乗算できない場合：テキストの トークン長とラベル位置マップに一貫性がありません。通常、データセットのラベルマップでは 256 長の位置マップを使用している一方で、model.max_text_len がデフォルトの 256 より小さい値に上書きされていることが原因です。model.max_text_len を元に戻すか、 同じ長さでラベルマップを再生成してください。

criterion.py で dimension 0 の index が範囲外になる場合：model.num_queries が現在のバッチ内のマッチした ODVG ターゲットに対して小さすぎます。model.num_queries を増やし、 model.num_select との互換性を保ってください。

images.tar.gz/<image>.jpg で NotADirectoryError が発生する場合：TAO CLI が アーカイブパスをディレクトリとして走査しようとしています。アーカイブを展開し、該当する image_dir フィールドに展開後の画像フォルダーを設定してください。アーカイブを使用するスキルのデータソースで runtime: extracted_folder を指定するのはこのためです。

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

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

TAO Core grounding_dino.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	現在のジョブの結果ディレクトリ
推論	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.pretrained_backbone_path	ptm_if_no_resume_model	再開用チェックポイントがない場合の PTM
トレーニング	results_dir	output_dir	現在のジョブの結果ディレクトリ
トレーニング	train.pretrained_model_path	ptm_if_no_resume_model	再開用チェックポイントがない場合の PTM
トレーニング	train.resume_training_checkpoint_path	resume_model	現在のジョブの結果フォルダーから推論したモデルファイル

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

SDK のリゾルバーを使わずに Grounding-DINO のチェックポイントを選択する場合は、 model_epoch_000_step_00046.pth のように、目的のエポック／ステップのアーティファクトと正確に一致させてください。gdino_model_latest.pth のシンボリックリンクが有効なのは、latest が明示的に要求された場合のみです。チェックポイントとエンジンの形状を一致させるため、model.backbone、model.num_queries、model.num_select、 model.num_feature_levels、model.max_text_len などの構造的なモデル設定と、エクスポート時の入力解像度を evaluate、inference、export、deploy の各 spec に引き継いでください。

デプロイ

• tao-deploy-grounding-dino