1. 项目概述与环境认知1.1 先搞明白MMDetection到底是什么MMDetection全称是OpenMMLab Toolbox for Object Detection是由国内顶尖人工智能研究团队开源的一个基于PyTorch的目标检测工具箱。它把主流的目标检测算法比如Faster R-CNN、YOLO系列、RetinaNet、Mask R-CNN、FCOS等几十种用统一的代码框架重新实现了一遍并且提供了开箱即用的训练、推理、评估脚本。你只需要修改一个配置文件就能在COCO、VOC这类标准数据集上训练出检测模型也可以直接在自定义数据集上做迁移学习和微调。业内很多做工业视觉检测、安防监控、自动驾驶感知的人都是拿它当基线工具来用。我当初第一次接触MMDetection时印象最深的就是它的模块化设计。它把目标检测任务拆成了dataset数据加载、model模型结构、evaluate评估指标、runner训练循环等几个独立模块。你想换backbone特征提取网络就改配置文件里的model.backbone字段想改数据增强策略就改train_pipeline里的配置项想在某个数据集上跑实验写一个继承自CustomDataset的数据类就行。相比从零手写检测网络这个框架能帮你省掉至少几个月的工程时间。但与之对应的代价是它的安装过程比一般Python库要复杂一些。因为MMDetection依赖一个底层的基础库叫MMCVOpenMMLab Computer Vision Library而MMCV内部又依赖PyTorch和CUDA版本。如果你直接用pip install mmdetection很有可能会碰到版本匹配问题——要么是MMCV编译失败要么是装上之后import就报错要么是跑demo时报各种cuda runtime error。这一篇系列文章的第一部分我就先把环境准备和安装这条路上最关键的几个坑全部拆解开让你能一次装到位。1.2 安装的总体目标与系列规划这篇是系列的第一篇核心任务只有一个在你的电脑上成功安装MMDetection并且用一个实际的推理Demo验证安装结果可用。我默认你的操作系统是LinuxUbuntu 18.04或20.04或Windows 10/11显卡是NVIDIA独立显卡。如果你没有GPU或者只有A卡/核显那跑MMDetection会很吃力建议你先找一个带GPU的服务器或者云主机然后再按本文步骤操作。按照我的计划系列第一篇覆盖从环境准备、版本选型到安装验证的全流程后续篇章再讲数据集准备、配置文件详解、模型训练和调优。不过这篇文章本身已经是完整的闭环你跟着走完就拥有一个可以正常使用并能跑通推理的MMDetection环境。2. 版本选型与兼容性分析2.1 版本对应关系是第一步也是最大的坑安装MMDetection最核心的一条经验不要直接装最新版也不要只固定某一个库的版本而是要把Python、PyTorch、CUDA、MMCV、MMDetection这五个东西的版本组合当成一个整体来选。它们之间是强耦合的。具体来说MMDetection的版本号决定了它依赖的MMCV主版本。以目前主流的MMDetection 2.x和3.x系列为例整个对应关系大致是MMDetection版本依赖的MMCV版本依赖的PyTorch版本依赖的Python版本2.25.x2.x系列最终版mmcv 1.3.8, 1.8.0PyTorch 1.5Python 3.63.0.0及以上mmcv 2.0.0PyTorch 1.8Python 3.73.2.0以上mmcv 2.0.1PyTorch 1.8Python 3.73.5.0以上mmcv 2.2.0PyTorch 1.8Python 3.7这张表格看起来简单但实际安装时很多人会栽在MMCV这里。因为MMCV有两种形态mmcv完整版包含所有CUDA算子和mmcv-lite轻量版只含必要部分。目标检测任务必须用完整版mmcv因为像Deformable Convolution、ROI Align这类算子都需要编译CUDA扩展。而mmcv-lite装上了之后跑很多模型会直接报错——算子不存在。再往下一层mmcv完整版在安装时需要和PyTorch版本、CUDA版本严格对齐。它的安装命令不是简单的pip install mmcv而是通过指定下载URL来安装。比如我要装的是CUDA 11.7 PyTorch 2.0.0的环境对应的命令就是pip install mmcv -f https://download.openmmlab.com/mmcv/dist/cu117/torch2.0.0/index.html注意这个URL里的cu117和torch2.0.0必须和你的实际环境严格一致。任何一处对不上pip就会去PyPI拉一个不带CUDA算子的版本或者干脆给你装一个需要本地编译的版本——本地编译不但慢而且极容易因为gcc版本、CUDA路径的问题直接失败。2.2 选型建议从GPU驱动开始往上确认根据我的实际经验最稳妥的选型路径是从底往上逐层确认而且每确认一层就记录一下当前结果。具体顺序是第一步看显卡型号和驱动版本。Linux下用nvidia-smi命令Windows下在终端里输入nvidia-smi如果有CUDA驱动的话或者打开NVIDIA控制面板。这一步的目的不是看显卡有多强而是确认支持的最高CUDA版本。第二步选CUDA版本。我的建议是不要追求最新CUDA选择PyTorch官方支持列表里比较成熟的版本。比如现在PyTorch 2.0.x对应支持CUDA 11.7和11.8PyTorch 2.1.x对应支持CUDA 11.8和12.1。选那个既有PyTorch官方预编译包又能在nvidia-smi看到的最高版本范围内的CUDA就是最稳的。第三步选Python版本。虽然官方说3.7都行但结合实际生态我强烈建议Python 3.8或3.9。Python 3.10和3.11对某些旧版本PyTorch不友好Python 3.7又略显老旧很多新库在3.7上已经放弃支持。3.8/3.9是兼容性最好的版本。第四步选PyTorch版本。查一下MMDetection官方文档里要求的范围然后在这个范围内选一个成熟稳定的版本例如2.0.1或1.13.1。不要选最新发布的大版本因为新大版本刚出来时相关的MMCV预编译包不一定马上跟上。第五步选MMDetection版本。如果目标是跑通日常训练和推理用3.2.0或3.5.0这类稳定版就很好它们对MMCV 2.0.x的支持已经在社区里被充分验证过了。到这一步版本组合就已经定了。以我自己最近一次安装为例最终的组合是Ubuntu 20.04 Python 3.8 CUDA 11.8 PyTorch 2.0.1 MMCV 2.0.1 MMDetection 3.2.0。这套组合装下来非常顺滑几乎没有遇到坑。2.3 为什么要用conda虚拟环境我不止一次见过有人直接把MMDetection装进系统全局Python环境里然后被各种依赖冲突折磨得欲哭无泪。原因很简单MMDetection依赖链上的库和很多其他深度学习项目是重叠但版本不一致的。比如某个项目需要opencv-python 4.5另一个需要4.6你全局环境没法同时满足。使用conda虚拟环境每个项目一套隔离的Python解释器和三方库互不干扰。以后你在这台机器上做另一个项目直接新建一个环境就行干净利落。而且conda环境还方便整体删掉重来——装坏了直接conda remove -n openmmlab --all几秒钟回到初始状态不用纠结怎么清理乱七八糟的残留。我在实际工作中通常习惯把环境建在默认base目录之外用conda create -p指定路径这样方便整体迁移和查找。不过新手朋友直接用conda create -n openmmlab python3.8 -y这种方式就够用了。3. 安装前的环境准备实操3.1 Linux系统的依赖安装不管你是Ubuntu还是CentOS安装前最好先把系统基础库补齐。虽然很多库在编译时会自动装但提前装齐能避免不少麻烦。以Ubuntu为例sudo apt update sudo apt install -y build-essential git gcc g make sudo apt install -y libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 libxrender-dev这里特别注意libgl1-mesa-glx和libglib2.0-0这两个包。MMDetection推理时如果要对图像做可视化或预处理很依赖OpenCV和Pillow而Pillow在Linux上需要libjpeg、libz等库OpenCV在显示图像时需要libGL。如果你发现导入cv2时报libGL.so.1: cannot open shared object file就是因为缺libgl1-mesa-glx这个包。还有一点容易被忽略检查一下你的系统是否安装了合适的CUDA驱动。很多新手以为装了Anaconda里带的cudatoolkit就万事大吉实际上PyTorch运行时是通过系统显卡驱动直接和GPU通信的。cudatoolkit只是提供了CUDA运行库而驱动需要另外装。驱动对应的CUDA版本只要不低于PyTorch所依赖的CUDA版本就行驱动高了可以向下兼容。验证驱动是否正常的简单方法就是执行nvidia-smi如果能正常输出显卡信息表格说明驱动没问题。如果提示command not found先查一下驱动装没装。3.2 Windows环境的准备工作Windows下安装MMDetection整体思路和Linux一致但有两个额外重点一是编译器二是路径。编译器方面Windows上需要安装Visual Studio的C生成工具版本建议2019或2022。因为MMCV编译时要用MSVC编译器。还有一个常见问题是Python版本对应的是64位还是32位现在默认都是64位但如果你不小心装了个32位Python后面几乎寸步难行建议安装前确认一下python -c import struct; print(struct.calcsize(P) * 8)输出的是64。路径方面Windows的默认路径经常带中文或空格比如C:\Users\张三\Anaconda3这对很多C编译工具链很不友好容易造成莫名其妙的编译失败。建议把Anaconda装在纯英文路径下项目目录也用英文命名。我见过太多因为中文字符编码问题导致的编译报错排查两三天都未必查得出来最后把路径改成英文瞬间就好了。3.3 验证基础环境是否就绪在正式安装MMDetection之前我们可以先把基础环境验证一遍确保前面的准备工作做扎实了。这个验证很快避免到了安装MMCV阶段才发现CUDA没配对。首先验证PyTorch能否调用GPUpython -c import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.device_count())如果输出第一行是2.0.1cu118之类第二行是True第三行是1以上那说明PyTorch本身装好且能正常用GPU。如果第二行是False先别急着往下走回头检查一下PyTorch版本是否安装了CUDA版。常见错误是用conda install pytorch装了CPU版——这里建议使用官方的安装指令而不是conda默认源。再验证一下编译工具链是否可用。Linux下执行gcc --versionWindows下执行cl如果能正常输出版本号说明编译器没问题。这一步很关键因为MMCV安装过程会编译很多CUDA算子编译器缺失或版本太老都会直接失败。4. MMDetection完整安装实操4.1 第一步创建并激活虚拟环境从这一步开始我们正式进入MMDetection安装流程。我以最稳的三件套组合为例Python 3.8 PyTorch 2.0.1 MMCV 2.0.1。先创建新的conda环境conda create -n openmmlab python3.8 -y conda activate openmmlab看到命令行前出现(openmmlab)前缀就说明环境激活成功。之后所有安装步骤都要在这个环境下操作不要关终端。4.2 第二步安装适配的PyTorchPyTorch的安装是我最强调用官方命令的一步。不要用pip install torch因为这样默认装的是CPU版本后面配CUDA会很麻烦。正确的做法是去PyTorch官网获取和你CUDA版本对应的安装命令。比如我们选的CUDA 11.8对应的安装命令就是pip install torch2.0.1 torchvision0.15.2 --index-url https://download.pytorch.org/whl/cu118这里有一个细节值得说明为什么连torchvision也要一起装因为MMDetection在数据增强和可视化时需要用到torchvision的transform接口而且torchvision和torch的版本必须匹配。所以一张装省得后续单独对版本。如果你是在Windows环境这两行命令同样适用。唯一区别是在某些老版本上Windows的torch通过pip安装时会自动附带CUDA相关DLL所以不需要额外多做什么。安装完成后用3.3节的方法验证一次确认torch.cuda.is_available()为True。这里有朋友可能会问PyTorch安装好了是不是就不用再单独装CUDA Toolkit了答案是运行层面确实不用。PyTorch在pip包里内置了运行所需的CUDA runtime库。只有你想把PyTorch之外的某些原生扩展编译成GPU版本时才需要完整的CUDA Toolkit。MMDetection的MMCV是预编译包不需要你本地的CUDA Toolkit所以走到这里为止环境已足够。4.3 第三步安装MMCVMMCV安装是整个流程里最容易出问题的一步。我前面说过要用指定的URL来安装而不是直接pip install mmcv。先根据MMDetection版本确定MMCV版本范围。以我推荐的MMDetection 3.2.0为例它要求mmcv2.0.0、2.1.0具体以官方requirements为准。再结合PyTorch 2.0.1和CUDA 11.8安装命令是pip install mmcv2.0.1 -f https://download.openmmlab.com/mmcv/dist/cu118/torch2.0.1/index.html这个命令里最关键的是-f参数后面的URL。它让pip在下载mmcv时去官方预编译索引里找与cu118和torch2.0.1匹配的版本。如果URL里的cu118和torch2.0.1和你实际环境不一致pip就会去PyPI找纯Python版本的mmcv那个版本没有编译CUDA算子跑检测模型时会报很多算子不存在的错误。整个mmcv包下载的体积通常在150MB到200MB左右因为包含了预编译的CUDA扩展库。安装时要确保网络情况良好不要中途断网。安装完毕后可以用一行命令验证算子是否齐全python -c from mmcv.ops import get_compiling_cuda_version, get_compiling_cuda_version; print(get_compiling_cuda_version())如果正常打印出cuda版本号说明MMCV预编译成功。如果报ImportError说明算子缺失或版本不匹配需要回头检查安装命令。4.4 第四步安装MMDetection本体MMDetection本身是一个纯Python包安装方式有源码安装和pip直接安装两种。我的建议是使用源码安装因为它带来两个额外好处一是以后想改框架内部代码时源码就在手边改完不用重新pip install就能生效二是源码里自带了配置示例、模型结构文件和基础Demo方便大家学习。源码安装首先需要git clone仓库git clone https://github.com/open-mmlab/mmdetection.git cd mmdetection然后切换到我们需要稳定版本的分支。因为3.2.0是发布的tag之一执行git checkout v3.2.0接着安装pip install -v -e .-v表示显示详细输出-e表示以开发模式安装也就是在site-packages里创建一个指向当前目录的链接这样当前目录下的代码改动可以实时生效不需要重复安装。如果是Windows环境源码安装前建议先确保VS生成工具可用。因为虽然大部分情况下mmdetection包不需要本地编译但一旦内部有部分扩展需要即时编译比如某些新的ops编译器不可用会报错。Linux环境下gcc已提前装好问题不大。4.5 第五步验证安装是否成功走到这一步基本安装流程已经结束但我们不能急着关终端。安装是否成功不是pip不报错就能证明的必须实际跑一遍导入和推理验证。先在任意目录下运行python -c import mmdet; print(mmdet.__version__)如果导入成功并打印版本号比如3.2.0说明MMDetection本体安装完成。接下来下载一个预训练模型和一张测试图片做一个完整的推理验证。MMDetection官方提供了现成的demopython demo/image_demo.py demo/demo.jpg checkpoints/rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth --device cuda:0如果没有联网下载模型也可以先手动下载。模型文件放在mmdetection/checkpoints目录下图片用项目中自带的demo/demo.jpg即可。如果你用的是没有GPU的机器不推荐把--device改成cpu也能跑只是速度慢很多。执行完成后你会在输出目录里看到标注了检测框的图片。框上带了类别标签和置信度。看到那张图说明环境百分百能用了。5. 常见错误与排查实战5.1 ImportError: libGL.so.1: cannot open shared object file这个错误在Linux无桌面服务器上特别常见。原因就是缺少OpenCV可视化所需的libGL库。解决方法很简单sudo apt install -y libgl1-mesa-glx libglib2.0-0装完之后再重启Python进程即可。很多教程里只提了libgl1但实际操作中libglib2.0-0也是高频缺失的建议一起装。5.2 ModuleNotFoundError: No module named mmcv这个报错通常是没装MMCV或者装到了别的环境。先确认你在正确的conda环境里再用python -c import mmcv; print(mmcv.version)查看是否真的存在。如果确实装了但还是找不到考虑一下你是不是用了sudo pip install——sudo会把包装到系统Python而不是conda环境这种情况改用pip install --user或者直接不带sudo重装。5.3 运行demo时报ModuleNotFoundError: No module named mmdet.models如果你是从GitHub克隆源码后运行的demo大概率是因为没有执行源码安装。MMDetection的demo脚本内部会引用mmdet包里的资源如果只是简单地把仓库克隆下来而不执行pip install -e .Python解释器就找不到模块路径。解决方法是进入仓库目录重新执行安装命令。5.4 GPU显存不够怎么办很多人装好环境后第一次跑demo用的还是RTX 2080 Ti 11G这样的显卡按理说显存绰绰有余。但如果报CUDA out of memory大概率是你用了过大的模型图片尺寸。RTMDet系列在V100上推理一张1080p图片只需要不到1GB显存通常不至于爆显存。但如果遇到爆显存可以尝试把图片resize到小尺寸再输入或者在自己的训练任务中缩小batch size。从检测算法角度来说显存占用最大的其实是训练阶段推理阶段一般不太吃显存。所以如果连demo都跑不起来爆显存建议用nvidia-smi看看是不是有其他进程占用了显存。很多实验室服务器上别人跑着大模型你这边开个推理就爆了先kill掉无关进程再说。5.5 配置里的超参不理解怎么办这是很多人安装完成后会遇到的问题虽然不是报错但很影响使用。第一次打开config文件时什么img_scale、batch_size、backbone、neck这些术语铺天盖地看不懂很正常。我的建议是先不要试图一次全弄懂。第一遍只需要找出几个关键配置项比如总epoch数、学习率、batch size、数据集路径改一改让训练能启动就行。其他细节后面一次一个点地啃用多了自然就熟了。6. 安装完成后的工作目录结构6.1 一个标准的MMDetection项目长什么样源码安装完成之后mmdetection目录里会出现很多子目录和文件常用的是这么几个目录/文件作用configs/存放所有模型的配置模板demo/官方推理演示脚本和测试图片mmdet/MMDetection核心Python包tools/训练、测试、转换模型的工具脚本checkpoints/自定义目录用来存放下载的预训练权重work_dirs/训练日志、模型文件输出目录日常使用路径是这样的改配置文件在configs下找对应模型的py文件拷贝一份修改训练用tools/train.py指定这个配置文件测试用tools/test.py推理用demo/image_demo.py。整体逻辑非常清晰。6.2 关于预训练模型下载的建议MMDetection官方提供了一批训练好的模型权重存放在Model Zoo中。下载时一定要关注两个信息一是使用的backbone是什么比如ResNet-50、Swin-T等二是训练数据集COCO还是其他。权重文件的命名里通常包含了这些信息。选定一个通用性强的模型比如RTMDet-tiny或Faster R-CNN R50很适合初学者。第一次跑通后再去换更复杂的模型。我在实际做项目时习惯把下载好的所有预训练权重放在checkpoints目录下统一管理然后在配置文件中把load_from路径指向对应的文件。不建议每次都在config里写完整URL来在线下载离线权重更稳定调试时不受网络波动影响。6.3 环境备份与迁移最后给大家一个只有老手才时刻谨记的习惯装好环境后立即把整个环境的依赖清单导出备份。pip freeze requirements_backup.txt以后万一环境坏了或者换了一台新机器就可以通过conda create -n openmmlab python3.8和pip install -r requirements_backup.txt快速恢复。如果你用的是conda环境也可以用conda env export openmmlab.yml来导出完整的配置。这套做法在团队协作时尤其有用。你自己单机调试没问题但别人复现你的环境如果不能一次到位最后浪费的还是整体时间。好环境是资产留好备份安全度过一整个迭代周期。7. 实测记录与后续规划7.1 一次完整安装的时间线与体验我最近在一台Ubuntu 20.04服务器上重装了一次完整环境整时间线大致是这样更新系统库和安装基础依赖大约10分钟conda创建环境加PyTorch安装约5分钟主要取决于网络速度MMCV的预编译包比较大下载加安装约8分钟克隆并安装MMDetection本体约5分钟验证推理Demo约2分钟。总体耗时30分钟左右全程没有遇到坑。这个时间比很多新手预想的要短。因为在预编译机制下大部分繁重的编译工作都已经为不同CUDA和PyTorch版本提前做好了我们要做的就是选对正确的组合下载对应的成品。反过来说很多人在这一步耗时一整天甚至一周原因只有一个——不按版本对应关系来。随便装一个最新PyTorch然后pip install mmcv结果装了一个没有算子的版本或者编译环境缺库这里报错那里报错陷入补丁式安装的恶性循环。看完这一篇希望大家都能一步到位。7.2 从安装到跑通的下一步建议安装完成只是万里长征第一步。接下来我建议按照以下顺序继续深入先用demo脚本把官方提供的几个模型Faster R-CNN、RetinaNet、RTMDet都跑一遍感受不同模型在速度和精度上的差异然后找一个公开数据集跑一次完整的训练流程熟悉tools/train.py参数最后再尝试用标注工具制作自己的数据集做一次自定义检测任务。这套路径是我带过很多新人的标准教学路径。实践下来直接拿着自己的数据从头训练往往因为对框架不熟遇到问题都不知道是数据问题还是模型问题。而先在标准数据集上把流程跑通再迁移到自己的数据排查问题的范围会缩小很多。7.3 我的实操体会装在项目里反复踩过几次坑之后我的体会是MMDetection的安装难点不在命令本身而在版本意识。它不像某些工具一样任意版本随便装都能跑而是三个核心库环环相扣每个都需要和上下游对齐。一旦理解了这一点安装就会变得非常简单——按图索骥30分钟绝对能搞定。最后再分享一个小技巧环境装好后第一次跑demo时建议打开终端的日志输出看看。MMDetection在推理时会打印模型结构、参数量、FLOPs、推理耗时等关键信息。这些信息在以后比较不同模型优劣时特别有用养成看日志的习惯对你的效率提升帮助巨大。