mmdetection3d从零安装到训练推理：版本兼容与踩坑全记录

深度学习领域搞3D目标检测的，应该没人能绕开 mmdetection3d 这个框架。它把当前主流的三维检测模型都收编了，从基于点云的 PointPillars、CenterPoint，到多模态融合的 BEVFusion、TransFusion，基本覆盖了学术界和工业界最常落地的方案。但话说回来，这个框架的能力有多强，它的安装过程就有多折磨人——版本对齐、编译报错、依赖冲突，每一步都能让人卡到怀疑人生。

我最早接触 mmdetection3d 是在 1.0 时代，那会儿光是配环境就折腾了一周，后来 1.1、1.2 版本迭代，API 变化也不小。最近这轮升级到了基于 mmcv 2.x 的新版本，安装逻辑跟以前又不太一样了。这篇文章我把自己这次从零开始安装、跑通训练和推理的完整过程整理出来，包括版本选择、编译坑位、数据集处理、配置文件改动，以及最后跑实验时的各种疑难杂症，直接照着抄就行。

1. 安装前的思路梳理与环境规划

先说结论：mmdetection3d 之所以难装，核心问题不在于框架本身，而在于它的依赖链路太长、太严。它强依赖特定版本的 mmcv、mmengine、mmdet，而这三个库又强依赖特定版本的 PyTorch 和 CUDA，任何一个版本不匹配，直接各种报错。所以动工之前，先把整个依赖管家的关系弄清楚。

1.1 版本兼容关系全景图

我先用我这次实际用的版本给大家一个明确坐标：Python 3.8、CUDA 11.3、PyTorch 1.10.1、mmengine 0.10.5、mmcv 2.0.1、mmdet 3.1.0、mmdetection3d 1.2.0。这条组合是官方文档推荐的一个稳定搭配，实测下来编译和跑模型都很顺。

版本选择有一个黄金原则：不要追新。很多人看到 PyTorch 出新版本就开心，装上之后发现 mmcv 还没适配，直接白给。mmcv 的编译是对 PyTorch 版本敏感的，它的预编译轮子只覆盖固定的几个版本组合。你去看 mmcv 的发布说明就会发现，每个新版 mmcv 都明确标注了支持的 PyTorch 和 CUDA 版本范围，超出范围的就得走源码编译，而源码编译又是一个新的坑。

这里我建议不管是新手还是老手，直接用官方推荐的稳定组合，别自己搭配。具体选型逻辑我拆成三点，大家对着自己的情况来。

1.2 硬件与驱动的前置检查

在动环境之前，先把机器的底子摸清楚。mmdetection3d 训练三维检测模型非常吃显存，特别是在处理点云体素化的时候，显存不够直接 OOM。我用一张 12G 显存的卡跑 CenterPoint 的默认配置，批大小还调小到了 4 才能正常训练，新手如果只有 8G 显存，建议先从 PointPillars 这个轻量模型入手。

检查 CUDA 驱动用 nvidia-smi 看驱动版本，驱动版本的适用范围比 PyTorch 的 CUDA 版本宽松很多。比如你机器上驱动是 470 系列的，那 PyTorch 用 CUDA 11.3 甚至 11.1 都行。关键是 PyTorch 实际调用的 CUDA runtime 版本，跟编译 mmcv 时用的版本要一致，这样整个链路才通。

还有一个容易被忽视的点：编译 mmcv 需要 gcc 和 g++ 的版本足够新，至少 5.4 以上。很多老服务器的 gcc 还是 4.8，编译的时候会报内部编译器错误，一脸懵。检查方法很简单，gcc --version 看一眼就能确认。

1.3 为什么推荐用 conda 而不是直接 pip

很多教程直接让你 pip install，但 mmdetection3d 这种多依赖链路的框架，没有 Python 版本隔离工具就是找死。一个机器上同时跑着 TF 和 PyTorch 项目再正常不过，pip 装全局的话，某次升级直接把另一个项目的依赖弄坏，这种经历我踩过不止一次。

所以第一步就是创建独立的 conda 环境。环境的 Python 版本选择 3.8 是最稳的，3.9 和 3.10 也能跑，但部分 spconv 的预编译轮子对 3.8 支持最完整。下面的命令直接执行，环境名我就叫 mm3d，大家也可以自己改。

