MMDetection 安装与推理验证完全指南从环境搭建到首次跑通检测模型【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetection本文基于 MMDetectionOpenMMLab 目标检测工具箱官方中文文档《开始你的第一步》展开系统讲解在 Linux/Windows/macOS 上准备 PyTorch 环境、通过 MIM 安装 MMEngine 与 MMCV、以源码或 MIM 方式安装 MMDetection并下载 RTMDet-tiny 权重完成首次推理验证的完整流程同时深入 CUDA 版本选择、纯 CPU 环境限制、Google Colab 与 Docker 部署等自定义安装场景。读完本文你可以独立完成 MMDetection 的环境搭建、安装校验并理解验证脚本背后的 API 调用链。依赖与环境准备MMDetection 支持在 Linux、Windows 和 macOS 上运行要求 Python 3.7 以上、CUDA 9.2 以上和 PyTorch 1.8 及其以上。当前仓库代码中 mmdet/version.py 声明的版本号为 3.3.0本文内容均以该仓库当前状态为准。如果你对 PyTorch 已有经验并完成了安装可以直接跳至安装流程否则请按以下步骤准备步骤 0.从 Miniconda 官方渠道下载并安装 Miniconda。步骤 1.创建并激活一个 conda 环境conda create --name openmmlab python3.8 -y conda activate openmmlab步骤 2.按照 PyTorch 官方说明安装 PyTorch。GPU 平台上执行conda install pytorch torchvision -c pytorchCPU 平台上执行conda install pytorch torchvision cpuonly -c pytorch安装流程官方推荐参照最佳实践安装 MMDetection但整个过程是可定制的可按需参考自定义安装。最佳实践步骤 0.使用 MIMOpenMMLab 的包管理工具安装 MMEngine 和 MMCVpip install -U openmim mim install mmengine mim install mmcv2.0.0注意在 MMCV v2.x 中mmcv-full已改名为mmcv。如果想安装不包含 CUDA 算子的精简版可以通过mim install mmcv-lite2.0.0rc1来安装。步骤 1.安装 MMDetection有两种方案方案 a如果你要开发并直接运行 mmdet从源码安装开发模式git clone https://gitcode.com/gh_mirrors/mm/mmdetection cd mmdetection pip install -v -e . # -v 指详细说明即产生更详细的输出 # -e 表示以可编辑模式安装项目对代码所做的本地修改都会即时生效无需重新安装方案 b如果你将 mmdet 作为依赖或第三方 Python 包直接用 MIM 安装mim install mmdet验证安装为了验证 MMDetection 是否安装正确官方提供了一套示例代码来执行模型推理。整个验证链路是下载配置与权重 → 运行推理 → 检查输出。步骤 1.下载配置文件和模型权重文件mim download mmdet --config rtmdet_tiny_8xb32-300e_coco --dest .下载需要数秒或更长时间取决于网络环境。完成后当前文件夹中会出现两个文件rtmdet_tiny_8xb32-300e_coco.py和rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth。对应的配置文件在仓库中同样存在即 rtmdet_tiny_8xb32-300e_coco.py可以对照查看其网络结构与训练参数。步骤 2.推理验证。方案 a如果你通过源码安装的 MMDetection直接运行以下命令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 cpu你会在当前文件夹的outputs/vis子目录中看到一张新的图像demo.jpg图像上叠加了网络预测的检测框。从源码看demo/image_demo.py 是一个基于DetInferencer封装的命令行推理工具其关键参数包括--weights检查点文件、--device推理设备默认cuda:0、--out-dir结果输出目录默认outputs、--pred-score-thr检测框置信度阈值默认 0.3、--batch-size批量大小默认 1、--show弹窗显示结果以及--no-save-vis/--no-save-pred控制是否保存可视化图或 JSON 预测结果。其中“保存目录/vis/文件名”这一拼接逻辑出自 DetInferencer 的可视化实现即可视化结果统一落在out_dir/vis/下与文档描述的outputs/vis完全对应。方案 b如果你通过 MIM 安装了 MMDetection可以打开 Python 解释器复制并粘贴以下代码from mmdet.apis import init_detector, inference_detector config_file rtmdet_tiny_8xb32-300e_coco.py checkpoint_file rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth model init_detector(config_file, checkpoint_file, devicecpu) # or devicecuda:0 inference_detector(model, demo/demo.jpg)你将看到一个包含DetDataSample的列表预测结果位于pred_instance字段中包含检测框、类别和得分。这两个 API 的真实行为可以从 mmdet/apis/inference.py 得到印证init_detector(config, checkpoint, palettenone, devicecuda:0, cfg_optionsNone)加载配置文件构造模型随后调用load_checkpoint加载权重并从 checkpoint 的meta.dataset_meta中恢复类别信息dataset_meta若检查点缺少类别信息则默认使用 COCO 80 类。cfg_options参数可在不修改配置文件的前提下覆盖配置项。inference_detector(model, imgs)支持单张或多张输入str/ndarray/序列内部依据model.cfg自动构建测试预处理管线get_test_pipeline_cfg在torch.no_grad()下调用model.test_step完成前向推理并返回DetDataSample或SampleList。值得注意的是当模型位于 CPU 设备时源码会断言模型中不存在RoIPool模块并抛出“CPU inference with RoIPool is not supported currently”这与下文 CPU 环境的功能限制一一对应。自定义安装安装流程中的每个环节都可以根据你的硬件与使用场景调整。CUDA 版本选择安装 PyTorch 时需要指定 CUDA 版本。如果不确定该选哪个官方建议如下对于 Ampere 架构的 NVIDIA GPU如 GeForce 30 系列及 NVIDIA A100CUDA 11 是必需的对于更早的 NVIDIA GPUCUDA 11 向后兼容但 CUDA 10.2 提供更好兼容性且更轻量。请确保 GPU 驱动版本满足最低要求可参阅 NVIDIA 官方的 CUDA 工具箱与驱动版本对应关系表。如果按最佳实践安装只需 CUDA 运行时库即可因为不需要在本地编译 CUDA 代码。但如果你希望从源码编译 MMCV或开发其他 CUDA 算子就必须安装完整的 CUDA 工具链并确保其版本与 PyTorch 安装时指定的cudatoolkit版本相匹配。不使用 MIM 安装 MMEngine若希望用 pip 而非 MIM 安装 MMEngine遵照 MMEngine 安装指南即可例如pip install mmengine不使用 MIM 安装 MMCVMMCV 包含 C 和 CUDA 扩展其对 PyTorch 的依赖比较复杂。MIM 会自动解析这些依赖、选择合适的 MMCV 预编译包使安装更简单但它并不是必需的。若用 pip 安装 MMCV需要遵照 MMCV 安装指南手动以-f指定 url 的形式给出对应 PyTorch 与 CUDA 版本的预编译包索引页。例如安装基于 PyTorch 1.12.x 和 CUDA 11.6 编译的 MMCV 时命令形如pip install mmcv2.0.0 -f 对应 cu116 / torch1.12.0 的 MMCV 预编译包索引 URL其中索引 URL 的具体形式请按 MMCV 官方安装指南中“根据 PyTorch 与 CUDA 版本选择”一节获取不要省略-f参数否则会回退到源码编译并大概率失败。在 CPU 环境中安装MMDetection 可以在 CPU 环境中构建。CPU 模式下可以进行模型训练需要 MMCV 版本 2.0.0rc1、测试或推理但以下功能不可用Deformable ConvolutionModulated Deformable ConvolutionROI poolingDeformable ROI poolingCARAFESyncBatchNormCrissCrossAttentionMaskedConv2dTemporal Interlace Shiftnms_cudasigmoid_focal_loss_cudabbox_overlaps因此尝试训练/测试/推理包含上述算子的模型将会报错。受影响的典型算子与模型对应关系如下表操作受影响模型Deformable Convolution / Modulated Deformable ConvolutionDCN、Guided Anchoring、RepPoints、CentripetalNet、VFNet、CascadeRPN、NAS-FCOS、DetectoRSMaskedConv2dGuided AnchoringCARAFECARAFESyncBatchNormResNeSt从源码结构看这条限制并非文档约定而是硬性断言inference.py 中inference_detector与async_inference_detector都会遍历模型模块一旦发现RoIPool就抛出CPU inference with RoIPool is not supported currently这解释了为何依赖 RoI 提取类算子的两阶段检测器无法在纯 CPU 下推理。在 Google Colab 中安装Google Colab 通常已内置 PyTorch 环境因此只需安装 MMEngine、MMCV 和 MMDetection步骤 1.使用 MIM 安装 MMEngine 和 MMCV!pip3 install openmim !mim install mmengine !mim install mmcv2.0.0,2.1.0步骤 2.从源码安装 MMDetection!git clone https://gitcode.com/gh_mirrors/mm/mmdetection %cd mmdetection !pip install -e .步骤 3.验证安装是否成功import mmdet print(mmdet.__version__) # 预期输出当前仓库为 3.3.0早期文档示例预期 3.0.0 或其他版本号注在 Jupyter Notebook 中感叹号!用于执行外部命令而%cd是 IPython 的魔术命令用于切换 Python 的工作路径。通过 Docker 使用 MMDetection仓库提供了一个 Dockerfile 来构建镜像请确保 Docker 版本 19.03# 基于 PyTorch 1.9CUDA 11.1 构建镜像 # 如果想要其他版本只需修改 Dockerfile 顶部的 ARG docker build -t mmdetection docker/查看 docker/Dockerfile 可以看到镜像的构建细节顶部通过ARG PYTORCH1.9.0、ARG CUDA11.1、ARG CUDNN8三个变量声明基础镜像pytorch/pytorch:${PYTORCH}-cuda${CUDA}-cudnn${CUDNN}-devel设置TORCH_CUDA_ARCH_LIST覆盖主流 GPU 架构随后通过pip install openmim和mim install mmengine0.7.1 mmcv2.0.0rc4安装依赖最后克隆仓库并pip install --no-cache-dir -e .以可编辑模式安装 MMDetection工作目录为/mmdetection。构建完成后用以下命令运行镜像docker run --gpus all --shm-size8g -it -v {DATA_DIR}:/mmdetection/data mmdetection其中--gpus all暴露全部 GPU--shm-size8g加大共享内存以缓解 DataLoader 多进程通信瓶颈-v把宿主机数据目录挂载进容器的数据路径。排除故障如果在安装过程中遇到问题请先查阅仓库中的 FAQ 页面。如果没有找到解决方案也可以在项目仓库的 Issue 区提交问题求助。使用多个 MMDetection 版本进行开发训练和测试脚本如 train.py 与 test.py已经修改了PYTHONPATH以确保脚本使用当前目录中的 MMDetection而非环境中安装的版本。如果希望环境使用默认安装的 MMDetection 而不是当前目录下的版本可以删除相关脚本中出现的这段代码PYTHONPATH$(dirname $0)/..:$PYTHONPATH小结环境准备只需三步Miniconda → conda 环境Python 3.8→ 按 GPU/CPU 平台安装 PyTorch最佳安装路径是openmim mim install mmengine/mmcv再按开发需求选择源码可编辑安装pip install -v -e .或mim install mmdet验证安装的标准动作是mim download拉取 RTMDet-tiny 配置与权重用 demo/image_demo.py 或init_detectorinference_detector完成一次 CPU/GPU 推理检查outputs/vis下的可视化结果或pred_instance中的检测框、类别与得分自定义安装需重点把控 CUDA 版本与 MMCV 预编译包的匹配、CPU 模式下的算子黑名单以及 Colab/Docker 两条免环境部署路线。【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetection创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MMDetection 安装与推理验证完全指南：从环境搭建到首次跑通检测模型
MMDetection 安装与推理验证完全指南从环境搭建到首次跑通检测模型【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetection本文基于 MMDetectionOpenMMLab 目标检测工具箱官方中文文档《开始你的第一步》展开系统讲解在 Linux/Windows/macOS 上准备 PyTorch 环境、通过 MIM 安装 MMEngine 与 MMCV、以源码或 MIM 方式安装 MMDetection并下载 RTMDet-tiny 权重完成首次推理验证的完整流程同时深入 CUDA 版本选择、纯 CPU 环境限制、Google Colab 与 Docker 部署等自定义安装场景。读完本文你可以独立完成 MMDetection 的环境搭建、安装校验并理解验证脚本背后的 API 调用链。依赖与环境准备MMDetection 支持在 Linux、Windows 和 macOS 上运行要求 Python 3.7 以上、CUDA 9.2 以上和 PyTorch 1.8 及其以上。当前仓库代码中 mmdet/version.py 声明的版本号为 3.3.0本文内容均以该仓库当前状态为准。如果你对 PyTorch 已有经验并完成了安装可以直接跳至安装流程否则请按以下步骤准备步骤 0.从 Miniconda 官方渠道下载并安装 Miniconda。步骤 1.创建并激活一个 conda 环境conda create --name openmmlab python3.8 -y conda activate openmmlab步骤 2.按照 PyTorch 官方说明安装 PyTorch。GPU 平台上执行conda install pytorch torchvision -c pytorchCPU 平台上执行conda install pytorch torchvision cpuonly -c pytorch安装流程官方推荐参照最佳实践安装 MMDetection但整个过程是可定制的可按需参考自定义安装。最佳实践步骤 0.使用 MIMOpenMMLab 的包管理工具安装 MMEngine 和 MMCVpip install -U openmim mim install mmengine mim install mmcv2.0.0注意在 MMCV v2.x 中mmcv-full已改名为mmcv。如果想安装不包含 CUDA 算子的精简版可以通过mim install mmcv-lite2.0.0rc1来安装。步骤 1.安装 MMDetection有两种方案方案 a如果你要开发并直接运行 mmdet从源码安装开发模式git clone https://gitcode.com/gh_mirrors/mm/mmdetection cd mmdetection pip install -v -e . # -v 指详细说明即产生更详细的输出 # -e 表示以可编辑模式安装项目对代码所做的本地修改都会即时生效无需重新安装方案 b如果你将 mmdet 作为依赖或第三方 Python 包直接用 MIM 安装mim install mmdet验证安装为了验证 MMDetection 是否安装正确官方提供了一套示例代码来执行模型推理。整个验证链路是下载配置与权重 → 运行推理 → 检查输出。步骤 1.下载配置文件和模型权重文件mim download mmdet --config rtmdet_tiny_8xb32-300e_coco --dest .下载需要数秒或更长时间取决于网络环境。完成后当前文件夹中会出现两个文件rtmdet_tiny_8xb32-300e_coco.py和rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth。对应的配置文件在仓库中同样存在即 rtmdet_tiny_8xb32-300e_coco.py可以对照查看其网络结构与训练参数。步骤 2.推理验证。方案 a如果你通过源码安装的 MMDetection直接运行以下命令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 cpu你会在当前文件夹的outputs/vis子目录中看到一张新的图像demo.jpg图像上叠加了网络预测的检测框。从源码看demo/image_demo.py 是一个基于DetInferencer封装的命令行推理工具其关键参数包括--weights检查点文件、--device推理设备默认cuda:0、--out-dir结果输出目录默认outputs、--pred-score-thr检测框置信度阈值默认 0.3、--batch-size批量大小默认 1、--show弹窗显示结果以及--no-save-vis/--no-save-pred控制是否保存可视化图或 JSON 预测结果。其中“保存目录/vis/文件名”这一拼接逻辑出自 DetInferencer 的可视化实现即可视化结果统一落在out_dir/vis/下与文档描述的outputs/vis完全对应。方案 b如果你通过 MIM 安装了 MMDetection可以打开 Python 解释器复制并粘贴以下代码from mmdet.apis import init_detector, inference_detector config_file rtmdet_tiny_8xb32-300e_coco.py checkpoint_file rtmdet_tiny_8xb32-300e_coco_20220902_112414-78e30dcc.pth model init_detector(config_file, checkpoint_file, devicecpu) # or devicecuda:0 inference_detector(model, demo/demo.jpg)你将看到一个包含DetDataSample的列表预测结果位于pred_instance字段中包含检测框、类别和得分。这两个 API 的真实行为可以从 mmdet/apis/inference.py 得到印证init_detector(config, checkpoint, palettenone, devicecuda:0, cfg_optionsNone)加载配置文件构造模型随后调用load_checkpoint加载权重并从 checkpoint 的meta.dataset_meta中恢复类别信息dataset_meta若检查点缺少类别信息则默认使用 COCO 80 类。cfg_options参数可在不修改配置文件的前提下覆盖配置项。inference_detector(model, imgs)支持单张或多张输入str/ndarray/序列内部依据model.cfg自动构建测试预处理管线get_test_pipeline_cfg在torch.no_grad()下调用model.test_step完成前向推理并返回DetDataSample或SampleList。值得注意的是当模型位于 CPU 设备时源码会断言模型中不存在RoIPool模块并抛出“CPU inference with RoIPool is not supported currently”这与下文 CPU 环境的功能限制一一对应。自定义安装安装流程中的每个环节都可以根据你的硬件与使用场景调整。CUDA 版本选择安装 PyTorch 时需要指定 CUDA 版本。如果不确定该选哪个官方建议如下对于 Ampere 架构的 NVIDIA GPU如 GeForce 30 系列及 NVIDIA A100CUDA 11 是必需的对于更早的 NVIDIA GPUCUDA 11 向后兼容但 CUDA 10.2 提供更好兼容性且更轻量。请确保 GPU 驱动版本满足最低要求可参阅 NVIDIA 官方的 CUDA 工具箱与驱动版本对应关系表。如果按最佳实践安装只需 CUDA 运行时库即可因为不需要在本地编译 CUDA 代码。但如果你希望从源码编译 MMCV或开发其他 CUDA 算子就必须安装完整的 CUDA 工具链并确保其版本与 PyTorch 安装时指定的cudatoolkit版本相匹配。不使用 MIM 安装 MMEngine若希望用 pip 而非 MIM 安装 MMEngine遵照 MMEngine 安装指南即可例如pip install mmengine不使用 MIM 安装 MMCVMMCV 包含 C 和 CUDA 扩展其对 PyTorch 的依赖比较复杂。MIM 会自动解析这些依赖、选择合适的 MMCV 预编译包使安装更简单但它并不是必需的。若用 pip 安装 MMCV需要遵照 MMCV 安装指南手动以-f指定 url 的形式给出对应 PyTorch 与 CUDA 版本的预编译包索引页。例如安装基于 PyTorch 1.12.x 和 CUDA 11.6 编译的 MMCV 时命令形如pip install mmcv2.0.0 -f 对应 cu116 / torch1.12.0 的 MMCV 预编译包索引 URL其中索引 URL 的具体形式请按 MMCV 官方安装指南中“根据 PyTorch 与 CUDA 版本选择”一节获取不要省略-f参数否则会回退到源码编译并大概率失败。在 CPU 环境中安装MMDetection 可以在 CPU 环境中构建。CPU 模式下可以进行模型训练需要 MMCV 版本 2.0.0rc1、测试或推理但以下功能不可用Deformable ConvolutionModulated Deformable ConvolutionROI poolingDeformable ROI poolingCARAFESyncBatchNormCrissCrossAttentionMaskedConv2dTemporal Interlace Shiftnms_cudasigmoid_focal_loss_cudabbox_overlaps因此尝试训练/测试/推理包含上述算子的模型将会报错。受影响的典型算子与模型对应关系如下表操作受影响模型Deformable Convolution / Modulated Deformable ConvolutionDCN、Guided Anchoring、RepPoints、CentripetalNet、VFNet、CascadeRPN、NAS-FCOS、DetectoRSMaskedConv2dGuided AnchoringCARAFECARAFESyncBatchNormResNeSt从源码结构看这条限制并非文档约定而是硬性断言inference.py 中inference_detector与async_inference_detector都会遍历模型模块一旦发现RoIPool就抛出CPU inference with RoIPool is not supported currently这解释了为何依赖 RoI 提取类算子的两阶段检测器无法在纯 CPU 下推理。在 Google Colab 中安装Google Colab 通常已内置 PyTorch 环境因此只需安装 MMEngine、MMCV 和 MMDetection步骤 1.使用 MIM 安装 MMEngine 和 MMCV!pip3 install openmim !mim install mmengine !mim install mmcv2.0.0,2.1.0步骤 2.从源码安装 MMDetection!git clone https://gitcode.com/gh_mirrors/mm/mmdetection %cd mmdetection !pip install -e .步骤 3.验证安装是否成功import mmdet print(mmdet.__version__) # 预期输出当前仓库为 3.3.0早期文档示例预期 3.0.0 或其他版本号注在 Jupyter Notebook 中感叹号!用于执行外部命令而%cd是 IPython 的魔术命令用于切换 Python 的工作路径。通过 Docker 使用 MMDetection仓库提供了一个 Dockerfile 来构建镜像请确保 Docker 版本 19.03# 基于 PyTorch 1.9CUDA 11.1 构建镜像 # 如果想要其他版本只需修改 Dockerfile 顶部的 ARG docker build -t mmdetection docker/查看 docker/Dockerfile 可以看到镜像的构建细节顶部通过ARG PYTORCH1.9.0、ARG CUDA11.1、ARG CUDNN8三个变量声明基础镜像pytorch/pytorch:${PYTORCH}-cuda${CUDA}-cudnn${CUDNN}-devel设置TORCH_CUDA_ARCH_LIST覆盖主流 GPU 架构随后通过pip install openmim和mim install mmengine0.7.1 mmcv2.0.0rc4安装依赖最后克隆仓库并pip install --no-cache-dir -e .以可编辑模式安装 MMDetection工作目录为/mmdetection。构建完成后用以下命令运行镜像docker run --gpus all --shm-size8g -it -v {DATA_DIR}:/mmdetection/data mmdetection其中--gpus all暴露全部 GPU--shm-size8g加大共享内存以缓解 DataLoader 多进程通信瓶颈-v把宿主机数据目录挂载进容器的数据路径。排除故障如果在安装过程中遇到问题请先查阅仓库中的 FAQ 页面。如果没有找到解决方案也可以在项目仓库的 Issue 区提交问题求助。使用多个 MMDetection 版本进行开发训练和测试脚本如 train.py 与 test.py已经修改了PYTHONPATH以确保脚本使用当前目录中的 MMDetection而非环境中安装的版本。如果希望环境使用默认安装的 MMDetection 而不是当前目录下的版本可以删除相关脚本中出现的这段代码PYTHONPATH$(dirname $0)/..:$PYTHONPATH小结环境准备只需三步Miniconda → conda 环境Python 3.8→ 按 GPU/CPU 平台安装 PyTorch最佳安装路径是openmim mim install mmengine/mmcv再按开发需求选择源码可编辑安装pip install -v -e .或mim install mmdet验证安装的标准动作是mim download拉取 RTMDet-tiny 配置与权重用 demo/image_demo.py 或init_detectorinference_detector完成一次 CPU/GPU 推理检查outputs/vis下的可视化结果或pred_instance中的检测框、类别与得分自定义安装需重点把控 CUDA 版本与 MMCV 预编译包的匹配、CPU 模式下的算子黑名单以及 Colab/Docker 两条免环境部署路线。【免费下载链接】mmdetectionOpenMMLab Detection Toolbox and Benchmark项目地址: https://gitcode.com/gh_mirrors/mm/mmdetection创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考