tao-train-nvpanoptix3d

NVPanoptix3D

NVPanoptix3D は、ポーズ付き RGB 画像からパノプティック 3D シーンを再構築します。占有状態の補完を行いながら、3D パノプティックセグメンテーション（セマンティック、インスタンス、パノプティックマスク）を生成します。VGGT バックボーン、Mask2Former スタイルのヘッド、3D フラスタム再構築に基づいて構築されています。

2D および 3D のステージチェックポイントを使用します。段階的な初期化には、train.checkpoint_2d と train.checkpoint_3d を設定してください。

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 オーバーライドによって、モデルのメタデータが変わることはありません。

トレーニング要件

• データセットの種類： nvpanoptix3d
• 形式： front3d、matterport
• モニタリング指標： kpi

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

アクション	Spec キー	ソース	ファイル	リスト？
evaluate	dataset.frustum_mask_path	eval_dataset	meta/frustum_mask.npz	いいえ
evaluate	dataset.label_map	eval_dataset	meta/colormap.json	いいえ
evaluate	dataset.val.json_path	eval_dataset	meta/val.json	いいえ
evaluate	dataset.val.base_dir	eval_dataset		いいえ
evaluate	dataset.test.json_path	inference_dataset	meta/test.json	いいえ
evaluate	dataset.test.base_dir	inference_dataset		いいえ
inference	dataset.frustum_mask_path	inference_dataset	meta/frustum_mask.npz	いいえ
inference	dataset.label_map	inference_dataset	meta/colormap.json	いいえ
inference	inference.images_dir	inference_dataset	images.tar.gz	いいえ
train	dataset.frustum_mask_path	train_datasets	meta/frustum_mask.npz	いいえ
train	dataset.label_map	train_datasets	meta/colormap.json	いいえ
train	dataset.train.json_path	train_datasets	meta/train.json	いいえ
train	dataset.train.base_dir	train_datasets		いいえ
train	dataset.val.json_path	eval_dataset	meta/val.json	いいえ
train	dataset.val.base_dir	eval_dataset		いいえ
train	dataset.test.json_path	inference_dataset	meta/test.json	いいえ
train	dataset.test.base_dir	inference_dataset		いいえ

一般的な仕様のオーバーライド

データソースのオーバーライドはすべてのアクションで必須です。エージェントは、上記のアクションごとのデータセット要件テーブルからデータソースパスを作成し、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.enable_3d": True,
    "model.sem_seg_head.num_classes": 13,
    "dataset.frustum_mask_path": f"{S3_TRAIN}/meta/frustum_mask.npz",
    "dataset.label_map": f"{S3_TRAIN}/meta/colormap.json",
    "dataset.train.json_path": f"{S3_TRAIN}/meta/train.json",
    "dataset.train.base_dir": f"{S3_TRAIN}",
    "dataset.val.json_path": f"{S3_EVAL}/meta/val.json",
    "dataset.val.base_dir": f"{S3_EVAL}",
    "dataset.test.json_path": f"{S3_EVAL}/meta/test.json",
    "dataset.test.base_dir": f"{S3_EVAL}",
}

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

{
    "dataset.enable_3d": True,
    "dataset.frustum_mask_path": f"{S3_EVAL}/meta/frustum_mask.npz",
    "dataset.label_map": f"{S3_EVAL}/meta/colormap.json",
    "dataset.val.json_path": f"{S3_EVAL}/meta/val.json",
    "dataset.val.base_dir": f"{S3_EVAL}",
    "dataset.test.json_path": f"{S3_EVAL}/meta/test.json",
    "dataset.test.base_dir": f"{S3_EVAL}",
}

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

{
    "dataset.enable_3d": True,
    "dataset.frustum_mask_path": f"{S3_EVAL}/meta/frustum_mask.npz",
    "dataset.label_map": f"{S3_EVAL}/meta/colormap.json",
    "inference.images_dir": f"{S3_EVAL}/images.tar.gz",
}

評価用データセット

任意です。検証用／テスト用の分割は、dataset.val と dataset.test のパスで設定します。

重要なパラメーター

