tao-train-rtdetr

RT-DETR

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

RT-DETR（Real-Time DEtection TRansformer）は、2D 物体検出用です。高い精度を維持しながら、リアルタイム推論を実現するよう設計されています。デプロイの最適化に向けた蒸留と量子化に対応しています。

バックボーンの重みには model.pretrained_backbone_path、モデル全体の重みには train.pretrained_model_path を設定してください。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）については、先に references/tao-deploy-rtdetr.md をお読みください。デプロイ仕様テンプレートは、このスキルの 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 の両方がパッケージに含まれている場合は、デフォルトでこのモデルの skill_dir を指定し、train アクションを tao-skill-bank:tao-run-automl 経由で実行してください。データセット、仕様、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に関するワークフロー／アプリケーションの上書き設定は維持してください。直接モデルをトレーニングするのは、automl_policy: off の場合、または train スキーマ／テンプレートがパッケージに含まれていない場合に限ります。スキーマがない場合は、AutoML は有効ですが、スキーマが生成されるまではこのモデルで実行できないことを報告してください。

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

対応アクション

パッケージ化された RT-DETR PyT CLI は、train、distill、quantize、evaluate、export、inference、default_specs に対応しています。このモデルスキルが公開するのは train、distill、quantize、evaluate、export、inference です。再開／再トレーニングは、train.resume_training_checkpoint_path を指定した train で行います。

親の PyT CLI は gen_trt_engine を公開していません。TensorRT エンジンの生成、TensorRT の評価、TensorRT の推論には models/rtdetr/deploy を使用してください。

トレーニング要件

• データセットタイプ： object_detection
• フォーマット： coco、coco_raw
• AutoML トレーニング指標： 手早い運用確認には val_mAP50、COCO／論文形式のベンチマーク比較には val_mAP を使用します。どちらも最大化します。これらは構造化された train ステータス KPI の正確な名前です。
• 単体評価指標： test_mAP50 と test_mAP。AutoML の試行ランキングには、評価器の test_* 名を使用しないでください。

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

アクション	Spec キー	ソース	ファイル	リスト?
distill	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
distill	dataset.val_data_sources	eval_dataset	image_dir: images.tar.gz, json_file: annotations.json	いいえ
evaluate	dataset.test_data_sources	eval_dataset	image_dir: images.tar.gz, json_file: annotations.json	いいえ
inference	dataset.infer_data_sources	inference_dataset	image_dir: images.tar.gz, classmap: label_map.txt	はい
quantize	dataset.train_data_sources	train_datasets	image_dir: images.tar.gz, json_file: annotations.json	はい
quantize	dataset.val_data_sources	eval_dataset	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	eval_dataset	image_dir: images.tar.gz, json_file: annotations.json	いいえ

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

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

S3_TRAIN = "s3://bucket/data/train"
S3_EVAL = "s3://bucket/data/eval"
CHECKPOINT = "/results/{train_job_id}/results_dir/model_epoch_000.pth"
ONNX_FILE = "/results/{export_job_id}/results_dir/rtdetr.onnx"

train（必須のデータソース）:

{
    "train.num_epochs": 10,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "train.gpu_ids": [0],
    "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_EVAL}/images.tar.gz", "json_file": f"{S3_EVAL}/annotations.json"},
}

resume train（必須のチェックポイント）:

{
    "train.num_epochs": 11,
    "train.resume_training_checkpoint_path": CHECKPOINT,
    "dataset.num_classes": "<num_classes> + 1",
    "dataset.eval_class_ids": [1, 2, 3, 4],
    "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_EVAL}/images.tar.gz", "json_file": f"{S3_EVAL}/annotations.json"},
}

evaluate（必須のデータソースとチェックポイント）:

{
    "dataset.num_classes": "<num_classes> + 1",
    "dataset.eval_class_ids": [1, 2, 3, 4],
    "dataset.test_data_sources": {"image_dir": f"{S3_EVAL}/images.tar.gz", "json_file": f"{S3_EVAL}/annotations.json"},
    "evaluate.checkpoint": CHECKPOINT,
}

export（必須のチェックポイントと出力）:

