tao-train-sparse4d

Sparse4D

独立安装？ 如果 TAO 技能库插件未能初始化会话，请运行 tao-setup，完成主机预检、凭据配置和跨技能发现。

Sparse4D 可根据同步且经过标定的多摄像头图像预测 3D 边界框和跟踪 ID。请从所选模型的实验规格和检查点开始。TAO 官方文档介绍了该模型的工作流。

说明

1. 确定请求的操作、数据监督方式、所选检查点和平台。阅读操作约定和所选平台技能。保留用户对平台、模型、数据和训练预算的选择。
2. 使骨干网络、有序类别、图像预处理、锚点和时间维度与所选检查点匹配。准备规格前，请遵循下文的骨干网络和检查点选择。
3. 如果提供了兼容的现有信息 PKL，请使用它们。对于原始数据，请遵循本地转换和产物检查。对于带有 2D 目标的真实标定场景，请阅读几何蒸馏；此流程不需要 3D 标注或通过转换生成的锚点。
4. 从 references/spec_template_<action>.yaml 和所选版本的实验规格开始。根据实际暂存的产物解析路径。将 results_dir 及任何特定于操作的 results_dir 绑定到当前作业输出目录；已发布的规格可能包含旧的输出路径。使用嵌套 YAML，而不是扁平的点分隔键；不要捏造 train/val/test 文件或场景后缀。检查已安装的运行时是否支持所请求工作流中使用的字段。
5. 为模型操作解析模型级镜像，并为 dataset_convert 解析操作级 Data Services 镜像。对于请求的 TAO 版本，请使用相应的技能库版本分支及其镜像固定配置；不要用默认分支的版本替代。遵循 tao-launch-workflow 以及所选平台的 submit / status / logs / cancel 约定，并保留其作业记录和明确的输出目录。沿用现有用户授权；仅在启动尚未获授权的工作时请求缺失的启动批准。
6. 验证生成的产物和模型指标。进程成功运行或短暂训练仅能作为冒烟测试结果，不能证明 3D 准确度有所提升。不要将尚未发布的实验性修复或其他运行的结果报告为所选镜像的验证结果。

骨干网络和检查点选择

• 遵循明确指定的 ResNet-50 或 ResNet-101 选择。对于现有的 Sparse4D 检查点，请使用随附的实验规格和版本元数据确定 model.backbone.type（resnet_50 或 resnet_101）。如果它们与请求的骨干网络不一致，请在启动前解决此不匹配；不要为了让检查点部分加载而更改架构。
• 如果尚未选择检查点或骨干网络，请询问要使用哪个兼容的已发布模型。架构中的默认值 resnet_101 只是配置默认值，并非推荐，也不能作为用户检查点相关信息的依据。
• 保留所选检查点的类别顺序、锚点、输入维度以及时间/查询维度。来源不明时，仅凭文件名不足以判定检查点。
• LTT MLP 是独立的几何适配器。从 ResNet-50 包中下载该适配器并不意味着已选择 Sparse4D 骨干网络。其有序分类体系必须与训练数据和模型匹配。
• 微调使用 train.pretrained_model_path。继续运行则使用 train.resume_training_checkpoint_path 和兼容的已保存训练状态。只有在明确请求时，才适合使用空预训练路径进行随机初始化，例如进行接线冒烟测试。

训练操作策略

提交训练请求前，请先阅读 references/skill_info.yaml。此模型已启用 AutoML。请保留显式设置 automl_policy: on / off；对于普通训练、不使用 HPO、按固定规格复现、范围受限的连通性冒烟测试或精确续训，本次运行应设为 off。其他情况默认设为 on，并在 schemas/train.schema.json 和 references/spec_template_train.yaml 均可用时，通过 tao-skill-bank:tao-run-automl 执行。保留数据集、检查点、规格、GPU/平台和预算覆盖设置。如果缺少 schema/template，请说明 AutoML 不可用，并在用户请求范围内直接训练。

AutoML 的监控名称为 val_mAP；Sparse4D 还会以别名形式输出 img_bbox_NuScenes/mAP 和 mAP。晋级后的续训任务可能会沿用源阶段的指标，而不会进行新的评估：请报告该指标的来源，并独立验证续训检查点。遵循 AutoML 技能对基线评估的要求。评估、推理、导出和量化仍由此技能负责。

训练要求

训练需要转换后的 OVPKL 数据、留出且带标签的验证数据、匹配的 anchors，以及选定的预训练检查点或续训状态。保留选定的骨干网络和有序分类体系。几何蒸馏还需要已发布的 LTT 检查点和准备好的监督缓存。根据用户请求和可用资源选择 GPU 数量及训练预算。

各操作的数据集要求

模型使用 OVPKL 标注。操作契约会声明分阶段输入、命令、输出和可选产物。嵌入在 info PKL、数据拆分列表和惰性索引中的路径，也必须在所选运行时中可见；仅暂存拆分文件，并不会暂存其引用的数据。

操作	运行时命令	所需数据/模型产物
dataset_convert	annotations convert -e SPEC（Data Services）	原始场景根目录、标定数据、图像；仅标注数据转换需要 3D 标注
train	sparse4d train -e SPEC	训练和留出的验证 PKL/数据拆分、图像根目录、匹配的 anchors、选定的预训练或续训检查点；所选监督方案的 LTT/缓存产物为可选
evaluate	sparse4d evaluate -e SPEC	evaluate.checkpoint、匹配的 anchors、位于 dataset.test_dataset.ann_file 的带标签留出 PKL、图像根目录
inference	sparse4d inference -e SPEC	inference.checkpoint、匹配的 anchors、位于 dataset.test_dataset.ann_file 的输入 PKL、图像根目录
export	sparse4d export -e SPEC	export.checkpoint、匹配的 anchors 和架构、显式指定的 export.onnx_file；不需要训练数据集或外部 LTT 检查点
quantize	sparse4d quantize -e SPEC	quantize.model_path 和所选后端的校准输入；检查运行时后端支持情况