• model.sem_seg_head.num_classes：セマンティッククラスの数。デフォルトは 13 です。
• model.mode：予測モード。選択肢：panoptic、instance、semantic。デフォルトは panoptic です。
• model.backbone_type：バックボーン。デフォルトは vggt です（スキーマで唯一の選択肢）。
• model.mask_former.num_object_queries：オブジェクトクエリの数。デフォルトは 100 です。
• model.mask_former.dec_layers：デコーダーレイヤー数。デフォルトは 10 です。
• model.frustum3d.truncation：3D フラスタムの切り捨て値。デフォルトは 3 です。
• model.frustum3d.panoptic_weight：パノプティック損失の重み。デフォルトは 25 です。
• model.frustum3d.completion_weights：補完損失の重み。デフォルトは [50, 25, 10] です。
• dataset.name：データセット名。選択肢：front3d、matterport、synthetic_hospital、synthetic_warehouse。
• dataset.downsample_factor：画像のダウンサンプリング係数。デフォルトは 1（Front3D）、2（Matterport）です。
• dataset.target_size：目標画像サイズ。デフォルトは [320, 240] です。
• dataset.depth_min：最小深度。デフォルトは 0.4 メートルです。
• dataset.depth_max：最大深度。デフォルトは 6.0 メートルです。
• train.lr：学習率。デフォルトは 2e-4 です。backbone_multiplier=0.1 です。
• train.lr_scheduler：選択肢：MultiStep、Warmuppoly。マイルストーンは [88, 96] です。
• train.precision：選択肢：fp16、fp32。デフォルトは fp16 です。
• train.distributed_strategy：選択肢：ddp、fsdp。デフォルトでは activation_checkpoint=True です。
• train.clip_grad_norm：勾配クリッピングのノルム。デフォルトは 0.1 です。
• export.onnx_file_2d：2D モデルコンポーネントの ONNX パス。
• export.onnx_file_3d：3D モデルコンポーネントの ONNX パス。
• export.max_voxels：エンジン入力の最大ボクセル数。デフォルトは 700000 です。
• inference.mode：選択肢：semantic、instance、panoptic。

マルチ GPU／マルチノード

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

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

• fsdp は NVPanoptix3D ではサポートされていません（コードは ddp のみを処理します）
• アクティベーションチェックポイントを有効にした ddp（デフォルトで有効）：find_unused_parameters=False
• アクティベーションチェックポイントを無効にした ddp：find_unused_parameters=True
• 3D を有効にした FAN バックボーンでは sync_batchnorm が自動的に有効になります

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

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

• 2D と 3D の ONNX モデルを個別にエクスポートします（onnx_file_2d、onnx_file_3d）
• TRT データ型：FP32、FP16 のみ
• max_voxels：700000（エンジン入力テンソルの上限）

ハードウェア

最低 2 GPU、推奨 4 GPU です。GPU ごとに 40GB 以上の VRAM が必要です（A100 を推奨）。3D 再構成は非常に多くのメモリを使用します。fp16 を推奨します。activation_checkpoint はデフォルトで有効です。マルチノードでは FSDP を使用します。AutoML はモデルレイヤーで有効です。train を AutoML 経由で振り分ける際は、この GPU／VRAM に関する指針を維持してください。

エラーパターン

フラスタムマスクが見つからない場合：データセットディレクトリに meta/frustum_mask.npz が存在することを確認してください。

ダウンサンプリング係数の不一致：Matterport3D では downsample_factor=2、Front3D／合成データセットでは 1 を使用してください。

3D 占有データによる OOM：3D 再構成中に GPU メモリが不足する場合は、frustum_dims または grid_dimensions を小さくしてください。

Spec Param / 親モデルの推論

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

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

アクション	Spec フィールド	推論関数	意味
評価	encryption_key	key	暗号化キー
評価	evaluate.checkpoint	parent_model	親ジョブの結果フォルダーから推論したモデルファイル
評価	results_dir	output_dir	現在のジョブの結果ディレクトリ
エクスポート	encryption_key	key	暗号化キー
エクスポート	export.checkpoint	parent_model	親ジョブの結果フォルダーから推論したモデルファイル
エクスポート	export.onnx_file_2d	create_onnx_file_2d	create_onnx_file_2d
エクスポート	export.onnx_file_3d	create_onnx_file_3d	create_onnx_file_3d
エクスポート	results_dir	output_dir	現在のジョブの結果ディレクトリ
推論	encryption_key	key	暗号化キー
推論	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推論したモデルファイル
推論	results_dir	output_dir	現在のジョブの結果ディレクトリ
トレーニング	encryption_key	key	暗号化キー
トレーニング	results_dir	output_dir	現在のジョブの結果ディレクトリ
トレーニング	train.checkpoint_2d	parent_model_or_ptm	利用可能な場合は親モデル、そうでなければ PTM
トレーニング	train.checkpoint_3d	ptm	事前学習済みモデル
トレーニング	train.resume_training_checkpoint_path	resume_model	現在のジョブの結果フォルダーから推論したモデルファイル

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