tao-train-sparse4d

Sparse4D

マルチカメラによる時系列3D物体検出とトラッキングのためのSparse4Dです。カメラビューと時間軸をまたぐ変形可能アテンションでスパースクエリを使用し、エンドツーエンドの3D認識を実現します。時系列トラッキング用のインスタンスバンクを含みます。

事前学習済みのResNet-101バックボーンが必要です。train.pretrained_model_pathを設定してください。

データクラススキーマ

生成されたTAO Coreスキーマはschemas/<action>.schema.jsonにパッケージ化され、利用可能なアクションはschemas/manifest.jsonに記載されています。生成された各スキーマでは、スキーマのトップレベルのdefaultフィールドからreferences/spec_template_<action>.yamlも出力されます。AutoMLの有効化は、references/skill_info.yamlのモデルレイヤーでautoml_enabledを介して宣言されます。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に渡してください。データセット、仕様、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policyに対するワークフロー／アプリケーションのオーバーライドは維持してください。直接モデルをトレーニングするのは、automl_policy: offの場合、またはパッケージ化されたtrainスキーマ／テンプレートが不足している場合に限ります。スキーマが不足している場合は、AutoMLは有効ですが、スキーマが生成されるまではこのモデルで実行できないことを報告してください。

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

トレーニング要件

• データセットタイプ： sparse4d
• 形式： ovpkl
• 監視メトリック： val_mAP

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

アクション	Spec キー	ソース	ファイル	リストか
dataset_convert	aicity.root	id		いいえ
evaluate	dataset.data_root	eval_dataset	(from convert job, spec: aicity.split)	いいえ
evaluate	model.head.instance_bank.anchor	train_datasets	/results/{dataset_convert_job_id}/anchor_init.npy	いいえ
evaluate	dataset.train_dataset.ann_file	train_datasets	(from convert job, spec: aicity.split)	いいえ
evaluate	dataset.val_dataset.ann_file	eval_dataset	(from convert job, spec: aicity.split)	いいえ
evaluate	dataset.test_dataset.ann_file	inference_dataset	(from convert job, spec: aicity.split)	いいえ
export	model.head.instance_bank.anchor	train_datasets	/results/{dataset_convert_job_id}/anchor_init.npy	いいえ
inference	dataset.data_root	inference_dataset	(from convert job, spec: aicity.split)	いいえ
inference	model.head.instance_bank.anchor	train_datasets	/results/{dataset_convert_job_id}/anchor_init.npy	いいえ
inference	dataset.train_dataset.ann_file	train_datasets	(from convert job, spec: aicity.split)	いいえ
inference	dataset.val_dataset.ann_file	eval_dataset	(from convert job, spec: aicity.split)	いいえ
inference	dataset.test_dataset.ann_file	inference_dataset	(from convert job, spec: aicity.split)	いいえ
quantize	dataset.data_root	train_datasets	(from convert job, spec: aicity.split)	いいえ
quantize	model.head.instance_bank.anchor	train_datasets	/results/{dataset_convert_job_id}/anchor_init.npy	いいえ
quantize	dataset.train_dataset.ann_file	train_datasets	(from convert job, spec: aicity.split)	いいえ
quantize	dataset.val_dataset.ann_file	eval_dataset	(from convert job, spec: aicity.split)	いいえ
quantize	dataset.test_dataset.ann_file	inference_dataset	(from convert job, spec: aicity.split)	いいえ
quantize	dataset.quant_calibration_dataset.images_dir	train_datasets		いいえ
train	dataset.data_root	train_datasets	(from convert job, spec: aicity.split)	いいえ
train	model.head.instance_bank.anchor	train_datasets	/results/{dataset_convert_job_id}/anchor_init.npy	いいえ
train	dataset.train_dataset.ann_file	train_datasets	(from convert job, spec: aicity.split)	いいえ
train	dataset.val_dataset.ann_file	eval_dataset	(from convert job, spec: aicity.split)	いいえ
train	dataset.test_dataset.ann_file	inference_dataset	(from convert job, spec: aicity.split)	いいえ

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

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

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

train（必須データソース）：

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.sequences.split_num": 90,
    "train_dataset.sequences_split_num": 90,
    "dataset.data_root": {"spec": f"{S3_TRAIN}/aicity.split)"},
    "model.head.instance_bank.anchor": f"{S3_TRAIN}//results/{dataset_convert_job_id}/anchor_init.npy",
    "dataset.train_dataset.ann_file": {"spec": f"{S3_TRAIN}/aicity.split)"},
    "dataset.val_dataset.ann_file": {"spec": f"{S3_EVAL}/aicity.split)"},
    "dataset.test_dataset.ann_file": {"spec": f"{S3_EVAL}/aicity.split)"},
}

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

{
    "dataset.data_root": {"spec": f"{S3_EVAL}/aicity.split)"},
    "model.head.instance_bank.anchor": f"{S3_TRAIN}//results/{dataset_convert_job_id}/anchor_init.npy",
    "dataset.train_dataset.ann_file": {"spec": f"{S3_TRAIN}/aicity.split)"},
    "dataset.val_dataset.ann_file": {"spec": f"{S3_EVAL}/aicity.split)"},
    "dataset.test_dataset.ann_file": {"spec": f"{S3_EVAL}/aicity.split)"},
}

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

{
    "model.head.instance_bank.anchor": f"{S3_TRAIN}//results/{dataset_convert_job_id}/anchor_init.npy",
}

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