conda create -n mm3d python=3.8 -y conda activate mm3d

到这里只是把地基打了，真正的重头戏在依赖安装，下一节详细讲。

2. 核心依赖安装实操与编译要点

环境建好之后，就是一条链接着一条链的安装。每一个环节我都把版本锁定死，因为到了这一步，任何一点意外都会让前面的努力白费。

2.1 PyTorch 安装的关键细节

PyTorch 的安装方式，官方给了一行命令，但直接照抄有时候会装上 CPU 版本，这个坑很多人踩了。我的建议是从 PyTorch 官网找到对应 CUDA 版本的历史安装指令，直接 pip install 指定 URL 安装轮子。

我这次的命令是：

pip install torch==1.10.1+cu113 torchvision==0.11.2+cu113 -f https://download.pytorch.org/whl/torch_stable.html

装完一定要验证 GPU 可用：

python -c "import torch; print(torch.cuda.is_available(), torch.__version__)"

输出True 1.10.1+cu113才算过关。我见过有人这一行输出 False，原因是装了 CPU 版，或者 CUDA 驱动太老导致 PyTorch 的 CUDA runtime 起不来。前者重装就行，后者得升级驱动或者换更低版本的 PyTorch，没有第三条路。

2.2 mmcv、mmdet、mmengine 的版本锁定策略

mmdetection3d 的依赖比较复杂，它同时依赖 mmcv（计算与通用模块）、mmdet（2D 检测基础库）、mmengine（训练引擎）。这三者的版本配对关系，官方在 README 里给了一张大表，让人看得头疼，但翻译成人话就是：mmdetection3d 1.x 要用 mmcv >= 2.0 和 mmdet >= 3.0，同时要求 mmengine 的存在。

安装 mmcv 是最麻烦的一环。mmcv 提供全功能和精简版，mmdetection3d 需要全功能版本，也就是带编译扩展的那个。预编译的轮子只在官方指定索引里有，你用 pip 默认源装的话大概率装上纯 Python 版的 mmcv，后面跑模型直接报 ImportError。

正确安装方式是：

pip install openmim mim install mmcv==2.0.1

mim 是 OpenMMLab 官方出的包管理工具，它最大的好处就是自动识别你当前的 CUDA 和 PyTorch 版本，选择合适的预编译轮子，不需要手动下载。装完之后验证编译扩展是否正常：

python -c "import mmcv; from mmcv.ops import get_compiling_cuda_version; print(get_compiling_cuda_version())"

能输出 CUDA 版本就说明扩展编译好了。接下来是 mmengine 和 mmdet：

pip install mmengine==0.10.5 pip install mmdet==3.1.0

注意这里不要用 mim install mmdet，因为 mmdet 没有预编译轮子，pip 直接装就行。到这里，mmdetection3d 的三个基础依赖就绪，可以进入框架本体安装。

2.3 spconv 与稀疏卷积库的选择

三维点云体素化之后，大部分计算都依赖稀疏卷积。mmdetection3d 里支持两种稀疏卷积库，一个是 spconv 1.x，一个是 spconv 2.x，两者的 API 不兼容，而 mmdetection3d 不同版本适配的是不同分支。

我用的 mmdetection3d 1.2.0 适配的是 spconv 2.x，安装命令：

pip install spconv-cu113

这里有个容易出问题的地方：spconv 的轮子名称跟 CUDA 版本严格绑定。如果你是 CUDA 11.1 就要装 spconv-cu111，如果是 11.3 就用 cu113。装错版本的典型症状是 import spconv 能过，但真正跑模型的时候报什么undefined symbol，写代码的人一看就明白是版本不匹配。

如果你的 CUDA 版本恰好没有预编译轮子，那就得从源码编译 spconv，这个过程会非常漫长，我编译过一次耗时半个多小时，建议还是尽量避开。所以前面选环境的时候，CUDA 版本选择要提前想好，就是为了这一步能直接命中预编译轮子。

2.4 mmdetection3d 本体安装与编译问题

