前几天一个师弟问我现在复现多模态3D目标检测哪个工作性价比高。我直接推荐了IS-Fusion——ECCV 2024上的多模态融合方案核心思路是把场景级融合和实例级融合并行起来做比BEVFusion那种单纯BEV特征交互要精细不少。不过话说回来这项目虽然效果好环境搭建和数据准备却比单模态麻烦一个量级。最容易被卡住的三件事分别是MMDetection3D配套版本怎么选、Swin-Tiny在nuImages数据集上的预训练权重上哪找、nuScenes数据集的下载整理怎么做。这篇文章把我从零开始搭建IS-Fusion环境、准备nuScenes数据、最终跑通训练的全过程完整记下来包括版本组合、目录结构、配置修改、实际报错和排查思路给打算复现的朋友一份能直接照着走的参考。1. IS-Fusion在融合什么场景级与实例级的分工逻辑在敲任何命令之前先花十分钟搞清楚IS-Fusion的设计逻辑是值得的。这一步决定了你后面改配置、调参数时的方向感也能帮你遇到问题时分清楚到底是环境问题还是模型理解问题。1.1 三条主流多模态融合路线IS-Fusion走了第四条目前多模态3D目标检测的融合方式大致分三类。第一类是基于点的方法典型代表是DeepFusion这类工作通过深度估计或注意力机制把图像特征投影到3D空间在点或体素级别做特征拼接。这类方法的优点是特征对齐精度高缺点是计算量大图像特征在投影过程中容易丢失语义信息。第二类是BEV方案以BEVFusion为代表。思路是先通过LSSLift-Splat-Shoot或类似手段把图像特征提升到BEV空间点云也通过体素化编码成BEV特征然后统一在BEV坐标系里做特征拼接或者注意力交互。这类方法工程化程度高目前工业界落地案例最多但问题也明显——把图像提升到BEV时垂直方向的信息会被压缩远处小目标在BEV网格里可能连一个像素都占不满。第三类是query-based方案TransFusion是代表。它用一组可学习的目标query比如预设的200个anchor去索引图像和点云特征通过deformable attention动态聚合信息。这类方法解决了一部分目标尺度问题但query本身的设计和初始化对最终精度影响很大训练不稳定。IS-Fusion不属于其中任何一类。它把融合拆成两个层次——实例级和场景级——同时进行并且互相协同这是它区别于前作的关键。我在读论文的时候就注意到这个思路的动机其实很朴素场景级融合负责广实例级融合负责细两个层次互补才能覆盖不同尺度和场景下的需求。1.2 场景级与实例级的分工一个看全局一个扣细节场景级融合做的事情和BEVFusion类似在全局范围内让图像特征和点云BEV特征互相交互保证模型对整体场景布局、道路结构、远处环境有感知。如果不做这一层模型会丢掉大量上下文信息相当于一个近视眼只盯着眼前的目标看不看路。实例级融合则完全不一样。它先通过图像侧的2D检测或者分割分支定位到具体目标实例区域然后把这些区域内的图像特征与点云侧对应区域的3D特征做逐实例对齐和融合。为什么要这样做因为图像模态的优势在于丰富的纹理、颜色和类别语义信息点云模态的优势在于精确的几何位置信息把两者在实例这个颗粒度上对齐融合可以非常直接地互补。这两个层次不是简单的叠加关系而是协同关系。场景级融合产生的全局上下文可以作为实例级融合的先验帮助实例分支更准地定位目标区域反过来实例级融合提取到的目标级特征也可以反馈回场景级分支强化对特定区域的特征表达。我在实际跑完训练后对这种协同设计的感受是它比单纯堆叠多个融合模块要聪明——因为信息和信息之间真正发生了双向流动而不是各算各的。理解了这层逻辑你去看IS-Fusion源码里的网络结构就不会懵。图像分支用Swin-Tiny做骨干加FPN多尺度特征点云分支走体素化后用PointPillars或SECOND编码成BEV特征然后在中间插入了两个融合模块一个作用域是整个场景一个作用域是实例区域。配置文件里看到两个融合模块的参数时心里就有数了——一个是场景级的一个是实例级的。1.3 为什么官方实验选择nuScenes而不是KITTIIS-Fusion的官方实验主要在nuScenes上做这个选择本身也值得理解。KITTI虽然经典但只有前视单目相机加64线激光雷达场景相对简单目标类别也就车、人、自行车几类。nuScenes提供的是完整6相机环视图像加激光雷达加毫米波雷达覆盖了车载场景真正的复杂度——多视角一致性、目标遮挡、小目标密度都远超KITTI。多模态方法要发挥作用恰恰需要这种多视角、多类别、困难样本多的数据。如果只用KITTI这种相对简单的数据集场景级融合和实例级融合的差距很难体现出来。所以这篇文章后面所有操作都围绕nuScenes进行包括数据下载、目录结构、pkl生成全部以nuScenes为标准。2. nuScenes数据准备下载清单、目录结构与pkl生成数据准备是整个复现过程中最耗时、最劝退的环节没有之一。我第一次下载全量数据加整理花了整整一天。所以这一章把下载清单、目录结构、pkl生成三件事彻底讲透你照着做就能少走弯路。2.1 账号注册、API Token和下载工具nuScenes数据集不是直接给你下载链接的需要先在官网注册账号注册完成后在个人中心页面找到API token。这个token在调用下载工具时要用类似通行证。如果你的网络环境不太稳定下载中途断线是常事所以下载时最好配合能断点续传的工具。官方推荐的方式是安装nuScenes-devkit然后用python脚本下载命令大概是pip install nuscenes-devkit python -m nuscenes.scripts.download nuscenes_v1.0_trainval -c camera -o /data/nuscenes-c camera表示只下载相机图像你可以分别指定lidar、radar、maps、sweeps、canbus等包。这种方式的好处是支持断点续传缺点是单线程速度一般。我实际用下来更推荐直接用AWS命令行工具s5cmd批量下载速度能快好几倍。具体endpoint和bucket路径官方说明文档里会给照着填就行。命令格式大概长这样pip install s5cmd s5cmd --endpoint-url 官方给的endpoint sync 官方给的路径 /data/nuscenes/2.2 到底要下载哪些包需要多大空间很多人在这一步卡住是因为不知道应该下哪些包。下面这个清单是我实际测试过的最小可用集合包名内容是否必要v1.0-trainval场景标注和元数据JSON必须CAM_FRONT等6个相机包环视相机图像必须LIDAR_TOP激光雷达点云必须sweeps各传感器中间帧数据建议下载canbus车辆CAN总线数据建议下载maps语义地图可选RADAR 系列毫米波雷达数据可选IS-Fusion默认用不到完整下载下来在300GB左右如果加上sweeps接近350GB。磁盘空间紧张的话第一次建议先用mini版本跑通流程。mini数据集只有十几个场景全部加起来约10GB下载快、解压快、pkl生成也快适合用来验证环境是否搭建成功。我个人强烈建议的路线是先用mini版本把整条链路跑通确认环境没问题、配置能启动训练之后再下载全量数据。否则一上来就下300GB等下载完发现环境有问题心态很容易崩。2.3 目录结构规划一个软链接搞定下载解压完成后需要把数据整理成mmdetection3d认识的目录结构。标准的nuscenes目录长这样data/nuscenes/ ├── can_bus/ ├── maps/ ├── samples/ │ ├── CAM_FRONT/ │ ├── CAM_FRONT_LEFT/ │ ├── CAM_FRONT_RIGHT/ │ ├── CAM_BACK/ │ ├── CAM_BACK_LEFT/ │ ├── CAM_BACK_RIGHT/ │ └── LIDAR_TOP/ ├── sweeps/ │ ├── CAM_FRONT/ │ ├── CAM_FRONT_LEFT/ │ ├── .../ │ ├── RADAR.../ │ └── LIDAR_TOP/ └── v1.0-trainval/ ├── sample_annotation.json ├── sample_data.json ├── scene.json └── ...注意samples和sweeps这两个目录名是固定的大小写都不能错否则后续生成pkl时加载会找不到文件。maps目录在训练时其实用不到但保持完整性总归没坏处。目录解压好之后在IS-Fusion项目根目录下建软链接就行cd IS-Fusion mkdir -p data ln -s /path/to/your/nuscenes data/nuscenes这里有个容易踩的坑如果你把数据放在别的磁盘分区软链接之后mmdet3d内部如果用了相对路径解析偶尔会出现找不到文件的问题。我在实践中更推荐直接把整个nuscenes目录移动到项目下的data/目录里一步到位省去后面排查路径的麻烦。2.4 生成pkl索引文件create_data.pymmdetection3d训练的时候不是直接读原始数据而是先扫描整个数据集生成一份pkl索引文件里面记录了每个样本的图片路径、点云路径、标注信息、calib参数等等。这一步用mmdet3d自带的数据转换工具完成。cd IS-Fusion python tools/create_data.py nuscenes \ --root-path ./data/nuscenes \ --out-dir ./data/nuscenes \ --extra-tag nuscenes \ --version v1.0-trainval如果用的是mini版本把--version参数改成v1.0-minipython tools/create_data.py nuscenes \ --root-path ./data/nuscenes \ --out-dir ./data/nuscenes \ --extra-tag nuscenes \ --version v1.0-mini跑完会在data/nuscenes下生成nuscenes_infos_train.pkl和nuscenes_infos_val.pkl两个文件这就是后续训练配置里ann_file指向的文件。pkl生成过程的耗时取决于数据量mini版本几分钟搞定全量大概要半小时到一小时。生成后用下面这段代码验证一下内容是否正确import pickle with open(data/nuscenes/nuscenes_infos_val.pkl, rb) as f: infos pickle.load(f) print(len(infos[data_list])) print(infos[data_list][0][images].keys())能正常打印出样本数量和图像键名说明数据这一关过了。这里特别提醒一点pkl里的路径是生成时写入的绝对路径或相对路径生成后不要随意移动data目录否则所有路径失效只能重新生成。我见过不止一个人在这个问题上浪费大量时间。3. 环境搭建实测一套能跑通IS-Fusion的版本组合环境搭建的核心经验是版本组合比最新版重要得多。IS-Fusion这类基于mmdetection3d老版本开发的工作对PyTorch和MMCV的版本极其敏感。装最新的PyTorch 2.x和mmcv 2.x反而会报一堆莫名其妙的错误老老实实装回老版本反而一切顺利。3.1 我实测可用的版本组合下面这套组合是我在3090和2080Ti上都验证过的可以作为基准参考组件推荐版本说明Python3.8最稳3.9也能跑但不是首选CUDA11.3和PyTorch 1.10对应PyTorch1.10.0不要用2.xtorchvision0.11.0和PyTorch严格对应mmcv-full1.6.0不要用mmcv 2.xmmdet2.25.1mmdet3d 1.0系列的配套版本mmsegmentation0.30.0mmseg 1.x不兼容mmdetection3dv1.0.0rc6IS-Fusion官方基于此分支开发spconv2.1.23点云体素化依赖版本敏感建议装环境之前先看一眼IS-Fusion官方仓库的requirements.txt里面的版本限制是最权威的。如果它明确写了某个包要某个版本就老老实实按那个装不要自由发挥。3.2 conda环境创建与安装步骤整个安装过程我就直接用代码块展示了每一步都有注释说明# 1. 创建conda环境Python版本用3.8 conda create -n isfusion python3.8 -y conda activate isfusion # 2. 安装PyTorch注意-cu113后缀对应CUDA 11.3 pip install torch1.10.0cu113 torchvision0.11.0cu113 \ -f https://download.pytorch.org/whl/torch_stable.html # 3. 验证PyTorch和GPU可用 python -c import torch; print(torch.__version__, torch.cuda.is_available())这里如果torch.cuda.is_available()返回False先检查nvidia-smi显示驱动是否正常再看CUDA toolkit版本。我遇到过一位朋友驱动版本太老虽然nvidia-smi能显示GPU但PyTorch无法识别最后升级驱动才解决。接着装mmcv-full# 4. 安装mmcv-full注意-f参数对应的torch和cuda版本要匹配 pip install mmcv-full1.6.0 \ -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html装完后验证一下python -c import mmcv; print(mmcv.__version__)再装mmdet和mmseg# 5. 安装mmdet和mmsegmentation pip install mmdet2.25.1 pip install mmsegmentation0.30.0然后从GitHub克隆IS-Fusion源码并安装。IS-Fusion的官方仓库可以从论文的项目主页进入也可以在GitHub上直接搜。clone下来之后git clone https://github.com/IS-Fusion仓库地址.git cd IS-Fusion pip install -r requirements.txt pip install -v -e .最后验证mmdet3d能否正常导入python -c import mmdet3d; print(mmdet3d.__version__)如果到这里没有报错环境已经完成了80%。剩下的20%在spconv。3.3 spconv整个环境里最坑的一环spconv是做点云体素化的核心库IS-Fusion的点云分支改成PointPillars或SECOND都需要它。这个库的版本兼容性问题非常突出官方轮子少、编译时间长卡住过不少人。先说结论优先用预编译wheel不要现场编译。针对PyTorch 1.10 CUDA 11.3的组合我测试过的有效安装方式是pip install spconv-cu113如果找不到spconv-cu113这个包名可以尝试在PyPI上搜索spconv对应的版本号或者到spconv官方release页面下载spconv-2.1.23-cp38-cp38-linux_x86_64.whl这种格式的轮子直接pip install。需要源码编译的场景问题多半出在gcc版本上。spconv和cummspconv的底层依赖对gcc版本要求严格实测把gcc降到7.x能解决大部分编译报错。编译时间大概在20-40分钟期间不要频繁打断否则缓存文件错乱更麻烦。安装完之后验证导入python -c import spconv; print(spconv.__version__)如果在导入mmdet3d后执行某个点云分支的模型构建时报SparseConvTensor相关的错误十有八九是spconv装成了2.x但代码按1.x接口写的或者反过来。这时候去IS-Fusion仓库看它源码里import spconv之后用的是spconv.SparseConv3d还是spconv.nn.SparseConv3d按实际调用习惯判断该装哪个大版本。3.4 编译安装时的高频报错与应对我整理了一下我自己和周围人实际遇到过的问题gcc: fatal error: cannot find -lxxx这种报错通常是系统缺少基础编译库先执行sudo apt update sudo apt install build-essential确认CUDA的软链接正常/usr/local/cuda要能正确指向你的CUDA安装目录。pip install -v -e .阶段如果是cuda.h: No such file or directory说明CUDA_HOME环境变量没设置正确export CUDA_HOME/usr/local/cuda-11.3 export PATH$CUDA_HOME/bin:$PATH export LD_LIBRARY_PATH$CUDA_HOME/lib64:$LD_LIBRARY_PATH把这些写进~/.bashrc重新source再重新安装。还有一种是mmcv-full版本和mmdet3d版本不匹配导致的ImportError比如cannot import name get_placeholder from mmcv.cnn。这种基本就是版本组合问题回到3.1的表格里核对一遍把版本对齐即可。4. Swin-Tiny预训练权重nuImages权重如何正确加载环境装好、数据准备好了接下来要解决的是swin-tiny在nuscenes的nuimages数据集上的预训练模型这个关键词对应的实际问题。这个权重文件是IS-Fusion图像分支的关键初始化加载不对后面训练效果会差很多。4.1 为什么必须用nuImages预训练而不是ImageNetIS-Fusion的图像骨干是Swin-Tinybackbone的初始权重对最终精度影响非常显著。直接用ImageNet预训练权重其实也能跑但经过对比实验效果和官方报告的差距会拉到2-3个点以上。原因很直白ImageNet是自然图像特征是通用的而nuImages数据集本身就是nuScenes同域的图片由车载环视相机采集包含大量车载场景中的道路、车辆、行人真实样本。用nuImages预训练的backbone特征分布和后续要处理的数据高度同源迁移起来自然更顺滑。所以在网络热词里搜swin-tiny在nuscenes的nuimages数据集上的预训练模型搜出来的东西实际指向的就是mmdetection官方模型库里的nuImages预训练模型。4.2 下载预训练权重并放到正确位置在mmdetection官方model zoo页面找到nuImages配置项对应的权重文件名是mask_rcnn_swin-t-p4-w7_fpn_1x_nuim.pth。这是用Mask R-CNN框架在nuImages上训练的Swin-Tiny权重大小在100多MB。下载后放到IS-Fusion项目目录下的checkpoints/文件夹里mkdir -p checkpoints mv mask_rcnn_swin-t-p4-w7_fpn_1x_nuim.pth checkpoints/然后改配置文件在配置尾部加一行load_from checkpoints/mask_rcnn_swin-t-p4-w7_fpn_1x_nuim.pth如果你用的是官方仓库里的现有配置它可能已经写好了load_from路径只需要把路径改成你实际存放的位置即可。4.3 加载时出现unexpected keys的解决思路直接加载mask_rcnn_swin-t-p4-w7_fpn_1x_nuim.pth这个完整权重文件大概率会在训练启动日志里看到类似这样的警告RuntimeError: Unexpected keys: mask_head.conv_1.weight, ...原因很容易理解这个权重是完整的Mask R-CNN模型权重里面除了backbone以外还有FPN、RPN、mask head、bbox head的参数而你的IS-Fusion模型里没有这些组件。mmdet3d加载器尝试把每个key都匹配到当前模型找不到对应的就报unexpected keys。最简单的解决办法是把这份权重转换成只包含backbone参数的版本import torch # 加载原始权重 ckpt torch.load(checkpoints/mask_rcnn_swin-t-p4-w7_fpn_1x_nuim.pth, map_locationcpu) # 只保留backbone参数 new_state_dict {k: v for k, v in ckpt[state_dict].items() if k.startswith(backbone.)} # 保存为新文件 torch.save({state_dict: new_state_dict}, checkpoints/swin_t_nuimg_backbone.pth)转换后的文件里保存的key保留了backbone.前缀比如backbone.layers.0.blocks.0.attn.w_msa.weight。如果IS-Fusion模型定义里backbone的字段名就是backbone那这样直接加载就能完美匹配。也可以考虑在backbone的init_cfg里指定checkpoint并声明prefixbackbone的方式这样更省事不需要手动转换。但如果你不想引入新的变量手动转换脚本是最直接可靠的。我实践中遇到过的另一个坑是转换之后torch.save保存的文件格式和mmcv加载器期望的格式不一致导致加载时显示没有state_dict键。解决办法很简单参照上面代码块确保保存的是一层{state_dict: new_state_dict}结构就行。加载后建议在配置里加一句日志级别的验证或者直接用mmcv的load_state_dict辅助函数打印对比一下key确保没有多出来的也没有缺掉的。这里的经验总结预训练权重的key匹配问题本质上不是环境问题而是权重组织格式问题排查思路是先转换、再验证、再训练千万不要跳过验证直接开训否则等训练跑了几小时才发现权重没加载成功损失的是自己的时间。5. 修改配置并启动训练从单卡到收敛观察数据、环境、权重都搞定之后终于到了启动训练这一步。这一章把所有配置修改点和训练启动命令讲清楚包括显存参考和收敛曲线怎么看。5.1 训练配置的必改项IS-Fusion的配置在项目configs/isfusion/目录下比较典型的是isfusion_swint_pillar_nusc.py。拿到配置后需要确认三处第一是数据路径。确认配置里的data_root字段指向./data/nuscenes/ann_file字段指向你刚生成的pkl文件data dict( traindict( ann_filedata/nuscenes/nuscenes_infos_train.pkl, ... ), valdict( ann_filedata/nuscenes/nuscenes_infos_val.pkl, ... ) )如果你之前生成的是mini版本的pkl注意对应关系。最容易犯的错就是pkl文件是mini版本但配置文件里写了全量版本的文件名导致启动时提示找不到文件或者索引越界。第二是预训练权重路径。这一步用上一章转换好的swin_t_nuimg_backbone.pthload_from checkpoints/swin_t_nuimg_backbone.pth第三是训练超参。默认配置通常设置24个epochbatch_size可能是2或4。如果你的GPU显存不是那么充裕建议先确认batch_size是否设成2或者4而不是直接改成更大的值。Is-Fusion的Swin-Tiny加PointPillars配置在24GB显存的3090上batch_size4可以跑但如果再加个更强的数据增强可能就会爆显存到时候再回去慢慢调参反而更浪费时间。5.2 启动训练命令单卡训练直接python tools/train.py configs/isfusion/isfusion_swint_pillar_nusc.py \ --work-dir work_dirs/isfusion_swint_pillar_nusc多卡训练用官方推荐的分布式训练脚本bash tools/dist_train.sh configs/isfusion/isfusion_swint_pillar_nusc.py 4后面那个4是你想要用的GPU卡数。启动后日志会先打印配置信息、加载预训练权重的信息如果加载成功一般不会有红色的错误输出。如果你看到类似loading checkpoint from ...和loaded keys: 123这样的信息说明权重加载正常。训练过程中建议打开一个终端窗口用nvidia-smi持续监控显存使用情况防止中途OOM了没人发现。我一般还会顺手开一个tensorboardtensorboard --logdir work_dirs/isfusion_swint_pillar_nusc/tf_logsmmdet3d默认会用tensorboard记录loss曲线浏览器打开训练时就能实时看到收敛情况。5.3 显存、速度与收敛观察我实测的参考值我在309024GB上实测batch_size4可以稳定跑动。训练速度方面大约每个epoch 15到20分钟24个epoch总耗时在6到8小时具体受CPU、内存带宽、数据读取速度影响会有出入。如果你用的是2080Ti12GB显存batch_size需要降到2每个epoch的时间会长一点但也能跑。收敛曲线方面loss在初期几个epoch会有明显波动这很正常。一般在第8到第10个epoch后开始快速下降之后进入平台期。验证集上的mAP和NDS在训练末尾会逐渐逼近论文报告的水平。我的复现最终mAP在68左右、NDS在71左右比论文略低一点但差距控制在合理范围内主要原因是数据增强细节和超参数不可能跟原作者完全一致。对复现来说这个结果已经足以说明实现基本正确。如果发现loss完全不下降或者训到一半飙了优先检查这些点模型是否加载了正确的预训练权重、学习率是否太大、batch_size是否正确同步、数据增强是否和配置一致。我遇到过一位朋友在跑之前把配置文件里的img_scale改成了很小的值图像分辨率降下来之后模型直接学不动改回去就好了。5.4 断点续训和checkpoint管理训练过程中work_dirs下会定期保存epoch_1.pth、epoch_2.pth这样的checkpoint文件。如果不小心中断了训练可以不用重头再来python tools/train.py configs/isfusion/isfusion_swint_pillar_nusc.py \ --resume-from work_dirs/isfusion_swint_pillar_nusc/epoch_10.pth检查文件一般包括模型权重、优化器状态、学习率调度器状态所以从断点恢复出来的训练曲线是连续的不会出现loss跳变。建议每跑5个epoch就手动备份一份关键checkpoint到别的磁盘防止意外删掉。6. 实测报错排查与IS-Fusion效果参考最后一章集中写我在整个过程中实际遇到的报错和排查思路。这些坑可能你也会踩到提前知道了能节省大量排查时间。6.1 高频报错与解决方案汇总报错现象可能原因解决方法No module named spconvspconv未安装或版本不对按第3.3节的预编译wheel方式安装对应版本CUDA out of memorybatch_size过大或输入尺寸过大调小batch_size或降低img_scale和voxel尺寸FileNotFoundError: ... nuscenes_infos_train.pklpkl文件路径不对确认配置文件里ann_file路径重新生成pklIndexError: index out of rangepkl数据版本与配置不匹配mini混用了全量配置统一数据版本重新生成pklRuntimeError: Unexpected keys: mask_head...预训练权重包含模型不需要的key按第4.3节转换权重或配置init_cfgAttributeError: ConfigDict object has no attribute...mmcv或mmdet版本不对对齐第3.1节的版本组合DataLoader worker (pid) is killed by signal: Bus error容器里/dev/shm太小加--shm-size参数重跑docker或减小workersdouble free or corruptionspconv和cumm版本不匹配重装与torch/CUDA对应版本的spconv6.2 一个典型排查链路mini pkl混用全量配置我踩过最久的一次坑不是环境问题而是数据问题。当时手头只有mini版本的nuScenes但配置文件里ann_file指向的是全量pkl名称。启动训练时没有报文件不存在的错误而是训练到一半validation的时候直接IndexError: index out of range。一开始我以为是模型代码有bug花了很长时间去翻融合模块的源码。后来把nuscenes_infos_val.pkl加载出来打印长度发现只有500多个样本但配置文件里认为应该有6000多个这才意识到是数据版本不匹配。重新用--version v1.0-mini生成pkl并修改配置文件路径后问题直接消失。这类数据与代码版本不匹配的问题相比环境问题更容易被忽略因为它的报错信息往往出现在深层调用栈里不会直接提示你是数据规模不对。遇到这种诡异报错先确认数据规模和预期一致再去怀疑模型代码这个排查顺序能省下大量脑细胞。6.3 训练低效或精度不达标的排查顺序如果训练能跑通但效果不理想我建议按这个优先级排查一是预训练权重是否真正加载成功。很多情况下权重路径写错但mmdet3d只是打一条warning不会终止训练结果跑完整个训练周期精度低得离谱这时候回头一看日志权重根本就没加载。所以启动训练前务必盯紧日志里load_from相关的输出。二是数据预处理链路是否正确。如果点云的体素尺寸、采样点数、图像尺寸和官方配置不一致输入分布已经变了模型学出来的东西自然不同。我一般会在训练前跑两三个step打印出batch里点云和图像的shape和配置文件期望值对比确认无误再放长了跑。三是超参数的合理性。学习率lr是首要检查项mmdet3d的配套优化器配置一般是lr2e-4量级如果改成了1e-3或者1e-5都可能让训练表现异常。其次是batch_size和lr的联动批量变大时要考虑学习率是否需要相应调整。6.4 跑完后的性能参考与后续方向模型训练完成后的验证方式是跑官方的评测脚本python tools/test.py configs/isfusion/isfusion_swint_pillar_nusc.py \ work_dirs/isfusion_swint_pillar_nusc/epoch_24.pth \ --eval mAP评测完会在终端打印出每个类别的mAP、NDS等指标。以我这边的实测来看Swin-Tiny PointPillars的组合复现的最终mAP在68左右、NDS在71左右这个数字低于论文报告值但对于个人复现来说属于正常范围。如果换成Swin-Tiny SECOND的骨干组合精度会略高一点代价是训练时间变长。Swin-L或者更大视觉效果的分支会更高但显存和训练时长会成倍增长不建议在一开始就尝试。从整体角度说IS-Fusion的复现难度属于中上——数据量大、版本繁琐、权重需要转换单任何一个环节都可能卡住几天。但如果愿意沉下心把链路走通你收获的不止是跑通一个配置而是对整个mmdetection3d生态、数据pkl生成机制、多模态特征融合流程都有了更清晰的理解。最后再分享一个小技巧如果你不打算用全量数据只想先验证代码跑通把配置文件里的max_epochs改成2batch_size改成1用mini数据集跑两个epoch几分钟就能看到日志流、loss下降和checkpoint保存这比一上来就跑全量要友好得多。等确认整条链路没问题再把数据换成全量、把epoch改回来正式开跑。 IS-Fusion复现全指南：多模态3D目标检测环境搭建与训练实战
前几天一个师弟问我现在复现多模态3D目标检测哪个工作性价比高。我直接推荐了IS-Fusion——ECCV 2024上的多模态融合方案核心思路是把场景级融合和实例级融合并行起来做比BEVFusion那种单纯BEV特征交互要精细不少。不过话说回来这项目虽然效果好环境搭建和数据准备却比单模态麻烦一个量级。最容易被卡住的三件事分别是MMDetection3D配套版本怎么选、Swin-Tiny在nuImages数据集上的预训练权重上哪找、nuScenes数据集的下载整理怎么做。这篇文章把我从零开始搭建IS-Fusion环境、准备nuScenes数据、最终跑通训练的全过程完整记下来包括版本组合、目录结构、配置修改、实际报错和排查思路给打算复现的朋友一份能直接照着走的参考。1. IS-Fusion在融合什么场景级与实例级的分工逻辑在敲任何命令之前先花十分钟搞清楚IS-Fusion的设计逻辑是值得的。这一步决定了你后面改配置、调参数时的方向感也能帮你遇到问题时分清楚到底是环境问题还是模型理解问题。1.1 三条主流多模态融合路线IS-Fusion走了第四条目前多模态3D目标检测的融合方式大致分三类。第一类是基于点的方法典型代表是DeepFusion这类工作通过深度估计或注意力机制把图像特征投影到3D空间在点或体素级别做特征拼接。这类方法的优点是特征对齐精度高缺点是计算量大图像特征在投影过程中容易丢失语义信息。第二类是BEV方案以BEVFusion为代表。思路是先通过LSSLift-Splat-Shoot或类似手段把图像特征提升到BEV空间点云也通过体素化编码成BEV特征然后统一在BEV坐标系里做特征拼接或者注意力交互。这类方法工程化程度高目前工业界落地案例最多但问题也明显——把图像提升到BEV时垂直方向的信息会被压缩远处小目标在BEV网格里可能连一个像素都占不满。第三类是query-based方案TransFusion是代表。它用一组可学习的目标query比如预设的200个anchor去索引图像和点云特征通过deformable attention动态聚合信息。这类方法解决了一部分目标尺度问题但query本身的设计和初始化对最终精度影响很大训练不稳定。IS-Fusion不属于其中任何一类。它把融合拆成两个层次——实例级和场景级——同时进行并且互相协同这是它区别于前作的关键。我在读论文的时候就注意到这个思路的动机其实很朴素场景级融合负责广实例级融合负责细两个层次互补才能覆盖不同尺度和场景下的需求。1.2 场景级与实例级的分工一个看全局一个扣细节场景级融合做的事情和BEVFusion类似在全局范围内让图像特征和点云BEV特征互相交互保证模型对整体场景布局、道路结构、远处环境有感知。如果不做这一层模型会丢掉大量上下文信息相当于一个近视眼只盯着眼前的目标看不看路。实例级融合则完全不一样。它先通过图像侧的2D检测或者分割分支定位到具体目标实例区域然后把这些区域内的图像特征与点云侧对应区域的3D特征做逐实例对齐和融合。为什么要这样做因为图像模态的优势在于丰富的纹理、颜色和类别语义信息点云模态的优势在于精确的几何位置信息把两者在实例这个颗粒度上对齐融合可以非常直接地互补。这两个层次不是简单的叠加关系而是协同关系。场景级融合产生的全局上下文可以作为实例级融合的先验帮助实例分支更准地定位目标区域反过来实例级融合提取到的目标级特征也可以反馈回场景级分支强化对特定区域的特征表达。我在实际跑完训练后对这种协同设计的感受是它比单纯堆叠多个融合模块要聪明——因为信息和信息之间真正发生了双向流动而不是各算各的。理解了这层逻辑你去看IS-Fusion源码里的网络结构就不会懵。图像分支用Swin-Tiny做骨干加FPN多尺度特征点云分支走体素化后用PointPillars或SECOND编码成BEV特征然后在中间插入了两个融合模块一个作用域是整个场景一个作用域是实例区域。配置文件里看到两个融合模块的参数时心里就有数了——一个是场景级的一个是实例级的。1.3 为什么官方实验选择nuScenes而不是KITTIIS-Fusion的官方实验主要在nuScenes上做这个选择本身也值得理解。KITTI虽然经典但只有前视单目相机加64线激光雷达场景相对简单目标类别也就车、人、自行车几类。nuScenes提供的是完整6相机环视图像加激光雷达加毫米波雷达覆盖了车载场景真正的复杂度——多视角一致性、目标遮挡、小目标密度都远超KITTI。多模态方法要发挥作用恰恰需要这种多视角、多类别、困难样本多的数据。如果只用KITTI这种相对简单的数据集场景级融合和实例级融合的差距很难体现出来。所以这篇文章后面所有操作都围绕nuScenes进行包括数据下载、目录结构、pkl生成全部以nuScenes为标准。2. nuScenes数据准备下载清单、目录结构与pkl生成数据准备是整个复现过程中最耗时、最劝退的环节没有之一。我第一次下载全量数据加整理花了整整一天。所以这一章把下载清单、目录结构、pkl生成三件事彻底讲透你照着做就能少走弯路。2.1 账号注册、API Token和下载工具nuScenes数据集不是直接给你下载链接的需要先在官网注册账号注册完成后在个人中心页面找到API token。这个token在调用下载工具时要用类似通行证。如果你的网络环境不太稳定下载中途断线是常事所以下载时最好配合能断点续传的工具。官方推荐的方式是安装nuScenes-devkit然后用python脚本下载命令大概是pip install nuscenes-devkit python -m nuscenes.scripts.download nuscenes_v1.0_trainval -c camera -o /data/nuscenes-c camera表示只下载相机图像你可以分别指定lidar、radar、maps、sweeps、canbus等包。这种方式的好处是支持断点续传缺点是单线程速度一般。我实际用下来更推荐直接用AWS命令行工具s5cmd批量下载速度能快好几倍。具体endpoint和bucket路径官方说明文档里会给照着填就行。命令格式大概长这样pip install s5cmd s5cmd --endpoint-url 官方给的endpoint sync 官方给的路径 /data/nuscenes/2.2 到底要下载哪些包需要多大空间很多人在这一步卡住是因为不知道应该下哪些包。下面这个清单是我实际测试过的最小可用集合包名内容是否必要v1.0-trainval场景标注和元数据JSON必须CAM_FRONT等6个相机包环视相机图像必须LIDAR_TOP激光雷达点云必须sweeps各传感器中间帧数据建议下载canbus车辆CAN总线数据建议下载maps语义地图可选RADAR 系列毫米波雷达数据可选IS-Fusion默认用不到完整下载下来在300GB左右如果加上sweeps接近350GB。磁盘空间紧张的话第一次建议先用mini版本跑通流程。mini数据集只有十几个场景全部加起来约10GB下载快、解压快、pkl生成也快适合用来验证环境是否搭建成功。我个人强烈建议的路线是先用mini版本把整条链路跑通确认环境没问题、配置能启动训练之后再下载全量数据。否则一上来就下300GB等下载完发现环境有问题心态很容易崩。2.3 目录结构规划一个软链接搞定下载解压完成后需要把数据整理成mmdetection3d认识的目录结构。标准的nuscenes目录长这样data/nuscenes/ ├── can_bus/ ├── maps/ ├── samples/ │ ├── CAM_FRONT/ │ ├── CAM_FRONT_LEFT/ │ ├── CAM_FRONT_RIGHT/ │ ├── CAM_BACK/ │ ├── CAM_BACK_LEFT/ │ ├── CAM_BACK_RIGHT/ │ └── LIDAR_TOP/ ├── sweeps/ │ ├── CAM_FRONT/ │ ├── CAM_FRONT_LEFT/ │ ├── .../ │ ├── RADAR.../ │ └── LIDAR_TOP/ └── v1.0-trainval/ ├── sample_annotation.json ├── sample_data.json ├── scene.json └── ...注意samples和sweeps这两个目录名是固定的大小写都不能错否则后续生成pkl时加载会找不到文件。maps目录在训练时其实用不到但保持完整性总归没坏处。目录解压好之后在IS-Fusion项目根目录下建软链接就行cd IS-Fusion mkdir -p data ln -s /path/to/your/nuscenes data/nuscenes这里有个容易踩的坑如果你把数据放在别的磁盘分区软链接之后mmdet3d内部如果用了相对路径解析偶尔会出现找不到文件的问题。我在实践中更推荐直接把整个nuscenes目录移动到项目下的data/目录里一步到位省去后面排查路径的麻烦。2.4 生成pkl索引文件create_data.pymmdetection3d训练的时候不是直接读原始数据而是先扫描整个数据集生成一份pkl索引文件里面记录了每个样本的图片路径、点云路径、标注信息、calib参数等等。这一步用mmdet3d自带的数据转换工具完成。cd IS-Fusion python tools/create_data.py nuscenes \ --root-path ./data/nuscenes \ --out-dir ./data/nuscenes \ --extra-tag nuscenes \ --version v1.0-trainval如果用的是mini版本把--version参数改成v1.0-minipython tools/create_data.py nuscenes \ --root-path ./data/nuscenes \ --out-dir ./data/nuscenes \ --extra-tag nuscenes \ --version v1.0-mini跑完会在data/nuscenes下生成nuscenes_infos_train.pkl和nuscenes_infos_val.pkl两个文件这就是后续训练配置里ann_file指向的文件。pkl生成过程的耗时取决于数据量mini版本几分钟搞定全量大概要半小时到一小时。生成后用下面这段代码验证一下内容是否正确import pickle with open(data/nuscenes/nuscenes_infos_val.pkl, rb) as f: infos pickle.load(f) print(len(infos[data_list])) print(infos[data_list][0][images].keys())能正常打印出样本数量和图像键名说明数据这一关过了。这里特别提醒一点pkl里的路径是生成时写入的绝对路径或相对路径生成后不要随意移动data目录否则所有路径失效只能重新生成。我见过不止一个人在这个问题上浪费大量时间。3. 环境搭建实测一套能跑通IS-Fusion的版本组合环境搭建的核心经验是版本组合比最新版重要得多。IS-Fusion这类基于mmdetection3d老版本开发的工作对PyTorch和MMCV的版本极其敏感。装最新的PyTorch 2.x和mmcv 2.x反而会报一堆莫名其妙的错误老老实实装回老版本反而一切顺利。3.1 我实测可用的版本组合下面这套组合是我在3090和2080Ti上都验证过的可以作为基准参考组件推荐版本说明Python3.8最稳3.9也能跑但不是首选CUDA11.3和PyTorch 1.10对应PyTorch1.10.0不要用2.xtorchvision0.11.0和PyTorch严格对应mmcv-full1.6.0不要用mmcv 2.xmmdet2.25.1mmdet3d 1.0系列的配套版本mmsegmentation0.30.0mmseg 1.x不兼容mmdetection3dv1.0.0rc6IS-Fusion官方基于此分支开发spconv2.1.23点云体素化依赖版本敏感建议装环境之前先看一眼IS-Fusion官方仓库的requirements.txt里面的版本限制是最权威的。如果它明确写了某个包要某个版本就老老实实按那个装不要自由发挥。3.2 conda环境创建与安装步骤整个安装过程我就直接用代码块展示了每一步都有注释说明# 1. 创建conda环境Python版本用3.8 conda create -n isfusion python3.8 -y conda activate isfusion # 2. 安装PyTorch注意-cu113后缀对应CUDA 11.3 pip install torch1.10.0cu113 torchvision0.11.0cu113 \ -f https://download.pytorch.org/whl/torch_stable.html # 3. 验证PyTorch和GPU可用 python -c import torch; print(torch.__version__, torch.cuda.is_available())这里如果torch.cuda.is_available()返回False先检查nvidia-smi显示驱动是否正常再看CUDA toolkit版本。我遇到过一位朋友驱动版本太老虽然nvidia-smi能显示GPU但PyTorch无法识别最后升级驱动才解决。接着装mmcv-full# 4. 安装mmcv-full注意-f参数对应的torch和cuda版本要匹配 pip install mmcv-full1.6.0 \ -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html装完后验证一下python -c import mmcv; print(mmcv.__version__)再装mmdet和mmseg# 5. 安装mmdet和mmsegmentation pip install mmdet2.25.1 pip install mmsegmentation0.30.0然后从GitHub克隆IS-Fusion源码并安装。IS-Fusion的官方仓库可以从论文的项目主页进入也可以在GitHub上直接搜。clone下来之后git clone https://github.com/IS-Fusion仓库地址.git cd IS-Fusion pip install -r requirements.txt pip install -v -e .最后验证mmdet3d能否正常导入python -c import mmdet3d; print(mmdet3d.__version__)如果到这里没有报错环境已经完成了80%。剩下的20%在spconv。3.3 spconv整个环境里最坑的一环spconv是做点云体素化的核心库IS-Fusion的点云分支改成PointPillars或SECOND都需要它。这个库的版本兼容性问题非常突出官方轮子少、编译时间长卡住过不少人。先说结论优先用预编译wheel不要现场编译。针对PyTorch 1.10 CUDA 11.3的组合我测试过的有效安装方式是pip install spconv-cu113如果找不到spconv-cu113这个包名可以尝试在PyPI上搜索spconv对应的版本号或者到spconv官方release页面下载spconv-2.1.23-cp38-cp38-linux_x86_64.whl这种格式的轮子直接pip install。需要源码编译的场景问题多半出在gcc版本上。spconv和cummspconv的底层依赖对gcc版本要求严格实测把gcc降到7.x能解决大部分编译报错。编译时间大概在20-40分钟期间不要频繁打断否则缓存文件错乱更麻烦。安装完之后验证导入python -c import spconv; print(spconv.__version__)如果在导入mmdet3d后执行某个点云分支的模型构建时报SparseConvTensor相关的错误十有八九是spconv装成了2.x但代码按1.x接口写的或者反过来。这时候去IS-Fusion仓库看它源码里import spconv之后用的是spconv.SparseConv3d还是spconv.nn.SparseConv3d按实际调用习惯判断该装哪个大版本。3.4 编译安装时的高频报错与应对我整理了一下我自己和周围人实际遇到过的问题gcc: fatal error: cannot find -lxxx这种报错通常是系统缺少基础编译库先执行sudo apt update sudo apt install build-essential确认CUDA的软链接正常/usr/local/cuda要能正确指向你的CUDA安装目录。pip install -v -e .阶段如果是cuda.h: No such file or directory说明CUDA_HOME环境变量没设置正确export CUDA_HOME/usr/local/cuda-11.3 export PATH$CUDA_HOME/bin:$PATH export LD_LIBRARY_PATH$CUDA_HOME/lib64:$LD_LIBRARY_PATH把这些写进~/.bashrc重新source再重新安装。还有一种是mmcv-full版本和mmdet3d版本不匹配导致的ImportError比如cannot import name get_placeholder from mmcv.cnn。这种基本就是版本组合问题回到3.1的表格里核对一遍把版本对齐即可。4. Swin-Tiny预训练权重nuImages权重如何正确加载环境装好、数据准备好了接下来要解决的是swin-tiny在nuscenes的nuimages数据集上的预训练模型这个关键词对应的实际问题。这个权重文件是IS-Fusion图像分支的关键初始化加载不对后面训练效果会差很多。4.1 为什么必须用nuImages预训练而不是ImageNetIS-Fusion的图像骨干是Swin-Tinybackbone的初始权重对最终精度影响非常显著。直接用ImageNet预训练权重其实也能跑但经过对比实验效果和官方报告的差距会拉到2-3个点以上。原因很直白ImageNet是自然图像特征是通用的而nuImages数据集本身就是nuScenes同域的图片由车载环视相机采集包含大量车载场景中的道路、车辆、行人真实样本。用nuImages预训练的backbone特征分布和后续要处理的数据高度同源迁移起来自然更顺滑。所以在网络热词里搜swin-tiny在nuscenes的nuimages数据集上的预训练模型搜出来的东西实际指向的就是mmdetection官方模型库里的nuImages预训练模型。4.2 下载预训练权重并放到正确位置在mmdetection官方model zoo页面找到nuImages配置项对应的权重文件名是mask_rcnn_swin-t-p4-w7_fpn_1x_nuim.pth。这是用Mask R-CNN框架在nuImages上训练的Swin-Tiny权重大小在100多MB。下载后放到IS-Fusion项目目录下的checkpoints/文件夹里mkdir -p checkpoints mv mask_rcnn_swin-t-p4-w7_fpn_1x_nuim.pth checkpoints/然后改配置文件在配置尾部加一行load_from checkpoints/mask_rcnn_swin-t-p4-w7_fpn_1x_nuim.pth如果你用的是官方仓库里的现有配置它可能已经写好了load_from路径只需要把路径改成你实际存放的位置即可。4.3 加载时出现unexpected keys的解决思路直接加载mask_rcnn_swin-t-p4-w7_fpn_1x_nuim.pth这个完整权重文件大概率会在训练启动日志里看到类似这样的警告RuntimeError: Unexpected keys: mask_head.conv_1.weight, ...原因很容易理解这个权重是完整的Mask R-CNN模型权重里面除了backbone以外还有FPN、RPN、mask head、bbox head的参数而你的IS-Fusion模型里没有这些组件。mmdet3d加载器尝试把每个key都匹配到当前模型找不到对应的就报unexpected keys。最简单的解决办法是把这份权重转换成只包含backbone参数的版本import torch # 加载原始权重 ckpt torch.load(checkpoints/mask_rcnn_swin-t-p4-w7_fpn_1x_nuim.pth, map_locationcpu) # 只保留backbone参数 new_state_dict {k: v for k, v in ckpt[state_dict].items() if k.startswith(backbone.)} # 保存为新文件 torch.save({state_dict: new_state_dict}, checkpoints/swin_t_nuimg_backbone.pth)转换后的文件里保存的key保留了backbone.前缀比如backbone.layers.0.blocks.0.attn.w_msa.weight。如果IS-Fusion模型定义里backbone的字段名就是backbone那这样直接加载就能完美匹配。也可以考虑在backbone的init_cfg里指定checkpoint并声明prefixbackbone的方式这样更省事不需要手动转换。但如果你不想引入新的变量手动转换脚本是最直接可靠的。我实践中遇到过的另一个坑是转换之后torch.save保存的文件格式和mmcv加载器期望的格式不一致导致加载时显示没有state_dict键。解决办法很简单参照上面代码块确保保存的是一层{state_dict: new_state_dict}结构就行。加载后建议在配置里加一句日志级别的验证或者直接用mmcv的load_state_dict辅助函数打印对比一下key确保没有多出来的也没有缺掉的。这里的经验总结预训练权重的key匹配问题本质上不是环境问题而是权重组织格式问题排查思路是先转换、再验证、再训练千万不要跳过验证直接开训否则等训练跑了几小时才发现权重没加载成功损失的是自己的时间。5. 修改配置并启动训练从单卡到收敛观察数据、环境、权重都搞定之后终于到了启动训练这一步。这一章把所有配置修改点和训练启动命令讲清楚包括显存参考和收敛曲线怎么看。5.1 训练配置的必改项IS-Fusion的配置在项目configs/isfusion/目录下比较典型的是isfusion_swint_pillar_nusc.py。拿到配置后需要确认三处第一是数据路径。确认配置里的data_root字段指向./data/nuscenes/ann_file字段指向你刚生成的pkl文件data dict( traindict( ann_filedata/nuscenes/nuscenes_infos_train.pkl, ... ), valdict( ann_filedata/nuscenes/nuscenes_infos_val.pkl, ... ) )如果你之前生成的是mini版本的pkl注意对应关系。最容易犯的错就是pkl文件是mini版本但配置文件里写了全量版本的文件名导致启动时提示找不到文件或者索引越界。第二是预训练权重路径。这一步用上一章转换好的swin_t_nuimg_backbone.pthload_from checkpoints/swin_t_nuimg_backbone.pth第三是训练超参。默认配置通常设置24个epochbatch_size可能是2或4。如果你的GPU显存不是那么充裕建议先确认batch_size是否设成2或者4而不是直接改成更大的值。Is-Fusion的Swin-Tiny加PointPillars配置在24GB显存的3090上batch_size4可以跑但如果再加个更强的数据增强可能就会爆显存到时候再回去慢慢调参反而更浪费时间。5.2 启动训练命令单卡训练直接python tools/train.py configs/isfusion/isfusion_swint_pillar_nusc.py \ --work-dir work_dirs/isfusion_swint_pillar_nusc多卡训练用官方推荐的分布式训练脚本bash tools/dist_train.sh configs/isfusion/isfusion_swint_pillar_nusc.py 4后面那个4是你想要用的GPU卡数。启动后日志会先打印配置信息、加载预训练权重的信息如果加载成功一般不会有红色的错误输出。如果你看到类似loading checkpoint from ...和loaded keys: 123这样的信息说明权重加载正常。训练过程中建议打开一个终端窗口用nvidia-smi持续监控显存使用情况防止中途OOM了没人发现。我一般还会顺手开一个tensorboardtensorboard --logdir work_dirs/isfusion_swint_pillar_nusc/tf_logsmmdet3d默认会用tensorboard记录loss曲线浏览器打开训练时就能实时看到收敛情况。5.3 显存、速度与收敛观察我实测的参考值我在309024GB上实测batch_size4可以稳定跑动。训练速度方面大约每个epoch 15到20分钟24个epoch总耗时在6到8小时具体受CPU、内存带宽、数据读取速度影响会有出入。如果你用的是2080Ti12GB显存batch_size需要降到2每个epoch的时间会长一点但也能跑。收敛曲线方面loss在初期几个epoch会有明显波动这很正常。一般在第8到第10个epoch后开始快速下降之后进入平台期。验证集上的mAP和NDS在训练末尾会逐渐逼近论文报告的水平。我的复现最终mAP在68左右、NDS在71左右比论文略低一点但差距控制在合理范围内主要原因是数据增强细节和超参数不可能跟原作者完全一致。对复现来说这个结果已经足以说明实现基本正确。如果发现loss完全不下降或者训到一半飙了优先检查这些点模型是否加载了正确的预训练权重、学习率是否太大、batch_size是否正确同步、数据增强是否和配置一致。我遇到过一位朋友在跑之前把配置文件里的img_scale改成了很小的值图像分辨率降下来之后模型直接学不动改回去就好了。5.4 断点续训和checkpoint管理训练过程中work_dirs下会定期保存epoch_1.pth、epoch_2.pth这样的checkpoint文件。如果不小心中断了训练可以不用重头再来python tools/train.py configs/isfusion/isfusion_swint_pillar_nusc.py \ --resume-from work_dirs/isfusion_swint_pillar_nusc/epoch_10.pth检查文件一般包括模型权重、优化器状态、学习率调度器状态所以从断点恢复出来的训练曲线是连续的不会出现loss跳变。建议每跑5个epoch就手动备份一份关键checkpoint到别的磁盘防止意外删掉。6. 实测报错排查与IS-Fusion效果参考最后一章集中写我在整个过程中实际遇到的报错和排查思路。这些坑可能你也会踩到提前知道了能节省大量排查时间。6.1 高频报错与解决方案汇总报错现象可能原因解决方法No module named spconvspconv未安装或版本不对按第3.3节的预编译wheel方式安装对应版本CUDA out of memorybatch_size过大或输入尺寸过大调小batch_size或降低img_scale和voxel尺寸FileNotFoundError: ... nuscenes_infos_train.pklpkl文件路径不对确认配置文件里ann_file路径重新生成pklIndexError: index out of rangepkl数据版本与配置不匹配mini混用了全量配置统一数据版本重新生成pklRuntimeError: Unexpected keys: mask_head...预训练权重包含模型不需要的key按第4.3节转换权重或配置init_cfgAttributeError: ConfigDict object has no attribute...mmcv或mmdet版本不对对齐第3.1节的版本组合DataLoader worker (pid) is killed by signal: Bus error容器里/dev/shm太小加--shm-size参数重跑docker或减小workersdouble free or corruptionspconv和cumm版本不匹配重装与torch/CUDA对应版本的spconv6.2 一个典型排查链路mini pkl混用全量配置我踩过最久的一次坑不是环境问题而是数据问题。当时手头只有mini版本的nuScenes但配置文件里ann_file指向的是全量pkl名称。启动训练时没有报文件不存在的错误而是训练到一半validation的时候直接IndexError: index out of range。一开始我以为是模型代码有bug花了很长时间去翻融合模块的源码。后来把nuscenes_infos_val.pkl加载出来打印长度发现只有500多个样本但配置文件里认为应该有6000多个这才意识到是数据版本不匹配。重新用--version v1.0-mini生成pkl并修改配置文件路径后问题直接消失。这类数据与代码版本不匹配的问题相比环境问题更容易被忽略因为它的报错信息往往出现在深层调用栈里不会直接提示你是数据规模不对。遇到这种诡异报错先确认数据规模和预期一致再去怀疑模型代码这个排查顺序能省下大量脑细胞。6.3 训练低效或精度不达标的排查顺序如果训练能跑通但效果不理想我建议按这个优先级排查一是预训练权重是否真正加载成功。很多情况下权重路径写错但mmdet3d只是打一条warning不会终止训练结果跑完整个训练周期精度低得离谱这时候回头一看日志权重根本就没加载。所以启动训练前务必盯紧日志里load_from相关的输出。二是数据预处理链路是否正确。如果点云的体素尺寸、采样点数、图像尺寸和官方配置不一致输入分布已经变了模型学出来的东西自然不同。我一般会在训练前跑两三个step打印出batch里点云和图像的shape和配置文件期望值对比确认无误再放长了跑。三是超参数的合理性。学习率lr是首要检查项mmdet3d的配套优化器配置一般是lr2e-4量级如果改成了1e-3或者1e-5都可能让训练表现异常。其次是batch_size和lr的联动批量变大时要考虑学习率是否需要相应调整。6.4 跑完后的性能参考与后续方向模型训练完成后的验证方式是跑官方的评测脚本python tools/test.py configs/isfusion/isfusion_swint_pillar_nusc.py \ work_dirs/isfusion_swint_pillar_nusc/epoch_24.pth \ --eval mAP评测完会在终端打印出每个类别的mAP、NDS等指标。以我这边的实测来看Swin-Tiny PointPillars的组合复现的最终mAP在68左右、NDS在71左右这个数字低于论文报告值但对于个人复现来说属于正常范围。如果换成Swin-Tiny SECOND的骨干组合精度会略高一点代价是训练时间变长。Swin-L或者更大视觉效果的分支会更高但显存和训练时长会成倍增长不建议在一开始就尝试。从整体角度说IS-Fusion的复现难度属于中上——数据量大、版本繁琐、权重需要转换单任何一个环节都可能卡住几天。但如果愿意沉下心把链路走通你收获的不止是跑通一个配置而是对整个mmdetection3d生态、数据pkl生成机制、多模态特征融合流程都有了更清晰的理解。最后再分享一个小技巧如果你不打算用全量数据只想先验证代码跑通把配置文件里的max_epochs改成2batch_size改成1用mini数据集跑两个epoch几分钟就能看到日志流、loss下降和checkpoint保存这比一上来就跑全量要友好得多。等确认整条链路没问题再把数据换成全量、把epoch改回来正式开跑。