tao-train-pointpillars

PointPillars

LiDAR 点群から 3D 物体検出を行う PointPillars です。柱ベースの表現を使って点群を疑似画像にエンコードし、2D 検出を適用します。自動運転やロボット工学で使用されます。

通常はスクラッチからトレーニングします。再開するには、train.resume_training_checkpoint_path を指定してください。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）については、最初に references/tao-deploy-pointpillars.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 の有効化は、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 経由で実行します。データセット、spec、出力ディレクトリ、GPU／プラットフォームの設定、親チェックポイント、automl_policy に関するワークフローやアプリケーションによるオーバーライドは維持してください。automl_policy: off の場合、またはパッケージ化された train スキーマ／テンプレートがない場合にのみ、モデルの直接トレーニングを使用してください。スキーマがない場合は、AutoML は有効ですが、スキーマが生成されるまではこのモデルで実行できないことを報告してください。

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

トレーニング要件

• データセットタイプ： pointpillars
• 形式： デフォルト
• モニタリング指標： loss

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

アクション	Spec キー	ソース	ファイル	リスト？
dataset_convert	dataset.data_path	id		いいえ
evaluate	dataset.data_path	train_datasets		いいえ
evaluate	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	いいえ
export	dataset.data_path	train_datasets		いいえ
export	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	いいえ
inference	dataset.data_path	train_datasets		いいえ
inference	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	いいえ
prune	dataset.data_path	train_datasets		いいえ
prune	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	いいえ
retrain	dataset.data_path	train_datasets		いいえ
retrain	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	いいえ
train	dataset.data_path	train_datasets		いいえ
train	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	いいえ

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

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

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

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

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

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

{
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

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

{
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

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

{
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

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

{
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

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

{
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

評価データセット

任意です。検証データ（val.tar.gz）はトレーニングデータとは別です。mAP の評価に使用します。

重要なパラメーター

• train.num_epochs：デフォルトは80です（他の TAO モデルより大幅に多い値です）。PointPillars で3D検出の収束を得るには、より多くのエポックが必要です。
• train.lr：学習率です。デフォルトは0.003です（adam_onecycle スケジューラー）。
• dataset.class_names：3Dオブジェクトクラスのリストです。デフォルトは7クラス（KITTI 形式）です。データセットに合わせて変更してください。
• dataset.data_path：点群データディレクトリへのパスです。
• dataset.data_info_path：dataset_convert ステップで生成されたデータ情報ファイルへのパスです。
• dataset.point_cloud_range：対象となる点群の空間範囲です。センサーの構成に合わせる必要があります。
• model.dense_head.anchor_generator_config：クラスごとのアンカー設定です。オブジェクトのサイズと点群の範囲に合わせて調整する必要があります。

マルチ GPU／マルチノード

起動方法： torchrun（LIGHTNING_EXCLUDED_NETWORK）。PyTorch ネイティブのDistributedDataParallelを使用します（Lightning Trainer は使用しません）。

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

• CUDA_VISIBLE_DEVICESはTAO_VISIBLE_DEVICESから明示的に設定されます
• nn.parallel.DistributedDataParallelを直接使用します（Lightning の strategy は使用しません）
• RANKが未設定の場合、NODE_RANKがRANKにコピーされます

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

変数	用途
WORLD_SIZE	ノード数
NODE_RANK	このノードのランク
MASTER_ADDR	ランク0のノードの IP
MASTER_PORT	ランク0のポート（デフォルトは29500）
NUM_GPU_PER_NODE	ノードあたりの GPU 数

ハードウェア

最低1 GPU、推奨4 GPUです。各 GPU に16GB以上（V100 または A100）の VRAM が必要です。PointPillars は3D検出において比較的効率的です。主なボトルネックは、大規模な点群データセットのデータ I/O です。

エラーパターン

dataset_convert が必要です：以前に実行した dataset_convert ジョブでdata_info_pathが設定されていない場合、トレーニングは失敗します。必ず先に変換を実行してください。

点群の範囲の不一致：point_cloud_rangeが実際のセンサーデータの範囲と一致しない場合、検出結果が不良になるか、空になります。

エポック番号：PointPillars のチェックポイントのエポック番号は、status.json に報告されるエポック数と1つずれる場合があります。

Spec Param / 親モデルの推論

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

TAO Core pointpillars.config.json の推論マッピング：

アクション	Spec フィールド	推論関数	意味
dataset_convert	results_dir	output_dir	現在のジョブの結果ディレクトリ
evaluate	evaluate.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
evaluate	key	key	暗号化キー
evaluate	results_dir	output_dir	現在のジョブの結果ディレクトリ
export	export.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
export	export.onnx_file	create_onnx_file	出力 ONNX パス
export	export.save_engine	create_engine_file	出力 TensorRT エンジンパス
export	key	key	暗号化キー
export	results_dir	output_dir	現在のジョブの結果ディレクトリ
gen_trt_engine	gen_trt_engine.onnx_file	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
gen_trt_engine	gen_trt_engine.save_engine	create_engine_file	出力 TensorRT エンジンパス
gen_trt_engine	key	key	暗号化キー
gen_trt_engine	results_dir	output_dir	現在のジョブの結果ディレクトリ
inference	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
inference	inference.trt_engine	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
inference	key	key	暗号化キー
inference	results_dir	output_dir	現在のジョブの結果ディレクトリ
prune	key	key	暗号化キー
prune	prune.model	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
prune	results_dir	output_dir	現在のジョブの結果ディレクトリ
retrain	key	key	暗号化キー
retrain	results_dir	output_dir	現在のジョブの結果ディレクトリ
retrain	train.pruned_model_path	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
train	key	key	暗号化キー
train	model.pretrained_model_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 に戻したり、チェックポイントパスを推測するために生成されたランナースクリプトを修正したりしないでください。

デプロイ

• tao-deploy-pointpillars — TAO Deploy を使用した TensorRT エンジン生成、TensorRT 評価、TensorRT 推論の PointPillars デプロイワークフロー。