tao-train-pointpillars

PointPillars

单独安装？ 如果此会话并非由 TAO skill bank 插件初始化，请先运行 tao-setup 技能（主机预检、凭据、跨技能发现）。

PointPillars 用于基于 LiDAR 点云进行 3D 目标检测。它通过基于柱体的表示将点云编码为伪图像，然后执行 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。

打包的 PyTorch PointPillars CLI 支持 dataset_convert、train、evaluate、inference、export 和 prune。它不提供父模型的 gen_trt_engine 操作；TensorRT 引擎只能通过部署流程生成。它也不提供单独的 retrain 子命令。使用剪枝后的模型重新训练时，请运行 pointpillars train -e ... 并填入 train.pruned_model_path。

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；维护者会在打包 skill bank 前重新生成架构和模板。

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 时，默认通过 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
• AutoML 训练指标： loss（最小化）。这是 train 操作按轮次输出的 KPI，也是 AutoML 必须提取用于试验排名的指标。
• 独立评估指标： evaluate 操作会输出召回率 KPI 以及特定于数据集的检测指标。对于通用点云数据集，请验证 bev mAP 和 3d mAP；不要用评估 mAP 替代 AutoML 输出的训练 loss。

各操作的数据集要求

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

常见 Spec 覆盖项

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

DATA_ROOT = "s3://bucket/data/pointpillars"
DATA_INFO = "/results/{dataset_convert_job_id}/results_dir/data_info"
CHECKPOINT = "/results/{train_job_id}/results_dir/checkpoint_epoch_1.pth"
PRUNED_MODEL = "/results/{prune_job_id}/results_dir/pruned_0.1.tlt"

运行 dataset_convert 前，原始 PointPillars 数据根目录必须是已解压的文件夹，其中包含匹配的 train/lidar、train/label、val/lidar 和 val/label 子文件夹。如果源数据集打包为单独的 train/val 压缩包，请将两者解压到同一个挂载的数据根目录下，并将 dataset.data_path 指向该根目录。

train（必需的数据源）：

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
}

resume train（必需的检查点）：

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "train.resume_training_checkpoint_path": CHECKPOINT,
}

evaluate（必需的数据源）：

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "evaluate.checkpoint": CHECKPOINT,
}

export（必需的数据源）：

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "export.checkpoint": CHECKPOINT,
    "export.onnx_file": "/results/{export_job_id}/results_dir/pointpillars.onnx",
}

inference（必需的数据源）：

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "inference.checkpoint": CHECKPOINT,
}

prune（必需的数据源）：

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "prune.model": CHECKPOINT,
}

retrain（必需的数据源）：

{
    "dataset.data_path": DATA_ROOT,
    "dataset.data_info_path": DATA_INFO,
    "train.pruned_model_path": PRUNED_MODEL,
}

对于本地 Docker，DATA_INFO 必须在每个 train/evaluate/export/prune/retrain 容器中可见。请使用来自同一结果根目录的 dataset_convert 任务，或将已转换的 results_dir/data_info 文件夹挂载/复制到当前运行中，并将 dataset.data_info_path 设置为挂载后的容器路径。如果宿主机 scratch 根目录挂载在 /results，且转换产物位于宿主机的 scratch/results/<job_id>/results_dir/data_info 下，那么直接任务的容器路径为 /results/results/<job_id>/results_dir/data_info。除非该文件夹已挂载到当前任务，否则不要复用来自其他运行根目录的 /results/<job_id>/... 路径。

对于 AutoML 训练工作流，请在调用 AutoMLRunner.run 前执行启动预检：在当前运行的 RESULTS_ROOT 下创建或生成 dataset_convert 输出，将 dataset.data_info_path 设置为当前运行的容器路径，并从训练容器的视角确认 dbinfos_train.pkl、infos_train.pkl 和 infos_val.pkl 均已存在。如果运行器是从先前的 AutoML 算法克隆或改编而来，请在新的运行根目录中更新转换产物；来自其他结果挂载的过时 CONVERT_JOB_ID 无效。

评估数据集

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

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

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

变量	用途
WORLD_SIZE	节点数量
NODE_RANK	此节点的秩
MASTER_ADDR	秩为 0 的节点 IP
MASTER_PORT	秩为 0 的端口（默认值为 29500）
NUM_GPU_PER_NODE	每个节点的 GPU 数量

硬件

至少需要 1 块 GPU，建议使用 4 块 GPU。每块 GPU 需要 16GB 以上显存（V100 或 A100）。PointPillars 在 3D 检测方面相对高效。主要瓶颈是大型点云数据集的数据 I/O。

错误模式

必须先运行 dataset_convert：如果 dataset.data_info_path 未填入先前 dataset_convert 作业生成的路径，训练将失败。务必先运行 convert，并确认训练容器能在 dataset.data_info_path 下访问 dbinfos_train.pkl 和 infos_train.pkl。本地 Docker 中常见的失败原因是路径指向了不同结果根目录下的过期 /results/<old_job_id>/...。

点云范围不匹配：如果 point_cloud_range 与实际传感器数据范围不匹配，检测效果会很差，甚至没有检测结果。

Epoch 编号：PointPillars 检查点的 epoch 编号可能比 status.json 报告的 epoch 编号偏移 1。

检查点选择：PointPillars 训练会生成类似 checkpoint_epoch_1.pth 的检查点。进行评估、推理、导出、剪枝和恢复训练时，请通过模型/作业检查点解析器选择目标检查点，并将该确切文件传给 evaluate.checkpoint、inference.checkpoint、export.checkpoint、prune.model 或 train.resume_training_checkpoint_path。不要猜测并选取最新的 model.pth；此模型不使用该文件名。

剪枝/重新训练密钥：PointPillars 剪枝会生成经过加密的 .tlt 文件。请在剪枝和重新训练配置中保留非空的 key；随附模板使用 TAO 默认值 tlt_encode。如果省略 key 或将其设为 null，工具包仍可能以容器成功代码退出，但日志中会记录密码错误，并生成空的 pruned_0.1.tlt。重新训练前，务必确认剪枝后的模型文件非空。

状态文件很重要：某些 PointPillars 操作失败后，入口脚本页脚仍可能显示 Execution status: PASS，且 Docker 退出代码为 0。将操作标记为通过前，请检查 results_dir/status.json 和预期文件。

本地 results_dir 配置：对于直接使用本地 Docker 的配置，请同时设置顶层 results_dir 和任何特定操作的 *.results_dir 字段。如果只设置了 evaluate.results_dir，而顶层字段留空，evaluate 可能会尝试写入 /opt/nvidia/eval，随后仍打印通用的 PASS 页脚。除非预期结果目录和状态/文件均存在，否则请将此操作视为失败。

Spec 参数 / 父模型推断

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

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

操作	Spec 字段	推断函数	含义
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	当前任务的结果目录
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