最后一步，安装 mmdetection3d。推荐用源码安装，这样最容易后续调试，也能随时拉最新修复：

git clone https://github.com/open-mmlab/mmdetection3d.git cd mmdetection3d pip install -v -e .

源码安装会自动执行 setup.py，真正干活的是里面的编译步骤。这里最常遇到的问题是两个：编译时内存不足导致进程被杀，以及没有安装 CUDA toolkit 导致编译扩展失败。

内存不足这个问题很现实，编译 C++/CUDA 扩展的时候，编译器会同时起多个进程，内存 8G 的机器很容易崩。解决办法是限制编译进程数：

MAX_JOBS=4 pip install -v -e .

没有安装完整的 CUDA toolkit 这个坑更隐蔽。很多人觉着装完 PyTorch 就有 CUDA 了，其实 PyTorch 自带的是 CUDA runtime，而编译扩展需要的是完整的 CUDA toolkit，包含 nvcc 编译器。验证 nvcc 是否存在：

which nvcc

如果找不到，就是没装 toolkit。装完之后还需要让系统能找到它，我的做法是在 ~/.bashrc 里加上：

export PATH=/usr/local/cuda-11.3/bin:$PATH export LD_LIBRARY_PATH=/usr/local/cuda-11.3/lib64:$LD_LIBRARY_PATH

这里有个容易混淆的点：PyTorch 编译好的轮子不依赖 nvcc 就能运行，但 mmcv 和 mmdetection3d 的源码编译环节必须在有 nvcc 的环境下进行。装完 PyTorch 直接跑模型没有问题，但源码编译一定缺这一步。

完成之后，验证是否安装成功：

python -c "import mmdet3d; print(mmdet3d.__version__)"

输出 1.2.0 即代表安装完成。如果你到这里一路通畅，恭喜你运气不错，后面还有数据集和模型配置等着呢。

3. 数据集准备与预处理细节

框架装好了只是万里长征第一步，做 3D 检测还得有数据。这里以 KITTI 数据集为例，把数据准备的完整过程和里面那些文档里不会写的细节一一说明。

3.1 KITTI 数据集下载与目录组织

KITTI 数据集是自动驾驶场景最经典的公开数据集，mmdetection3d 官方有配套的数据转换脚本。数据集本体需要在官网注册后下载，这里有四个核心部分：彩色图像、点云 velodyne、标定文件 calib 和标签 label_2。下载完解压之后，目录组织成这样：

data/kitti/ ├── ImageSets/ ├── testing/ │ ├── calib/ │ ├── image_2/ │ └── velodyne/ └── training/ ├── calib/ ├── image_2/ ├── label_2/ └── velodyne/

不少人在这个环节遇到的第一个问题是没有 ImageSets 文件夹里的索引文件，后续创建数据时需要用到这些文件来划分训练集和验证集。这个需要单独从官网下载，因为是独立于主干数据的压缩包。

3.2 数据转换脚本的执行顺序

mmdetection3d 对原始数据做了一步预处理，把原始的点云和标注转换成更紧凑的 npy 格式，这里涉及到 pkl 索引文件的生成。执行时需要先创建数据目录软链接或直接放数据，然后运行官方给的脚本：

python tools/create_data.py kitti --root-path ./data/kitti --out-dir ./data/kitti --extra-tag kitti

这个脚本耗时取决于数据量，KITTI 完整版大概需要几分钟到十几分钟不等。跑完之后会在 data/kitti 目录下生成 kitti_infos_train.pkl、kitti_infos_val.pkl 和 kitti_infos_test.pkl 三个索引文件，同时还有一个 gt_database 文件夹存放所有训练样本的点云局部信息，这部分是后续做数据增强时 database sampler 模块要用的。

有一个非常容易忽略但是极其重要的操作：数据转换脚本执行前必须把 kitti 数据做成软链接放进 mmdetection3d 的 data 目录下，或者直接把数据目录放到 mmdetection3d/data 下面。转换脚本写死了相对路径，我之前放在别的目录，调了半天脚本发现问题出在这。

3.3 点云坐标系与标注格式理解

