tao-train-deformable-detr

Deformable DETR

2D 物体検出向けの Deformable DETR です。変形可能アテンションを使用して、マルチスケールの特徴処理を効率化します。精度を維持しながら、DINO より軽量です。

事前学習済みのバックボーン重みを使用します。バックボーンのみを読み込むには、model.pretrained_backbone_path を設定してください。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）については、最初に references/tao-deploy-deformable-detr.md をお読みください。Deploy spec のテンプレートは、このスキルの references/ フォルダーに spec_template_deploy_*.yaml というプレフィックスで格納されています。

Dataclass スキーマ

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

Train アクションのポリシー

このモデルはモデルレイヤーで AutoML が有効になっています。train ステージのリクエストに対応する前に、references/skill_info.yaml を読み、明示的な automl_policy の値、またはユーザーのワークフローリクエストから、この実行に適用する設定を解決してください。「AutoML をオフにする」、「AutoML を無効にする」、「HPO を使わない」、「通常のトレーニング」などの表現は、この実行に限り automl_policy: off として扱ってください。それ以外の場合は、デフォルトで auto を使用します。automl_policy: auto、automl_enabled: true であり、schemas/train.schema.json と references/spec_template_train.yaml の両方がパッケージ化されている場合は、デフォルトでこのモデルの skill_dir を指定して、train アクションを tao-skill-bank:tao-run-automl にルーティングしてください。データセット、spec、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に対するワークフロー／アプリケーションのオーバーライドは維持してください。直接モデルをトレーニングするのは、automl_policy: off の場合、またはパッケージ化された train スキーマ／テンプレートがない場合に限ってください。スキーマがない場合は、AutoML は有効ですが、スキーマが生成されるまでこのモデルでは実行できないことを報告してください。

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

トレーニング要件

• データセットの種類： object_detection
• 形式： coco、coco_raw
• モニタリング指標： val_mAP50

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

アクション	仕様キー	ソース	ファイル	リスト？
evaluate	dataset.test_data_sources.image_dir	eval_dataset	images.tar.gz	いいえ
evaluate	dataset.test_data_sources.json_file	eval_dataset	annotations.json	いいえ
export	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
export	dataset.val_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
gen_trt_engine	gen_trt_engine.tensorrt.calibration.cal_image_dir	calibration_dataset	images.tar.gz	はい
inference	dataset.infer_data_sources.image_dir	inference_dataset	images.tar.gz	はい
inference	dataset.infer_data_sources.classmap	inference_dataset	label_map.txt	いいえ
quantize	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
quantize	dataset.val_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
quantize	dataset.quant_calibration_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	いいえ
train	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
train	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（必須のデータソース）：

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

evaluate（必須のデータソース）：

{
    "dataset.num_classes": "<num_classes> + 1",
    "dataset.test_data_sources.image_dir": f"{S3_EVAL}/images.tar.gz",
    "dataset.test_data_sources.json_file": f"{S3_EVAL}/annotations.json",
}

export（必須のデータソース）：

{
    "dataset.num_classes": "<num_classes> + 1",
    "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"}],
}

gen_trt_engine（必須のデータソース）：

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

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

{
    "dataset.num_classes": "<num_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",
}

quantize（必須のデータソース）：

{
    "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 が計算されます。

重要なパラメーター

• dataset.num_classes：オブジェクトクラスの数です。デフォルトは 91（COCO）です。アノテーションと一致している必要があります。
• 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 がワーカーを起動します）。

仕様キー	説明	デフォルト
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 のデフォルト値

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

TAO Deploy の全リファレンス：tao-deploy-deformable-detr。

ハードウェア

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

エラーパターン

CUDA out of memory：batch_size を減らします（4 -> 2 -> 1）。

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

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

Dataset size smaller than total batch size：batch_size または num_gpus を減らします。

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

モデル固有の推論マッピングは config.json ではなく、この MD ファイルに記述します。生成されたランナーはこのセクションを読み取り、SDK ヘルパーを使って create_job() の前にマッピングを適用します。これは、以前のマイクロサービスにおける 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	現在のジョブの結果ディレクトリ
gen_trt_engine	encryption_key	key	暗号化キー
gen_trt_engine	gen_trt_engine.onnx_file	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
gen_trt_engine	gen_trt_engine.tensorrt.calibration.cal_cache_file	create_cal_cache	キャリブレーションキャッシュのパス
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.resume_training_checkpoint_path	resume_model	現在のジョブの結果フォルダーから推論されるモデルファイル

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