MMCV与MMDetection：从环境配置到模型推理的避坑实践

1. 环境准备：从零搭建深度学习环境

刚接触MMDetection框架时，最让人头疼的就是环境配置。我清楚地记得第一次安装时，因为版本不匹配导致反复重装了5次CUDA。为了避免大家踩同样的坑，这里分享一套经过验证的环境搭建方案。

首先需要明确的是，MMDetection的运行依赖四个核心组件：Python解释器、PyTorch深度学习框架、CUDA计算平台以及MMCV基础库。这四个组件就像叠积木，任何一层不稳固都会导致整个系统崩溃。建议按照以下顺序进行安装：

1. 确认显卡驱动版本：在命令行执行nvidia-smi，右上角会显示最高支持的CUDA版本（比如12.2）。这个数字决定了后续所有组件的版本上限
2. 安装Anaconda：推荐使用Python 3.8版本，这个版本在兼容性上表现最稳定
3. 创建独立环境：conda create -n mmdet python=3.8 -y

注意：千万不要直接使用系统默认的Python环境，后期出现依赖冲突时你会感谢这个决定

接下来是PyTorch安装，这里有个小技巧：与其在PyTorch官网复制安装命令，不如直接去下载预编译的whl文件。以CUDA 11.8环境为例，可以访问https://download.pytorch.org/whl/torch/ 找到对应版本的torch和torchvision，这样安装速度能快10倍不止。

2. MMCV安装的三大陷阱

作为MMDetection的基石，MMCV的安装堪称新手劝退第一关。经过多次实践，我总结出三个最常见的坑点：

2.1 版本匹配的玄学

PyTorch、CUDA和MMCV的版本必须严格对应。比如PyTorch 2.0.1+cu118对应的MMCV应该是2.0.x系列。但文档里不会告诉你的是，PyTorch的小版本号（x.x.1和x.x.0）其实可以混用。也就是说，当你的PyTorch是1.8.1时，完全可以安装MMCV 1.8.0版本。

验证版本兼容性的黄金命令组合：

bash复制python -c "import torch; print(torch.__version__); print(torch.version.cuda)"

2.2 编译安装还是预编译包

MMCV提供两种安装方式：

• 预编译包（推荐）：pip install mmcv-full=={mmcv_version} -f https://download.openmmlab.com/mmcv/dist/{cuda_version}/{torch_version}/index.html
• 源码编译：适合定制化需求，但需要配置C++编译环境

实测发现，Windows环境下源码编译成功率不足30%，而预编译包基本能一次成功。如果遇到"Could not build wheels for mmcv"错误，请立即切换安装方式。

2.3 网络问题解决方案

由于MMCV的预编译包存放在境外服务器，国内用户常会遇到下载超时。这时可以：

1. 使用清华镜像源：添加-i https://pypi.tuna.tsinghua.edu.cn/simple
2. 手动下载whl文件：从https://download.openmmlab.com/mmcv/dist/ 找到对应版本
3. 设置代理（需符合当地法律法规）

安装完成后，用这个命令验证是否支持GPU：

python复制import mmcv
print(mmcv.__version__)
print(mmcv.ops.get_compiling_cuda_version())

3. MMDetection的安装艺术

当MMCV安装成功后，MMDetection的安装就简单多了。不过仍有几个细节需要注意：

3.1 两种安装方式对比

建议研究阶段使用源码安装，生产环境用直接安装。我曾经因为图省事用了直接安装，后来调试模型时不得不重装整个环境。

3.2 验证安装的正确姿势

很多教程会教你用import mmdet验证，但这远远不够。真正的验证应该包含以下步骤：

1. 检查基础功能：python -c "from mmdet.apis import init_detector; print('OK')"
2. 测试CUDA支持：在代码中添加device='cuda:0'参数
3. 运行demo脚本（后续章节会详细说明）

重要提示：如果遇到"No module named 'mmdet.ops' "错误，说明MMCV没有正确编译CUDA算子，需要重新安装MMCV

4. 一站式验证：RTMDet模型推理实战

环境装好了不算成功，能跑通模型才是终点。我们以RTMDet-tiny模型为例，演示完整的验证流程。

4.1 模型下载的智能方案

新手常犯的错误是手动下载配置文件和权重文件。其实OpenMMLab提供了更优雅的方案：

bash复制pip install openmim
mim download mmdet --config rtmdet_tiny_8xb32-300e_coco --dest .

这个命令会自动完成三件事：

1. 下载最新配置文件（.py）
2. 获取预训练权重（.pth）
3. 保存到当前目录

我曾经手动下载错版本，导致模型无法加载，白白浪费了两小时排查时间。

4.2 推理脚本的隐藏参数

官方demo脚本其实有很多实用参数：

bash复制python demo/image_demo.py \
    demo/demo.jpg \
    rtmdet_tiny_8xb32-300e_coco.py \
    --weights rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth \
    --device cuda:0 \
    --score-thr 0.3 \
    --out-dir outputs \
    --palette random

其中--palette random可以让每个类别的显示颜色不同，这在处理多目标检测时特别有用。而--score-thr可以过滤低质量检测框，根据我的经验，小目标检测设为0.3效果最佳。

4.3 常见报错解决方案

1. CUDA out of memory：尝试减小--batch-size，或者使用--device cpu先验证流程
2. Missing config file：检查配置文件路径，确保和下载的版本一致
3. KeyError: 'CLASSES'：这是版本兼容问题，需要在配置文件中添加classes=('object',)

记得第一次成功跑通推理时，输出目录下的result.jpg让我兴奋了半天。虽然只是检测出几个简单的目标，但意味着整个环境搭建终于成功了。

5. 性能优化小技巧

环境跑通只是开始，要让模型发挥最佳性能还需要一些调优：

5.1 加速安装过程

• 使用国内镜像源：在~/.pip/pip.conf中添加

ini复制[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

• 并行编译：设置环境变量MAX_JOBS=8加速源码编译
• 禁用冗余依赖：安装时添加--no-deps参数

5.2 推理速度优化

通过修改配置文件中的test_pipeline可以显著提升速度：

1. 减小输入尺寸：修改img_scale参数
2. 使用半精度：添加fp16=dict(loss_scale=512.)
3. 启用cudnn_benchmark：设置cudnn_benchmark=True

在我的RTX 3090上，经过优化后RTMDet-tiny的推理速度从45FPS提升到了78FPS。

5.3 内存管理技巧

遇到显存不足时，可以尝试以下方案：

1. 启用gradient checkpointing
2. 使用torch.backends.cudnn.benchmark = True
3. 调整DataLoader的num_workers（通常设为CPU核心数的75%）

记得有次训练时显存总是不够，后来发现是DataLoader的persistent_workers参数没设置，修改后显存占用直接减少了20%。