tao-train-bevfusion

BEVFusion

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

BEVFusion 用于多传感器 3D 目标检测。在鸟瞰图（BEV）空间中融合 LiDAR 点云和相机图像。用于自动驾驶，以实现稳健的 3D 感知。

设置 Swin 图像骨干网络的预训练骨干网络路径。

BEVFusion 需要专用的 BEVFusion TAO 容器 nvcr.io/nvidia/tao/tao-toolkit:5.5.0-pyt。共享的 TAO PyTorch 7.x 镜像 不包含 mmdet3d，因此在任何 BEVFusion 操作解析其 spec 之前就会失败。模型技能操作名为 dataset_convert，但 5.5 容器的 CLI 子任务是 bevfusion convert -e <spec>。

数据类架构

生成的 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。保留工作流/应用对数据集、spec、输出目录、GPU/平台设置、父检查点和 automl_policy 的覆盖设置。仅在 automl_policy: off 或缺少已打包的训练架构/模板时，才直接进行模型训练；如果缺少架构/模板，请说明 AutoML 已启用，但在为此模型生成架构之前无法运行。

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

训练要求

• 数据集类型： bevfusion
• 格式： 默认
• 监控指标： AP11

各操作的数据集要求

操作	Spec 键	来源	文件	列表？
dataset_convert	root_dir	id		否
evaluate	dataset.test_dataset	train_datasets	ann_file: results/{dataset_convert_job_id}/kitti_person_infos_val.pkl	否
inference	dataset.root_dir	train_datasets		否
inference	dataset.test_dataset	train_datasets	ann_file: results/{dataset_convert_job_id}/kitti_person_infos_val.pkl	否
train	dataset.train_dataset	train_datasets	ann_file: results/{dataset_convert_job_id}/kitti_person_infos_train.pkl	否
train	dataset.val_dataset	train_datasets	ann_file: results/{dataset_convert_job_id}/kitti_person_infos_val.pkl	否
train	dataset.test_dataset	train_datasets	ann_file: results/{dataset_convert_job_id}/kitti_person_infos_val.pkl	否

典型的规格覆盖项

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

DATA_ROOT = "/path/to/kitti_root"
CONVERTED = DATA_ROOT  # BEVFusion 5.5 writes info pickles into root_dir.
DATA_PREFIX = {"pts": "training/velodyne_reduced", "img": "training/image_2"}

dataset_convert（必需的数据源）：

{
    "root_dir": DATA_ROOT,
    "results_dir": DATA_ROOT,
    "mode": "training",
}

train（必需的数据源）：

{
    "train.num_epochs": 30,
    "train.checkpoint_interval": 10,
    "train.validation_interval": 10,
    "train.num_gpus": 1,
    "dataset.root_dir": DATA_ROOT,
    "dataset.train_dataset": {"ann_file": f"{CONVERTED}/kitti_person_infos_train.pkl", "data_prefix": DATA_PREFIX},
    "dataset.val_dataset": {"ann_file": f"{CONVERTED}/kitti_person_infos_val.pkl", "data_prefix": DATA_PREFIX},
    "dataset.test_dataset": {"ann_file": f"{CONVERTED}/kitti_person_infos_val.pkl", "data_prefix": DATA_PREFIX},
}

evaluate（必需的数据源）：

{
    "dataset.root_dir": DATA_ROOT,
    "dataset.test_dataset": {"ann_file": f"{CONVERTED}/kitti_person_infos_val.pkl", "data_prefix": DATA_PREFIX},
}

inference（必需的数据源）：

{
    "dataset.root_dir": DATA_ROOT,
    "dataset.test_dataset": {"ann_file": f"{CONVERTED}/kitti_person_infos_val.pkl", "data_prefix": DATA_PREFIX},
}

评估数据集

可选。验证集划分通过数据集配置中的 ann_file 设置。

重要参数

• dataset.classes：检测类别列表。默认值为 ["person"]。必须与标注类别一致。
• dataset.type：数据集类型。可选值：KittiPersonDataset、TAO3DSyntheticDataset、TAO3DDataset。
• dataset.root_dir：KITTI 风格数据集的根目录。
• dataset.box_type_3d：3D 框坐标系。可选值：lidar、camera。默认值为 lidar。
• train.optimizer.lr：学习率。默认值为 2e-4（AdamW）。如需混合精度，请通过 optimizer.wrapper_type 使用 AmpOptimWrapper。
• input_modality：控制传感器模态的字典。键：use_lidar（True）、use_camera（True）、use_radar（False）、use_map（False）。
• model.img_backbone：图像骨干网络。默认值为 mmdet.SwinTransformer（Swin-Tiny）。embed_dims=96，depths=[2,2,6,2]。
• model.view_transform.type：用于 BEV 投影的视角变换。可选值：DepthLSSTransform、LSSTransform。默认值为 DepthLSSTransform。
• model.point_cloud_range：LiDAR 的空间范围。默认值为 [0,-40,-3,70.4,40,1]。
• model.voxel_size：体素尺寸。默认值为 [0.05, 0.05, 0.1]。
• dataset.train_dataset.batch_size：每个 GPU 的批量大小。默认值为 4。

多 GPU / 多节点

