tao-train-nvpanoptix3d

NVPanoptix3D

スタンドアロンでインストールする場合 このセッションが TAO skill bank プラグインによって初期化されていない場合は、最初に tao-setup スキルを実行してください（ホストの事前確認、認証情報、スキル間の検出）。

NVPanoptix3D は、姿勢推定済みの RGB 画像からパノプティック 3D シーンを再構築します。占有状態の補完とともに、3D パノプティックセグメンテーション（セマンティックマスク、インスタンスマスク、パノプティックマスク）を生成します。VGGT バックボーンと Mask2Former 方式のヘッド、および 3D フラスタム再構成に基づいています。

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

クイックスタート（docker run）

Docker ネイティブで起動します。ホストに TAO SDK や Python は必要ありません。ローカルの Docker／プラットフォームスキルに、より厳格な環境固有のコマンド（非 root UID のマッピング、 キャッシュのリダイレクト、リモートデーモンなど）がある場合は、そちらを使用してください。

TAO_PYT_IMAGE_DEFAULT=nvcr.io/nvidia/tao/tao-toolkit:7.3.0-pyt  # versions-key: images.tao_toolkit.pyt
TAO_PYT_IMAGE="${TAO_PYT_IMAGE:-$TAO_PYT_IMAGE_DEFAULT}"
RUN_ROOT="${RUN_ROOT:-$PWD}"
DOCKER_COMMON=(
  --rm --gpus all --shm-size=8g
  --shm-size=8g
  --ulimit memlock=-1
  --ulimit stack=67108864
  -v "$RUN_ROOT/data:/data:ro"
  -v "$RUN_ROOT/specs:/specs:ro"
  -v "$RUN_ROOT/results:/results"
)

トレーニング：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  python -m nvidia_tao_pytorch.cv.nvpanoptix3d.entrypoint.nvpanoptix3d train -e /specs/train.yaml

評価：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  python -m nvidia_tao_pytorch.cv.nvpanoptix3d.entrypoint.nvpanoptix3d evaluate -e /specs/evaluate.yaml

推論：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  python -m nvidia_tao_pytorch.cv.nvpanoptix3d.entrypoint.nvpanoptix3d inference -e /specs/inference.yaml

エクスポート：

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  python -m nvidia_tao_pytorch.cv.nvpanoptix3d.entrypoint.nvpanoptix3d export -e /specs/export.yaml

各アクションには -e で仕様を指定します。results_dir は仕様内で設定するか、コマンドラインで上書きします。仕様が参照する事前学習済み重みのディレクトリをマウントし、すべてのアクションでコンテナ内のパスに一貫性を持たせてください。

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 が有効になっています。トレーニング段階のリクエストに対応する前に、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 は有効だが、スキーマが生成されるまでこのモデルでは実行できないことを報告してください。

AutoML では、最適化指標として PRQ を使用し、direction=maximize にしてください。 NVPanoptix3D の train 検証ジョブと evaluate ジョブは、どちらも status.json に PRQ、RSQ、RRQ を出力するため、ベースライン、各推奨設定、および 最終的な最良チェックポイントの評価すべてで、一貫して PRQ を使用してください。 モデル内部のチェックポイント処理では train.optim.monitor_name: train_loss を使用できますが、 最小構成のジョブでは数値の train_loss が TAO ステータスチャネルに確実にエクスポートされるとは限りません。AutoML の選択指標には使用しないでください。マルチフィデリティの昇格では、中断後のエポックから新しい PRQ を取得する必要があります。また、明示的なエポック／ステップのチェックポイントから再開し、実際のチェックポイントを生成して、evaluate／inference に合格する必要があります。 evaluate、inference、export、デプロイの各フローなど、train 以外のアクションはこのモデルのスキル内に留めてください。実行ごとの automl_policy 上書きによって、モデルメタデータが変更されることはありません。

トレーニング要件

• データセットの種類: nvpanoptix3d
• 形式: front3d, matterport
• モニタリング指標: PRQ
• AutoML の最適化方向: 最大化
• 検証ステータスと評価ステータスの KPI は PRQ、RSQ、RRQ です。AutoML の選択には PRQ を使用してください。異なるワークフローで、各トライアルについて該当するスカラー値が外部に出力されることが証明され、その代理目的関数の使用について明示的な承認を得ていない限り、train_loss や val_loss は使用しないでください。

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

アクション	Spec Key	ソース	ファイル	リスト化？
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	.jpg/.png の RGB 画像が入ったフラットフォルダー	いいえ
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 オーバーライド

データソースのオーバーライドはすべてのアクションで必須です。エージェントは、上記のアクション別データセット要件の表に基づいてデータソースのパスを構築し、spec_overrides に含める必要があります。 シーンデータを data/images.tar.gz として保存するパッケージ済み S3 フォルダーでは、TAO ローダーが base_dir/data/<scene_id>/... を想定しているため、スキルのメタデータは親の data/ ディレクトリへの展開を要求します。

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,
    "dataset.contiguous_id": 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（必須データソース）：

