MMDetection环境配置与Demo运行：版本匹配与避坑指南

环境准备是安装这类深度学习框架的第一道坎。很多同学在装mmdetection时卡住九成以上都是环境版本没对齐比如PyTorch和CUDA的搭配问题、MMCV和mmdet版本不匹配之类。与其直接甩命令不如先说清楚这工具的定位它本质上是一个基于PyTorch的目标检测工具箱把Faster R-CNN、YOLO系列、Mask R-CNN这些主流检测模型都收拢进了同一套代码框架里支持训练、验证、推理全流程。这篇文章就是带你从零开始把环境搞定、把demo跑通并且把过程中可能踩的坑提前给你标出来。1. 环境准备与方案选型1.1 核心版本匹配关系先看版本问题。mmdetection对版本极其敏感装错版本是后面所有诡异报错的第一源头。核心依赖链是Python - PyTorch - MMCV - MMDetection。这条链上的每一环都有对应的兼容关系必须严格对齐。我自己常用的稳定搭配是Python 3.8 或 3.93.10以上某些老版本算子会编译失败PyTorch 1.13.1 或 2.0.1适配大多数GPU服务器MMCV 2.0.1注意新版mmdet依赖MMCV 2.x不再兼容1.xMMDetection 3.x提示如果你用的是mmdet 3.0以上版本的话对应需要安装的是mmcv 2.0以上版本。老教程里那种pip install mmcv-full的写法在新版本已经不适用了。这里有一个关键认知更新mmcv和mmcv-full已经合并。以前要区分基础版和完整版现在新版直接pip install mmcv就行不要再去搜老教程里的mmcv-full命令。1.2 环境隔离与安装方式选型强烈建议用conda环境隔离不要直接装在服务器的基础环境里。我见过太多人因为装了mmdet之后把原本跑得好好的TensorFlow的依赖搞坏了。操作方式conda create -n mmdet python3.9 -y conda activate mmdetconda解决了Python版本层面的隔离包管理方面我一般用pip处理。原因也很简单日常见到的mmdet相关依赖包在pip仓库中的更新及时而且官方文档的安装命令也全部基于pip。这里不建议混用conda install和pip install来装同一类包容易把环境搞乱。1.3 为什么这套方案最稳总结我复现过多台机器、多套环境后的体感Python 3.9加PyTorch 1.13是目前兼容性测试面最广、网上可查的坑最全的组合。如果你是一个经验不多的人不建议直接上Python 3.11加PyTorch 2.1这种太新的组合虽然也可以用部分第三方算子需要现场编译报错内容也更冷门排查起来会麻烦不少。2. 核心依赖安装细节拆解2.1 PyTorch安装的首要原则PyTorch的安装要放在所有依赖之前。因为MMCV必须要知道你用的是哪一版PyTorch编译器要针对已有PyTorch的C接口来编译算子。GPU版本的安装命令以CUDA 11.8为例pip install torch1.13.1 torchvision0.14.1 torchaudio0.13.1 --index-url https://download.pytorch.org/whl/cu118CPU版本的安装命令没有独立显卡的机器或者只是先跑通demopip install torch1.13.1 torchvision0.14.1 torchaudio0.13.1 --index-url https://download.pytorch.org/whl/cpu注意如果你装的是CPU版后面MMCV编译相关的包也要走CPU对应版本二者不能混。跑demo的话CPU也够用推理速度慢一些但能跑通。2.2 验证PyTorch是否装好安装完成后不要急着装MMCV先做一个最简单的验证。这一步能帮你把问题精准定位在“PyTorch没装好”而不是“mmdet有问题”。python -c import torch; print(torch.__version__); print(torch.cuda.is_available())如果是GPU版本看到输出中第二行是True就说明CUDA环境接通了。输出False的话也不用慌可能是CUDA驱动版本和PyTorch要求的CUDA版本不匹配此时优先检查显卡驱动版本而不是反复重装PyTorch。2.3 MMCV的完整安装流程新版mmdet对应安装的MMCV版本是2.x。安装方式官方推荐用mim来装主要是mim会自动匹配与你当前PyTorch和CUDA版本对应的MMCV版本这一步能省掉大量查表对版本的时间。pip install -U openmim mim install mmcv2.0.1如果你对版本兼容性机制感兴趣也可以手动指定预编译包安装。方式是在MMCV官方预编译包列表里找到对应组合形如pip install mmcv2.0.1 -f https://download.openmmlab.com/mmcv/dist/cu118/torch1.13/index.html这两种方式优先推荐mim。理由在于手动指定URL时需要你自己确认cu118、torch1.13这些字符串和你本机环境完全一致一旦写错安装过程也不报错运行时就会出算子不匹配的诡异问题排查起来会很折腾。2.4 为什么要先装MMCV再装mmdetMMCV是底层计算机视觉基础库包含IO、图像处理、CUDA算子等核心组件mmdet是基于MMCV搭建的目标检测算法库。这个依赖层级决定了编译顺序不可颠倒。如果先装mmdet它依赖的MMCV版本会被pip自动解析并安装这时可能会装成最新版而最新版MMCV和你的mmdet版本未必兼容。3. 实操过程与demo运行3.1 正式安装mmdetectionMMCV装好之后安装mmdet本身反而很简单。推荐直接用pip安装发布版pip install mmdet3.1.0如果你后面有改源码的需求也可以走源码安装方式git clone https://github.com/open-mmlab/mmdetection.git cd mmdetection pip install -v -e .源码安装的好处是改代码后即时生效不需要重新安装。日常调试配置、看loss曲线、改模型结构时比较方便。但如果你只是跑demo强烈建议直接pip安装源码安装过程中会有一次完整的build过程相对耗时也更容易出现编译报错。3.2 安装后的最终验证装完所有依赖后执行一次完整的验证命令python -c import mmdet; print(mmdet.__version__)如果能正常输出版本号说明核心安装没问题。这里也可以顺手把mim验证带上mim download mmdet --config mask-rcnn_r50_fpn_1x_coco --dest ./checkpoints这个命令的作用是下载模型对应的配置文件和预训练权重后面跑demo正好用得上。3.3 跑通第一张图片的demo先准备一张测试图片什么内容都行建议选一张带多个物体的照片效果更直观。官方demo脚本调用方式如下python demo/image_demo.py demo.jpg checkpoint/mask-rcnn_r50_fpn_1x_coco_20200205-d4ca0a35.pth --device cpu命令行参数拆解一下第一个参数是输入图片路径第二个是模型权重文件路径--device cpu指定在CPU上运行如果你的机器有GPU把这个参数换成cuda:0即可。脚本会自动输出标注了检测框的图片并保存为demo.jpg.png。如果你的标签文字出现乱码通常是检测类别名称里中文字体缺失造成需要额外准备中文字体文件不是检测流程本身的问题。3.4 从图片demo过渡到摄像头demo图片demo跑通之后摄像头实时检测才是真正提现框架能力的场景。官方代码库里已经有现成的脚本python demo/webcam_demo.py configs/mask-rcnn/mask-rcnn_r50_fpn_1x_coco.py checkpoint/mask-rcnn_r50_fpn_1x_coco_20200205-d4ca0a35.pth摄像头demo的配置文件和权重文件的对应关系与image_demo略有差异需要同时传入config和checkpoint两个参数。脚本会实时调用电脑摄像头并以模型推理速度输出检测结果。实测下来GPU环境下Mask R-CNN能做到实时流畅CPU环境下帧率会明显下降这属于正常现象不要以为是代码卡死了。4. 常见问题排查与避坑经验4.1 安装环节报错速查报错信息常见原因解决办法ModuleNotFoundError: No module named mmcvMMCV没有安装成功或装错了环境确认当前激活的conda环境是不是mmdet再pip listFile src/mmcv_imread.cpp ... fatal errorMMCV源码编译缺少gcc环境apt install build-essential或yum install gcc-cundefined symbol: _ZN2at5ErrorC1E...PyTorch与MMCV版本不匹配卸载mmcv后用mim重新安装匹配版本No matching distribution found for mmcv指定的MMCV版本在当前Python/PyTorch组合下没有预编译包调整Python或者PyTorch版本到推荐组合ImportError: libGL.so.1: cannot open shared object file系统缺少OpenGL运行库apt install libgl1 libglib2.0-04.2 运行demo时的常见问题demo阶段最常见的报错之一是ValueError: device 1或类似的设备分配异常。这通常是因为机器上有多张显卡模型默认被分配到序号为0的显卡但该卡被其他进程占用了显存。解决办法是运行前指定空闲显卡CUDA_VISIBLE_DEVICES1 python demo/image_demo.py ...如果遇到的是KeyError: classes这类问题大多数情况下是权重文件和配置文件不匹配。比如你用Mask R-CNN的权重去加载了Faster R-CNN的配置那肯定会出问题。建议下载权重时仔细核对文件名和配置路径。4.3 训练模型也要提前掌握的配置常识虽然本文标题是安装和跑demo但不少人的最终诉求其实是训练自定义模型。提前做一些知识铺垫对你后续切换任务会顺畅很多。mmdetection的配置文件采用Python格式核心需要修改的位置就那么几处data_root指向你自己的数据集路径num_classes改成你的类别数metainfo里的classes列表替换成自定义类别。训练前还要检查load_from字段是否指向预训练权重最好把预训练权重下载好放本地避免训练启动时临时去外网拉文件。推荐在跑demo后做一次最小化的训练实验就用官方自带的config训练5个epoch确认整个训练流程能走通。这比完全从零开始写训练脚本要安稳得多也方便你判断问题是出在框架本身还是自己的代码逻辑上。4.4 实测中值得留个心眼的小细节有几个容易被忽视的细节我实际踩过不少次坑。其一如果训练或demo过程中出现OOM显存溢出优先降低batch_size或者img_scale不要一上来就缩减模型规模。模型是小了显存占用也小了但检测效果跟着掉反而会误导你对问题的判断。其二多卡训练时要确保每张卡的batch_size一致用CUDA_VISIBLE_DEVICES控制可见卡数时不要改动config里的world size相关参数否则训练启动后会报设备数量预期不一致的错误。另外mmdet自带的高层API写法比较通用如果你想替换backbone、neck或者head通常只要修改config里的对应字段就行不用重写整个模型类。整个框架把“配置即代码”这个理念贯彻得很到位这一点在实际项目中能给你剩不少功夫。