tao-train-pointpillars

PointPillars

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

LiDAR 点群から 3D オブジェクトを検出するための PointPillars です。ピラー形式の表現を使って点群を疑似画像にエンコードし、その後 2D 検出を適用します。自動運転やロボティクスで使用されます。

通常はスクラッチから学習します。学習を再開するには、train.resume_training_checkpoint_path を指定してください。

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

パッケージ化された PyTorch PointPillars CLI は、dataset_convert、train、evaluate、inference、export、prune をサポートしています。親モデルの gen_trt_engine アクションは公開していません。TensorRT エンジンの生成はデプロイ専用です。また、独立した retrain サブコマンドも公開していません。枝刈り済みモデルから再学習するには、train.pruned_model_path を設定して pointpillars train -e ... を使用します。

データクラススキーマ

生成された 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 が有効になっています。学習段階のリクエストを処理する前に、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 オーバーライドは、モデルのメタデータを変更しません。

学習要件

• データセットの種類： pointpillars
• 形式： デフォルト
• AutoML の学習メトリクス： loss（最小化）。これは train アクションがエポックごとに出力する KPI であり、AutoML が試行の順位付けのために抽出する必要があるメトリクスです。
• 単独評価メトリクス： evaluate アクションは、再現率 KPI とデータセット固有の検出メトリクスを出力します。一般的な点群データセットでは、bev mAP と 3d mAP を確認してください。評価時の mAP を、AutoML が出力する学習時の loss の代わりに使用しないでください。

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

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

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

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

DATA_ROOT = "s3://bucket/data/pointpillars"
DATA_INFO = "/results/{dataset_convert_job_id}/results_dir/data_info"
CHECKPOINT = "/results/{train_job_id}/results_dir/checkpoint_epoch_1.pth"
PRUNED_MODEL = "/results/{prune_job_id}/results_dir/pruned_0.1.tlt"

生の PointPillars データのルートは、dataset_convert の実行前に、train/lidar、train/label、val/lidar、val/label の各サブフォルダーを含む展開済みフォルダーである必要があります。元のデータセットが train/val 別々のアーカイブとしてパッケージ化されている場合は、両方を同じマウント済みデータルートの下に展開し、dataset.data_path をそのルートに設定してください。

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

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
}

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

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "train.resume_training_checkpoint_path": CHECKPOINT,
}

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

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "evaluate.checkpoint": CHECKPOINT,
}

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

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "export.checkpoint": CHECKPOINT,
    "export.onnx_file": "/results/{export_job_id}/results_dir/pointpillars.onnx",
}

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

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "inference.checkpoint": CHECKPOINT,
}

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

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "prune.model": CHECKPOINT,
}

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

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "train.pruned_model_path": PRUNED_MODEL,
}

ローカル Docker では、DATA_INFO をすべての train/evaluate/export/prune/retrain コンテナーから参照できるようにする必要があります。同じ results ルートの dataset_convert ジョブを使用するか、変換済みの results_dir/data_info フォルダーを現在の実行環境にマウントまたはコピーし、dataset.data_info_path をそのマウント先のコンテナーパスに設定してください。ホストのスクラッチルートが /results にマウントされ、変換アーティファクトがホスト上の scratch/results/<job_id>/results_dir/data_info にある場合、直接ジョブのコンテナーパスは /results/results/<job_id>/results_dir/data_info です。そのフォルダーが現在のジョブにマウントされていない限り、別の実行ルートの /results/<job_id>/... パスを再利用しないでください。

AutoML の train ワークフローでは、AutoMLRunner.run を呼び出す前に、起動前の確認としてこの処理を行います。現在の実行環境の RESULTS_ROOT に dataset_convert の出力を作成または配置し、dataset.data_info_path を現在の実行環境のコンテナーパスに設定して、train コンテナーから dbinfos_train.pkl、infos_train.pkl、infos_val.pkl が確認できることを検証してください。以前の AutoML アルゴリズムからランナーを複製または適応した場合は、新しい実行ルート内の変換アーティファクトを更新してください。別の results マウントを参照する古い CONVERT_JOB_ID は無効です。

評価用データセット

任意です。検証データ（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 Key	説明	デフォルト
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 ジョブで dataset.data_info_path が設定されていないと、トレーニングは失敗します。必ず最初に変換を実行し、トレーニングコンテナーから dataset.data_info_path 配下の dbinfos_train.pkl と infos_train.pkl を参照できることを確認してください。ローカル Docker でよくある失敗の原因は、別の結果ルートからの古い /results/<old_job_id>/... パスです。

点群範囲の不一致：point_cloud_range が実際のセンサーデータの範囲と一致しない場合、検出結果の精度が低下したり、検出できなくなったりします。

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

チェックポイントの選択：PointPillars のトレーニングでは、checkpoint_epoch_1.pth のような名前のチェックポイントが出力されます。評価、推論、エクスポート、プルーニング、再開では、モデル／ジョブのチェックポイントリゾルバーを通じて目的のチェックポイントを選択し、そのファイルを evaluate.checkpoint、inference.checkpoint、export.checkpoint、prune.model、または train.resume_training_checkpoint_path に指定してください。最新の model.pth を選ぶのは避けてください。このモデルではそのファイル名は使用されません。

プルーニング／再トレーニングのキー：PointPillars のプルーニングでは、暗号化された .tlt アーティファクトが出力されます。プルーニングと再トレーニングの仕様では、空でない key を指定してください。パッケージ化されたテンプレートでは、TAO のデフォルトである tlt_encode が使われます。key を省略するか null にすると、ツールキットはコンテナーの成功コードで終了していても、パスフレーズエラーをログに記録し、空の pruned_0.1.tlt を作成することがあります。再トレーニングに使用する前に、プルーニング済みモデルのファイルサイズが 0 ではないことを必ず確認してください。

ステータスファイルは重要です：PointPillars の一部の失敗では、エントリーポイントのフッターに Execution status: PASS と表示され、Docker の終了コードが 0 になる場合があります。アクションを成功と判断する前に、results_dir/status.json と期待されるアーティファクトを確認してください。

ローカルの results_dir の設定：ローカル Docker に直接指定する仕様では、トップレベルの results_dir と、各アクション固有の *.results_dir フィールドを両方設定してください。evaluate.results_dir だけを設定し、トップレベルのフィールドを空欄にすると、評価結果が /opt/nvidia/eval に書き込まれ、その後、汎用の PASS フッターが表示される場合があります。期待される結果ディレクトリとステータス／アーティファクトファイルが存在しない場合は、アクションを失敗として扱ってください。

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

モデル固有の推論マッピングは、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	現在のジョブの結果ディレクトリ
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