启动方式： torchrun（LIGHTNING_EXCLUDED_NETWORK）。入口点运行 torchrun --nnodes=N --nproc-per-node=M train.py，而不是普通的 python。

规格键	说明	默认值
train.num_gpus	每个节点的 GPU 数量	1
train.gpu_ids	GPU 设备索引	[0]
train.num_nodes	节点数量	1

• CUDA_VISIBLE_DEVICES 会根据 TAO_VISIBLE_DEVICES 显式设置
• BEVFusion 使用基于 mmdet3d 的分布式训练，而不是 Lightning DDP
• 如果未设置 RANK，则会将 NODE_RANK 复制到 RANK

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

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

硬件

支持使用一块 GPU，搭配小型数据集和批量大小进行最简冒烟测试／AutoML 验证。 常规训练建议使用 2 块或更多 GPU，条件允许时使用 4 块 GPU。 每块 GPU 需要 24GB 或更多显存（推荐 A100）。BEVFusion 需要进行多传感器融合，因此对显存要求较高。

错误模式

必须执行 dataset_convert：训练前运行 model-skill 的 dataset_convert 操作（在 BEVFusion 5.5 容器中执行 bevfusion convert -e <spec>），生成 kitti_person_infos_train.pkl、kitti_person_infos_val.pkl 和 training/velodyne_reduced。对于直接运行的 local-docker 5.5，将 results_dir 设置为与 root_dir 相同的挂载路径；转换器会在该路径写入信息 pickle 文件，之后会在 root_dir 下查找这些文件以缩减点云。

KITTI 目录名称：BEVFusion 5.5 转换器会将缩减后的点云写入 training/velodyne_reduced，并在 training/image_2 下查找相机图像。将 dataset_convert 串接到 train/evaluate 或推理流程时，不要使用过时的 training/lidar_reduced 或 training/images/ 默认路径。

BEVFusion 5.5 配置项：使用打包模板中的 5.5 数据类键。移除较新版本的顶层/操作键，例如 model_name、wandb.group、wandb.run_id、train.checkpoint_interval_unit、evaluate.trt_engine、evaluate.batch_size、inference.trt_engine 和 inference.batch_size。对于 train、evaluate 和 inference 规格，保留未运行操作的占位项（train、evaluate 和 inference），并在需要时将检查点字符串留空；5.5 运行器会在执行所选操作前生成完整的实验配置。未指定检查点时，train.pretrained_checkpoint 和 train.resume_training_checkpoint_path 请使用 YAML null，而非空字符串。

ModuleNotFoundError: No module named 'mmdet3d'：共享的 TAO PyTorch 7.x 镜像不包含 BEVFusion 的 mmdet3d 依赖。请使用 nvcr.io/nvidia/tao/tao-toolkit:5.5.0-pyt；该镜像包含 mmdet3d，并提供 BEVFusion 的 convert、train、evaluate 和 inference 子任务。

BEVFusion 5.5 评估后发生 SIGSEGV：某些 local-docker 运行可能会写入检查点或预测文件，但在 cuMemRetainAllocationHandle 中出现 Signal 11 (SIGSEGV) 后，仍以 TAO Execution status: FAIL 结束。不要仅凭 Docker 退出代码判定操作成功；请检查 TAO 日志或 status.json。在 CUDA 12+ 主机上，保留 TAO 5.5 依赖栈，并应用 tao-pytorch 中 BEVFusion 的旋转 IoU CPU 回退方案和运行器清理；不要将操作切换到共享的 7.x 镜像。CPU 回退为默认设置；BEVFUSION_ROTATE_IOU_BACKEND=gpu 是显式启用旧版 Numba CUDA 评估器的选项。如果在此次故障前已生成检查点，下游诊断时仅使用预期的确切检查点（例如 epoch_1.pth），除非操作明确要求使用最新检查点，否则不要将 last_checkpoint 视为最佳检查点。

缺少模态数据：如果使用多模态融合，请确保相机图像和 LiDAR 点云都已就绪。

Epoch 编号：BEVFusion 检查点的 epoch 编号可能不遵循标准的零填充格式。

检查点交接：使用 SDK/模型检查点解析器选择父模型。直接串接运行 local-docker 时，请检查训练结果并传入预期检查点的确切路径，例如 epoch_1.pth；只有在用户明确要求使用最新检查点时才使用 latest.pth。恢复/重新训练时，必须设置 train.resume: true，并将 train.resume_training_checkpoint_path 指向要恢复的确切检查点。

规格参数／父模型推断

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

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

操作	规格字段	推断函数	含义
dataset_convert	results_dir	output_dir	当前作业的结果目录
evaluate	encryption_key	key	加密密钥
evaluate	evaluate.checkpoint	parent_model	从父作业结果文件夹推断出的模型文件
evaluate	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.pretrained_checkpoint	ptm_if_no_resume_model	不存在恢复检查点时使用的 PTM
train	train.resume_training_checkpoint_path	resume_model	从当前作业结果文件夹推断出的模型文件

对于 parent_model 或 parent_model_folder，请将上游 train/export/AutoML 子作业 ID 作为 parent_job_id 传入。SDK 会列出父作业的结果文件夹，筛选检查点制品，并返回选定的模型文件或文件夹。不要将这些映射加回 config.json，也不要修改生成的运行器脚本来猜测检查点路径。