{
    "dataset.num_classes": "<num_classes> + 1",
    "export.checkpoint": CHECKPOINT,
    "export.onnx_file": ONNX_FILE,
    "export.input_height": 640,
    "export.input_width": 640,
}

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

{
    "dataset.num_classes": "<num_classes> + 1",
    "quantize.layers": [
        {
            "module_name": "*",
            "weights": {
                "dtype": "float8_e4m3fn"
            },
            "activations": {
                "dtype": "float8_e4m3fn"
            }
        }
    ],
    "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_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.json"},
    "quantize.model_path": CHECKPOINT,
}

inference（必須のデータソースとチェックポイント）:

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

distill（必須のデータソースと teacher チェックポイント）:

{
    "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_EVAL}/images.tar.gz", "json_file": f"{S3_EVAL}/annotations.json"},
    "distill.pretrained_teacher_model_path": CHECKPOINT,
}

Eval Dataset

任意です。指定した場合、各チェックポイントでの検証 mAP を提供します。

重要なパラメータ

• dataset.num_classes: クラス数。デフォルトは 80（MSCOCO の 80 クラス）。データセットのアノテーションと一致している必要があります。
• model.backbone: デフォルトは resnet_50。対応: ResNet の各種バリアント、ConvNeXt、FAN、EfficientViT。RT-DETR はより軽量なバックボーンによるリアルタイム処理に最適化されています。
• train.optim.lr: 学習率。デフォルトは 1e-4（DINO の 2e-4 より低い）。lr_backbone のデフォルトは 1e-5 です。
• dataset.augmentation.train_spatial_size: 学習時の入力サイズ。デフォルトは [640, 640]。DINO のマルチスケール（最大 1333）より小さい値です。RT-DETR の速度の鍵となります。
• model.num_feature_levels: デフォルトは 3（DINO の 4 に対して）。return_interm_indices は [1,2,3] です。
• train.enable_ema: 指数移動平均。デフォルトは False。有効にすると収束がより安定する可能性があります。
• dataset.remap_mscoco_category: デフォルトは False。91 から 80 へのカテゴリ ID の再マッピングを行う元の MSCOCO データセットに対してのみ True に設定します。

マルチ GPU／マルチノード

起動方法： torchrun（LIGHTNING_EXCLUDED_NETWORK）。エントリーポイントは torchrun --nnodes=N --nproc-per-node=M train.py を実行します。通常の python ではありません。

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

• train.num_gpus を増やす場合は、train.gpu_ids も同じ範囲の可視デバイスに設定してください。たとえば、8 GPU の単一ノードで Slurm を実行するには、"train.num_gpus": 8 と "train.gpu_ids": [0, 1, 2, 3, 4, 5, 6, 7] の両方を指定する必要があります。
• CUDA_VISIBLE_DEVICES は明示的に設定されます（Lightning 管理モデルが TAO_VISIBLE_DEVICES を使用する場合とは異なります）。
• アクティベーションチェックポイントを使用する ddp：find_unused_parameters=False
• 使用しない場合の ddp：find_unused_parameters=True
• fsdp をサポートしており、FP16 が強制されます。

マルチノード環境変数（オーケストレーターが設定）：

変数	用途
WORLD_SIZE	ノード数（マルチノードモードを有効化）
NODE_RANK	このノードのランク（0 起点）
MASTER_ADDR	ランク 0 のノード IP
MASTER_PORT	ランク 0 のポート（デフォルト 29500）
NUM_GPU_PER_NODE	ノードあたりの GPU 数（デフォルト：可視デバイスすべて）

重要： RANK が未設定の場合、NODE_RANK が RANK にコピーされます。これは torchrun のマルチノード実行に必要です。

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

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

蒸留

RT-DETR は教師モデルを使用した知識蒸留をサポートしています。distill アクションに加え、distill.pretrained_teacher_model_path と蒸留バインディング設定が必要です。

出発点として、同梱の references/spec_template_distill.yaml を使用してください。検証済みのデフォルトバインディングでは、RT-DETR 蒸留器の明示的な IOU 特徴パスを使用します。

distill:
  bindings:
  - student_module_name: srcs
    teacher_module_name: srcs
    criterion: IOU
    weight: 1.0

