入门¶

先决条件¶

在本节中，我们将演示如何使用 PyTorch 准备环境。

MMDetection 在 Linux、Windows 和 macOS 上运行。它需要 Python 3.7+、CUDA 9.2+ 和 PyTorch 1.8+。

注意

如果您熟悉 PyTorch 并已安装它，请跳过本部分，直接进入下一节。否则，您可以按照以下步骤进行准备。

步骤 0. 从官方网站下载并安装 Miniconda。

步骤 1. 创建一个 conda 环境并激活它。

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

步骤 2. 按照官方说明安装 PyTorch，例如：

在 GPU 平台上

conda install pytorch torchvision -c pytorch

在 CPU 平台上

conda install pytorch torchvision cpuonly -c pytorch

安装¶

我们建议用户遵循我们的最佳实践来安装 MMDetection。但是，整个过程是高度可定制的。有关更多信息，请参阅定制安装部分。

最佳实践¶

步骤 0. 使用MIM安装MMEngine和MMCV。

pip install -U openmim
mim install mmengine
mim install "mmcv>=2.0.0"

注意：在 MMCV-v2.x 中，mmcv-full 重命名为 mmcv，如果您想安装不带 CUDA 操作的 mmcv，您可以使用 mim install "mmcv-lite>=2.0.0rc1" 来安装精简版。

步骤 1. 安装 MMDetection。

情况 a：如果您直接开发并运行 mmdet，请从源代码安装它

git clone https://github.com/open-mmlab/mmdetection.git
cd mmdetection
pip install -v -e .
# "-v" means verbose, or more output
# "-e" means installing a project in editable mode,
# thus any local modifications made to the code will take effect without reinstallation.

情况 b：如果您将 mmdet 用作依赖项或第三方软件包，请使用 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。

步骤 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，其中边界框绘制在汽车、长椅等上。

情况 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, device='cpu')  # or device='cuda:0'
inference_detector(model, 'demo/demo.jpg')

您将看到一个 DetDataSample 列表，预测结果在 pred_instance 中，表示检测到的边界框、标签和分数。

跟踪安装¶

我们建议用户遵循我们的最佳实践来安装用于跟踪任务的 MMDetection。

最佳实践¶

步骤 0. 使用MIM安装MMEngine和MMCV。

pip install -U openmim
mim install mmengine
mim install "mmcv>=2.0.0"

步骤 1. 安装 MMDetection。

情况 a：如果您直接开发并运行 mmdet，请从源代码安装它

git clone https://github.com/open-mmlab/mmdetection.git
cd mmdetection
pip install -v -e . -r requirements/tracking.txt
# "-v" means verbose, or more output
# "-e" means installing a project in editable mode,
# thus any local modifications made to the code will take effect without reinstallation.

情况 b：如果您将 mmdet 用作依赖项或第三方软件包，请使用 MIM 安装它

mim install mmdet[tracking]

步骤 2. 安装 TrackEval。

pip install git+https://github.com/JonathonLuiten/TrackEval.git

验证安装¶

为了验证 MMDetection 是否已正确安装，我们提供了一些示例代码来运行推理演示。

步骤 1. 我们需要下载配置文件和检查点文件。

mim download mmdet --config bytetrack_yolox_x_8xb4-amp-80e_crowdhuman-mot17halftrain_test-mot17halfval --dest .

下载可能需要几秒钟或更长时间，具体取决于您的网络环境。完成后，您将在当前文件夹中找到两个文件 bytetrack_yolox_x_8xb4-amp-80e_crowdhuman-mot17halftrain_test-mot17halfval.py 和 bytetrack_yolox_x_crowdhuman_mot17-private-half_20211218_205500-1985c9f0.pth。

步骤 2. 验证推理演示。

情况 a：如果您从源代码安装 MMDetection，只需运行以下命令。

python demo/mot_demo.py demo/demo_mot.mp4 bytetrack_yolox_x_8xb4-amp-80e_crowdhuman-mot17halftrain_test-mot17halfval.py --checkpoint bytetrack_yolox_x_crowdhuman_mot17-private-half_20211218_205500-1985c9f0.pth --out mot.mp4

您将在您的文件夹中看到一个新的视频 mot.mp4，其中边界框绘制在人身上。

情况 b：如果您使用 MIM 安装 MMDetection，请打开您的 Python 解释器和 demo/mot_demo.py，然后像情况 a 一样运行它。

定制安装¶

CUDA 版本¶

