tao-train-deformable-detr

Deformable DETR

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

2D物体検出向けの Deformable DETR です。変形可能なアテンションを使用し、複数スケールの特徴を効率的に処理します。精度を競争力のある水準に保ちながら、DINO より軽量です。

事前学習済みの重みを使用します。バックボーンのみを読み込む場合は model.pretrained_backbone_path を、モデル全体の初期化には train.pretrained_model_path を設定してください。

サポートされている親モデルのアクションは train、evaluate、inference、export、quantize です。PyT モデルコンテナは、このネットワークのネイティブな gen_trt_engine サブタスクをサポートしていません。references/skill_info.yaml で宣言されている gen_trt_engine アクションは、TAO Deploy コンテナで実行する必要があります。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 オーバーライドによってモデルのメタデータが変わることはありません。

トレーニング要件

• データセットの種類： object_detection
• 形式： coco、coco_raw
• AutoML の指標契約： 評価に基づいて選択する場合は、最大化を方向とする test_mAP50 を使用してください。トレーニングログのみを使う AutoML ワークフローでは val_mAP50 のみを使用してください。
• トレーニング監視指標： AP50 には val_mAP50、COCO／論文形式のベンチマーク比較には val_mAP を使用してください。
• Evaluate アクションの指標： AP50 には test_mAP50、COCO／論文形式のベンチマーク比較には test_mAP を使用してください。Evaluate アクションを通じて比較する AutoML 試行では、評価器の出力から val_* KPI を探すのではなく、対応する test_* KPI を使用する必要があります。

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

アクション	仕様キー	ソース	ファイル	リスト？
評価	dataset.test_data_sources.image_dir	eval_dataset	images.tar.gz	いいえ
評価	dataset.test_data_sources.json_file	eval_dataset	annotations.json	いいえ
エクスポート	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
エクスポート	dataset.val_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
推論	dataset.infer_data_sources.image_dir	inference_dataset	images.tar.gz	はい
推論	dataset.infer_data_sources.classmap	inference_dataset	label_map.txt	いいえ
量子化	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
量子化	dataset.val_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
量子化	dataset.quant_calibration_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	いいえ
トレーニング	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
トレーニング	dataset.val_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい

典型的な仕様の上書き

データソースの上書きはすべてのアクションで必須です。エージェントは、アクションごとのデータセット要件の表に基づいてデータソースのパスを構築し、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,
    "train.gpu_ids": [0],
    "dataset.num_classes": "<object classes> + 1",
    "dataset.eval_class_ids": [1, 2, "..."],
    "dataset.train_data_sources": [{"image_dir": f"{S3_TRAIN}/images.tar.gz", "json_file": f"{S3_TRAIN}/annotations.json"}],
    "dataset.val_data_sources": [{"image_dir": f"{S3_TRAIN}/images.tar.gz", "json_file": f"{S3_TRAIN}/annotations.json"}],
}

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

{
    "dataset.num_classes": "<object classes> + 1",
    "dataset.eval_class_ids": [1, 2, "..."],
    "dataset.test_data_sources.image_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.test_data_sources.json_file": f"{S3_EVAL}/annotations.json",
}

トレーニングまたはAutoMLの実行で、model.enc_layers、model.dec_layers、model.num_queries、model.num_selectなど、アーキテクチャに影響するフィールドを変更した場合は、選択したチェックポイントを使用する評価、エクスポート、推論、デプロイの各アクションにも同じ値を引き継いでください。上記のフィールドに加えて、model.num_feature_levels、model.dim_feedforward、入力画像の寸法、データセットのクラスメタデータも、変更した場合は引き継いでください。デフォルトのアーキテクチャにチェックポイントを読み込むと、テンソルの形状が一致せず失敗することがあります。特に、処理を高速化するためにトランスフォーマーを縮小するスモークテスト実行では注意が必要です。

エクスポート（必須のデータソース）：

{
    "dataset.num_classes": "<object classes> + 1",
    "dataset.eval_class_ids": [1, 2, "..."],
    "dataset.train_data_sources": [{"image_dir": f"{S3_TRAIN}/images.tar.gz", "json_file": f"{S3_TRAIN}/annotations.json"}],
    "dataset.val_data_sources": [{"image_dir": f"{S3_TRAIN}/images.tar.gz", "json_file": f"{S3_TRAIN}/annotations.json"}],
}

TensorRTエンジンの生成：

exportの後に、deployの仕様テンプレートを使用してください。親のPyTモデルコンテナからdeformable_detr gen_trt_engineを呼び出さないでください。このCLIが提供するのはconvert、evaluate、export、inference、quantize、train、default_specsであり、gen_trt_engineは含まれていません。モデルのアクションメタデータによって、エンジン生成にはTAO Deployコンテナが選択されます。

Deployでエンジンを生成するには、エクスポートされたONNXファイルを入力として使用します。エンジンはgen_trt_engine.trt_engineに作成されます。

