tao-train-pointpillars

PointPillars

用于基于 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 开头。

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。使用打包的 train 架构来获取 automl_default_parameters、automl_disabled_parameters、默认值、最小值/最大值范围、枚举、选项权重、数学条件、依赖项和常用参数。不要期望运行时存在 ~/tao-core；维护者会在打包技能库之前重新生成架构/模板。

训练操作策略

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

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

训练要求

• 数据集类型： pointpillars
• 格式： default
• 监控指标： loss

各操作的数据集要求

操作	规范键	来源	文件	列表？
dataset_convert	dataset.data_path	id		否
evaluate	dataset.data_path	train_datasets		否
evaluate	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	否
export	dataset.data_path	train_datasets		否
export	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	否
inference	dataset.data_path	train_datasets		否
inference	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	否
prune	dataset.data_path	train_datasets		否
prune	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	否
retrain	dataset.data_path	train_datasets		否
retrain	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	否
train	dataset.data_path	train_datasets		否
train	dataset.data_info_path	train_datasets	/results/{dataset_convert_job_id}/data_info/	否

常见的规格覆盖项

每个操作都必须覆盖数据源 — Agent 必须根据上方的“各操作数据集要求”表构建数据源路径，并将其包含在 spec_overrides 中。

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

train（必需的数据源）：

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

evaluate（必需的数据源）：

{
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

export（必需的数据源）：

{
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

inference（必需的数据源）：

{
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

prune（必需的数据源）：

{
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

retrain（必需的数据源）：

{
    "dataset.data_path": f"{S3_TRAIN}",
    "dataset.data_info_path": f"{S3_TRAIN}//results/{dataset_convert_job_id}/data_info/",
}

评估数据集

可选。验证数据（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

• 会根据 TAO_VISIBLE_DEVICES 显式设置 CUDA_VISIBLE_DEVICES
• 直接使用 nn.parallel.DistributedDataParallel（不使用 Lightning strategy）
• 如果未设置 RANK，则将 NODE_RANK 复制到 RANK

多节点环境变量（由编排器设置）：

Variable	用途
WORLD_SIZE	节点数量
NODE_RANK	当前节点的 rank
MASTER_ADDR	rank-0 节点 IP
MASTER_PORT	rank-0 端口（默认值为 29500）
NUM_GPU_PER_NODE	每个节点的 GPU 数量

硬件

最低需要 1 张 GPU，建议使用 4 张 GPU。每张 GPU 需要 16 GB 以上显存（V100 或 A100）。PointPillars 在 3D 检测任务中效率较高。主要瓶颈是大型点云数据集的数据 I/O。

错误模式

需要先运行 dataset_convert：如果 data_info_path 未通过之前的 dataset_convert 作业填充，训练将会失败。请务必先运行 convert。

点云范围不匹配：如果 point_cloud_range 与实际传感器数据范围不匹配，检测结果会很差或为空。

训练轮次编号：PointPillars 检查点中的训练轮次编号可能会比 status.json 报告的轮次偏移 1。

规格参数 / 父模型推断

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

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

操作	规格字段	推断函数	含义
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	当前作业结果目录
gen_trt_engine	gen_trt_engine.onnx_file	parent_model	根据父作业结果文件夹推断出的模型文件
gen_trt_engine	gen_trt_engine.save_engine	create_engine_file	输出 TensorRT 引擎路径
gen_trt_engine	key	key	加密密钥
gen_trt_engine	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 — 使用 TAO Deploy 生成 TensorRT 引擎、执行 TensorRT 评估和 TensorRT 推理的 PointPillars 部署工作流。