{
    "evaluate.checkpoint": "<selected train/AutoML checkpoint>",
    "dataset.enable_3d": True,
    "dataset.contiguous_id": 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（必須データソース）：

{
    "inference.checkpoint": "<selected train/AutoML checkpoint>",
    "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": "/path/to/flat_rgb_images",
}

評価データセット

任意です。検証用／テスト用の分割は、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.contiguous_id：ラベルマップのJSONがカテゴリIDに対するtrainId値をすでに提供している場合は、Trueに設定してください。デフォルトのFalseのままにすると、trainIdのないプレースホルダーカテゴリが合成され、メタデータの構築時に失敗することがあります。
• 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：現在の学習コードでサポートされているのはfp32のみです。
• train.distributed_strategy：選択肢：ddp、fsdp。activation_checkpoint=Trueがデフォルトです。
• train.clip_grad_norm：勾配クリッピングのノルムです。デフォルトは0.1です。
• export.onnx_file_2d：2Dモデルコンポーネントの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

• NVPanoptix3Dでは**fsdpはサポートされていません**（コードはddpのみを処理します）
• activation checkpointingありのddp（デフォルトで有効）：find_unused_parameters=False
• activation checkpointingなしのddp：find_unused_parameters=True
• 3Dを有効にしたFANバックボーンでは、sync_batchnormが自動的に有効になります

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

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

• 2D ONNXモデルをexport.onnx_file_2dにエクスポートします。現在のエクスポート用エントリーポイントはexport_2d_modelを呼び出します。export.onnx_file_3dはスキーマに存在しますが、このツールキットのイメージでは生成されません。
• TRTのデータ型：FP32、FP16のみ
• max_voxels：700000（エンジン入力テンソルの上限）

ハードウェア

GPUは最低2基、推奨4基です。各GPUに40GB以上のVRAMが必要です（A100を推奨）。3D再構成は非常にメモリを大量に消費します。train.precision: fp32を使用してください。現在の学習エントリーポイントではfp16が拒否されます。activation_checkpointはデフォルトで有効です。マルチノードにはFSDPを使用してください。モデル層ではAutoMLが有効になっています。学習をAutoML経由で実行する場合も、このGPU／VRAMに関するガイダンスを維持してください。

エラーパターン

PyTorch イメージでの nvpanoptix3d: not found：パッケージに含まれているモジュールのエントリーポイントコマンドを使用します。 python -m nvidia_tao_pytorch.cv.nvpanoptix3d.entrypoint.nvpanoptix3d <action> -e <spec>。 7.0 の PyTorch イメージには NVPanoptix3D パッケージが含まれていますが、nvpanoptix3d コンソールスクリプトは公開されていません。

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

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

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

fp16 精度が拒否される：スキーマでは fp16 が提示されていますが、現在のトレーニングエントリーポイントは ValueError: Only fp32 precision is supported. を発生させます。トレーニングと再開／再トレーニングには train.precision: fp32 を使用してください。

推論データローダーの長さがゼロ：inference.images_dir は、直下にある .jpg と .png ファイルのみを検索します。S3 のテストアーカイブを展開するとシーンごとのサブディレクトリが作成される場合は、推論を実行する前に、実際の RGB 画像を含むフラットなフォルダーを作成するか、そのフォルダーを指定してください。

エクスポート後に 3D ONNX が見つからない：現在のエクスポートエントリーポイントは 2D ONNX エクスポーターのみを呼び出し、export.onnx_file_2d に書き込みます。ツールキットのイメージに 3D エクスポーターが追加されない限り、export.onnx_file_3d を必須にしないでください。

エポックの境界で再開が停止する：1 エポックのスモークランでは、model_epoch_000_step_00020.pth など、エポック終了時のチェックポイントが書き込まれます。train.num_epochs を元の実行より 1 エポックだけ増やして再開すると、チェックポイントを復元した後、新しいエポックのチェックポイントを生成せずに停止することがあります。エポック境界のチェックポイントから実際に再トレーニングされることを検証する場合は、train.num_epochs を元のスモークランより少なくとも 2 エポック増やし、それに応じて train.optim.max_steps も引き上げてください。たとえば、model_epoch_000_step_00020.pth から再開する場合は、モデルを評価、推論、またはエクスポートに渡す前に、model_epoch_001_step_00040.pth などの新しい正確なエポック／ステップのチェックポイントが生成されるよう、train.num_epochs: 3 と十分な max steps を設定する必要があります。

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

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

モデル固有の引き継ぎマッピング：

アクション	Spec フィールド	推論関数	意味
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_2d	create_onnx_file_2d	出力 2D ONNX パス
export	results_dir	output_dir	現在のジョブの結果ディレクトリ
inference	encryption_key	key	暗号化キー
inference	inference.checkpoint	parent_model	親ジョブの結果フォルダーから推論されるモデルファイル
inference	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	encryption_key	key	暗号化キー
train	results_dir	output_dir	現在のジョブの結果ディレクトリ
train	train.checkpoint_2d	parent_model_or_ptm	利用可能な場合は親モデル、それ以外の場合は PTM
train	train.checkpoint_3d	ptm	事前学習済みモデル
train	train.resume_training_checkpoint_path	resume_model	現在のジョブの結果フォルダーから推論されるモデルファイル

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