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、默认值、最小值/最大值边界、枚举、选项权重、数学条件、依赖项和常用参数。不要假设运行时存在 ~/tao-core；维护者会在打包技能库前重新生成架构/模板。

训练操作策略

此模型在模型层级已启用 AutoML。处理任何训练阶段请求前，先读取 references/skill_info.yaml，并根据明确指定的 automl_policy 值或用户的工作流请求解析本次运行的策略。将“turn off AutoML”“disable AutoML”“no HPO”或“plain training”等表述视为仅对本次运行设置 automl_policy: off；否则默认为 auto。当 automl_policy: auto、automl_enabled: true，且已打包 schemas/train.schema.json 和 references/spec_template_train.yaml 时，默认使用此模型的 skill_dir 将训练操作路由到 tao-skill-bank:tao-run-automl。保留工作流/应用对数据集、规格、输出目录、GPU/平台设置、父检查点和 automl_policy 的覆盖。仅当 automl_policy: off 或缺少打包的训练架构/模板时，才直接进行模型训练；若缺少架构，请说明此模型已启用 AutoML，但在生成架构前无法运行 AutoML。

非训练操作（如 evaluate、inference、export）和部署流程仍由此模型技能处理。每次运行的 automl_policy 覆盖不会更改模型元数据。

训练要求

• 数据集类型： nvpanoptix3d
• 格式： front3d、matterport
• 监控指标： kpi

各操作的数据集要求

操作	规格键	来源	文件	列表？
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		否

常见规格覆盖项

数据源覆盖项对每项操作都必须提供 — Agent 必须根据上方的「每项操作的数据集要求」表构造数据源路径，并将其加入 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 路径配置 val/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 启动工作进程）。

Spec Key	描述	默认值
train.num_gpus	GPU 数量	1
train.gpu_ids	GPU 设备索引	[0]
train.num_nodes	节点数量	1
train.distributed_strategy	仅支持 ddp	ddp

• NVPanoptix3D 不支持 fsdp（代码仅处理 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 以上显存（建议使用 A100）。3D 重建的显存占用非常高。建议使用 fp16。默认启用 activation_checkpoint。多节点场景使用 FSDP。模型层已启用 AutoML；通过 AutoML 路由 train 时，请保留这些 GPU/显存要求。

错误模式

缺少视锥掩码：确保数据集目录中存在 meta/frustum_mask.npz。

下采样因子不匹配：Matterport3D 使用 downsample_factor=2，Front3D / synthetic 数据集使用 1。

3D 占用网格 OOM：如果 3D 重建期间 GPU 显存不足，请减小 frustum_dims 或 grid_dimensions。

Spec 参数 / 父模型推断

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

TAO Core nvpanoptix3d.config.json 中的推断映射：

操作	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	create_onnx_file_2d
export	export.onnx_file_3d	create_onnx_file_3d	create_onnx_file_3d
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，也不要修改生成的运行器脚本来猜测检查点路径。