1. 为什么MMDetection环境配置这么难刚接触MMDetection的开发者经常会遇到这样的场景明明按照官方文档一步步操作却在最后一步跑demo时突然报错屏幕上跳出一堆看不懂的CUDA错误信息。这种情况我见过太多根本原因往往出在版本依赖的连环套上。MMDetection的环境配置就像搭积木PyTorch是底座MMCV是中间的支架MMDetection是最上层的建筑。如果底座和支架的尺寸不匹配整个建筑就会摇摇欲坠。在实际项目中我发现90%的环境问题都源于这三个关键组件的版本不兼容。举个例子去年我在部署一个基于YOLOv3的项目时就踩过这样的坑当时直接安装了最新版的MMDetection 3.0结果发现项目代码需要的是2.25.1版本。更麻烦的是MMDetection 2.25.1要求MMCV 1.5.0而MMCV 1.5.0又需要PyTorch 1.10。这种环环相扣的依赖关系稍有不慎就会导致环境崩溃。2. 环境搭建前的必要检查2.1 硬件环境确认在开始安装前我强烈建议先花5分钟做个硬件检查。打开终端运行nvidia-smi这个命令会显示两个关键信息GPU型号和CUDA驱动版本。比如输出中的CUDA Version: 11.4表示系统支持的最高CUDA工具包版本。但要注意这不等同于你能使用的CUDA版本——PyTorch的CUDA版本必须≤这个驱动版本。我曾经在RTX 3090上犯过一个错误直接安装了CUDA 11.7结果发现PyTorch 1.12.0最高只支持到CUDA 11.6。这种情况就需要降级CUDA工具包或者选择支持更高CUDA版本的PyTorch。2.2 软件版本规划确定硬件支持后就需要规划软件版本组合。这里有个实用技巧先确定MMDetection版本再倒推其他组件版本。比如你要复现的论文使用的是MMDetection 2.25.1那么查MMDetection 2.25.1的requirements.txt发现需要MMCV 1.5.0查MMCV 1.5.0的文档发现需要PyTorch 1.6最后根据PyTorch版本选择对应的CUDA工具包这种逆向推导法能避免90%的版本冲突问题。我习惯把这些版本信息整理成表格组件版本备注CUDA工具包11.3≤驱动支持的11.4PyTorch1.10.2需匹配CUDA 11.3MMCV1.5.0需完整版(mmcv-full)MMDetection2.25.1从源码安装3. 一步步搭建稳定环境3.1 创建虚拟环境我强烈建议使用conda而不是直接pip安装因为conda能更好地处理CUDA等系统级依赖。下面是创建环境的完整命令conda create -n mmdet python3.8 -y conda activate mmdet这里有几个细节需要注意Python版本建议选择3.8这是大多数MMDetection版本的甜点版本环境名称(mmdet)可以自定义但不要包含特殊字符记得激活环境后再进行后续操作3.2 安装PyTorch和CUDA工具包PyTorch安装是最容易出错的一步。以CUDA 11.3为例正确的安装命令应该是conda install pytorch1.10.2 torchvision0.11.3 cudatoolkit11.3 -c pytorch这里容易踩的坑有忘记指定torchvision版本导致与PyTorch不兼容直接从pip安装可能缺少CUDA相关依赖使用conda默认频道而不是pytorch频道导致版本滞后安装完成后用以下命令验证python -c import torch; print(torch.__version__, torch.version.cuda)如果输出与安装版本一致且能正常检测到GPU说明PyTorch安装成功。3.3 安装MMCV完整版MMCV的安装命令比较特殊需要根据CUDA和PyTorch版本选择对应的安装包。以CUDA 11.3 PyTorch 1.10为例pip install mmcv-full1.5.0 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html关键点在于URL中的cu113和torch1.10必须与实际环境严格匹配。如果URL拼写错误可能会安装不兼容的版本。3.4 安装MMDetection根据项目需求有两种安装方式方式一直接安装适合学习官方demopip install mmdet2.25.1方式二源码安装适合复现论文git clone https://github.com/open-mmlab/mmdetection.git cd mmdetection git checkout v2.25.1 # 切换到指定版本 pip install -r requirements/build.txt pip install -v -e .源码安装时要注意记得切换到对应版本的分支/标签-e参数让代码修改能即时生效先安装build依赖再安装主包4. 环境验证与问题排查4.1 基础环境验证安装完成后我习惯用这个三件套命令检查环境python -c import torch; print(PyTorch版本:, torch.__version__) python -c import mmcv; print(MMCV版本:, mmcv.__version__) python -c import mmdet; print(MMDetection版本:, mmdet.__version__)如果三个命令都能正确输出版本号说明基础环境没问题。4.2 功能测试更严格的测试是运行一个完整的检测流程from mmdet.apis import init_detector, inference_detector config configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py checkpoint checkpoints/faster_rcnn_r50_fpn_1x_coco_20200130-047c8118.pth model init_detector(config, checkpoint, devicecuda:0) result inference_detector(model, demo/demo.jpg) model.show_result(demo/demo.jpg, result, out_fileresult.jpg)如果这个脚本能成功生成带检测框的图片说明环境完全正常。4.3 常见问题解决问题一CUDA运行时错误症状报错包含CUDA error、CUBLAS_STATUS等关键词。解决方案确认PyTorch CUDA版本与系统CUDA驱动兼容尝试重置CUDA环境变量unset LD_LIBRARY_PATH问题二MMCV导入错误症状报错mmcv._ext不存在或undefined symbol。解决方案确认安装的是mmcv-full而不是mmcv检查MMCV版本是否与PyTorch匹配尝试重新编译pip uninstall mmcv-full pip install mmcv-full --no-cache-dir问题三DETR系列模型报错症状使用DETR或Deformable DETR时出现多头注意力相关错误。解决方案安装特定版本的PyTorch和CUDA从源码重新编译pip uninstall mmdet pip install -e . --no-cache-dir5. 环境管理进阶技巧5.1 环境快照配置好的环境一定要保存快照conda env export environment.yml pip freeze requirements.txt这样在另一台机器上可以快速重建环境conda env create -f environment.yml pip install -r requirements.txt5.2 多版本共存如果需要同时维护多个MMDetection项目可以使用conda的clone功能conda create --name mmdet2 --clone mmdet conda activate mmdet2 pip install mmdet2.3.05.3 容器化部署对于生产环境我推荐使用DockerFROM nvidia/cuda:11.3.1-base RUN conda create -n mmdet python3.8 RUN conda install pytorch1.10.2 torchvision0.11.3 cudatoolkit11.3 -c pytorch RUN pip install mmcv-full1.5.0 -f https://download.openmmlab.com/mmcv/dist/cu113/torch1.10/index.html RUN pip install mmdet2.25.1这样能确保环境完全一致避免在我机器上能跑的问题。6. 特定算法的适配技巧6.1 YOLO系列适配MMDetection中的YOLOv3/v4实现有些特殊要求需要安装额外的依赖pip install albumentations0.5.2配置文件中的anchor设置需要与数据集匹配训练时建议使用更大的batch size6.2 DETR系列适配Transformer-based模型如DETR对PyTorch版本更敏感推荐使用PyTorch 1.8以获得更好的transformer支持可能需要手动安装PyTorch的multihead attention扩展pip install torch1.10.2cu113 -f https://download.pytorch.org/whl/torch_stable.html训练时学习率需要适当调整6.3 自定义模型开发当基于MMDetection开发新模型时建议从最近的MMDetection版本开始继承标准组件时注意版本变化测试时使用--no-validate参数快速验证最后提醒一点所有环境配置都要记录详细日志。我习惯用Markdown文件记录每次环境变更包括日期、版本号、安装命令和遇到的问题。这样三个月后回看项目时还能清楚知道当时的环境细节。