Sparse4D

Sparse4D 是一种用于多相机时序 3D 目标检测与跟踪的模型。它利用跨相机视角和时间的稀疏查询与可变形注意力进行端到端 3D 感知，并配套实例库（instance bank）实现时序跟踪。当需要训练、评估、导出、量化 TAO Sparse4D 模型或对其执行推理时，可使用本技能。

独立安装？ 如果当前会话不是由 TAO 技能库插件初始化，请先运行 tao-setup 技能（主机预检、凭据、跨技能发现）。

训练动作策略

该模型在模型层已启用 AutoML。处理训练请求前，请阅读 references/skill_info.yaml，并根据 automl_policy 或用户工作流解析覆盖。默认 automl_policy: on，只暴露 on/off。当 automl_policy: on 且 automl_enabled: true、相关 schema 存在时，通过 tao-skill-bank:tao-run-automl 启动训练；否则直接训练。非训练动作如评估、推理、导出仍在本技能中。

训练要求

数据集类型：sparse4d
格式：ovpkl
监控指标：val_mAP（在日志中可能以 img_bbox_NuScenes/mAP 或 mAP 形式出现）

各动作的数据集要求

以下为各动作所需的数据源覆盖：dataset_convert、evaluate、export、inference、quantize、train 都需要基于转换任务的输出设置 dataset.data_root、anchor 路径和训练/验证/测试 ann_file。转换任务需先运行，以生成 anchor_init.npy 和 *_infos_*.pkl。

重要参数

model.backbone：骨干网络，默认 resnet_101
model.neck.out_channels：FPN输出通道，默认 256
model.input_shape：输入图像尺寸 [W,H]，默认 [1408,512]
model.head.num_output：检测输出查询数，默认 300
model.head.num_decoder：解码器层数，默认 6
model.head.temporal：是否启用时域推理，默认 True
model.head.instance_bank.num_anchor：实例库锚点数，默认 900
model.head.instance_bank.num_temp_instances：临时实例数，默认 600
model.depth_branch.loss_weight：深度监督损失权重，默认 0.2
dataset.batch_size：每GPU批次大小，默认 2
dataset.num_frames：序列长度，默认 200
train.optim.lr：学习率，默认 5e-5（骨干 lr_mult=0.2）
train.precision：可选 bf16/fp16/fp32，默认 bf16
evaluate.metrics：默认 [“detection”]，可选跟踪评估

多GPU / 多节点

启动方式：Lightning 管理（单进程启动，Lightning 自动拉起 worker）。关键设置：train.num_gpus（默认1）、train.gpu_ids（默认[0]）、train.num_nodes（默认1）。多GPU策略为 ddp_find_unused_parameters_true，始终启用 sync_batchnorm。迭代次数按公式计算，增加GPU会同步扩大有效批次并减少每epoch迭代数。

硬件

最少需要 2 张 GPU，推荐 8 张 40GB+（A100）。模型内存占用高，训练实际使用 bf16。多GPU强烈推荐。

错误模式

必须先运行 dataset_convert 以生成注解 pkl 和 anchor_init.npy。
dataset_convert 须使用 AICity 到 OVPKL 转换容器和 annotations convert 命令。
若 H5 深度路径出错，运行 scripts/normalize_depth_paths.py 统一路径。
缺少 anchor 文件时，应指向转换结果中的 anchor_init.npy。
时序训练 OOM 时，可减小 dataset.num_frames 或 dataset.batch_size。
量化时，应向模型传递正确的 quantize.model_path，并选择与评估/推理一致的精确 checkpoint。