{
    "gen_trt_engine.tensorrt.data_type": "FP16",
    "dataset.num_classes": "<object classes> + 1",
    "gen_trt_engine.tensorrt.calibration.cal_image_dir": [f"{S3_TRAIN}/images.tar.gz"],
}

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

{
    "dataset.num_classes": "<object classes> + 1",
    "dataset.infer_data_sources.image_dir": [f"{S3_EVAL}/images.tar.gz"],
    "dataset.infer_data_sources.classmap": f"{S3_EVAL}/label_map.txt",
}

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

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

評価用データセット

任意です。指定すると、チェックポイントの各間隔で検証mAPが計算されます。

チェックポイントの処理

トレーニングでは、model_epoch_<epoch>_step_<step>.pthというパターンのエポックとステップを含むチェックポイントが出力され、さらにdd_model_latest.pthシンボリックリンクも作成されます。後続のアクションでは、モデル固有またはSDK提供のチェックポイントリゾルバーを使用して、対象のアーティファクトを選択してください。ユーザーが明示的に最新を指定していない限り、評価、推論、エクスポート、量子化にはdd_model_latest.pthシンボリックリンクではなく、選択した正確なチェックポイントパスを渡してください。再開または再トレーニングでは、再開元となる正確なチェックポイントをtrain.resume_training_checkpoint_pathに設定してください。

重要なパラメーター

• dataset.num_classes：背景クラスを含むオブジェクトクラスの数です。デフォルトは 91（COCO）です。アノテーションと一致している必要があります。
• dataset.eval_class_ids：COCO メトリクスに含める前景カテゴリ ID です。カスタムデータセットでは、すべてのオブジェクトカテゴリ ID を設定してください。テンプレートのデフォルトではクラス ID 1 のみが評価されます。
• model.backbone：デフォルトは resnet_50 です。サポート対象：resnet_50、gcvit_tiny、gcvit_small、gcvit_base、gcvit_large、gcvit_large_384（DINO より対応範囲が限られています）。
• train.optim.lr：学習率です。デフォルトは 2e-4（AdamW）です。lr_backbone は 2e-5 です。
• train.optim.lr_steps：MultiStep LR スケジュールです。デフォルトは [40] です。短期間の実行では、総エポック数の約 80% に合わせて設定してください。
• model.num_queries：オブジェクトクエリの数です。デフォルトは 300 です。有効範囲は 100～900 です。
• model.dropout_ratio：Transformer レイヤーのドロップアウトです。デフォルトは 0.3（DINO の 0.0 より高い値）です。大規模データセットでは下げ、小規模データセットでは上げてください。
• model.dim_feedforward：FFN の隠れ層の次元です。デフォルトは 1024（DINO の 2048 に対して）です。増やすと性能が向上しますが、メモリ消費量も増加します。

マルチ 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 の環境変数が設定されている必要があります。

train.num_gpus を増やす場合は、train.gpu_ids にも同じ範囲の利用可能な デバイスを設定してください。たとえば、単一ノードで 8 GPU を使う Slurm の実行では、 "train.num_gpus": 8 と "train.gpu_ids": [0, 1, 2, 3, 4, 5, 6, 7] の 両方を指定する必要があります。

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

• エクスポート入力：640x640、opset 17
• TRT のデータ型：FP32、FP16、INT8
• TRT ワークスペース：1024 MB
• TRT max_batch_size：1

ハードウェア

最低 1 GPU、推奨 4 GPU です。各 GPU に 16GB 以上（V100 または A100）の VRAM が必要です。FFN が小さいため、DINO よりわずかに軽量です。batch_size=4 は、ほとんどの 16GB 以上の GPU で実行できます。

エラーパターン

CUDA のメモリ不足：batch_size を減らしてください（4 → 2 → 1）。

num_select must be < num_queries * num_classes：DINO と同じ制約です。

return_interm_indices length must match num_feature_levels：デフォルトは num_feature_levels=4 に対して [1,2,3,4] です。

データセットサイズが総バッチサイズより小さい：batch_size または num_gpus を減らしてください。

AutoML のメトリクス抽出：Deformable DETR は、構造化された学習ステータスに val_mAP と val_mAP50 を出力します。一方、単独の evaluate アクションは test_mAP と test_mAP50 を出力します。COCO／論文形式の学習のみの比較では val_mAP を最適化してください。AP50 を明示的に使う学習のみのワークフローでは val_mAP50 を最適化してください。AutoML が evaluate アクションで各推奨値をスコアリングする場合は、対応する KPI である test_mAP または test_mAP50 を使用してください。生ログを解析する前に、results_dir/train/status.json または AutoML の結果状態を優先してください。デフォルトの物体検出モデルの実行では、val_loss を最適化しないでください。

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

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

TAO Core deformable_detr.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	現在のジョブの結果ディレクトリ
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 に戻したり、チェックポイントパスを推測するよう生成されたランナースクリプトにパッチを適用したりしないでください。

デプロイ

• tao-deploy-deformable-detr