过去这半年，我陆续复现过几类视觉模型，从 3DGS（3D高斯泼溅）到 FixMatch 这类半监督分类方法，再到 AdaLoRA 这种参数高效微调方案。这些项目各有各的门道，但要说把工程底子练得最扎实的，还是最近完成的 Sparse4Dv3 代码复现。Sparse4Dv3 是面向自动驾驶视觉中心 3D 检测与跟踪的稀疏 4D 感知算法，核心思路很直接：用一组可学习的稀疏查询取代传统 BEV 特征图，从多视角图像中采样时序信息，直接输出 3D 检测框和跟踪结果。它在 nuScenes 数据集上的 NDS 指标能做到 0.61 附近，在同类稀疏感知方案里非常有代表性。
这篇笔记不是我复现过程的流水账，而是想把这套经验完整写下来，从环境配置、数据处理、模型结构拆解，到多卡训练、指标核对、问题排查，全部覆盖。如果你正准备入坑自动驾驶感知方向的项目复现，或者正在调 Sparse4D 系列代码但遇到 loss 不稳、指标偏低的情况，这份记录应该能帮你少走不少弯路。需要提前说明的是，项目里的具体参数我会给出参考值，但更建议以官方仓库的 config 为准，毕竟环境和个人硬件差异很大。
1. 复现前最重要的事：先吃透 Sparse4Dv3 改了什么
很多人拿到开源代码第一件事就是配环境、跑训练，结果跑到一半发现模型结构理解错了，改来改去浪费大量时间。我的习惯是先把论文和代码结构过一遍，把关键设计点抄在纸上再动手。Sparse4Dv3 不是那种换了个损失函数就能涨点的简单工作，它的三个核心创新点和代码结构是强绑定的，理解不到位，后续排查问题会非常痛苦。
1.1 三代 Sparse4D 到底在解决什么问题
Sparse4D 系列是地平线在纯视觉 3D 检测方向的一组代表性工作。第一代最核心的贡献，是把主流 BEV 方案里的“稠密网格”换成了“稀疏查询”。BEV 类方案需要先把多视角图像投影到统一的俯视图网格上，再在网格上用 transformer 解码，网格分辨率一高，算力和显存就成倍上涨。Sparse4D 的做法是直接用一组低维的稀疏锚点作为查询，通过可变形注意力去透视图像上采样特征，整个流程不再依赖显式的 BEV 体素特征。这个思路在当时非常前沿，直接拉低了视觉中心 3D 检测的计算成本。
到了 Sparse4Dv2，作者把时序信息加了进来。它把上一帧的对齐特征和当前帧查询做融合，又增加了第二轮 refine 阶段，让每一帧的检测都能借助历史帧的信息来提精度。v2 的性能已经很不错，但那时它做时序融合的粒度还偏向特征级，对不同时间尺度、不同目标状态的表达能力有限。
Sparse4Dv3 的主要工作，就是沿着“时序”和“稀疏”这两条线继续深挖。它提出实例级时序融合，让每个检测实例直接聚合它在历史帧中的特征与位置；又提出解耦注意力，把采样点拆成定位组和内容组，让查询同时拥有全局定位和局部精修的能力；再加上一个质量估计器，用预测的 3D IoU 去修正分类置信度。这几个设计，每个都对最终指标有实打实的贡献，代码里也都有对应的模块。
1.2 复现的目标是“跑准”，不是“跑通”
做代码复现，常见误区是以为“能跑起来”就等于“复现成功”。对 Sparse4Dv3 这种训练依赖很重的模型来说，跑通只是第一步，能不能把 nuScenes val 上的 NDS 拉到接近论文水平，才是真正考验人的地方。
为什么难？首先是训练时间长，8 卡起步，十几二十个小时是常态；其次是数据预处理细节多，nuScenes 的 infos 文件怎么生成、can_bus 怎么关联、多视角相机参数怎么对齐，都会直接影响模型输入；再者，Sparse4Dv3 里有大量“不加就掉点”的训练技巧，比如 GT 采样、EMA、长时序训练、混合精度等等。这些技巧在论文里可能只是两三句话，但在复现时每一项都可能拉开好几个点的差距。
我在动手前把论文和官方 README 各读了两遍，然后把关键超参数抄到便签上再开始配环境。这个习惯救了我很多次，因为很多问题其实是前期设计没想清楚，而不是代码写错了。接下来我就按实际复现的顺序，把这套流程完整展开。
2. 环境准备与 nuScenes 数据预处理
Sparse4Dv3 是典型的重依赖项目，环境稍有不对，光编译就能耗掉你半天。这一节先讲版本组合怎么选，再说 nuScenes 数据怎么准备，最后是加载性能优化。这些都是“看不见”但特别影响体验的环节。
2.1 版本组合怎么选最稳
官方代码基于 MMDetection3D 生态，所以版本匹配是第一道坎。我这次采用的组合如下，整体比较稳：
- Python 3.8.8
- PyTorch 1.11.0
- CUDA 11.3
- mmcv-full 1.5.3
- mmdet 2.25.1
- mmengine 0.6.0
- mmdet3d 1.0.0rc4
- numpy 1.21.5
这组版本不是唯一答案，但它是社区里跑通率比较高的一套组合。mmcv-full 编译起来比较耗时，能用预编译的 wheel 就直接用，不要自己从源码编。如果用的是比较新的显卡，比如 RTX 4090 或者更高型号，还要注意驱动自带的 CUDA 版本和 PyTorch 的 CUDA runtime 是否兼容，否则会在模型前向时报奇怪的算子错误。
还有个小经验：建好 conda 环境后，先写一段简单的脚本，import torch、mmcv、mmdet3d，确认都能正常加载再进入下一步。这不花多少时间，但能帮你把“环境杂症”和“业务代码问题”隔离开。我在这个环节吃过亏，一度以为模型代码有问题，查了半天发现是 mmcv 编译时没带 CUDA 算子。
2.2 nuScenes 数据制备与 infos 生成
Sparse4Dv3 在 nuScenes 数据集上训练和评估。你需要先从官网注册下载完整数据，包括 camera、lidar、map、can_bus 这几大类。很多人会漏掉 can_bus，但它恰恰是 ego 运动信息的来源，Sparse4Dv3 的时序对齐非常依赖它。
数据准备的核心是生成 infos 文件。官方仓库通常会提供 create_data.py 之类的脚本，把原始数据转成包含图像路径、标定参数、位姿信息、GT 标注的 pkl 文件。这个转换过程比较耗时，建议先用 nuScenes mini 集把整个流程跑通，确认 pkl 正常生成了，再处理全量数据。全量数据生成的 pkl 文件可能有几个 GB，磁盘空间要预留足够。
生成完之后，至少手动检查三处：每个 sample 的相机数量是否一致、can_bus 时间戳能否对上、图像尺寸是否统一。我在第一次生成时发现部分场景因为传感器异常少了几帧相机数据，如果不过滤，训练时会直接导致 batch 维度对不齐。
2.3 数据加载性能优化
数据加载慢是这类项目的通病，尤其是 nuScenes 这种图片数量很大的数据集。GPU 利用率上不去、训练时显存占用波动大，很多时候问题就出在 DataLoader 上。
优先把数据放在 SSD 上，机械硬盘读图的速度会直接拖垮训练。其次，num_workers 不是越大越好，我试过 8 个 worker 反而比 4 个更慢，因为在老版本 mmdet3d 的 DataLoader 里有内存锁问题。我最终用 4 到 6 个 worker 配合 pin_memory=True，整体吞吐最稳定。如果你的内存足够大，也可以考虑把 pkl 里的图像预先解码缓存到内存，能省掉不少随机的 IO 时间，但要注意内存占用不要挤占训练进程。
3. 核心代码结构与关键模块拆解
环境搭好、数据准备完，接下来就是重头戏：读懂代码结构。Sparse4Dv3 的代码量不算小，但核心模块相对集中。这一节我按“结构概览、时序融合、注意力与质量估计”三块来讲，这也是我在复现时认为最值得花时间的部分。
3.1 官方仓库的结构，以及我建议的阅读顺序
Sparse4Dv3 的官方实现基于 MMDetection3D 框架，核心代码通常放在 projects/Sparse4Dv3 目录下。按模块来划分，大致包括模型主体、检测头、注意力模块、时序融合模块、质量估计模块和若干工具方法。
我建议的阅读顺序是：先看模型主体，搞清楚 backbone、neck、head 是怎么串起来的；然后看 head，理解 proposal 生成和 refine 阶段的关系；接着读注意力模块，弄明白可变形采样是怎么做的；最后再看时序融合和质量估计器。不要一上来就钻进某个算子细节里，先把数据流走通，知道每个模块输入输出是什么，再深入细节。
我自己在复现的时候，会先跑一次前向，用几个断点打印出查询的数量、特征维度、坐标范围，对照论文里的描述检查是否一致。这一步看似简单，但能非常有效地帮你建立起“代码变量”和“公式符号”之间的对应关系。
3.2 实例级时序融合：代码中最精彩的部分
实例级时序融合是 Sparse4Dv3 相比前两代变化最大的地方。它的目标很直白：当前帧的每一个稀疏查询，都应该去历史帧里找到属于同一个目标的“自己”，然后把历史帧里的特征拿过来用。这样即使当前帧目标被遮挡、模糊，模型也能凭借历史信息给出更稳的预测。
代码里做这件事，大致分三步。第一步，把历史帧的查询位置投影到当前帧坐标系下，投影过程需要用到外参、内参和 ego 运动轨迹；第二步，在当前帧查询和历史帧查询之间做特征聚合，可以是基于距离的最近邻匹配，也可以是可学习的注意力打分；第三步，把聚合后的历史特征和当前帧特征做融合，再输入后续的解码层。整个过程中有一个类似记忆池的结构，用来缓存若干帧的查询特征和对应时间戳。
这个模块最坑的地方在于坐标变换。我在第一次实现时把外参矩阵的行列顺序弄错了，结果模型训练出来 NDS 非常低，排查了很久才发现是历史帧查询投影偏了一个方向。如果你也在复现这个模块，建议单独写个可视化脚本，把投影后的历史锚点画到当前帧图像上，看看位置合不合理，这一步能省下大量盲调时间。
3.3 解耦注意力与质量估计器
解耦注意力是在可变形注意力基础上的改动。标准可变形注意力会让每个查询在所有采样点上学一组偏移，然后采特征。Sparse4Dv3 的思路是把采样点拆成两组：一组负责“位置”，偏移范围可以大一些，主要用于搜索目标在空间中的大致位置；另一组负责“内容”，偏移范围小一些，集中在目标附近做精细特征提取。这样做的好处是同一个查询既能看全局，又能看细节，而计算量并没有成倍增加。
质量估计器则是在 head 里多接了一个小分支，用来预测预测框与真实框之间的 3D IoU。推理时，把这个预测的 IoU 乘到分类分数上，作为最终置信度。这一招解决的是分类分数和定位质量不匹配的问题：有些框分类很自信但位置偏了，单纯按分类分数排序会把这类框排上去，乘上 IoU 预测之后，质量差的框会被压下去。
代码里这个模块通常不复杂，但对最终指标影响很明显。我建议把质量估计器的预测结果单独打印出来和真实 IoU 对比一下，如果两者相关性很弱，说明这个分支没有训练好，需要考虑调整损失权重或者给这个分支更长的训练轮数。
4. 训练复现的关键环节与多卡调参
数据和模型都准备好了，就进入最耗资源的训练环节。Sparse4Dv3 的多卡训练有很多细节，稍不注意就是训练两天发现指标离论文差一大截。这一节我把整套训练流程、涨分技巧和显存优化经验都写出来。
4.1 完整训练流程与超参数参考
Sparse4Dv3 的训练通常是分阶段走的。第一阶段先训练一个不含长时序的 base 模型，用来初始化模型参数；第二阶段再加载 base 权重，用连续多帧的时序数据进行长时序训练。这样做的原因是，实例级时序融合对查询的初始质量很敏感，如果一开始就上长时序，模型容易不稳定。
我参考社区里的常见配置，用如下一组参数：
- 输入图像尺寸：短边 900，长边 1600
- 优化器：AdamW，初始学习率 2e-4，weight decay 0.01
- 学习率调度：cosine 衰减
- 训练轮数：24 epoch
- batch size：8（8 卡，每卡 1 个样本）
- 混合精度：fp16
- EMA：decay 设为 0.9998
- GT 采样：开启
这组配置下，在 8 卡 A100 上大概要训练一天左右，如果换 V100 或者加长时序，时间还要翻倍。训练过程中要定期保存 checkpoint，最好每 1 到 2 个 epoch 存一次，同时记录验证集上的 NDS 和 mAP，用最好的那版做最终评估。
4.2 涨分关键的三个 Trick
第一个是 GT 采样。自动驾驶场景的类别分布很不均衡，行人和车辆这种常见类别样本多，但一些少见类别如工程车、拖车就很少。GT 采样的做法是，从数据集中随机挑选其他帧的真实 3D 框，以合理的位置和朝向复制到当前训练样本里，增加少见类别的样本量。这个 trick 在 Sparse4Dv3 里非常影响 NDS，我试过不加的情况下，指标能掉 3 到 5 个点，影响非常直观。
第二个是 EMA。对模型参数做指数移动平均，可以减少训练后期参数的剧烈震荡，尤其在检测头部分效果明显。推理时加载 EMA 版本的权重，通常比直接用最后一轮权重更稳。这个技巧实现的代码量很小，但性价比很高。
第三个是长时序训练。第二阶段用连续多帧数据做实例级时序融合，是 Sparse4Dv3 最终涨到高指标的关键。时序帧数不是越多越好，帧数增加会带来显存和训练时间的线性增长，我试过 5 帧和 8 帧，8 帧在远距离小目标上的收益最明显，但训练成本也更高。建议根据自己的卡量和时间预算来选择。
4.3 显存、训练时长与 checkpoint 策略
显存是训练这类模型最现实的问题。把 fp16 打开是最基本的操作；如果还是 OOM，可以先把输入图像尺寸降下来，等代码完全跑通之后再调回去。另一个办法是开启梯度累计，比如每 2 个 step 累加一次梯度，等效于扩大 batch size，但不会增加单卡显存压力。Sparse4Dv3 的时序融合模块在长时序训练时会缓存多帧特征，这部分比较吃显存，可以考虑用 gradient checkpointing 换取显存空间。
训练时长要提前做好心理预期。我自己的经验是，第一阶段 base 模型训练相对快一些，第二阶段长时序训练才是真正的大头。如果中途因为环境问题或数据问题中断，最好能保存 ckpt 支持无缝恢复，不然重来一次的成本太高。checkpoint 保存建议同时保留普通权重和 EMA 权重，这样即使普通权重后期过拟合，也能用 EMA 版本兜底。
5. 复现过程中的常见问题与排查实录
这一节把我在实际复现中踩过的坑和排查思路整理出来，按环境、数据、训练三块分类。每一条都是真实经历，希望能帮你省下一些调 bug 的时间。
5.1 环境配置阶段的坑
mmcv-full 编译报错是重灾区。最常见的错误是 CUDA 版本和 PyTorch 的 CUDA runtime 不一致，导致编译时找不到 cu 头文件。解决办法就是官方找一版匹配的组合，直接用预编译 wheel，不要自己编。
另一个常见问题是用多卡训练时，deformable attention 的自定义算子报“CUDA error: invalid device function”。这个问题多数是 mmcv 编译时没有开启对应显卡的算力支持，重新安装匹配当前显卡的 mmcv 版本即可。印象里这种报错特别迷惑人，因为单卡跑得通，一上多卡就崩。
5.2 数据准备阶段的坑
生成 infos 文件时，出现 KeyError 指向 can_bus，一般是 data 目录里少了 can_bus 文件夹，或者路径配置不对。还有可能是时间戳对齐出问题，这会导致后续时序融合时找不到对应的位姿信息。另一个常见问题是数据增强后图像尺寸不一致，比如随机翻转或者 resize 没有按照统一尺度，会导致 backbone 输出的特征图尺寸和 head 预期不匹配。
我也遇到过训练时 GPU 利用率只有 30% 左右的情况，排查下来是 num_workers 设太高导致 DataLoader 内部发生内存争抢。把 num_workers 降到 4 并打开 pin_memory 之后，GPU 利用率恢复到 90% 以上。数据加载这个环节看着不起眼，但确实能影响整个训练节奏。
5.3 训练过程中的坑
训练时 loss 变成 NaN，是最让人头疼的问题。我遇到的情况有两种：一种是初试学习率太高，导致 loss 直接爆掉，调低学习率后恢复；另一种是某张训练图像是全黑帧，经过归一化之后出现异常值，在数据加载时做一下过滤就好了。排查方式很简单，写一段代码单独加载几个 batch，跑一次前向和反传，看看 NaN 出现在哪里，再做针对处理。
还有一种奇怪现象：训练 loss 正常下降，但验证时 NDS 和 mAP 几乎为 0。这种情况十有八九不是模型没学会，而是推理后处理时坐标转换出了问题。比如把网络输出的归一化坐标还原到 ego 坐标系时，用错了外参顺序，或者忽略了翻转增强。先拿一张图可视化预测框和标注框，通常一眼就能看出问题在哪。
5.4 常见问题速查表
我整理了一张速查表，方便你遇到问题时快速定位方向。
| 现象 | 可能原因 | 解决方式 |
|---|---|---|
| mmcv 编译失败 | CUDA 版本与 PyTorch 不匹配 | 换预编译 wheel 或调整 CUDA 版本 |
| 多卡训练报 invalid device | mmcv 未适配当前显卡算力 | 重装匹配显卡的 mmcv 全量版本 |
| infos 生成报 can_bus 缺失 | 数据目录缺少 can_bus 或路径错误 | 下载完整 nuScenes 数据并检查路径 |
| 图像尺寸不一致 | 数据增强未按统一 scale | 检查 transform 配置，固定短边/长边 |
| GPU 利用率很低 | num_workers 设置过高 | 降到 4~6，打开 pin_memory |
| loss 为 NaN | 学习率过高或异常输入帧 | 降低学习率，检查并过滤黑帧/坏帧 |
| 训练 loss 正常但指标为 0 | 后处理坐标转换错误 | 可视化预测框，核对坐标变换流程 |
| 显存溢出 | 输入尺寸或时序帧数过大 | 开启 fp16、梯度累计或 gradient checkpointing |
| 指标比论文低几个点 | 缺少 GT 采样或 EMA | 补齐训练技巧，加载 EMA 权重评估 |
这张表不是万能答案，但它覆盖了我复现过程中绝大多数问题。遇到新问题的时候，建议先把变量隔离：是环境问题，是数据问题，还是模型结构问题，确定了方向再动手改。
整个 Sparse4Dv3 复现下来，我最大的感受是：这类工程项目的坑往往不在模型定义，而在数据 pipeline 和多卡训练的配合。建议刚上手的人先下载官方预训练权重，在 mini 集上把整个推理和评估流程跑通，确认指标和预期一致，再上多卡做全量训练。我自己就是因为跳过了这步，第一次全量训练结束后才发现 infos 文件里 can_bus 对齐方式写错了，白白浪费了两天算力。
Sparse4Dv3 后续往端到端方向扩展的空间很大，如果有余力，建议把 v3 的代码结构和下一代改进位置一起对照着读，收获会更多。希望这份复现笔记对你有些帮助。