评估 CLI 会调用测试数据加载器。仅设置 dataset.val_dataset.ann_file 不会指定评估数据；该字段用于训练期间的验证。请保留完整规格中未使用的数据集部分，不要凭空创建或暂存未使用的标注文件。

请将 model.head.instance_bank.anchor 解析为所选资源包或兼容的带标签转换所提供的显式模型产物。评估或导出不需要从必需的训练数据集中推断该产物。

有关精确的产物交接方式，请参阅检查点和输出解析。不要选择找到的第一个检查点，也不要依赖已移除的 SDK 作业解析器。

典型规格覆盖项

对于 AutoML，请根据上表中的具体暂存路径和 skill_info.yaml 的 data_sources 构建 spec_overrides；点分隔键是 AutoML 覆盖映射，不是容器 YAML 格式。只设置所选操作所需的输入。

范围	要解析的覆盖项
训练数据	dataset.data_root、dataset.train_dataset.ann_file、dataset.val_dataset.ann_file
模型初始化	model.backbone.type、model.head.instance_bank.anchor、dataset.classes，以及 train.pretrained_model_path 或 train.resume_training_checkpoint_path
训练资源	train.num_gpus、train.num_epochs、dataset.batch_size 和 dataset.num_workers，并保留所请求的预算
几何蒸馏	训练片段中的 LTT/缓存路径和路由字段；HPO 期间保留经过验证的类别顺序和监督策略
评估和推理	dataset.data_root、dataset.test_dataset.ann_file、匹配的锚点，以及该操作的检查点
输出	results_dir 和绑定到当前作业的操作专属输出路径

当 dataset.lazy_load: true 时，将拆分数据集的父目录作为文件夹暂存，其中包括与拆分数据集放在一起的 <split>_lazy_index.pkl，以及使用时的 _pkl_cam_counts.pkl。将 ann_file 指向该暂存目录；不要仅暂存文件，以免文件被移到索引之外。确保引用的 PKL 和图像可见，并在迁移后重建索引。dataset.pkl_cam_counts_path 是可选的摄像头数量覆盖项，不是惰性加载索引。

配置和资源检查

生成的架构和模板描述打包后的契约；schemas/manifest.json 列出了各项操作。不要要求用户的机器上有 TAO Core 检出目录。启动时使用与运行时匹配的发行版规格：架构支持新字段，不代表旧镜像也支持该字段。

• model.backbone.type：与所选检查点匹配。
• train.optim.lr、train.optim.lr_scheduler 和 train.optim.grad_clip：优化器设置嵌套在 optim 下。
• dataset.batch_size：每 GPU 的批次大小。支持时，dataset.max_cameras 可减少采样的训练摄像头数量；请验证最终的监督覆盖范围。
• train.precision：可选 bf16、fp16 或 fp32，具体取决于硬件和运行时支持。BF16 并非必需。
• train.num_gpus、train.gpu_ids、train.num_nodes：使用所选平台的资源分配。支持使用单 GPU 进行冒烟训练；内存需求取决于骨干网络、分辨率、摄像头数量、批次大小和时间配置。
• dataset.num_frames 和 dataset.num_bev_groups 是调度/数据规模设置，不是用于控制激活内存的序列长度参数。比较不同数据集或 GPU 数量下的训练预算前，请检查实际的数据加载器长度和迭代次数。
• dataset.eval_dist_fcn 和 dataset.eval_hota：选择受支持的检测/跟踪评估。进行比较时，请保持阈值、类别顺序、数据集以及原始检查点或 EMA 检查点的选择一致。

Lightning 会管理本地工作进程。不要再添加第二个分布式启动器。请使用平台的多节点环境契约；TAO 的 WORLD_SIZE 启动器变量表示节点数量，而不是全局 GPU 数量。混合 3D/2D 分布式训练还需要几何蒸馏参考中同步的路由设置。

错误模式

• 缺少标注或图像： 检查转换器输出和嵌入路径。保留生成的 BEV 组后缀、摄像头 ID、帧 ID 和挂载根路径。转换 train 不会同时生成 val 和 test 输出。
• 缺少锚点： 复用所选预训练包中的匹配锚点，或在兼容时使用带标注转换生成的锚点。无标注转换会有意跳过锚点初始化。
• 旧版 HDF5 深度元组： 检查受影响的带标注 PKL，仅当文档说明的布局匹配时，才使用转换参考中的可选归一化辅助工具。未标注场景没有需要归一化的深度路径。
• 时序 OOM： 首先降低每个 GPU 的批次大小，或使用受支持的摄像头采样；保留检查点架构。不要盲目缩减锚点／时序维度，也不要把 num_frames 当作内存优化手段。
• LTT 或教师缓存不匹配： 核实类别顺序、场景／摄像头／帧关联及容器路径。发布的 LTT 路线支持其原有的七个类别；更改类别名称并不能适配权重。
• 导出形状重塑： 在训练缩减版冒烟测试模型之前，先检查转换参考中的导出器约定。当前导出使用 20 个虚拟摄像头和 600 个缓存的时序实例；推理成功本身不能证明导出兼容。
• 不支持的量化后端／镜像： 报告所选镜像、后端、确切检查点和故障。不要声称历史验证镜像上的结果能证明当前运行时可用，也不要移除该操作来掩盖故障。