企业官网建设流程全解析

做3D目标检测的人，多少都被mmdetection3d的环境配置折磨过。这个项目本身很好用，但它的环境依赖链条之长、版本耦合之紧，几乎是我见过所有开源项目里数一数二的。每次有人问我“为什么我明明照着官方文档装，最后还是import报错”，我基本都能猜到问题出在哪儿——八成是mmcv和PyTorch版本对不上，或者spconv编译出的问题。这篇内容不适合完全没有接触过深度学习环境的人，但只要你装过PyTorch、搞过conda，跟着下面的思路走，基本可以一次装通，少走我当年踩过的那些弯路。

我自己从mmdetection3d 0.x时代就开始用，后来1.0版本大改又把环境翻新了一遍，中间踩过无数坑。这篇文章我尽量把“为什么要这么做”讲清楚，而不是只给你一堆死命令。毕竟版本一更新，死命令就失效了，但背后的匹配逻辑和排查方法，你可以一直用下去。

1. 动手之前，先理清这个项目的依赖链条

1.1 为什么环境这么难配？难点到底在哪

mmdetection3d不是个孤立项目，它建立在整整一摞底层库之上。用一句话说，它是“站在其他开源框架肩膀上的框架”。它的直接父依赖是mmdetection（2D目标检测库）和mmsegmentation（语义分割库），而这两个库又要跑在mmcv这个底层视觉基础库上，mmcv又依赖PyTorch，PyTorch又依赖CUDA和显卡驱动。

这条链子只要有一环版本不匹配，整个就崩了。最典型的例子就是mmcv：mmcv分两个版本线，老版本叫mmcv-full，新版本直接把mmcv-full合并进mmcv了。每个mmcv版本官网只预编译了特定PyTorch和CUDA组合的包，如果你用了一个没预编译的组合，就得从源码现场编译，而源码编译mmcv动不动就要半小时以上，中途还可能因为内存不足、编译器太老、网络中断等原因失败。

我见过很多人在这一步放弃的。其实不是动手能力差，而是没搞明白“版本匹配”和“编译工具链”这两个关键点。

1.2 版本兼容表怎么看？我的推荐组合

官方在文档里给过一个兼容矩阵，列了mmdet、mmseg、mmcv、PyTorch、Python几个维度的版本对应关系。这里我直接给两个时代、几组被大量验证过的组合，你们照着抄就行。

第一类是比较稳的旧版组合，适合还在用老代码、或者显卡驱动老一点的环境：

我可以直接告诉你，只要你不是在跑很特殊的老模型，就直接选新版组合，装起来反而省心。新版不再强制spconv1.x源码编译，很多稀疏卷积操作可以直接用mmcv内置算子了；而且新版用mim工具一条命令就能装mmcv，能下载预编译包就别自己编译，这是最重要的省时诀窍。

注意：显卡驱动版本不要太老。哪怕你只在CPU跑数据预处理，后面只要一装GPU版的PyTorch，驱动不支持就会直接提示CUDA driver version is insufficient。建议先把nvidia-smi里显示的CUDA版本查出来，只要大于等于你目标CUDA版本就行。

1.3 我的推荐组合背后的选择逻辑

很多人纠结“到底选哪一版CUDA”，其实只要显卡驱动支持，选哪一版差别不大。真正要考虑的是生态兼容：你后面还要不要装spconv？spconv2要求PyTorch 1.13以上；要不要装open3d？open3d新版本对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 python=3.8 -y conda activate mm3d

然后先装一些基础依赖。这里有个小窍门：先把numpy装好，不要依赖后装的PyTorch顺手带出来的numpy版本。因为PyTorch不同版本会锁numpy版本范围，如果让它自动装，有可能装出一个跟你后面其他库不兼容的numpy。提前用一个单独命令装好，可以避免很多玄学问题。

pip install numpy==1.23.5 cython wheel

Cython一定要提前装。我见过太多人在编译spconv的时候报No module named 'Cython'，就是因为没提前装，结果编译流程跑到一半戛然而止。先装好，后面至少少踩一个坑。

2.2 PyTorch安装：这一步别用默认pip源

PyTorch的安装推荐直接用官方命令。这里最容易犯的错误是直接pip install torch，这样装到的通常是CPU版或某个固定CUDA版，跟你想的不一定一样。要指定CUDA版本，去官方PyTorch官网找对应命令即可：

pip install torch==1.13.0 torchvision==0.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 mmcv==2.1.0

如果mim找不到你当前PyTorch/CUDA对应的预编译包，它会提示你需要源码编译，这时别慌，源码编译也只能接受。但编译前有几个环境变量必须设好，不然容易翻车。

首先，设置FORCE_CUDA=1，强制按CUDA模式编译；其次，设置TORCH_CUDA_ARCH_LIST，这个变量千万别跳过，它会告诉编译器你的显卡计算能力是什么。如果没设，编译器会一个个尝试支持所有常见架构，极其耗时，而且可能在其中一个架构上编译失败导致整体失败。查自己显卡算力可以用nvidia-smi配合网络搜索，也可以通过下面的命令：

import torch print(torch.cuda.get_device_capability())

得到类似(7, 5)返回，就设置成TORCH_CUDA_ARCH_LIST="7.5"。然后源码编译：

export FORCE_CUDA=1 export TORCH_CUDA_ARCH_LIST="7.5" pip install mmcv==2.1.0

编译期间不要动终端，别同时开大量占内存的程序。编译到一半内存爆炸的情况我也遇到过，加了MAX_JOBS=4来限制并发后就好多了：

export MAX_JOBS=4

注意：mmcv源码编译完不代表万事大吉，建议编译后立刻测一下import mmcv，再跑一个小的算子测试确认GPU版本生效，别等到后面跑训练才发现装的是CPU版。

2.4 安装mmdet和mmsegmentation

mmcv装好之后，mmdet和mmsegmentation就是常规安装了，直接pip即可。新版组合我推荐：

pip install mmdet==3.2.0 pip install mmsegmentation==1.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 高频报错速查表

我把平时帮别人排查时遇到的高频问题整理成一张表格，基本都是那些翻来覆去出现的版本冲突和编译问题：

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 size=1跑通一个迭代，再逐步增加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系列项目的环境问题，优先去官方文档看“安装”和“常见问题”两节，绝大多数报错都能找到对应说明，比直接在社区里发帖问要快得多。