这一步不直接操作代码，但对后面调参和排查结果非常关键。KITTI 数据集的坐标系定义是：x 轴朝前，y 轴朝左，z 轴朝上，单位是米。标签文件里每个物体的信息包含类别、截断程度、遮挡程度、2D 框坐标、3D 框尺寸（高宽长）、3D 框中心坐标（x, y, z）和绕 yaw 轴的旋转角。

mmdetection3d 内部处理时，会把 KITTI 的坐标系转换到统一的 LiDAR 坐标系，这个转换逻辑在不同的数据集上不一样。理解不了这一点，后面可视化点云时看标注框跟点云对不上，会怀疑数据转换出错，其实可能是坐标系映射没对上号。

调试时最实用的验证方法是用官方提供的可视化工具直接渲染点云和 3D 框，比对着 label 裸看直观得多。可视化前需要安装 mayavi 或者 open3d，我推荐用 open3d，pip 直接装就行，没有 mayavi 那一堆 Qt 依赖。

4. 模型配置文件的组成与关键参数讲解

mmdetection3d 的核心设计就是一切皆配置，改模型、改数据、改训练策略全在 config 文件里进行。这也是它最大的优点：不需要改一行代码就能跑通不同模型。但前提是你得理解配置文件的组织方式和继承机制。

4.1 配置文件继承关系拆解

打开 configs 目录，看到的是各种模型的一堆 .py 文件。这些文件不是孤立的，而是通过base字段构成一个继承树。以 pointpillars 为例，它的配置文件通常会继承一个模型定义文件、一个数据集配置、一个 schedule 配置和一个 runtime 配置。

比如：

_base_ = [ '../_base_/models/pointpillars_hv_secfpn_kitti.py', '../_base_/datasets/kitti-3d-3class.py', '../_base_/schedules/cyclic-40e.py', '../_base_/default_runtime.py' ]

这行代码理解透了，配置文件的逻辑就通了。后续想改模型结构，只需要打开模型定义文件，找到对应字段修改；想换数据集，把数据集配置整体替换；改学习率策略，去 schedule 文件里调。真正做下来只需要在顶层配置文件覆盖特定参数，别的全走继承。

看配置会用到一个小技巧：在跑训练之前用工具检查一下最终生效的完整配置，避免继承链条太深导致改了没生效的问题。命令如下：

python tools/misc/print_config.py configs/pointpillars/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class.py

把看到的输出理解成最终训练时用的完整配置。别嫌麻烦，这个工具在排查配置问题时救过我好几次。

4.2 数据 pipeline 里那些容易被忽略的预处理参数

配置里 model 部分的数据预处理参数，直接影响训练效果和显存占用。像体素化这一步，voxel_size 决定了一个点云被切分成多细的网格，直接影响模型的精度和空域分辨率。pointpillars 默认的 voxel_size 是 [0.16, 0.16, 4]，表示 x、y 方向 16 厘米一个格子，z 方向 4 米一个格子。z 方向分得粗是因为大部分障碍物的高度差异不靠这个维度区分。

max_num_points 和 max_voxels 这两个参数也值得注意。它们定义了每个体素最多放多少个点、每帧最多保留多少个非空体素。max_voxels 设置小了会导致部分点云被丢弃，设置大了会浪费显存。我调试过一次，发现模型在远处小物体上表现得很差，排查到最后是 max_voxels 太小把远距离的稀疏点云都滤掉了，适当调大之后效果明显改善。

4.3 训练超参数与评估指标配置

训练相关的配置左右着整个模型的收敛行为。训练一个 3D 检测模型时，常用的优化器是 AdamW，学习率策略用 one cycle 或者 step 衰减的都有。pointpillars 默认用的是 CyclicLR，这种策略在目标检测任务上收敛快，迭代周期短，效果也不错。

评估指标的配置也值得关注。KITTI 数据集标准的评估指标是 3D mAP，分 Car、Pedestrian、Cyclist 三个类别计算，每个类别还按难度分 Easy、Moderate、Hard 三档。实际项目里我只看 Moderate 这一档，因为它是综合表现的代表。评估代码会在验证阶段自动计算这些指标，反应到日志里形如mAP_car_moderate。

