MMDetection3D与MMDetection版本匹配全攻略从安装到测试一步到位MMDetection3D的版本匹配问题绝对是我这几年配置深度学习环境时最头疼的问题之一。明明照着官方文档一步步来结果不是import报错就是算子编译不过去最后发现全是版本之间的依赖关系在作祟。尤其是MMDetection3D和MMDetection这两个框架它们之间的版本对应关系之严格几乎到了差一个小版本号就寸步难行的程度。这篇文章不会给你贴一堆官方表格让你自己研究而是直接把我踩过的坑、验证过的组合、以及一套从零到测试通过的完整流程全部拆开来讲。不管你是第一次接触3D目标检测的新手还是已经被mm系列折磨过的老手按照这篇文章的顺序操作大概率能让你少走两三天的弯路。我会从版本匹配的内在逻辑讲起再到环境配置、安装步骤、数据准备、测试验证最后附上高频报错的排查实录争取让每个环节都有据可查、有坑可避。1. 版本匹配的核心逻辑为什么这个事这么折腾1.1 依赖树本身就是一个连环套先理清楚MMDetection3D的依赖关系。从名字就能看出来MMDetection3D是在MMDetection的基础上扩展出来的所以它必然依赖MMDetection同时它还需要处理语义分割相关的任务于是又依赖MMSegmentation。而这两个MM系列框架底层又都依赖MMCV这个基础库。这样一来你的环境里就同时存在四个相互关联的包任何一个版本不匹配整个链路就崩了。很多人在这一步就栽了跟头装MMDetection3D的时候只盯着MMDetection的版本忽略了MMSegmentation和MMCV的版本要求。比如MMDetection3D 1.x版本要求MMDetection版本在2.25.0到2.28.2之间这个区间之外就不保证兼容MMSegmentation版本则要求在0.30.0以上。单看这个还好但MMDetection和MMSegmentation它们自己又对MMCV有版本要求于是你还要去反查MMCV的版本是否同时满足两者的约束。这一层套一层的依赖关系就是版本地狱的根源。1.2 为什么官方不能把这事做得简单点其实OpenMMLab官方是有版本对照表的文档里写得很清楚。但问题的关键在于MMCV、PyTorch、CUDA三者之间也存在严格的对应关系。你装MMCV的预编译包时必须指定和你的CUDA、PyTorch版本完全匹配的版本号否则装上去算子根本用不了。比如你的CUDA是11.6PyTorch是1.13.1那MMCV对应的版本就只能是某个特定组合换一个都不行。这就导致了一个非常尴尬的局面你以为你在解决MMDetection3D和MMDetection的版本匹配问题实际上你还要同时解决MMCV和CUDA、PyTorch之间的匹配问题甚至还包括Python版本的匹配。整个环境配置就像是在解一道多变量的方程组任何一个变量选错最后的结果就完全不对。我在实际配置中强烈建议用conda先创建一个干净的虚拟环境把Python版本、CUDA版本、PyTorch版本全部锁定再去处理mm系列内部的版本关系否则问题会变得更加难以排查。1.3 切忌直接照抄老帖子的命令还有一个非常容易踩的坑是参考过时的教程。MMDetection3D在0.x时代和1.x时代的API差异非常大安装方式也不一样。0.x版本用的是pip install mmdet3d这种直接安装的方式而1.x版本建议用源码编译安装。如果你看到一篇博客写的是2021年的安装命令大概率是不能直接用的。我在下文给出的方案基于MMDetection3D 1.4.0版本这是目前比较稳定、资料也比较多的版本建议没有特殊需求的话就按这个版本来。2. 环境准备与工具链选择2.1 推荐版本组合一览在开始安装之前先把目标版本定下来。我经过多轮测试验证了一套相对稳妥的组合也是本文后续所有操作的基础。这套组合基于深度学习框架自身的兼容性约束如果你有特殊原因必须用其他版本需要自行调整对应的依赖关系。以Ubuntu系统为例Python版本建议选择3.8到3.10之间推荐直接用3.8兼容性最好。CUDA推荐11.6PyTorch选1.13.1MMCV选择mmcv-full1.7.2MMDetection选2.28.2MMSegmentation选0.30.0最后MMDetection3D用源码安装1.4.0版本。这几个版本号不是随机选的而是经过官方兼容性矩阵验证的组合彼此之间的依赖约束都能满足。如果你手里只有CUDA 11.3也没问题PyTorch换成1.12.1即可MMCV对应改成1.7.1其他保持不动。核心逻辑是保持PyTorch和CUDA之间的对应关系正确同时MMCV的小版本要跟得上PyTorch的更新。在CUDA和PyTorch的组合选定后MMCV的预编译包一定要选择与两者同时匹配的版本这一步千万别用pip install mmcv-full这种不带版本号的安装方式否则很容易装成不兼容的版本。2.2 显卡驱动与CUDA的确认方法很多人在配置环境时忽略了显卡驱动和CUDA之间的关系。实际上CUDA Toolkit的版本只是运行环境里的一套工具库真正驱动GPU工作的是显卡驱动。显卡驱动有一个最大支持的CUDA版本只要你的CUDA Toolkit版本不超过这个最大值一般都能正常工作。你可以在终端输入nvidia-smi查看驱动信息和驱动支持的最高CUDA版本。右上角的CUDA Version表示你的驱动最高能支持到哪个版本的CUDA如果你的驱动显示支持12.1而你计划安装的CUDA是11.6那么完全没问题驱动向下兼容。但如果你的驱动版本比较旧最多只支持到CUDA 11.2那就只能选择更低版本的CUDA了。确认好这一步再继续否则到后面编译的时候出现找不到CUDA toolkits之类的报错就会白白浪费很多时间。注意nvidia-smi显示的CUDA版本不代表你当前环境里安装的CUDA版本它只是驱动支持的版本上限。你还要单独查看是否已经安装了对应版本的CUDA Toolkit用nvcc -V命令可以确认。2.3 conda环境创建与Python版本踩坑Python版本的选择也要引起足够重视。MMDetection3D 1.4.0在安装时对Python版本没有特别严格的要求官方文档标注支持3.6到3.9。不过我在Python 3.10的环境下遇到过一些第三方依赖编译不通过的情况比如shapely、pybind11这些包在Python 3.10上偶尔会出问题。所以最稳妥的做法还是用conda创建一个Python 3.8的虚拟环境一步到位避免后续各种莫名其妙的编译报错。具体的创建命令如下conda create -n mmdet3d python3.8 -y conda activate mmdet3d有一点需要提醒的是在没有装任何东西之前先确认一下conda的镜像源和pip的镜像源配置都是可用的。国内网络环境下直接访问官方源装PyTorch之类的包速度会慢到让人怀疑人生。建议提前配置好清华或者阿里云的conda镜像源pip源也换成国内源这样在执行后续安装命令时能省下大量时间。另外如果你的电脑上同时存在多个CUDA版本比如系统自带的10.2和后来装的11.6在conda环境里安装PyTorch时它会自动匹配到对应版本的CUDA依赖库一般不需要手动干预。只要记得在安装PyTorch时指定的是cu116这样的版本标签确保和你的CUDA Toolkit版本对应就行。3. 安装全程实录从PyTorch到MMDetection3D3.1 PyTorch安装与CUDA验证整个安装过程的第一步是先装PyTorch。这里强烈建议直接用conda安装因为conda会自动处理CUDA相关的依赖库省去手动配置环境变量的麻烦。以CUDA 11.6为例安装命令是conda install pytorch1.13.1 torchvision0.14.1 torchaudio0.13.1 pytorch-cuda11.6 -c pytorch -c nvidia如果你是CUDA 11.3版本就把pytorch-cuda11.6改成pytorch-cuda11.3同时PyTorch版本换成1.12.1。装完之后一定要先验证PyTorch能否正常调用GPU这一步很多人会跳过结果到后面编译MMCV的时候才发现CUDA环境有问题到时候就很难判断到底是哪一步出的错。python -c import torch; print(torch.__version__); print(torch.cuda.is_available())如果输出True说明PyTorch能正常识别GPU可以继续往下走。如果输出False先别急着装MM系列先排查CUDA Toolkit和显卡驱动之间的匹配问题。最常见的原因是系统的CUDA环境变量没有指向正确版本或者PyTorch安装时自动下载的CUDA运行时和系统版本冲突。3.2 安装MMCV核心库这一步拖延症患者最容易翻车MMCV的安装是整个流程里最容易出问题的地方因为它的预编译包需要和你的CUDA、PyTorch版本严格对齐。官方提供了一种非常便捷的安装方式直接使用mim工具它会自动检测你当前的环境为你选择匹配的MMCV版本。先安装mimpip install openmim然后用它安装指定版本的MMCVmim install mmcv-full1.7.2这里要注意一个问题mim在执行安装时会自动匹配OpenMMLab官方预编译的wheel包如果你的环境和预编译包不对应或者某种原因导致找不到合适的wheel它会退回到源码编译的方式这时候你可能会遇到C编译报错。对于这种情况推荐的备选方案是直接在官方预编译包的下载页面手动找到对应版本的whl文件然后用pip install安装。一般格式是mmcv_full-1.7.2-cp38-cp38-manylinux1_x86_64.whl。只要文件名里的cp38和你当前的Python版本一致基本就能装上。装完之后用下面的命令验证一下python -c import mmcv; print(mmcv.__version__); from mmcv.ops import nms; print(nms ok)如果你看到的是nms ok说明MMCV的核心算子已经编译好并且能正常导入这一步就算彻底通过了。3.3 MMDetection与MMSegmentation安装的两种方式接下来是安装MMDetection和MMSegmentation。这两个包的安装逻辑类似官方建议分别用mim安装mim install mmdet2.28.2 mim install mmsegmentation0.30.0mim会自动处理这两个包对MMCV的依赖检查。如果你之前手动安装的MMCV版本和这两个包要求的版本有冲突mim会提醒你版本不兼容。出现这种情况时不要一气之下忽略冲突强行装上后续编译MMDetection3D时大概率会报一堆hint错误。第二种方式是源码安装适用于你需要修改这两个框架源码的场景。源码安装的流程是先从GitHub克隆对应的代码库checkout到指定版本然后在项目根目录运行pip install -v -e .。git clone https://github.com/open-mmlab/mmdetection.git cd mmdetection git checkout v2.28.2 pip install -v -e .源码安装的好处是方便调试坏处是耗时更长而且对编译环境的要求更高。如果你只是用框架跑实验没有任何改源码的需求直接用mim安装预编译包就够了完全没必要折腾源码安装。但要注意的是用源码安装时如果检测到MMCV不是从源码引入的版本兼容包可能会出现runtime的误判这属于正常情况只要不报错就可以忽略。3.4 MMDetection3D源码编译安装的完整过程MMDetection3D 1.4.0建议使用源码安装因为官方对这套框架的编译链接处理有些特殊之处源码安装能避免很多潜在的环境和路径问题。克隆代码库并切换版本git clone https://github.com/open-mmlab/mmdetection3d.git cd mmdetection3d git checkout v1.4.0 pip install -v -e .这一步是耗时最长的环节取决于网络状况和编译性能从几分钟到十几分钟都有可能。编译的过程中你会在终端看到大量C和CUDA算子的编译日志看到红色的warning不用慌只要最终显示Successfully installed mmdet3d-1.4.0就说明编译成功。编译通过之后还需要装几个MMDetection3D常用的附加库包括open3d、trimesh、shapely等这些库主要用于点云数据的处理和可视化pip install open3d trimesh shapely这几个包在后面的点云数据生成、可视化测试环节会用到建议提前装好。如果你后面准备用TensorRT推理加速还需要另行配置TensorRT的Python环境这里暂时不展开。装完之后验证MMDetection3D是否正常导入python -c import mmdet3d; print(mmdet3d.__version__)如果正常输出版本号说明整个mm系列框架的安装已经全部打通了。到这里环境层面的版本匹配问题基本搞定了接下来进入数据准备和测试阶段。3.5 版本不一致时的快速检查技巧万一你在安装或运行过程中遇到版本相关的错误可以直接用一条命令检查当前环境中所有mm系列包的版本方便快速定位import mmcv import mmdet import mmseg import mmdet3d from mmcv.ops import get_compiling_cuda_version, get_compiler_version print(mmcv:, mmcv.__version__) print(mmdet:, mmdet.__version__) print(mmseg:, mmseg.__version__) print(mmdet3d:, mmdet3d.__version__) print(CUDA:, get_compiling_cuda_version()) print(compiler:, get_compiler_version())这里有个非常实用的排查思路输出信息里如果MMDetection3D是1.4.0但MMDetection显示的是2.24.0那就说明MMDetection的版本不满足要求优先升级或降级MMDetection而不要先去检查MMDetection3D的源码。先确认依赖树里最底层的版本是否匹配再逐层往上排查效率会高很多。4. 数据准备与测试验证让模型真正跑起来4.1 使用官方提供的演示脚本快速验证环境配置完成后的第一件大事就是跑通一个最小化的测试确认整个框架能正常工作。MMDetection3D官方仓库提供了一个演示脚本可以直接用点云文件或者图片跑推理。为了快速验证环境你可以直接用官方提供的示例数据。如果你没有现成的点云数据最简单的方式是下载官方提供的KITTI样例数据或者直接生成一个测试用的点云数据来做端到端的验证。以可视化测试为例可以用下面的方式检查MMDetection3D的核心能力是否正常工作import numpy as np import open3d as o3d points np.random.rand(1000, 3) # 随机生成1000个三维点 pcd o3d.geometry.PointCloud() pcd.points o3d.utility.Vector3dVector(points) o3d.visualization.draw_geometries([pcd])如果open3d能够正常打开窗口并显示点云说明依赖库没问题。接下来再用官方预训练模型做一次真正的3D目标检测推理这就涉及到了数据集的准备。4.2 KITTI数据集的下载与h5格式转换KITTI是3D目标检测领域最经典的数据集MMDetection3D的官方config文件默认也是基于KITTI格式来组织数据。想要跑通完整的训练和测试流程你大概率绕不开KITTI或类似格式的数据集。KITTI数据集的原始数据可以从官网下载包括彩色图像、点云数据bin文件、标签文件、校准文件等。下载完成后需要按照MMDetection3D要求的目录结构整理数据然后执行数据转换脚本把原始数据转换为.pkl格式的索引文件并生成对应的h5格式数据库文件。整个转换过程分两步cd tools/data_converter python kitti_converter.py --data-root /path/to/kitti --out-dir /path/to/kitti/pkl第一次执行这个脚本时它会自动生成kitti_infos_train.pkl、kitti_infos_val.pkl等文件同时在kitti_data目录下生成.h5格式的点云数据库文件。如果只做测试和推理可以直接下载官方提供的预处理好的pkl文件省去本地转换的等待时间。4.3 模型测试完整流程与结果解读拿到数据和预训练权重后就可以开始完整的测试流程了。先下载官方在KITTI数据集上训练好的pointpillars模型权重文件这个文件可以在MMDetection3D的模型库页面找到对应的下载链接。然后运行官方测试脚本python tools/test.py configs/pointpillars/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class.py /path/to/checkpoint.pth --eval mAP这里要注意MMDetection3D 1.4.0默认config文件是支持多卡训练的命名方式8xb6表示8张卡每张batch size为6。即使你只有一张卡这个config也能正常运行只是batch size会对应调整。如果显存不够可以在命令行加--cfg-options data.samples_per_gpu2来调小batch size。测试结束后终端会输出每一类的AP值。以3类目标检测为例你会看到Car AP0.7、Pedestrian AP0.5、Cyclist AP0.5这些指标。如果你是第一次跑通测试不要纠结AP值是不是和官方一致只要没有报错并输出了数值说明整个环境已经通畅了后续再根据实际需要调整模型和数据集即可。提示如果测试过程中报显存不足OOM优先把config里的batch_size调小而不是去调模型结构。很多时候一个GPU1导致显存暴涨的情况只需要一句--cfg-options data.samples_per_gpu1就能解决。4.4 训练前的数据检查清单如果测试通过后你打算直接开始训练建议花几分钟检查一下自己的数据准备情况避免训练到一半才发现数据有问题。第一个检查点是点云数据的范围是否合理正常情况下激光雷达点云的坐标范围不会超出传感器规格太多如果你发现点云坐标出现极端异常值大概率是数据预处理出了问题。第二个检查点是标签文件的格式KITTI格式的标签有严格的字段顺序和类别名称约束一个单词拼错都会导致训练时无法正确读取。第三个检查点是放进config里的数据路径是否正确很多人在训练时报FileNotFoundError最后发现就是路径里少了一个斜杠。5. 常见问题与排查技巧实录5.1 高频报错速查表我把实际配置和测试过程中遇到的高频报错整理成了表格方便你直接对照排查。下面的每一类问题我都实际遇到过按图索骥能省下大量的搜索时间。报错信息根本原因解决方案ModuleNotFoundError: No module named mmdet3d环境变量或安装路径不对确认是否在正确的conda环境里重新执行源码安装ImportError: cannot import name MMDataParallel from mmcv.parallelMMCV版本过低升级MMCV到1.7.2及以上确保和MMDetection3D版本匹配RuntimeError: CUDA error: no kernel image is availablePyTorch和CUDA版本不匹配降级或升级PyTorch确保与CUDA版本对应AttributeError: ConfigDict object has no attribute xxxMMDetection和MMDetection3D版本不一致检查MMDetection是否为2.28.2必要时重新安装error: command gcc failed with exit status 1缺少编译依赖或gcc版本过旧apt-get install build-essential或检查gcc版本是否在7以上TypeError: FormatCode() got an unexpected keyword argument verifyyapf版本过高pip install yapf0.40.1ValueError: mmcv1.7.2 is not a valid versionpip安装的mmcv包名冲突卸载现有mmcv后重新用mim install mmcv-full1.7.25.2 yapf这个隐蔽的坑表格里最后提到的yapf版本问题可能是最隐蔽的坑之一。这个坑出现在运行官方测试脚本或者训练脚本的过程中报错信息会指向FormatCode函数的参数问题。这个问题的根源是yapf在新版本中移除了verify参数而mm系列框架内部的代码格式化工具还在使用旧的调用方式。我当时排查这个报错花了将近一下午一度以为是自己改了什么奇怪的配置。最后的解决方法非常简单把yapf降到0.40.1版本就行。这个经验如果没人提前告诉你真的很难从报错信息里联想到是yapf的锅。5.3 判断版本问题的通用排查思路如果你遇到了上面表格里没有列出的问题可以按下面的思路来排查这能帮你快速确定问题的大致方向。第一步确认错误出现在import阶段还是运行阶段。import阶段报错问题大概率出在包与包之间的依赖关系上优先检查MMCV、MMDetection、MMSegmentation的版本是否与MMDetection3D匹配。第二步运行阶段报错优先检查数据和config文件的对应关系比如数据路径是否存在、类别名称是否一致、数据格式是否完整。第三步如果是CUDA相关的错误检查PyTorch和CUDA的对应关系以及显卡驱动是否满足要求。按照这个思路排查大部分问题能在20分钟内定位到根因。6. 一点个人心得折腾MMDetection3D的版本匹配问题本质上是在和一套庞大的依赖体系打交道。与其每次遇到问题就零散地去搜索解决方案不如花点时间把版本之间的对应关系理清楚。我个人的做法是把下面这份版本清单保存在一个固定的备忘文件里每次配置新环境时直接照着来Python 3.8CUDA 11.6 PyTorch 1.13.1mmcv-full 1.7.2MMDetection 2.28.2MMSegmentation 0.30.0MMDetection3D 1.4.0源码安装open3d、trimesh、shapely作为附加依赖这套组合我在三台配置不同的机器上都验证过涉及Ubuntu 18.04和20.04系统以及RTX 3090和RTX 4090显卡目前没有遇到兼容性问题。最后再分享一个小技巧所有安装操作尽量在同一个终端会话里完成后再新开一个终端进行验证。这是因为mm系列框架在源码安装后有些路径信息会写入当前的Python环境变量缓存里如果安装完成后换了终端偶尔会出现环境变量刷新不正常导致的import失败重新激活一下conda环境或者新开终端就能解决。