安装 PyTorch 时，您需要指定 CUDA 版本。如果您不清楚选择哪个，请遵循我们的建议

对于基于 Ampere 的 NVIDIA GPU，例如 GeForce 30 系列和 NVIDIA A100，CUDA 11 是必须的。
对于旧的 NVIDIA GPU，CUDA 11 向后兼容，但 CUDA 10.2 提供更好的兼容性且更轻量级。

请确保 GPU 驱动程序满足最低版本要求。有关更多信息，请参阅此表。

注意

如果您遵循我们的最佳实践，则安装 CUDA 运行时库就足够了，因为不会在本地编译任何 CUDA 代码。但是，如果您希望从源代码编译 MMCV 或开发其他 CUDA 运算符，您需要从 NVIDIA 的网站安装完整的 CUDA 工具包，并且它的版本应与 PyTorch 的 CUDA 版本匹配。即，在 conda install 命令中指定的 cudatoolkit 版本。

不使用 MIM 安装 MMEngine¶

要使用 pip 而不是 MIM 安装 MMEngine，请遵循MMEngine 安装指南。

例如，您可以通过以下命令安装 MMEngine。

pip install mmengine

不使用 MIM 安装 MMCV¶

MMCV 包含 C++ 和 CUDA 扩展，因此以复杂的方式依赖于 PyTorch。MIM 自动解决此类依赖关系，使安装更轻松。但是，这不是必须的。

要使用 pip 而不是 MIM 安装 MMCV，请遵循MMCV 安装指南。这需要根据 PyTorch 版本及其 CUDA 版本手动指定 find-url。

例如，以下命令安装为 PyTorch 1.12.x 和 CUDA 11.6 构建的 MMCV。

pip install "mmcv>=2.0.0" -f https://download.openmmlab.com/mmcv/dist/cu116/torch1.12.0/index.html

在纯 CPU 平台上安装¶

MMDetection 可以为纯 CPU 环境构建。在 CPU 模式下，您可以训练（需要 MMCV 版本 >= 2.0.0rc1）、测试或推断模型。

但是，此模式下某些功能将消失

可变形卷积
调制可变形卷积
ROI 池化
可变形 ROI 池化
CARAFE
SyncBatchNorm
CrissCrossAttention
MaskedConv2d
时间交织移位
nms_cuda
sigmoid_focal_loss_cuda
bbox_overlaps

如果您尝试训练/测试/推断包含上述操作的模型，将引发错误。下表列出了受影响的算法。

运算符	模型
可变形卷积/调制可变形卷积	DCN、Guided Anchoring、RepPoints、CentripetalNet、VFNet、CascadeRPN、NAS-FCOS、DetectoRS
MaskedConv2d	Guided Anchoring
CARAFE	CARAFE
SyncBatchNorm	ResNeSt

在 Google Colab 上安装¶

Google Colab 通常已安装 PyTorch，因此我们只需要使用以下命令安装 MMEngine、MMCV 和 MMDetection。

步骤 1. 使用 MIM 安装 MMEngine 和 MMCV。

!pip3 install openmim
!mim install mmengine
!mim install "mmcv>=2.0.0,<2.1.0"

步骤 2. 从源代码安装 MMDetection。

!git clone https://github.com/open-mmlab/mmdetection.git
%cd mmdetection
!pip install -e .

步骤 3. 验证。

import mmdet
print(mmdet.__version__)
# Example output: 3.0.0, or an another version.

注意

在 Jupyter 中，感叹号 ! 用于调用外部可执行文件，而 %cd 是一个魔法命令用于更改 Python 的当前工作目录。

使用 Docker 的 MMDetection¶

我们提供了一个 Dockerfile 来构建镜像。确保您的 docker 版本 >=19.03。

# build an image with PyTorch 1.9, CUDA 11.1
# If you prefer other versions, just modified the Dockerfile
docker build -t mmdetection docker/

使用以下命令运行它

docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmdetection/data mmdetection

故障排除¶

如果您在安装过程中遇到一些问题，请先查看常见问题解答页面。如果您找不到解决方案，可以在 GitHub 上打开一个问题。

在开发中使用多个版本的 MMDetection¶

训练和测试脚本已在 PYTHONPATH 中修改，以确保脚本使用它们自己的 MMDetection 版本。

要将默认版本的 MMDetection 安装到您的环境中，您可以在相关脚本中排除以下代码

PYTHONPATH="$(dirname $0)/..":$PYTHONPATH