tao-train-nvpanoptix3d

NVPanoptix3D

单独安装？ 如果本会话并非由 TAO 技能库插件初始化，请先运行 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；维护者需在打包技能库前重新生成架构和模板。

训练操作策略

此模型在模型层启用了 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 时，默认通过 tao-skill-bank:tao-run-automl 执行训练操作，并提供此模型的 skill_dir。保留工作流/应用对数据集、规范、输出目录、GPU/平台设置、父检查点和 automl_policy 的覆盖。仅当 automl_policy: off 或缺少已打包的训练架构/模板时，才直接进行模型训练；如果缺少架构，请说明 AutoML 已启用，但在生成架构之前，此模型无法运行 AutoML。

对于 AutoML，使用 PRQ 作为优化指标，且 direction=maximize。 NVPanoptix3D 的训练验证和评估作业都会在 status.json 中输出 PRQ、RSQ 和 RRQ，因此基准、每项推荐以及最终最佳检查点评估都应统一使用 PRQ。模型内部可能会使用 train.optim.monitor_name: train_loss 进行检查点管理，但精简作业无法可靠地将数值型 train_loss 导出到 TAO 状态通道；请勿将其用作 AutoML 选择指标。多保真度晋级必须在恢复训练的轮次后获取新的 PRQ，并且仍须从明确指定的轮次/步数检查点恢复、生成实际检查点，且通过评估/推理。 evaluate、inference、export 和部署流程等非训练操作仍由此模型技能处理。单次运行的 automl_policy 覆盖不会更改模型元数据。

训练要求

• 数据集类型： nvpanoptix3d
• 格式： front3d、matterport
• 监控指标： PRQ
• AutoML 方向： 最大化
• 验证和评估状态 KPI 为 PRQ、RSQ 和 RRQ。AutoML 选择时使用 PRQ；除非其他工作流证明每次试验都会外部输出该精确标量，并且已明确批准使用代理目标，否则不要使用 train_loss 或 val_loss。

各操作的数据集要求

操作	Spec Key	来源	文件	列表？
评估	dataset.frustum_mask_path	eval_dataset	meta/frustum_mask.npz	否
评估	dataset.label_map	eval_dataset	meta/colormap.json	否
评估	dataset.val.json_path	eval_dataset	meta/val.json	否
评估	dataset.val.base_dir	eval_dataset		否
评估	dataset.test.json_path	inference_dataset	meta/test.json	否
评估	dataset.test.base_dir	inference_dataset		否
推理	dataset.frustum_mask_path	inference_dataset	meta/frustum_mask.npz	否
推理	dataset.label_map	inference_dataset	meta/colormap.json	否
推理	inference.images_dir	inference_dataset	.jpg/.png RGB 图像的平铺文件夹	否
训练	dataset.frustum_mask_path	train_datasets	meta/frustum_mask.npz	否
训练	dataset.label_map	train_datasets	meta/colormap.json	否
训练	dataset.train.json_path	train_datasets	meta/train.json	否
训练	dataset.train.base_dir	train_datasets		否
训练	dataset.val.json_path	eval_dataset	meta/val.json	否
训练	dataset.val.base_dir	eval_dataset		否
训练	dataset.test.json_path	inference_dataset	meta/test.json	否
训练	dataset.test.base_dir	inference_dataset		否

典型 Spec 覆盖项

每个操作都必须覆盖数据源——Agent 必须根据上方的各操作数据集要求表构建数据源路径，并将其包含在 spec_overrides 中。 对于将场景数据存储在 data/images.tar.gz 中的打包 S3 文件夹，技能元数据要求将其解压到父级 data/ 目录，因为 TAO 加载器需要 base_dir/data/<scene_id>/...。

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

训练（必需的数据源）：

{
    "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.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.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
• 不使用时的 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（引擎输入张量限制）

硬件

至少需要 2 块 GPU，建议使用 4 块 GPU。每块 GPU 需要 40GB 以上显存（建议使用 A100）。3D 重建非常消耗显存。请使用 train.precision: fp32；当前训练入口会拒绝 fp16。默认启用 activation_checkpoint。多节点训练使用 FSDP。在模型层启用了 AutoML；通过 AutoML 路由训练时，请保留这些 GPU/显存指南。

错误模式

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。

恢复训练在 epoch 边界处停止：单 epoch 烟雾测试会写入 epoch 结束检查点，例如 model_epoch_000_step_00020.pth。如果将 train.num_epochs 设置为仅比原始运行多一个 epoch，然后恢复训练，可能会恢复检查点后直接停止，而不生成新的 epoch 检查点。验证从 epoch 边界检查点实际重新训练时，请将 train.num_epochs 至少设置为比源烟雾测试多两个 epoch，并相应提高 train.optim.max_steps。例如，从 model_epoch_000_step_00020.pth 恢复时，需要设置 train.num_epochs: 3，并将 max steps 设为足够大，以便生成新的精确 epoch/step 检查点，例如 model_epoch_001_step_00040.pth，之后再将模型交给评估、推理或导出。

Spec 参数 / 父模型推断

特定于模型的推断映射应写在此 MD 文件中，而不是 config.json 中。生成的运行器应读取此部分，并在调用 create_job() 前使用 SDK 辅助函数应用这些映射。这与旧版微服务的 infer_params.py 流程一致。

特定于模型的传递映射：

操作	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	输出 2D ONNX 路径
导出	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 中，也不要修改生成的运行器脚本来猜测检查点路径。