1. 项目概述为什么要在Linux上配置MMRotate如果你正在计算机视觉特别是遥感图像或任意方向目标检测领域深耕那么MMRotate这个工具箱对你来说绝对不陌生。作为OpenMMLab生态中专门处理旋转目标检测的利器它集成了大量先进的算法和模型从基础的旋转R-CNN到最新的Oriented R-CNN、Rotated FCOS等是科研和工程实践的得力助手。然而和许多基于PyTorch的深度学习框架一样MMRotate的环境配置尤其是在Linux系统上常常是新手遇到的第一道坎也是老手偶尔会翻车的地方。我经历过无数次从零开始配置环境的痛苦从CUDA版本不匹配到PyTorch和MMCV的“爱恨情仇”再到各种依赖包的连环报错。所以今天我想系统地梳理一遍在Linux系统上配置MMRotate环境的完整流程这不仅仅是一份安装指南更是一份融合了多年踩坑经验的避坑手册。无论你使用的是Ubuntu、CentOS还是其他发行版无论你用的是N卡、A卡还是CPU虽然不推荐这篇文章都将带你走通这条路。我们的目标很明确搭建一个稳定、可复现、能跑通训练和测试的MMRotate开发环境为后续的算法研究或项目部署打下坚实基础。2. 环境配置的核心思路与前置准备配置MMRotate环境本质上是在搭建一个由操作系统、驱动、深度学习框架、计算机视觉库和特定工具箱组成的软件栈。这个栈的每一层都必须兼容否则就会“牵一发而动全身”。我们的核心思路是自底向上层层验证确保每一步都稳固后再进行下一步。2.1 硬件与操作系统基础首先明确你的硬件。对于深度学习一块支持CUDA的NVIDIA GPU是首选它能将训练和推理速度提升数十倍。确认你的显卡型号例如RTX 3090, RTX 4090等这决定了你能安装的CUDA驱动版本上限。操作系统方面主流的Linux发行版都可以我个人长期使用Ubuntu 20.04 LTS或22.04 LTS它们在社区支持和软件兼容性上表现最好。CentOS/Rocky Linux等企业级发行版也可以但可能需要自己解决更多依赖。本文将以Ubuntu 22.04为例进行说明。2.2 核心软件栈依赖关系图在动手之前我们必须理清几个关键组件的关系这是避免版本冲突的关键NVIDIA驱动 让系统识别并使用你的GPU。版本需要与CUDA Toolkit兼容。CUDA Toolkit NVIDIA提供的并行计算平台和编程模型是PyTorch等框架调用GPU的基础。这是版本管理的重中之重。cuDNN NVIDIA深度神经网络库是CUDA的加速库。PyTorch 核心深度学习框架。其版本必须与CUDA版本严格匹配。MMCV OpenMMLab的计算机视觉基础库是MMRotate的基石。它有mmcv和mmcv-full两个版本后者包含CUDA算子性能更强但必须与特定的PyTorchCUDA组合编译或安装预编译包。MMRotate 我们的目标工具箱它依赖于特定版本的MMCV和PyTorch。一个常见的版本组合示例如下以2024年中期为参考PyTorch 1.13.1 CUDA 11.7MMCV-full 1.7.1 (与上述PyTorch和CUDA版本对应)MMRotate 1.0.0注意永远不要盲目安装最新版。先去 MMRotate官方文档 查看“安装”章节确认其推荐的PyTorch和MMCV版本然后根据这个信息去选择CUDA版本。2.3 必备工具安装在开始核心配置前先确保系统有基本的编译和包管理工具。sudo apt update sudo apt upgrade -y sudo apt install -y build-essential cmake git wget vim curl software-properties-commonbuild-essential和cmake是编译C/CUDA扩展如mmcv-full所必需的。git用于克隆代码仓库。3. 深度学习基础环境搭建驱动、CUDA与PyTorch这是整个流程中最容易出错的部分需要格外小心。3.1 NVIDIA驱动安装如果你使用的是云服务器或预装了驱动的工作站可以跳过此步。否则推荐使用系统自带的apt仓库安装最为稳定。首先添加官方显卡驱动PPA仓库并安装推荐版本的驱动# 添加PPA仓库 sudo add-apt-repository ppa:graphics-drivers/ppa -y sudo apt update # 检查系统推荐的驱动版本 ubuntu-drivers devices # 通常会推荐一个以“nvidia-driver-5xx”格式命名的包直接安装推荐版本 sudo apt install nvidia-driver-535 -y # 以535为例请根据推荐修改安装完成后必须重启系统。sudo reboot重启后在终端输入nvidia-smi。如果看到显卡信息、驱动版本和CUDA版本如CUDA 12.2说明驱动安装成功。这里显示的CUDA版本是驱动支持的最高CUDA Toolkit版本实际安装的CUDA Toolkit版本可以低于它。3.2 CUDA Toolkit与cuDNN安装强烈建议使用conda环境来管理CUDA这可以让你在同一台机器上拥有多个不同CUDA版本的环境互不干扰是深度学习环境管理的黄金法则。首先安装Miniconda一个轻量化的Anacondawget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda echo export PATH$HOME/miniconda/bin:$PATH ~/.bashrc source ~/.bashrc创建一个新的conda环境并在此环境中安装CUDA Toolkit和cuDNN。假设我们根据MMRotate要求选择PyTorch 1.13.1 CUDA 11.7的组合# 创建名为mmrotate的环境指定Python版本通常3.8最兼容 conda create -n mmrotate python3.8 -y conda activate mmrotate # 在conda环境中安装CUDA 11.7和cuDNN 8.5 conda install cudatoolkit11.7 cudnn8.5 -c conda-forge -y通过conda安装的CUDA是独立于系统环境的。安装后在环境中检查nvcc --version # 如果提示命令未找到是正常的因为conda的CUDA路径可能需要手动添加但PyTorch能识别 # 更重要的验证将在安装PyTorch后进行。3.3 PyTorch安装前往 PyTorch官网 找到历史版本。根据我们的选择PyTorch 1.13.1 CUDA 11.7使用pip安装命令。注意要使用conda环境内的pip。# 确保已激活conda环境 conda activate mmrotate # 安装PyTorch 1.13.1 CUDA 11.7 pip install torch1.13.1cu117 torchvision0.14.1cu117 torchaudio0.13.1 --extra-index-url https://download.pytorch.org/whl/cu117安装完成后进行关键验证python -c import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))如果输出你的PyTorch版本、True以及你的显卡型号如NVIDIA GeForce RTX 4090那么恭喜你PyTorch和CUDA环境配置成功。这是万里长征中最关键的一步。4. MMCV与MMRotate的安装与编译基础环境打好后就可以安装MMLab系列的核心组件了。4.1 安装MMCV-fullMMCV有两个版本mmcv-lite纯Python实现无需编译和mmcv-full包含CUDA算子需编译。为了性能我们选择mmcv-full。方法一推荐安装预编译包OpenMMLab为常见的PyTorch和CUDA组合提供了预编译的mmcv-full轮子wheel。这避免了耗时的本地编译过程。你需要根据你的PyTorch版本、CUDA版本和系统环境去 MMCV官方文档 查找对应的安装命令。例如对于PyTorch 1.13.1 CUDA 11.7 Linux系统pip install mmcv-full1.7.1 -f https://download.openmmlab.com/mmcv/dist/cu117/torch1.13/index.html务必检查URL中的cu117和torch1.13是否与你的环境匹配。如果不匹配去官网查找正确的链接。方法二从源码编译如果找不到完全匹配的预编译包或者你需要进行自定义修改则需要从源码编译。这是一个相对耗时的过程。# 首先安装一些额外的依赖 pip install openmim git clone https://github.com/open-mmlab/mmcv.git cd mmcv # 切换到与MMRotate兼容的版本分支例如v1.7.1 git checkout v1.7.1 # 编译安装mmcv-full。环境变量FORCE_CUDA和MAX_JOBS可以加速编译。 FORCE_CUDA1 pip install -e . -v编译过程可能需要10-30分钟取决于你的机器性能。完成后同样使用pip list | grep mmcv来验证。4.2 安装MMRotate及其依赖安装好MMCV后MMRotate的安装就相对简单了。我们同样使用mim这个OpenMMLab的包管理工具它能很好地处理依赖。# 使用mim安装mmdetection这是MMRotate的强依赖 mim install mmdet2.28.2 # 克隆MMRotate仓库并安装 git clone https://github.com/open-mmlab/mmrotate.git cd mmrotate # 安装依赖包和mmrotate自身可编辑模式方便修改代码 pip install -r requirements/build.txt pip install -v -e .-e参数代表“可编辑模式”editable mode这样你对mmrotate目录下源代码的修改会直接生效无需重新安装。4.3 环境完整性验证安装完成后进行一个快速的完整性测试确保各个组件能协同工作。import torch import mmcv import mmdet import mmrotate print(fPyTorch版本: {torch.__version__}) print(fPyTorch CUDA可用: {torch.cuda.is_available()}) print(fMMCV版本: {mmcv.__version__}) print(fMMDetection版本: {mmdet.__version__}) print(fMMRotate版本: {mmrotate.__version__}) # 尝试创建一个简单的旋转检测器配置看是否报错 from mmrotate.models import RotatedRetinaNet print(关键模块导入成功)如果所有导入和打印都成功没有报错那么你的MMRotate环境就已经配置成功了。5. 实战使用MMRotate训练DOTA数据集环境搭好了不跑个模型怎么行我们以经典的DOTA遥感图像旋转目标检测数据集为例走通一个简单的训练流程。这能帮你再次验证环境并熟悉MMRotate的工作流。5.1 数据准备DOTA数据集很大我们以其中一部分为例。假设你已经下载了DOTA数据集其目录结构通常如下DOTA/ ├── train/ │ ├── images/ (存放图片如 P0000.png, P0001.png...) │ └── labelTxt-v1.0/ (存放标注文件如 P0000.txt, P0001.txt...) ├── val/ │ ├── images/ │ └── labelTxt-v1.0/ └── test/ └── images/DOTA的标注文件.txt格式是x1 y1 x2 y2 x3 y3 x4 y4 category difficult。我们需要将其转换为MMRotate支持的格式通常是DOTA或HRSC格式。MMRotate提供了转换脚本。首先按照MMRotate要求组织数据# 在mmrotate目录下创建data文件夹并建立软链接 cd mmrotate mkdir -p data ln -s /path/to/your/DOTA data/dota然后使用官方脚本进行格式转换和数据集划分python tools/data/dota/split/img_split.py --base-json tools/data/dota/split/split_configs/ss_trainval.json python tools/data/dota/split/img_split.py --base-json tools/data/dota/split/split_configs/ss_test.json这个步骤会将大图切割成小图例如1024x1024以适应GPU内存并生成MMDetection可用的Coco格式的json文件。5.2 配置模型与训练MMRotate使用配置文件config来定义模型、数据、训练策略等一切。我们选择一个简单的模型开始比如rotated_retinanet。修改配置文件 配置文件位于configs/目录下。我们复制一个基础配置并针对我们的数据和环境进行修改。cp configs/rotated_retinanet/rotated_retinanet_obb_r50_fpn_1x_dota_le90.py my_rotated_retinanet_dota.py主要修改点data_root 指向你的数据路径如data/dota/split_1024/。ann_file和img_prefix 指向切割后生成的训练和验证json文件及图片目录。num_classes DOTA有15个类别plane, ship...所以设为15。runner中的max_epochs 控制训练轮数可以先设为121x schedule试试。optimizer中的lr 学习率根据你的batch size调整。配置文件中的lr通常针对8 GPU如果你用1 GPUlr应除以8。启动训练 使用tools/train.py脚本。python tools/train.py my_rotated_retinanet_dota.py --work-dir work_dirs/my_exp--work-dir 指定工作目录训练日志、模型权重都会保存在这里。训练开始后终端会输出损失、学习率、评估指标等信息。Tensorboard日志也会保存在work-dir下的tf_logs目录中可以用tensorboard --logdir work_dirs/my_exp来可视化。5.3 模型测试与推理训练完成后使用tools/test.py在验证集上评估模型性能。python tools/test.py my_rotated_retinanet_dota.py work_dirs/my_exp/latest.pth --eval mAP--eval mAP 指定评估指标为平均精度mean Average Precision这是目标检测的核心指标。如果你想对单张图片或一个文件夹进行推理可以使用demo脚本python demo/image_demo.py demo/demo.jpg my_rotated_retinanet_dota.py work_dirs/my_exp/latest.pth --device cuda:0 --out-file result.jpg这会在result.jpg上画出预测的旋转框。6. 常见问题与深度排错指南即使按照步骤操作也难免会遇到问题。这里汇总了一些高频问题和解决方案。6.1 CUDA相关错误CUDA error: no kernel image is available for execution或RuntimeError: CUDA out of memory的前置错误。原因 这是最经典的版本不匹配错误。通常是因为mmcv-full或PyTorch是在一个CUDA版本下编译的但当前环境使用的是另一个CUDA版本。例如用CUDA 11.3编译的mmcv-full跑在CUDA 11.7的PyTorch环境下。解决彻底检查版本一致性conda list | grep -E (cudatoolkit|pytorch|mmcv)。确保cudatoolkit版本、torch版本的后缀如cu117以及mmcv-full安装命令中指定的CUDA版本三者完全一致。如果使用预编译的mmcv-full务必从OpenMMLab官方提供的、与你PyTorchCUDA版本精确对应的链接下载。最彻底的方案创建一个全新的conda环境严格按照PyTorch官网命令-对应MMCV预编译包的顺序重装。NVIDIA-SMI has failed because it couldn‘t communicate with the NVIDIA driver原因 NVIDIA驱动未正确安装或加载失败。解决运行nvidia-smi看是否正常显示。如果不正常尝试重装驱动sudo apt install --reinstall nvidia-driver-535。检查内核版本是否与驱动兼容有时系统升级内核后需要重新安装驱动模块sudo apt install linux-headers-$(uname -r)然后重新配置驱动sudo dpkg-reconfigure nvidia-driver-535。6.2 编译与安装错误编译mmcv-full时卡住或报g/gcc错误原因 编译器版本或依赖缺失。解决确保安装了build-essential和cmake。升级setuptools和wheelpip install -U setuptools wheel。如果报错提到C版本可以尝试设置环境变量export CXXg-9如果你的g-9可用。如果机器内存较小编译可能因内存不足而失败尝试设置MAX_JOBS1MAX_JOBS1 pip install -e . -v。ImportError: cannot import name ‘xxx‘ from ‘mmcv‘原因 MMCV版本与MMRotate或MMDetection不兼容。解决 查阅MMRotate官方文档的get_started.md文件找到其明确要求的MMCV版本范围。卸载当前版本安装指定版本pip install mmcv-full1.7.1。6.3 训练与运行时错误KeyError: ‘xxx‘ is not in the model registry原因 配置文件中的某个模块如backbone, neck, head名称写错或者对应的代码没有正确注册。解决 仔细检查配置文件中的model字典下的各个type字段确保其字符串与MMRotate代码中registry.py注册的名称完全一致。常见错误是复制配置文件后type字段指向了不存在的类。数据加载错误如FileNotFoundError或标注解析错误原因 数据路径错误或标注文件格式不符合预期。解决使用绝对路径或在配置文件中使用相对于mmrotate目录的路径。运行一个简单的数据检查脚本打印出数据加载器读取的第一个样本的信息看路径和标注是否正常。对于DOTA数据集务必确认已经完成了正确的切割和格式转换步骤生成的train.json和val.json文件内容正确。GPU内存溢出OOM原因 输入图像太大、batch size太大或模型太复杂。解决减小batch size 在配置文件的data字段中修改samples_per_gpu。使用更小的输入尺寸 修改配置文件中的img_scale如从(1024, 1024)改为(800, 800)。使用梯度累积 如果无法减小batch size可以通过梯度累积来模拟大batch。在optimizer_config中设置cumulative_iters4表示每4个iter才更新一次权重等效于batch size扩大4倍。使用混合精度训练 在配置文件中添加fp16 dict(loss_scale512.)可以显著减少GPU内存占用并加快训练速度。6.4 环境管理与复现如何复现环境最佳实践 使用conda env export导出环境。conda activate mmrotate conda env export environment.yml这个environment.yml文件记录了所有conda安装的包及其精确版本。别人可以通过conda env create -f environment.yml来复现完全相同的环境。补充 对于通过pip安装的包如mmcv-full,mmrotate虽然conda也会记录一部分但为了更精确可以同时运行pip freeze requirements.txt。多个项目需要不同版本的PyTorch/MMCV怎么办核心方法 为每个项目创建独立的conda环境。这是conda的核心价值所在。环境之间完全隔离互不影响。配置MMRotate环境是一个系统工程关键在于理解组件间的依赖关系并保持版本链的一致性。从稳定的驱动和CUDA基础到匹配的PyTorch和MMCV最后到MMRotate本身每一步的验证都不可或缺。当遇到问题时学会阅读错误信息从下往上追溯根源通常都能在版本不匹配、路径错误或依赖缺失这几个常见方向上找到答案。这份指南希望能帮你扫清障碍把更多精力投入到有趣的算法研究和应用开发中去。