pred_logits／pred_boxes などの DINO 形式の出力名に置き換えないでください。また、モジュールがキャプチャした特徴リストを返すことを確認していない限り、任意のデコーダーヘッドをバインドしないでください。RT-DETR 蒸留器では、IOU バインディングに srcs または dsrcs を使用する必要があります。

ハードウェア

最低 1 GPU、推奨 2 GPU です。GPU あたり 16GB 以上（V100 または A100）の VRAM が必要です。RT-DETR は入力サイズが小さく（640x640）、特徴レベルも少ないため、DINO／GDINO よりメモリ効率に優れています。小規模から中規模のデータセットであれば、単一 GPU でも良好に学習できます。

エラーパターン

CUDA out of memory：batch_size を減らしてください。640x640 の RT-DETR は 1333px の DINO より軽量ですが、16GB の GPU では batch_size が 8 を超えると OOM が発生する場合があります。

num_classes の不一致：RT-DETR のデフォルトは 80 です（DINO のように 91 ではありません）。dataset.num_classes がアノテーションのカテゴリ数と一致していることを確認してください。

カテゴリ ID による CUDA index assert：COCO のカテゴリ ID が 1 始まりである場合や、0 始まりの連続した ID に再マッピングされていない場合は、dataset.num_classes を max(category_id) + 1 に設定し、dataset.eval_class_ids を実際のカテゴリ ID と一致させてください。パッケージに含まれる 4 クラスの S3 サンプルでは ID が 1～4 なので、dataset.num_classes: 5、dataset.eval_class_ids: [1, 2, 3, 4] を使用してください。

return_interm_indices と num_feature_levels の不一致：デフォルトは num_feature_levels=3 の場合に [1,2,3] です。変更する場合は整合性を保つ必要があります。

エクスポート時の形状の不一致：モデルを別の形状でトレーニングし、検証していない限り、RT-DETR のエクスポートとデプロイ側のコンシューマーの入力サイズは、検証済みのデフォルトである 640x640 を維持してください。以前のパッケージに含まれていた 960x544 のテンプレート形状では、hybrid_encoder.py の位置埋め込みの加算時に The size of tensor a (...) must match the size of tensor b (...) が発生し、ONNX トレースに失敗する場合があります。

AutoML のメトリクス抽出：RT-DETR は、構造化されたトレーニングステータスとログに検出メトリクスを出力します。COCO／論文形式のベンチマーク比較では、direction: maximize を指定して val_mAP を最適化してください。明示的に AP50 を扱うワークフローでは、val_mAP50 を最適化してください。単独評価では、対応する test_mAP と test_mAP50 のキーが出力されます。生ログを解析する前に、results_dir/train/status.json または AutoML の結果状態を参照してください。デフォルトの検出モデルの実行では、val_loss を最適化しないでください。

チェックポイントの引き継ぎ：evaluate／export／inference／quantize／distill／resume では、最適な AutoML 子ジョブの results_dir/train/ フォルダーに対してチェックポイントリゾルバーを使用し、処理に適した model_epoch_*.pth チェックポイントを選択してください。RT-DETR が latest のシンボリックリンクも書き込む場合がありますが、latest が明示的に要求された場合に限り使用してください。dataset.num_classes、dataset.eval_class_ids、model.num_queries、model.num_select はトレーニング時の設定と一致させてください。

親タスクの rtdetr gen_trt_engine が PyT CLI に拒否される：検証済みの 7.0.0 PyT コンテナーでは、rtdetr gen_trt_engine は親モデルのサブタスクとして有効ではありません。TensorRT エンジンの生成、TensorRT 評価、TensorRT 推論には、RT-DETR のデプロイワークフロー（references/tao-deploy-rtdetr.md）を使用してください。

Spec Param / 親モデル推論

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

TAO Core の rtdetr.config.json からの推論マッピング:

アクション	Spec フィールド	推論関数	意味
distill	distill.pretrained_teacher_model_path	parent_model	親ジョブの結果フォルダーから推論されたモデルファイル
distill	encryption_key	key	暗号化キー
distill	results_dir	output_dir	現在のジョブの結果ディレクトリ
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-rtdetr