做3D目标检测的人多少都被mmdetection3d的环境配置折磨过。这个项目本身很好用但它的环境依赖链条之长、版本耦合之紧几乎是我见过所有开源项目里数一数二的。每次有人问我“为什么我明明照着官方文档装最后还是import报错”我基本都能猜到问题出在哪儿——八成是mmcv和PyTorch版本对不上或者spconv编译出的问题。这篇内容不适合完全没有接触过深度学习环境的人但只要你装过PyTorch、搞过conda跟着下面的思路走基本可以一次装通少走我当年踩过的那些弯路。我自己从mmdetection3d 0.x时代就开始用后来1.0版本大改又把环境翻新了一遍中间踩过无数坑。这篇文章我尽量把“为什么要这么做”讲清楚而不是只给你一堆死命令。毕竟版本一更新死命令就失效了但背后的匹配逻辑和排查方法你可以一直用下去。1. 动手之前先理清这个项目的依赖链条1.1 为什么环境这么难配难点到底在哪mmdetection3d不是个孤立项目它建立在整整一摞底层库之上。用一句话说它是“站在其他开源框架肩膀上的框架”。它的直接父依赖是mmdetection2D目标检测库和mmsegmentation语义分割库而这两个库又要跑在mmcv这个底层视觉基础库上mmcv又依赖PyTorchPyTorch又依赖CUDA和显卡驱动。这条链子只要有一环版本不匹配整个就崩了。最典型的例子就是mmcvmmcv分两个版本线老版本叫mmcv-full新版本直接把mmcv-full合并进mmcv了。每个mmcv版本官网只预编译了特定PyTorch和CUDA组合的包如果你用了一个没预编译的组合就得从源码现场编译而源码编译mmcv动不动就要半小时以上中途还可能因为内存不足、编译器太老、网络中断等原因失败。我见过很多人在这一步放弃的。其实不是动手能力差而是没搞明白“版本匹配”和“编译工具链”这两个关键点。1.2 版本兼容表怎么看我的推荐组合官方在文档里给过一个兼容矩阵列了mmdet、mmseg、mmcv、PyTorch、Python几个维度的版本对应关系。这里我直接给两个时代、几组被大量验证过的组合你们照着抄就行。第一类是比较稳的旧版组合适合还在用老代码、或者显卡驱动老一点的环境组件旧版推荐新版推荐Python3.73.8 / 3.9PyTorch1.8.0 / 1.10.01.13.0 / 2.0.0CUDA11.1 / 11.311.7 / 11.8mmcv-full / mmcv1.4.2 / 1.6.02.0.0 / 2.1.0mmdet2.14.0 / 2.24.03.1.0 / 3.2.0mmsegmentation0.14.1 / 0.20.21.0.0 / 1.2.0mmdetection3d0.17.2 / 0.18.11.0.0rc6 / 1.1.1我可以直接告诉你只要你不是在跑很特殊的老模型就直接选新版组合装起来反而省心。新版不再强制spconv1.x源码编译很多稀疏卷积操作可以直接用mmcv内置算子了而且新版用mim工具一条命令就能装mmcv能下载预编译包就别自己编译这是最重要的省时诀窍。注意显卡驱动版本不要太老。哪怕你只在CPU跑数据预处理后面只要一装GPU版的PyTorch驱动不支持就会直接提示CUDA driver version is insufficient。建议先把nvidia-smi里显示的CUDA版本查出来只要大于等于你目标CUDA版本就行。1.3 我的推荐组合背后的选择逻辑很多人纠结“到底选哪一版CUDA”其实只要显卡驱动支持选哪一版差别不大。真正要考虑的是生态兼容你后面还要不要装spconvspconv2要求PyTorch 1.13以上要不要装open3dopen3d新版本对Python 3.10以上就不太友好。所以我的建议是Python 3.8 PyTorch 1.13 CUDA 11.7这是目前平衡性最好的组合。PyTorch 2.0也可以用但我遇到过一次mmcv源码编译时与TorchScript的兼容问题虽然最终解决了但没必要让新手一上来就打这种怪。2. 一步步搭建环境从零到可运行2.1 创建虚拟环境与基础依赖任何项目都建议用conda虚拟环境隔离尤其是mmdetection3d这种依赖一大堆的跟别的项目混在一起迟早会炸。创建环境这一步很简单conda create -n mm3d python3.8 -y conda activate mm3d然后先装一些基础依赖。这里有个小窍门先把numpy装好不要依赖后装的PyTorch顺手带出来的numpy版本。因为PyTorch不同版本会锁numpy版本范围如果让它自动装有可能装出一个跟你后面其他库不兼容的numpy。提前用一个单独命令装好可以避免很多玄学问题。pip install numpy1.23.5 cython wheelCython一定要提前装。我见过太多人在编译spconv的时候报No module named Cython就是因为没提前装结果编译流程跑到一半戛然而止。先装好后面至少少踩一个坑。2.2 PyTorch安装这一步别用默认pip源PyTorch的安装推荐直接用官方命令。这里最容易犯的错误是直接pip install torch这样装到的通常是CPU版或某个固定CUDA版跟你想的不一定一样。要指定CUDA版本去官方PyTorch官网找对应命令即可pip install torch1.13.0 torchvision0.14.0 --extra-index-url https://download.pytorch.org/whl/cu117如果你在国内网络环境建议给pip配好国内镜像源但上面的--extra-index-url不要去掉。我试过只配镜像装PyTorch结果装出来是CPU版白白折腾了一晚上。装完后立刻验证一下python -c import torch; print(torch.__version__); print(torch.cuda.is_available())如果输出False先别怀疑显卡先看看是不是装了CPU版确认不是之后再看驱动版本。这是一个非常基础的排查顺序很多人一上来就怀疑CUDA没装好其实90%的情况是包版本的问题。2.3 安装mmcv决定成败的关键一步mmcv是整套环境里最脆弱的一环。新版项目推荐直接用mim来装mim能自动匹配当前PyTorch和CUDA版本对应的预编译mmcv包省去手工查表的麻烦pip install openmim mim install mmcv2.1.0如果mim找不到你当前PyTorch/CUDA对应的预编译包它会提示你需要源码编译这时别慌源码编译也只能接受。但编译前有几个环境变量必须设好不然容易翻车。首先设置FORCE_CUDA1强制按CUDA模式编译其次设置TORCH_CUDA_ARCH_LIST这个变量千万别跳过它会告诉编译器你的显卡计算能力是什么。如果没设编译器会一个个尝试支持所有常见架构极其耗时而且可能在其中一个架构上编译失败导致整体失败。查自己显卡算力可以用nvidia-smi配合网络搜索也可以通过下面的命令import torch print(torch.cuda.get_device_capability())得到类似(7, 5)返回就设置成TORCH_CUDA_ARCH_LIST7.5。然后源码编译export FORCE_CUDA1 export TORCH_CUDA_ARCH_LIST7.5 pip install mmcv2.1.0编译期间不要动终端别同时开大量占内存的程序。编译到一半内存爆炸的情况我也遇到过加了MAX_JOBS4来限制并发后就好多了export MAX_JOBS4注意mmcv源码编译完不代表万事大吉建议编译后立刻测一下import mmcv再跑一个小的算子测试确认GPU版本生效别等到后面跑训练才发现装的是CPU版。2.4 安装mmdet和mmsegmentationmmcv装好之后mmdet和mmsegmentation就是常规安装了直接pip即可。新版组合我推荐pip install mmdet3.2.0 pip install mmsegmentation1.2.0这里有个我踩过的坑不建议直接安装最新版。mmdet的某个新小版本曾经和mmcv 2.1.0配合时出了一个算子兼容问题导致训练时直接报RuntimeError。老老实实按兼容表选版本比追新稳妥得多。如果用的是0.x时代的mmdet3d配旧版mmdet注意老版本还会依赖mmcv-full而不是mmcv这是两个不同的包千万别混着装。我在0.17.2时代见过有人先装了新版mmcv再装老版mmcg-full结果两个包互相覆盖最后整个环境坏掉。旧项目就用老版本组合不要混搭。2.5 安装mmdetection3d本体这一步建议直接git clone源码然后本地instal而不是用pip安装预编译包。原因在于第一你后面很可能要改源码或者看源码第二本地装会执行setup脚本把编译选项、路径信息等配置好更稳定。git clone https://github.com/open-mmlab/mmdetection3d.git cd mmdetection3d pip install -e .-e表示editable模式也就是说源码改动会即时反映到环境里方便调试。如果想加深对项目的理解我建议你在这之后自己把mmdet3d目录下的结构翻一遍看看models、datasets、apis这些模块的划分后面调试模型时会很有帮助。3. 验证安装跑第一个Demo之前必做的检查3.1 环境自检清单很多人装完所有包之后迫不及待去跑demo结果报错一个一个蹦出来。我的建议是先跑一段综合自检脚本把每个关键库挨个import一遍确认版本号再动手python -c import torch; print(torch, torch.__version__) python -c import mmcv; print(mmcv, mmcv.__version__) python -c import mmdet; print(mmdet, mmdet.__version__) python -c import mmseg; print(mmseg, mmseg.__version__) python -c import mmdet3d; print(mmdet3d, mmdet3d.__version__)每个库的版本号都要对上兼容表。如果哪个版本有出入优先卸载重装那个库而不是继续往下走不然等下报错更本找不到原因。3.2 跑通官方Demo下载权重可视化点云检测结果验证完import下一步就是用官方提供的点云demo走一遍真实检测流程。mmdetection3d仓库里自带了demo数据和一个可视化工脚本。新版项目的demo入口在demo/pcd_demo.py。你可以先手动下载一个点云测试文件比如KITTI的某个bin格式点云文件然后下载对应的模型权重mim download mmdet3d --config pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class --dest ./checkpoints这一步mim会自动读取模型配置并下载对应权重。然后执行python demo/pcd_demo.py demo/data/kitti/kitti_000008.bin \ configs/pointpillars/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class.py \ checkpoints/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class.pth \ --out-file result.png看到输出的result.png里出现带有3D检测框的可视化结果说明你的mmdetection3d从安装到推理整体通了。对我而言这一步比任何文字版本对照表都让人放心因为它验证了整个链路数据读取、模型加载、CUDA算子调用、后处理可视化。3.3 跑一个小小的训练脚本验证反传推理通了不代表训练能用。有些人推理没问题一到训练就报错原因是训练涉及损失函数反传而反传用到的某些算子覆盖了不同分支。建议在跑完demo后随便挑一个小数据集配置比如KITTI的PointPillars把迭代次数改小到2跑几个iteration看loss能不能正常下降python tools/train.py configs/pointpillars/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class.py --work-dir ./test_train记得先改配置文件里的runner或max_epochs把时间控制在一两分钟。如果这一步也能顺利跑完恭喜你环境是真的通了可以放心去训模型了。4. 常见问题与排查技巧实录4.1 高频报错速查表我把平时帮别人排查时遇到的高频问题整理成一张表格基本都是那些翻来覆去出现的版本冲突和编译问题报错信息常见原因解决方案AssertionError: MMCVxxx is used but incompatiblemmcv版本与mmdet/mmdet3d不匹配按兼容表卸载重装对应版本ModuleNotFoundError: No module named mmcv环境装错或没用对应conda环境检查pip list里的mmcv是否存在ImportError: libcudart.so.xxx: cannot openCUDA版本不一致或LD_LIBRARY_PATH缺失确认PyTorch对应CUDA与系统驱动兼容RuntimeError: CUDA error: no kernel image is availableCUDA版本与显卡算力不匹配重新编译mmcv并正确设置TORCH_CUDA_ARCH_LISTModuleNotFoundError: No module named Cython编译前未装Cython先pip install cython再重新安装依赖包Segmentation fault直接崩溃常见于spconv1.x版本或数据加载线程冲突检查是否用的mmcv内置稀疏卷积或减少DataLoader线程数训练时loss为NaN学习率过大或数据预处理异常调整学习率检查点云坐标、归一化参数AttributeError: module mmcv has no attribute opsmmcv旧版没有新版ops模块升级mmcv或修改代码兼容旧版4.2 spconv相关问题的完整处理流程spconv是mmdetection3d老版本中绕不开的痛。如果你是旧版配置spconv1.x源码编译几乎成了标配而编译它的报错花样极多。我总结下来编译spconv成功的关键有四点一是提前装好Cython和pybind11二是在编译前先import一次torch让torch的头文件路径被正确识别三是编译器版本不能太老GCC太低直接编不过四是内存要足编译spconv时峰值内存能到8GB以上。如果你实在不想受这个罪有两个替代方案第一新版mmdetection3d不再强依赖spconv1.x很多模型可以直接用mmcv的稀疏卷积实现那你干脆别装spconv了第二直接装spconv2它的预编译包覆盖面更广pip安装就行编译时间比spconv1.x短得多。4.3 数据加载卡死与内存溢出的排查思路训练或验证时卡在数据加载阶段是另一个高频问题。我遇到过一个典型案例程序在读取KITTI数据时直接卡死但没有报任何错。最后排查发现不是代码问题而是DataLoader的num_workers设得太高加上共享内存不足多进程之间打起来了。解决办法很简单把num_workers调小或者减少每个worker的预取数量。还有一个常见情况是验证时显卡显存溢出一上来就把batch size拉到模型极限导致OOM。建议先用batch size1跑通一个迭代再逐步增加batch size直到找到合适值。4.4 老版本项目升级到新版本时的匹配问题每次mmdetection3d大版本升级都会带来一大堆配置破坏。从0.x升到1.0的时候光改名就有几十处比如mmdet3d.models下的很多类名变了configs目录结构也调整了。如果你手上有一个老项目要升级我的建议是别在旧环境上打补丁直接新建一个conda环境装新版组合然后把config文件和自定义模型代码逐步迁移。这样至少能保证新环境的干净出问题也好排查。迁移的时候对照官方的upgrade文档逐项改不要跳过。5. 一些实操心得与最后的建议5.1 多版本环境管理的最佳实践搞3D检测的手头大概率不止一个项目需要维护老模型可能要0.17.2的环境新模型用1.x的环境。电脑配置够的话建议给每个大版本单独建一个conda环境命名带上版本号比如mm3d_017、mm3d_100。这样看似占用空间大一点实际上能避免大量隐性冲突。之前我图省事在一个环境里既跑0.18又跑1.0来回卸载重装最后把什么搞坏了都不知道。conda环境名是免费的多建几个真的不亏。5.2 环境配置的最终建议记录你的成功路径装成功一次之后把你的安装命令和版本号全部记录下来。我自己的习惯是在项目目录下放一份install.sh把从conda create开始的每一步命令都固化下来同时注明这份脚本验证过的版本组合。好处是下次换电脑或者给同事部署的时候一条命令就能复现不用再趟一遍坑。我也建议你顺手记录一下nvcc -V、nvidia-smi、python -c import torch; print(torch.__version__)这几个输出关键时刻排查问题能省很多事。mmdetection3d的环境配置说到底就三个核心版本匹配、源码编译选项、以及“先跑通小流程再上大流程”的验证思路。只要这三条思路在哪怕以后版本组合变了你也能自己解决。最后再分享一个小技巧所有mm系列项目的环境问题优先去官方文档看“安装”和“常见问题”两节绝大多数报错都能找到对应说明比直接在社区里发帖问要快得多。 
长河君 · 2026/10/22 5:23:20 · 阅读 1.2k mmdetection3d环境配置全攻略：版本匹配与编译避坑指南
做3D目标检测的人多少都被mmdetection3d的环境配置折磨过。这个项目本身很好用但它的环境依赖链条之长、版本耦合之紧几乎是我见过所有开源项目里数一数二的。每次有人问我“为什么我明明照着官方文档装最后还是import报错”我基本都能猜到问题出在哪儿——八成是mmcv和PyTorch版本对不上或者spconv编译出的问题。这篇内容不适合完全没有接触过深度学习环境的人但只要你装过PyTorch、搞过conda跟着下面的思路走基本可以一次装通少走我当年踩过的那些弯路。我自己从mmdetection3d 0.x时代就开始用后来1.0版本大改又把环境翻新了一遍中间踩过无数坑。这篇文章我尽量把“为什么要这么做”讲清楚而不是只给你一堆死命令。毕竟版本一更新死命令就失效了但背后的匹配逻辑和排查方法你可以一直用下去。1. 动手之前先理清这个项目的依赖链条1.1 为什么环境这么难配难点到底在哪mmdetection3d不是个孤立项目它建立在整整一摞底层库之上。用一句话说它是“站在其他开源框架肩膀上的框架”。它的直接父依赖是mmdetection2D目标检测库和mmsegmentation语义分割库而这两个库又要跑在mmcv这个底层视觉基础库上mmcv又依赖PyTorchPyTorch又依赖CUDA和显卡驱动。这条链子只要有一环版本不匹配整个就崩了。最典型的例子就是mmcvmmcv分两个版本线老版本叫mmcv-full新版本直接把mmcv-full合并进mmcv了。每个mmcv版本官网只预编译了特定PyTorch和CUDA组合的包如果你用了一个没预编译的组合就得从源码现场编译而源码编译mmcv动不动就要半小时以上中途还可能因为内存不足、编译器太老、网络中断等原因失败。我见过很多人在这一步放弃的。其实不是动手能力差而是没搞明白“版本匹配”和“编译工具链”这两个关键点。1.2 版本兼容表怎么看我的推荐组合官方在文档里给过一个兼容矩阵列了mmdet、mmseg、mmcv、PyTorch、Python几个维度的版本对应关系。这里我直接给两个时代、几组被大量验证过的组合你们照着抄就行。第一类是比较稳的旧版组合适合还在用老代码、或者显卡驱动老一点的环境组件旧版推荐新版推荐Python3.73.8 / 3.9PyTorch1.8.0 / 1.10.01.13.0 / 2.0.0CUDA11.1 / 11.311.7 / 11.8mmcv-full / mmcv1.4.2 / 1.6.02.0.0 / 2.1.0mmdet2.14.0 / 2.24.03.1.0 / 3.2.0mmsegmentation0.14.1 / 0.20.21.0.0 / 1.2.0mmdetection3d0.17.2 / 0.18.11.0.0rc6 / 1.1.1我可以直接告诉你只要你不是在跑很特殊的老模型就直接选新版组合装起来反而省心。新版不再强制spconv1.x源码编译很多稀疏卷积操作可以直接用mmcv内置算子了而且新版用mim工具一条命令就能装mmcv能下载预编译包就别自己编译这是最重要的省时诀窍。注意显卡驱动版本不要太老。哪怕你只在CPU跑数据预处理后面只要一装GPU版的PyTorch驱动不支持就会直接提示CUDA driver version is insufficient。建议先把nvidia-smi里显示的CUDA版本查出来只要大于等于你目标CUDA版本就行。1.3 我的推荐组合背后的选择逻辑很多人纠结“到底选哪一版CUDA”其实只要显卡驱动支持选哪一版差别不大。真正要考虑的是生态兼容你后面还要不要装spconvspconv2要求PyTorch 1.13以上要不要装open3dopen3d新版本对Python 3.10以上就不太友好。所以我的建议是Python 3.8 PyTorch 1.13 CUDA 11.7这是目前平衡性最好的组合。PyTorch 2.0也可以用但我遇到过一次mmcv源码编译时与TorchScript的兼容问题虽然最终解决了但没必要让新手一上来就打这种怪。2. 一步步搭建环境从零到可运行2.1 创建虚拟环境与基础依赖任何项目都建议用conda虚拟环境隔离尤其是mmdetection3d这种依赖一大堆的跟别的项目混在一起迟早会炸。创建环境这一步很简单conda create -n mm3d python3.8 -y conda activate mm3d然后先装一些基础依赖。这里有个小窍门先把numpy装好不要依赖后装的PyTorch顺手带出来的numpy版本。因为PyTorch不同版本会锁numpy版本范围如果让它自动装有可能装出一个跟你后面其他库不兼容的numpy。提前用一个单独命令装好可以避免很多玄学问题。pip install numpy1.23.5 cython wheelCython一定要提前装。我见过太多人在编译spconv的时候报No module named Cython就是因为没提前装结果编译流程跑到一半戛然而止。先装好后面至少少踩一个坑。2.2 PyTorch安装这一步别用默认pip源PyTorch的安装推荐直接用官方命令。这里最容易犯的错误是直接pip install torch这样装到的通常是CPU版或某个固定CUDA版跟你想的不一定一样。要指定CUDA版本去官方PyTorch官网找对应命令即可pip install torch1.13.0 torchvision0.14.0 --extra-index-url https://download.pytorch.org/whl/cu117如果你在国内网络环境建议给pip配好国内镜像源但上面的--extra-index-url不要去掉。我试过只配镜像装PyTorch结果装出来是CPU版白白折腾了一晚上。装完后立刻验证一下python -c import torch; print(torch.__version__); print(torch.cuda.is_available())如果输出False先别怀疑显卡先看看是不是装了CPU版确认不是之后再看驱动版本。这是一个非常基础的排查顺序很多人一上来就怀疑CUDA没装好其实90%的情况是包版本的问题。2.3 安装mmcv决定成败的关键一步mmcv是整套环境里最脆弱的一环。新版项目推荐直接用mim来装mim能自动匹配当前PyTorch和CUDA版本对应的预编译mmcv包省去手工查表的麻烦pip install openmim mim install mmcv2.1.0如果mim找不到你当前PyTorch/CUDA对应的预编译包它会提示你需要源码编译这时别慌源码编译也只能接受。但编译前有几个环境变量必须设好不然容易翻车。首先设置FORCE_CUDA1强制按CUDA模式编译其次设置TORCH_CUDA_ARCH_LIST这个变量千万别跳过它会告诉编译器你的显卡计算能力是什么。如果没设编译器会一个个尝试支持所有常见架构极其耗时而且可能在其中一个架构上编译失败导致整体失败。查自己显卡算力可以用nvidia-smi配合网络搜索也可以通过下面的命令import torch print(torch.cuda.get_device_capability())得到类似(7, 5)返回就设置成TORCH_CUDA_ARCH_LIST7.5。然后源码编译export FORCE_CUDA1 export TORCH_CUDA_ARCH_LIST7.5 pip install mmcv2.1.0编译期间不要动终端别同时开大量占内存的程序。编译到一半内存爆炸的情况我也遇到过加了MAX_JOBS4来限制并发后就好多了export MAX_JOBS4注意mmcv源码编译完不代表万事大吉建议编译后立刻测一下import mmcv再跑一个小的算子测试确认GPU版本生效别等到后面跑训练才发现装的是CPU版。2.4 安装mmdet和mmsegmentationmmcv装好之后mmdet和mmsegmentation就是常规安装了直接pip即可。新版组合我推荐pip install mmdet3.2.0 pip install mmsegmentation1.2.0这里有个我踩过的坑不建议直接安装最新版。mmdet的某个新小版本曾经和mmcv 2.1.0配合时出了一个算子兼容问题导致训练时直接报RuntimeError。老老实实按兼容表选版本比追新稳妥得多。如果用的是0.x时代的mmdet3d配旧版mmdet注意老版本还会依赖mmcv-full而不是mmcv这是两个不同的包千万别混着装。我在0.17.2时代见过有人先装了新版mmcv再装老版mmcg-full结果两个包互相覆盖最后整个环境坏掉。旧项目就用老版本组合不要混搭。2.5 安装mmdetection3d本体这一步建议直接git clone源码然后本地instal而不是用pip安装预编译包。原因在于第一你后面很可能要改源码或者看源码第二本地装会执行setup脚本把编译选项、路径信息等配置好更稳定。git clone https://github.com/open-mmlab/mmdetection3d.git cd mmdetection3d pip install -e .-e表示editable模式也就是说源码改动会即时反映到环境里方便调试。如果想加深对项目的理解我建议你在这之后自己把mmdet3d目录下的结构翻一遍看看models、datasets、apis这些模块的划分后面调试模型时会很有帮助。3. 验证安装跑第一个Demo之前必做的检查3.1 环境自检清单很多人装完所有包之后迫不及待去跑demo结果报错一个一个蹦出来。我的建议是先跑一段综合自检脚本把每个关键库挨个import一遍确认版本号再动手python -c import torch; print(torch, torch.__version__) python -c import mmcv; print(mmcv, mmcv.__version__) python -c import mmdet; print(mmdet, mmdet.__version__) python -c import mmseg; print(mmseg, mmseg.__version__) python -c import mmdet3d; print(mmdet3d, mmdet3d.__version__)每个库的版本号都要对上兼容表。如果哪个版本有出入优先卸载重装那个库而不是继续往下走不然等下报错更本找不到原因。3.2 跑通官方Demo下载权重可视化点云检测结果验证完import下一步就是用官方提供的点云demo走一遍真实检测流程。mmdetection3d仓库里自带了demo数据和一个可视化工脚本。新版项目的demo入口在demo/pcd_demo.py。你可以先手动下载一个点云测试文件比如KITTI的某个bin格式点云文件然后下载对应的模型权重mim download mmdet3d --config pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class --dest ./checkpoints这一步mim会自动读取模型配置并下载对应权重。然后执行python demo/pcd_demo.py demo/data/kitti/kitti_000008.bin \ configs/pointpillars/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class.py \ checkpoints/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class.pth \ --out-file result.png看到输出的result.png里出现带有3D检测框的可视化结果说明你的mmdetection3d从安装到推理整体通了。对我而言这一步比任何文字版本对照表都让人放心因为它验证了整个链路数据读取、模型加载、CUDA算子调用、后处理可视化。3.3 跑一个小小的训练脚本验证反传推理通了不代表训练能用。有些人推理没问题一到训练就报错原因是训练涉及损失函数反传而反传用到的某些算子覆盖了不同分支。建议在跑完demo后随便挑一个小数据集配置比如KITTI的PointPillars把迭代次数改小到2跑几个iteration看loss能不能正常下降python tools/train.py configs/pointpillars/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class.py --work-dir ./test_train记得先改配置文件里的runner或max_epochs把时间控制在一两分钟。如果这一步也能顺利跑完恭喜你环境是真的通了可以放心去训模型了。4. 常见问题与排查技巧实录4.1 高频报错速查表我把平时帮别人排查时遇到的高频问题整理成一张表格基本都是那些翻来覆去出现的版本冲突和编译问题报错信息常见原因解决方案AssertionError: MMCVxxx is used but incompatiblemmcv版本与mmdet/mmdet3d不匹配按兼容表卸载重装对应版本ModuleNotFoundError: No module named mmcv环境装错或没用对应conda环境检查pip list里的mmcv是否存在ImportError: libcudart.so.xxx: cannot openCUDA版本不一致或LD_LIBRARY_PATH缺失确认PyTorch对应CUDA与系统驱动兼容RuntimeError: CUDA error: no kernel image is availableCUDA版本与显卡算力不匹配重新编译mmcv并正确设置TORCH_CUDA_ARCH_LISTModuleNotFoundError: No module named Cython编译前未装Cython先pip install cython再重新安装依赖包Segmentation fault直接崩溃常见于spconv1.x版本或数据加载线程冲突检查是否用的mmcv内置稀疏卷积或减少DataLoader线程数训练时loss为NaN学习率过大或数据预处理异常调整学习率检查点云坐标、归一化参数AttributeError: module mmcv has no attribute opsmmcv旧版没有新版ops模块升级mmcv或修改代码兼容旧版4.2 spconv相关问题的完整处理流程spconv是mmdetection3d老版本中绕不开的痛。如果你是旧版配置spconv1.x源码编译几乎成了标配而编译它的报错花样极多。我总结下来编译spconv成功的关键有四点一是提前装好Cython和pybind11二是在编译前先import一次torch让torch的头文件路径被正确识别三是编译器版本不能太老GCC太低直接编不过四是内存要足编译spconv时峰值内存能到8GB以上。如果你实在不想受这个罪有两个替代方案第一新版mmdetection3d不再强依赖spconv1.x很多模型可以直接用mmcv的稀疏卷积实现那你干脆别装spconv了第二直接装spconv2它的预编译包覆盖面更广pip安装就行编译时间比spconv1.x短得多。4.3 数据加载卡死与内存溢出的排查思路训练或验证时卡在数据加载阶段是另一个高频问题。我遇到过一个典型案例程序在读取KITTI数据时直接卡死但没有报任何错。最后排查发现不是代码问题而是DataLoader的num_workers设得太高加上共享内存不足多进程之间打起来了。解决办法很简单把num_workers调小或者减少每个worker的预取数量。还有一个常见情况是验证时显卡显存溢出一上来就把batch size拉到模型极限导致OOM。建议先用batch size1跑通一个迭代再逐步增加batch size直到找到合适值。4.4 老版本项目升级到新版本时的匹配问题每次mmdetection3d大版本升级都会带来一大堆配置破坏。从0.x升到1.0的时候光改名就有几十处比如mmdet3d.models下的很多类名变了configs目录结构也调整了。如果你手上有一个老项目要升级我的建议是别在旧环境上打补丁直接新建一个conda环境装新版组合然后把config文件和自定义模型代码逐步迁移。这样至少能保证新环境的干净出问题也好排查。迁移的时候对照官方的upgrade文档逐项改不要跳过。5. 一些实操心得与最后的建议5.1 多版本环境管理的最佳实践搞3D检测的手头大概率不止一个项目需要维护老模型可能要0.17.2的环境新模型用1.x的环境。电脑配置够的话建议给每个大版本单独建一个conda环境命名带上版本号比如mm3d_017、mm3d_100。这样看似占用空间大一点实际上能避免大量隐性冲突。之前我图省事在一个环境里既跑0.18又跑1.0来回卸载重装最后把什么搞坏了都不知道。conda环境名是免费的多建几个真的不亏。5.2 环境配置的最终建议记录你的成功路径装成功一次之后把你的安装命令和版本号全部记录下来。我自己的习惯是在项目目录下放一份install.sh把从conda create开始的每一步命令都固化下来同时注明这份脚本验证过的版本组合。好处是下次换电脑或者给同事部署的时候一条命令就能复现不用再趟一遍坑。我也建议你顺手记录一下nvcc -V、nvidia-smi、python -c import torch; print(torch.__version__)这几个输出关键时刻排查问题能省很多事。mmdetection3d的环境配置说到底就三个核心版本匹配、源码编译选项、以及“先跑通小流程再上大流程”的验证思路。只要这三条思路在哪怕以后版本组合变了你也能自己解决。最后再分享一个小技巧所有mm系列项目的环境问题优先去官方文档看“安装”和“常见问题”两节绝大多数报错都能找到对应说明比直接在社区里发帖问要快得多。