企业官网建设流程全解析

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.6，PyTorch是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.6，PyTorch选1.13.1，MMCV选择mmcv-full==1.7.2，MMDetection选2.28.2，MMSegmentation选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 python=3.8 -y conda activate mmdet3d

有一点需要提醒的是，在没有装任何东西之前，先确认一下conda的镜像源和pip的镜像源配置都是可用的。国内网络环境下直接访问官方源装PyTorch之类的包，速度会慢到让人怀疑人生。建议提前配置好清华或者阿里云的conda镜像源，pip源也换成国内源，这样在执行后续安装命令时能省下大量时间。

另外，如果你的电脑上同时存在多个CUDA版本（比如系统自带的10.2和后来装的11.6），在conda环境里安装PyTorch时，它会自动匹配到对应版本的CUDA依赖库，一般不需要手动干预。只要记得在安装PyTorch时指定的是cu116这样的版本标签，确保和你的CUDA Toolkit版本对应就行。

3. 安装全程实录：从PyTorch到MMDetection3D

3.1 PyTorch安装与CUDA验证

整个安装过程的第一步，是先装PyTorch。这里强烈建议直接用conda安装，因为conda会自动处理CUDA相关的依赖库，省去手动配置环境变量的麻烦。以CUDA 11.6为例，安装命令是：

conda install pytorch==1.13.1 torchvision==0.14.1 torchaudio==0.13.1 pytorch-cuda=11.6 -c pytorch -c nvidia

如果你是CUDA 11.3版本，就把pytorch-cuda=11.6改成pytorch-cuda=11.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版本。

先安装mim：

pip install openmim

然后用它安装指定版本的MMCV：

mim install mmcv-full==1.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 mmdet==2.28.2 mim install mmsegmentation==0.30.0

mim会自动处理这两个包对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_gpu=2来调小batch size。

测试结束后，终端会输出每一类的AP值。以3类目标检测为例，你会看到Car AP@0.7、Pedestrian AP@0.5、Cyclist AP@0.5这些指标。如果你是第一次跑通测试，不要纠结AP值是不是和官方一致，只要没有报错并输出了数值，说明整个环境已经通畅了，后续再根据实际需要调整模型和数据集即可。

提示：如果测试过程中报显存不足（OOM），优先把config里的batch_size调小，而不是去调模型结构。很多时候一个GPU=1导致显存暴涨的情况，只需要一句--cfg-options data.samples_per_gpu=1就能解决。

4.4 训练前的数据检查清单

如果测试通过后你打算直接开始训练，建议花几分钟检查一下自己的数据准备情况，避免训练到一半才发现数据有问题。第一个检查点是点云数据的范围是否合理，正常情况下激光雷达点云的坐标范围不会超出传感器规格太多，如果你发现点云坐标出现极端异常值，大概率是数据预处理出了问题。第二个检查点是标签文件的格式，KITTI格式的标签有严格的字段顺序和类别名称约束，一个单词拼错都会导致训练时无法正确读取。第三个检查点是放进config里的数据路径是否正确，很多人在训练时报FileNotFoundError，最后发现就是路径里少了一个斜杠。

5. 常见问题与排查技巧实录

5.1 高频报错速查表

我把实际配置和测试过程中遇到的高频报错整理成了表格，方便你直接对照排查。下面的每一类问题我都实际遇到过，按图索骥能省下大量的搜索时间。

5.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.8
• CUDA 11.6 + PyTorch 1.13.1
• mmcv-full 1.7.2
• MMDetection 2.28.2
• MMSegmentation 0.30.0
• MMDetection3D 1.4.0（源码安装）
• open3d、trimesh、shapely作为附加依赖

这套组合我在三台配置不同的机器上都验证过，涉及Ubuntu 18.04和20.04系统，以及RTX 3090和RTX 4090显卡，目前没有遇到兼容性问题。最后再分享一个小技巧：所有安装操作尽量在同一个终端会话里完成后，再新开一个终端进行验证。这是因为mm系列框架在源码安装后，有些路径信息会写入当前的Python环境变量缓存里，如果安装完成后换了终端，偶尔会出现环境变量刷新不正常导致的import失败，重新激活一下conda环境或者新开终端就能解决。