注意一个细节：mmdetection3d 的评估代码把 kitti 的 2D 检测结果也一起算了。如果你只关心 3D 框精度，看 3D 相关的指标就好。因为 2D mAP 对 3D 模型的整体能力反应有限，初学时容易看错维度。

5. 训练、验证与可视化全流程

配置完成，数据就绪，接下来就是动手跑流程的时候。这一节是实操环节，从训练启动到输出结果，我尽量把每一步的步骤和可能遇到的问题都覆盖到。

5.1 训练启动与日志监控技巧

启动训练很简单，一行命令：

bash tools/dist_train.sh configs/pointpillars/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class.py 2

最后的数字 2 代表用几块 GPU 并行。单卡用户直接：

python tools/train.py configs/pointpillars/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-3class.py

训练一开始会在终端输出一个进度条，同时间隔打印 loss 数值。这里有一个训练启动慢容易让人误解的地方：第一次跑的时候因为要编译一些模型组件，以及初始化数据集索引，看起来像是卡住了，有的机器上这个初始化阶段能持续几分钟，不要急着去关进程，先耐心等待。

训练过程中有两点需要盯住的：第一是 loss 初始值是否正常。pointpillars 训练开始的时候，loss 在 3~5 之间波动比较常见，如果一开始就是几十甚至上百，说明配置有问题，大概率是学习率设置不合理或者数据预处理出错。第二是每轮的 mAP 提升趋势。正常情况下，前几轮 mAP 从 0 开始缓慢上升，到后面逐渐平稳。如果一直卡在 0 附近不动，检查一下 GT 采样数据增强是否正常生效。

5.2 模型权重保存与恢复训练

训练过程中，权重文件会保存成 .pth 文件。默认的保存策略是每隔几个 epoch 存一次，同时保留验证集上表现最好的那一份。对于长训练，可以看到 work_dirs 目录下手动生成的文件不断增长。

如果训练中断了，可以用 resume 参数恢复：

python tools/train.py 配置文件路径 --resume 断点权重路径

恢复训练非常常用，特别是大模型训练跑了很多天，一旦因为外力中断，从头再来谁都受不了。恢复训练的时候要注意学习率调度器也会同步恢复，不会从 epoch 0 重新开始。

5.3 模型推理与结果输出

推理也有现成的脚本，命令如下：

python tools/test.py 配置文件路径 权重路径 --out results.pkl

加了 --out 参数会把所有帧的预测结果序列化到 pkl 文件里，方便后续做性能分析或者错误检测。不加这个参数的话，只会输出评估指标。

值得强调的是，.pkl 文件并不直接可视化，需要用配套脚本把它渲染成图片或者点云的动画效果。我常用的做法是先把 pkl 转成能逐帧读取的结构，然后用 matplotlib 或者 open3d 渲染，看模型预测的框和点云的实际匹配程度，比只看 mAP 数字能发现问题，比如某些类别预测框的角度全部偏了这种细粒度错误，mAP 变化不大但肉眼一看就很明显。

5.4 点云可视化与结果验证

可视化是整个流程里最能直观感受模型好坏的一环。mmdetection3d 官方提供了一整套可视化工具：

python tools/visualize.py 配置文件路径 --pred 预测pkl --show

加上 --show 会弹出窗口逐帧看结果，服务器跑实验没显示器的场景可以改成 --show-dir，把渲染结果保存成图片文件批量导出。

点云可视化需要注意一个判断基准：模型输出的 3D 框必须紧密贴合点云簇。如果框恰好切在点云的边缘上，模型总体上是可信的；如果大量框都框偏了目标的中心，或者框的角度与点云簇的主轴方向明显对不上，那问题就出在训练数据或者超参数上面了，不是推理阶段的问题。

6. 高频报错排查与解决方案速查

这个部分是我实际训练过程中踩过的坑和最终解决办法，整理成表格，大家遇到类似问题直接对号入座。

6.1 模型结构相关报错的排查逻辑

配置错误导致的模型结构报错是最隐蔽的，因为报错信息往往跟实际原因差得很远。有一次我改了一个别名叫 bbox_head 的输出维度，结果训练时报的是 tensor shape mismatch，跑去检查数据尺寸问题，耽误了不少时间。后来才意识到是 head 输出维度跟类别数不对应。