{
    "dataset.data_root": {"spec": f"{S3_EVAL}/aicity.split)"},
    "model.head.instance_bank.anchor": f"{S3_TRAIN}//results/{dataset_convert_job_id}/anchor_init.npy",
    "dataset.train_dataset.ann_file": {"spec": f"{S3_TRAIN}/aicity.split)"},
    "dataset.val_dataset.ann_file": {"spec": f"{S3_EVAL}/aicity.split)"},
    "dataset.test_dataset.ann_file": {"spec": f"{S3_EVAL}/aicity.split)"},
}

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

{
    "dataset.data_root": {"spec": f"{S3_TRAIN}/aicity.split)"},
    "model.head.instance_bank.anchor": f"{S3_TRAIN}//results/{dataset_convert_job_id}/anchor_init.npy",
    "dataset.train_dataset.ann_file": {"spec": f"{S3_TRAIN}/aicity.split)"},
    "dataset.val_dataset.ann_file": {"spec": f"{S3_EVAL}/aicity.split)"},
    "dataset.test_dataset.ann_file": {"spec": f"{S3_EVAL}/aicity.split)"},
    "dataset.quant_calibration_dataset.images_dir": f"{S3_TRAIN}",
}

評価データセット

任意です。検証／テストの分割は、データセットの ann_file パスで設定します。

重要なパラメーター

• model.backbone：バックボーンです。デフォルトは resnet_101 です。
• model.neck.out_channels：FPN の出力チャンネル数です。デフォルトは 256 です。num_outs=4 です。
• model.input_shape：入力画像の形状 [W, H] です。デフォルトは [1408, 512] です。
• model.head.num_output：検出出力クエリーの数です。デフォルトは 300 です。
• model.head.num_decoder：デコーダー層の数です。デフォルトは 6 です。
• model.head.temporal：時間的推論を有効にします。デフォルトは True です。
• model.head.instance_bank.num_anchor：インスタンスバンクのアンカー数です。デフォルトは 900 です。
• model.head.instance_bank.num_temp_instances：時間的インスタンスの数です。デフォルトは 600 です。
• model.depth_branch.loss_weight：深度教師あり学習の損失重みです。デフォルトは 0.2 です。
• dataset.batch_size：GPU あたりのバッチサイズです。デフォルトは 2 です。
• dataset.num_frames：シーケンス長です。デフォルトは 200 です。
• dataset.classes：検出クラスです。デフォルトは [person, gr1_t2, agility_digit, nova_carter] です。トラッキング用の num_ids=70 です。
• train.optim.lr：学習率です。デフォルトは 5e-5 です。img_backbone の lr_mult=0.2 です。
• train.lr_scheduler：線形ウォームアップ（500 イテレーション、ratio 0.333）付きのコサインスケジューラーです。
• train.grad_clip.max_norm：勾配クリッピングです。デフォルトは 25 です。
• train.precision：選択肢：bf16、fp16、fp32 です。デフォルトは bf16 です。
• evaluate.metrics：評価メトリクスです。デフォルトは ["detection"] です。トラッキング評価も選択できます。
• evaluate.tracking.enabled：トラッキング評価を有効にします。tracking_threshold=0.2 です。

マルチ GPU／マルチノード

起動方式： Lightning による管理（単一の python プロセスで、Lightning がワーカーを起動します）。

仕様キー	説明	デフォルト
train.num_gpus	GPU の数	1
train.gpu_ids	GPU デバイスのインデックス	[0]
train.num_nodes	ノードの数	1

• マルチ GPU 戦略：ddp_find_unused_parameters_true（fsdp はサポートされていません）
• sync_batchnorm は常に有効です（True）
• エポックあたりのイテレーション数は、次の式で計算されます：num_frames * num_bev_groups / (num_nodes * num_gpus * batch_size)
• スケーリング： GPU 数を増やすと、有効バッチサイズが大きくなり、エポックあたりのイテレーション数は比例して減少します

マルチノード環境変数（オーケストレーターが設定）：WORLD_SIZE、NODE_RANK、MASTER_ADDR、MASTER_PORT、NUM_GPU_PER_NODE。

ハードウェア

最低 2 GPU、推奨 8 GPU です。GPU あたり 40GB 以上（A100 を推奨）の VRAM が必要です。マルチカメラの時間的モデルはメモリを大量に消費します。実用的な学習には bf16 が必要です。マルチ GPU を強く推奨します。インスタンスバンクは時間的推論に多くのメモリを必要とします。

エラーのパターン

dataset_convert が必要：アノテーションの pickle ファイルと anchor_init.npy を生成するため、最初に dataset_convert を実行する必要があります。

アンカーファイルが見つからない：model.head.instance_bank.anchor に、dataset_convert の結果に含まれる anchor_init.npy のパスを設定してください。

時間的処理による OOM：時間的学習中にメモリ不足になった場合は、dataset.num_frames または dataset.batch_size を減らしてください。

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

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

TAO Core の sparse4d.config.json からの推論マッピング：

アクション	Spec フィールド	推論関数	意味
dataset_convert	results_dir	output_dir	現在のジョブの結果ディレクトリ
evaluate	encryption_key	key	暗号化キー
evaluate	evaluate.checkpoint	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	results_dir	output_dir	現在のジョブの結果ディレクトリ
quantize	encryption_key	key	暗号化キー
quantize	quantize.model_path	parent_model	親ジョブの結果フォルダーから推論されたモデルファイル
quantize	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	encryption_key	key	暗号化キー
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 に戻したり、チェックポイントのパスを推測するように生成されたランナースクリプトを修正したりしないでください。