2. 环境准备与版本匹配MMDetection 的安装第一道坎往往不是安装本身而是环境。我见过太多人卡在 import 报错翻来覆去查不到原因最后发现是 CUDA 和 PyTorch 版本对不上。所以先把环境这关捋清楚后面能省一大半的事。2.1 系统与硬件层面的前置要求先说结论Linux 和 Windows 都支持macOS 只能做 CPU 推理没法跑 GPU 训练M 系列芯片虽然能用 MPS 后端但 MMDetection 对 MPS 的支持并不完整很多算子会落到 CPU 上速度优势体现不出来。我的建议是如果你想认真做训练直接上 Linux NVIDIA 显卡省心。Windows 下面不是不能跑但编译一些自定义算子时经常会碰见 MSVC 版本、路径空格这类幺蛾子我身边好几个同事最后都换到 Ubuntu 了。硬件方面显存是一个很现实的问题。拿 COCO 数据集训练时如果用的输入尺寸是 1333x800batch size 设为 2一张 8G 显存的卡跑 Faster R-CNN 都紧巴巴的更别说 Cascade Mask R-CNN 这种重型模型了。如果你手里是 6G 或者 8G 的卡建议先从两阶段检测器开始试或者直接缩小输入尺寸、降低 batch size先把流程跑通再追求精度。2.2 Python 版本解析MMDetection 的依赖链是MMDetection 依赖 MMEngine 和 MMCVMMCV 又依赖 PyTorch。这条链条里任何一个版本不匹配都会在运行时冒出一堆莫名其妙的报错。先说结论Python 建议用 3.8 到 3.10。3.7 太老很多新版本依赖已经不提供对应的 wheel 包了3.11 以上则可能因为某些算子库没跟上而导致安装失败。我建议直接新建一个虚拟环境别偷懒conda create -n openmmlab python3.8 -y conda activate openmmlab注意如果你用的是公司内网或者服务器没有外网权限conda 创建环境时可能会卡在 Solving environment 这一步这时候可以换成python -m venv配合 pip 使用或者配置好内网镜像源再操作。2.3 CUDA 与 PyTorch 版本匹配的黄金法则这一节是整个安装过程中的重中之重。简单来说PyTorch 的 CUDA 版本必须和驱动支持的 CUDA 版本兼容但这里有个常见的误区很多人以为驱动要装带 CUDA Toolkit 的那个版本。其实驱动本身就是兼容的关键看 PyTorch 编译时用的 CUDA 版本。用nvidia-smi查看驱动支持的 CUDA 版本比如显示CUDA Version: 12.1那说明你的驱动最高支持 CUDA 12.1。这时你就完全可以装 CUDA 11.8 或 12.1 的 PyTorch 轮子。举个例子# 查看驱动版本 nvidia-smi # 输出示例 # NVIDIA-SMI 525.85.12 Driver Version: 525.85.12 CUDA Version: 12.1然后安装对应 PyTorch# CUDA 11.8 版本 pip install torch2.0.1 torchvision0.15.2 --index-url https://download.pytorch.org/whl/cu118 # CUDA 12.1 版本 pip install torch2.1.1 torchvision0.16.1 --index-url https://download.pytorch.org/whl/cu121这里有个实测经验MMDetection 3.x 支持 PyTorch 1.8 到 2.x但推荐 1.13 以上。PyTorch 太旧的话很多新出的 CUDA 算子编译不过去反而拖慢进度。2.4 用一张表理清 MMCV 全家桶的关系MMDetection 3.x 之后官方把原来的 MMCV 拆成了两块MMCV 和 MMEngine。很多人第一次装的时候看到mmcv-full和mmcv两个名字直接懵掉。这张表可以直接保存下来组件名作用安装方式MMEngine训练、验证、日志、钩子等基础框架pip install mmengineMMCV计算机视觉底层算子如 NMS、RoIAlign、Deformable Convpip install mmcv -f 对应链接MMDetection检测模型库真正写代码时 import 的对象pip install mmdet注意这里建议装mmcv而不是mmcv-full。在 2.x 时代装的是mmcv-full3.x 时代统一叫mmcv不需要再区分-full后缀。如果你在网上查到的教程是 2023 年之前的用的多半是mmcv-full那份教程很可能已经过时了。MMCV 的安装建议用官方预编译轮子避免本地编译。本地编译 MMCV 极慢我见过一台 8 核机器编译了整整一个半小时最后还失败的情况。pip install mmcv -f https://download.openmmlab.com/mmcv/dist/cu118/torch2.0/index.html以上链接的写法要对应你实际的 CUDA 和 PyTorch 版本。如果版本对不上编译时你会看到类似Undefined symbols的报错查半天都不一定能定位到。3. MMDetection 本体安装的完整流程环境准备好以后MMDetection 的安装就很简单了。但为了照顾第一次接触 OpenMMLab 生态的朋友我还是按完整步骤来写每一步都说明为什么这样做。3.1 从源码安装还是 pip 安装MMDetection 官方提供两种方式pip install mmdet直接安装稳定版适合只想调用现成模型做推理的用户从 GitHub 拉源码git clone后运行pip install -v -e .可编辑安装适合要改核心代码、加自定义模型或 debug 源码的用户我的建议是入门阶段直接 pip 安装即可。因为 MMDetection 的复现能力已经很强写训练脚本时只需要改配置文件基本用不着动源码。等到后面你要自定义 head、加 loss 或者改 hook 时再换成源码安装也不迟。如果你还是想用源码安装步骤是git clone https://github.com/open-mmlab/mmdetection.git cd mmdetection pip install -v -e .这里-e表示可编辑模式即源码改了什么import 时立刻生效不用重新装一遍。这个模式在开发时的体验非常好我常用它来给模型加自定义 loss改完直接重新跑训练就行。3.2 验证安装是否成功的三个命令很多教程教你装完以后python -c import mmdet只要不报错就算成功。但说实话这种验证太粗糙了。至少应该做到以下三步# 第一步确认 import 成功 python -c import mmdet; print(mmdet.__version__) # 第二步确认 mmcv 和 torch 版本匹配 python -c import mmcv; print(mmcv.__version__) # 第三步确认 CUDA 环境可用 python -c import torch; print(torch.cuda.is_available())第三步尤其重要。很多人 import 全部正常一跑训练就报CUDA error: no kernel image is available for execution on the device原因就是 PyTorch 编译时的 CUDA 版本高于驱动所支持的版本。如果torch.cuda.is_available()返回False或报错不要继续往后走回头检查驱动和 PyTorch 版本。提示在 Linux 服务器上用nvidia-smi和python -c import torch; print(torch.version.cuda)对比两个 CUDA 版本号是最快的排查方法。3.3 一个最小推理 Demo装完之后为了确认整个链路真的通了我最喜欢跑一个官方自带的推理脚本。不需要训练权重直接用demo目录下的脚本和预训练模型就能测出来python demo/image_demo.py demo/demo.jpg configs/faster_rcnn/faster-rcnn_r50_fpn_1x_coco.py \ --weights https://download.openmmlab.com/mmdetection/v2.0/faster_rcnn/faster_rcnn_r50_fpn_1x_coco_20200130-047c8118.pth \ --device cuda:0注意上面的模型权重链接用了 2.x 时代的旧地址在 3.x 版本里已经失效了。正确做法是去 Model Zoo 页面下载对应的.pth文件或者直接用官网脚本里的默认链接。如果链接失效可以在终端里看到 HTTP 404 的报错这会浪费你不少时间。如果推理脚本跑起来以后能看到一张标注好检测框的图片那环境就是真的通了可以进入下一步跑训练流程。4. 实操环节如何运行一次完整的训练到这里你的 MMDetection 已经能跑推理了。但装环境的意义往往是为了训练自己的数据集这一步也是很多人最容易卡住的地方——不是环境问题而是数据集格式和配置文件的问题。我来拆开讲。4.1 数据集目录结构MMDetection 的训练数据用的是 COCO 格式这是目标检测领域最通用的标注格式。即使你手里的数据不是 COCO 标准也得先转成这个格式。一个标准的 COCO 格式数据集目录长这样data/ ├── coco/ │ ├── annotations/ │ │ ├── instances_train2017.json │ │ └── instances_val2017.json │ ├── train2017/ │ │ ├── 000000000001.jpg │ │ └── ... │ └── val2017/ │ ├── 000000000042.jpg │ └── ...如果你用的是自定义数据集我建议直接用一些标注工具导出 COCO 格式而不是自己手写 JSON。手写标注文件很容易在类别 id 上出错比如 COCO 的类别 id 从 1 开始计数而很多工具的背景类别是 0一个不留神就会导致训练 loss 直接崩到 NaN。4.2 配置文件的关键参数解读MMDetection 的核心玩法就是改配置文件。以faster-rcnn_r50_fpn_1x_coco.py为例你需要关注以下内容num_classes必须改成你自己的类别数。如果是单类目标检测这里要填 1如果是 3 类就填 3。注意背景类不算在里面。data_root指向你的数据集目录比如/home/user/data/coco。batch_sizesamples_per_gpu这个参数代表每张卡每步训练的图片数。显存不够就调小比如 2、1。max_epochs1x约等于 12 个 epoch代表 12 个 epoch 的训练进度计划。如果数据量小可以改成20x或50x但要注意学习率调整策略也要一并改否则后期 loss 难收敛。这里有个新手常踩的坑只改了num_classes忘了改模型 head 中的num_classes。在 MMDetection 3.x 中这个参数分散在多个地方比如roi_head里的bbox_head和mask_head如果是 Mask R-CNN。最好的办法是在配置文件里用_base_继承后重新model dict(roi_headdict(bbox_headdict(num_classes你的类别数)))这样能一次性覆盖所有 head 的类别数。4.3 训练命令与日志观察配置改好以后训练命令本身很简单python tools/train.py configs/faster_rcnn/faster-rcnn_r50_fpn_1x_coco.py但要真正判断训练是否正常你需要观察几个关键指标loss_rpn_clsRPN 分支的分类损失正常来说应该逐步降低。loss_cls最终检测头的分类损失。loss_bbox回归损失。如果这个值突然变成inf或者NaN基本可以断定是学习率过大或者标注框出现了 0 尺寸比如某个 bounding box 的宽或高为 0。lr每轮迭代打印的学习率确认它是按照调度策略在变化。日志里如果出现nan或inf第一反应不是调参而是检查数据用可视化脚本把标注画到原图上看看是不是有错标。我处理过不下 5 次 NaN loss 的问题最后原因全是标注文件有脏数据。4.4 测试与评估训练完成后出一张 mAP 报告是必须的python tools/test.py configs/faster_rcnn/faster-rcnn_r50_fpn_1x_coco.py \ work_dirs/faster-rcnn_r50_fpn_1x_coco/epoch_12.pth \ --eval bbox--eval bbox会输出 COCO 格式的 AP 结果包含APIoU0.50:0.95、APIoU0.50、APIoU0.75等指标。如果你自己的任务对定位精度要求高可以重点看APIoU0.75如果只关心粗定位看APIoU0.50就够了。5. 常见问题与排查技巧实录这一部分是我个人实际踩坑的总结很多问题看起来不复杂但解决起来绕了远路。统一整理成速查表方便你直接对照排查。5.1 问题速查表现象可能原因解决方案ModuleNotFoundError: No module named mmcvMMCV 未安装或安装在别的环境检查当前环境pip list重新安装 mmcv 对应版本ImportError: cannot import name Config from mmcvMMCV 版本过旧还在 1.x 时代升级到最新版 mmcv或者改用 mmengine 中的 ConfigCUDA error: no kernel image is availablePyTorch 的 CUDA 版本高于驱动支持版本降低 PyTorch 的 CUDA 版本或升级显卡驱动RuntimeError: Attempting to deserialize object on a CUDA device加载了 GPU 训练的权重到 CPU 环境加载权重时加map_locationcpu训练时 loss 为 NaN标注有脏数据、学习率过大、BN 的 momentum 过小可视化检查标注降低 lr或改momentum为0.01安装过程卡死pip 长时间无响应网络问题或者本地编译 MMCV 太慢换镜像源或直接用预编译的 MMCV 轮子5.2 多卡训练时常见的坑多卡训练是很多刚上手的人容易出问题的地方。首先要保证启动命令带了CUDA_VISIBLE_DEVICES指定可见的卡号CUDA_VISIBLE_DEVICES0,1,2,3 bash tools/dist_train.sh configs/faster_rcnn/faster-rcnn_r50_fpn_1x_coco.py 4这里4是卡的数量不是卡编号。如果你只有 2 张卡就写2否则进程会一直等不到足够的卡。另一个多卡训练常遇见的坑是每张卡的 batch size 和总 batch size 的关系。配置文件里的samples_per_gpu是单卡的值总 batch size samples_per_gpu * 卡数。如果你想让总 batch size 保持 8用 4 卡训练samples_per_gpu就设成 2用 2 卡训练samples_per_gpu就设成 4。学习率需要根据总 batch size 适当调整一般线性缩放但我见过很多人直接用默认 lr 也不出问题因为 COCO 上的 0.02 本来就是一个相对保守的值。5.3 到底要不要编译 CUDA 算子很多人在安装 MMCV 时会纠结要不要用MMCV_WITH_OPS1编译算子。我的经验是能不用就不用。预编译轮子已经覆盖了绝大多数常用算子如nms、roi_align、deformable_conv2d等。只有当你用了官方预编译没覆盖的 CUDA 算子或者自定义算子时才需要本地编译。如果你确实需要编译务必注意两点确保当前环境能访问到nvcc即 CUDA Toolkit 真的装了编译前不要忘了设置环境变量FORCE_CUDA1否则可能出现“看起来编译了实际上没用 GPU”的情况编译过程中如果看到fatal error: cuda_runtime_api.h: No such file or directory说明 CUDA 路径没找到可能需要手动指定export CUDA_HOME/usr/local/cuda5.4 我踩过的三个隐蔽的坑最后聊三个不太容易排查、但一旦遇上非常折磨人的问题。第一个是配置文件缓存问题。MMDetection 3.x 在跑过一次训练后会在work_dirs里生成一个并合并过的完整配置存档。当你后续改了_base_里的配置再跑tools/train.py时如果用法不当可能没真正用上你的新配置而是还在用缓存。解决方法是训练前删掉work_dirs下的旧文件或者看一眼终端日志里打印出来的配置是不是你预期的那份。第二个是路径分隔符在 Windows 下的表现。如果你在 Windows 上跑配置文件里的路径最好统一用正斜杠/或者用os.path.join生成别直接在 .py 里拼反斜杠不然会在mmcv底层路径处理时报No such file or directory。第三个是预训练权重自动下载太慢。每次修改模型结构重新训练时MMDetection 默认会自动下载对应骨干网络的 ImageNet 预训练权重。如果网络不好会一直卡在下载环节。我的做法是提前手动下载好.pth文件然后在配置文件里指定model dict( backbonedict( init_cfgdict(typePretrained, checkpoint/path/to/resnet50-19c8e357.pth)))这样不仅快还能避免服务器没外网权限时反复超时的窘境。6. 基于实际场景的选型建议聊完安装和训练再补充一点我自己在实践中总结的选型经验。经常有人问好不容易装好了到底该跑哪个模型这里给几类典型需求做个简单对照。6.1 轻量级部署场景选型如果你是要部署到边缘设备、手机端或者嵌入式平台那重量级的 Cascade R-CNN 肯定不合适。我建议优先考虑RTMDetMMDetection 3.x 主推的实时检测模型部署友好精度和速度的平衡点非常好。YOLOX如果你更熟悉 YOLO 系列MMDetection 里也有 YOLOX 的实现能直接复用这套训练和部署链路。FCOS单阶段无锚框检测器结构简洁训练速度也快。这些模型在 COCO 上的精度可能不如两阶段大模型但部署时的推理速度和显存占用优势非常明显。6.2 高精度场景选型如果对精度要求极高不关心速度优先考虑Cascade Mask R-CNN级联结构能逐步提升 IoU 阈值在高 IoU 指标上有明显优势。DINO基于 DETR 系列的最新成果在 COCO 上刷新过不少次 SOTA但对显存和训练时间的要求也更高。Mask2Former如果你同时要做实例分割和全景分割这个模型在统一框架上做得非常好。这些模型的训练时间通常以天为单位需要你有足够的 GPU 资源和耐心。6.3 实际项目里我常用的一个组合下面给一个我实际做项目时的经验组合供参考任务工业质检中的缺陷检测 数据类型单类缺陷小目标2000张图 推荐配置 模型RTMDet-s backbone默认 训练50 epochbatch size 8需要在多卡或大显存下 增强随机翻转 多尺度训练scale jitter 部署TensorRT FP16这个组合在速度和精度上比较均衡单卡的 8G 显存也能跑得动适合快速验证和项目交付。7. 写在最后的实际体会装 MMDetection 这件事看起来只是敲几行命令但背后藏着版本依赖和深度学习环境管理的整个逻辑。我当年第一次装的时候也经历过编译到凌晨、报错到怀疑人生的阶段。后来总结出两个最简单有效的原则一是所有东西都尽量用官方预编译版本二是每次只变更一个版本变量。如果你在安装过程中卡住了不要急着搜报错原文先用pip list把当前环境里的核心包版本全部查一遍对照一下 torch、mmcv、mmdet、mmengine 的版本关系。一般来说90% 的问题都能在这一步定位到。剩下的 10%再去看官方文档的 Issue 区或者 FAQ基本都能解决。另外一个小技巧安装完以后不管最后跑成什么样都建议把环境用conda env export environment.yaml导出一份。这样就算以后换机器也能用一份文件把环境完整还原回来。这个习惯救了我不止一次。如果你接下来准备训练自己的数据集我的建议是从一个超小型的 Demo 数据开始哪怕是 10 张图先跑通整套流程确认数据格式、标签、评估环节都没问题再上全部数据。很多问题在 10 张图上暴露出来远比你在 5000 张图上折腾一整天要划算得多。