这类问题排查有一个通用路子：先看报错的第一行追溯调用栈，确认是模型 forward 阶段还是 loss 计算阶段；如果是 forward 阶段，基本是输入数据 shape 跟模型期望值不匹配；如果是 loss 计算阶段，大概率是 head 输出维度和 GT 格式对不上。把配置文件里的 model 部分逐层拆开，跟数据集里的标注字段对应一遍，就能定位出问题。

6.2 训练过程中显存优化的实战方案

显存不够是刚入门 3D 检测最容易碰到的问题。同一个模型，2D 检测跑得欢，3D 检测直接爆显存，根本原因在于点云的体素化。一张图卡的显存要同时放下体素特征、稀疏索引和 dense 输出，开销比图像大得多。

我实测过的显存优化排序：调低 batch size 是最快的方案，但效果有限；减少 max_voxels 能显著降低显存，但过度减少会丢点；用梯度累积模拟更大的 batch size，能缓解显存和精度的矛盾；换模型结构则是最彻底的方案，pointpillars 比 centerpoint 显存省不少。

新手最容易忽略的其实是数据缓存，mmdetection3d 默认会在第一次加载数据集时做一系列预处理。如果机器内存紧张，可以把配置文件里的缓存机制调整一下，尽量把点云预处理放在流式环节而不是全部加载进内存。

6.3 预训练权重加载失败的处理

加载预训练权重主要两个场景：一是从 2D 检测模型迁移，二是从官方 3D 模型继续训练。官方权重下载速度慢，建议提前下载好放到本地目录，配置里用 load_from 指定本地路径。

加载失败时最常见的报错是 size mismatch，本质原因是配置修改后模型结构跟权重不一致。比如你改了类别数，head 输出维度变了，预训练权重里对应层的参数自然对不上。处理方式有两种：开着 strict=False 跳过这一层的权重加载，以及修改配置文件让模型结构跟预训练权重完全对齐。

还有一个情况值得说明：有些用户只加载 backbone 权重，比如用 2D 检测器在 ImageNet 上预训练的 ResNet 骨架，这时就需要写一个自定义的加载逻辑，只初始化 backbone 部分的参数，其余部分随机初始化。这个逻辑在 config 文件里通过 init_cfg 字段配出来，看起来不多但实用价值高。

7. 一些实操经验和最后的提醒

这个框架我用了很长时间，从最初的装不上、跑不通，到后来的调优、迁移新数据集，每一步都踩了不少坑。最后分享几个个人总结的经验。

第一，版本锁定是王道。不要盲目升级任何依赖包，一个项目配好了环境就尽量固定住。很多人反复收到版本冲突的困扰，本质原因就是升级了某个包破坏了原本的兼容链。我把环境的完整包列表用 conda env export 导出来，每次都是直接重建环境，没出过问题。

第二，先跑通再调参。很多新手一上来就上大模型、大数据，结果调试周期被拖得很长。实际开发流程应该反过来：先在 KITTI 上把 pointpillars 跑通，再看训练日志和可视化结果理解整个流程，最后再换大模型调精度。这个顺序能让你快速建立正确的直觉。

第三，多方案对比是王道。3D 检测模型的精度提升不像 2D 检测那样靠堆模型就能解决，数据集噪声、点云密度、传感器参数这些因素在效果上占比很大。换模型不如先检查数据质量，可视化几帧数据看看有没有标注错位、点云稀疏的情况。

最后一点是关于算力的：如果你条件允许，尽量用多卡训练。3D 检测模型即便用 pointpillars，单卡训练 KITTI 也要几个小时，换成 centerpoint 直接翻倍。多卡并行不仅省时间，在探索超参组合时优势更明显。调参过程中能用小模型快跑验证的就别用大模型慢跑，时间就是效率。

写到这里，安装、数据准备、配置、训练、推理、查错，整个流程里我认为值得说的东西都在了。mmdetection3d 的下手难度确实偏高，但它能覆盖的模型范围和社区资源也是目前同类框架里最丰富的，只要把这条链路走通一次，后续迁移到新数据集、新模型就会快很多。