企业官网建设流程全解析

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依赖一个底层的基础库叫MMCV（OpenMMLab Computer Vision Library），而MMCV内部又依赖PyTorch和CUDA版本。如果你直接用pip install mmdetection，很有可能会碰到版本匹配问题——要么是MMCV编译失败，要么是装上之后import就报错，要么是跑demo时报各种cuda runtime error。这一篇系列文章的第一部分，我就先把环境准备和安装这条路上最关键的几个坑全部拆解开，让你能一次装到位。

1.2 安装的总体目标与系列规划

这篇是系列的第一篇，核心任务只有一个：在你的电脑上成功安装MMDetection，并且用一个实际的推理Demo验证安装结果可用。我默认你的操作系统是Linux（Ubuntu 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系列为例，整个对应关系大致是：

这张表格看起来简单，但实际安装时很多人会栽在"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.8，PyTorch 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 python=3.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能否调用GPU：

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

如果输出第一行是2.0.1+cu118之类，第二行是True，第三行是1以上，那说明PyTorch本身装好且能正常用GPU。如果第二行是False，先别急着往下走，回头检查一下PyTorch版本是否安装了CUDA版。常见错误是用conda install pytorch装了CPU版——这里建议使用官方的安装指令，而不是conda默认源。

再验证一下编译工具链是否可用。Linux下执行：

gcc --version

Windows下执行：

cl

如果能正常输出版本号，说明编译器没问题。这一步很关键，因为MMCV安装过程会编译很多CUDA算子，编译器缺失或版本太老都会直接失败。

4. MMDetection完整安装实操

4.1 第一步：创建并激活虚拟环境

从这一步开始，我们正式进入MMDetection安装流程。我以最稳的三件套组合为例：Python 3.8 + PyTorch 2.0.1 + MMCV 2.0.1。

先创建新的conda环境：

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

看到命令行前出现(openmmlab)前缀，就说明环境激活成功。之后所有安装步骤都要在这个环境下操作，不要关终端。

4.2 第二步：安装适配的PyTorch

PyTorch的安装是我最强调用官方命令的一步。不要用pip install torch，因为这样默认装的是CPU版本，后面配CUDA会很麻烦。正确的做法是去PyTorch官网获取和你CUDA版本对应的安装命令。

比如我们选的CUDA 11.8，对应的安装命令就是：

pip install torch==2.0.1 torchvision==0.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 第三步：安装MMCV

MMCV安装是整个流程里最容易出问题的一步。我前面说过，要用指定的URL来安装，而不是直接pip install mmcv。

先根据MMDetection版本确定MMCV版本范围。以我推荐的MMDetection 3.2.0为例，它要求mmcv>=2.0.0、<2.1.0（具体以官方requirements为准）。再结合PyTorch 2.0.1和CUDA 11.8，安装命令是：

pip install mmcv==2.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官方提供了现成的demo：

python 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下找对应模型的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 python=3.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、推理耗时等关键信息。这些信息在以后比较不同模型优劣时特别有用，养成看日志的习惯，对你的效率提升帮助巨大。