update codes

docs/zh_cn/advanced_guides/structures.md

+# 数据结构（待更新）

docs/zh_cn/advanced_guides/transforms.md

+# 数据变换（待更新）
+
+按照惯例，我们使用 `Dataset` 和 `DataLoader` 进行多进程的数据加载。`Dataset` 返回字典类型的数据，数据内容为模型 `forward` 方法的各个参数。由于在目标检测中，输入的图像数据具有不同的大小，我们在 `MMCV` 里引入一个新的 `DataContainer` 类去收集和分发不同大小的输入数据。更多细节请参考[这里](https://github.com/open-mmlab/mmcv/blob/master/mmcv/parallel/data_container.py)。
+
+数据的准备流程和数据集是解耦的。通常一个数据集定义了如何处理标注数据（annotations）信息，而一个数据流程定义了准备一个数据字典的所有步骤。一个流程包括一系列的操作，每个操作都把一个字典作为输入，然后再输出一个新的字典给下一个变换操作。
+
+我们在下图展示了一个经典的数据处理流程。蓝色块是数据处理操作，随着数据流程的处理，每个操作都可以在结果字典中加入新的键（标记为绿色）或更新现有的键（标记为橙色）。
+
+![pipeline figure](../../../resources/data_pipeline.png)
+
+这些操作可以分为数据加载（data loading）、预处理（pre-processing）、格式变化（formatting）和测试时数据增强（test-time augmentation）。
+
+下面的例子是 `Faster R-CNN` 的一个流程：
+
+```python
+img_norm_cfg = dict(
+    mean=[123.675, 116.28, 103.53], std=[58.395, 57.12, 57.375], to_rgb=True)
+train_pipeline = [
+    dict(type='LoadImageFromFile'),
+    dict(type='LoadAnnotations', with_bbox=True),
+    dict(type='Resize', img_scale=(1333, 800), keep_ratio=True),
+    dict(type='RandomFlip', flip_ratio=0.5),
+    dict(type='Normalize', **img_norm_cfg),
+    dict(type='Pad', size_divisor=32),
+    dict(type='DefaultFormatBundle'),
+    dict(type='Collect', keys=['img', 'gt_bboxes', 'gt_labels']),
+]
+test_pipeline = [
+    dict(type='LoadImageFromFile'),
+    dict(
+        type='MultiScaleFlipAug',
+        img_scale=(1333, 800),
+        flip=False,
+        transforms=[
+            dict(type='Resize', keep_ratio=True),
+            dict(type='RandomFlip'),
+            dict(type='Normalize', **img_norm_cfg),
+            dict(type='Pad', size_divisor=32),
+            dict(type='ImageToTensor', keys=['img']),
+            dict(type='Collect', keys=['img']),
+        ])
+]
+```

docs/zh_cn/api.rst

+mmdet.apis
+--------------
+.. automodule:: mmdet.apis
+    :members:
+
+mmdet.datasets
+--------------
+
+datasets
+^^^^^^^^^^
+.. automodule:: mmdet.datasets
+    :members:
+
+api_wrappers
+^^^^^^^^^^^^^^^^^
+.. automodule:: mmdet.datasets.api_wrappers
+    :members:
+
+samplers
+^^^^^^^^^^
+.. automodule:: mmdet.datasets.samplers
+    :members:
+
+transforms
+^^^^^^^^^^^^
+.. automodule:: mmdet.datasets.transforms
+    :members:
+
+mmdet.engine
+--------------
+
+hooks
+^^^^^^^^^^
+.. automodule:: mmdet.engine.hooks
+    :members:
+
+optimizers
+^^^^^^^^^^^^^^^
+.. automodule:: mmdet.engine.optimizers
+    :members:
+
+runner
+^^^^^^^^^^
+.. automodule:: mmdet.engine.runner
+    :members:
+
+schedulers
+^^^^^^^^^^^^^^^^^
+.. automodule:: mmdet.engine.schedulers
+    :members:
+
+mmdet.evaluation
+--------------------
+
+functional
+^^^^^^^^^^^^^^^^^
+.. automodule:: mmdet.evaluation.functional
+    :members:
+
+metrics
+^^^^^^^^^^
+.. automodule:: mmdet.evaluation.metrics
+    :members:
+
+
+mmdet.models
+--------------
+
+backbones
+^^^^^^^^^^^^^^^^^^
+.. automodule:: mmdet.models.backbones
+    :members:
+
+data_preprocessors
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: mmdet.models.data_preprocessors
+    :members:
+
+dense_heads
+^^^^^^^^^^^^^^^
+.. automodule:: mmdet.models.dense_heads
+    :members:
+
+detectors
+^^^^^^^^^^
+.. automodule:: mmdet.models.detectors
+    :members:
+
+layers
+^^^^^^^^^^
+.. automodule:: mmdet.models.layers
+    :members:
+
+losses
+^^^^^^^^^^
+.. automodule:: mmdet.models.losses
+    :members:
+
+necks
+^^^^^^^^^^^^
+.. automodule:: mmdet.models.necks
+    :members:
+
+roi_heads
+^^^^^^^^^^^^^
+.. automodule:: mmdet.models.roi_heads
+    :members:
+
+seg_heads
+^^^^^^^^^^^^^
+.. automodule:: mmdet.models.seg_heads
+    :members:
+
+task_modules
+^^^^^^^^^^^^^
+.. automodule:: mmdet.models.task_modules
+    :members:
+
+test_time_augs
+^^^^^^^^^^^^^^^^^^^^
+.. automodule:: mmdet.models.test_time_augs
+    :members:
+
+utils
+^^^^^^^^^^
+.. automodule:: mmdet.models.utils
+    :members:
+
+
+mmdet.structures
+--------------------
+
+structures
+^^^^^^^^^^^^^^^^^
+.. automodule:: mmdet.structures
+    :members:
+
+bbox
+^^^^^^^^^^
+.. automodule:: mmdet.structures.bbox
+    :members:
+
+mask
+^^^^^^^^^^
+.. automodule:: mmdet.structures.mask
+    :members:
+
+mmdet.testing
+----------------
+.. automodule:: mmdet.testing
+    :members:
+
+mmdet.visualization
+--------------------
+.. automodule:: mmdet.visualization
+    :members:
+
+mmdet.utils
+--------------
+.. automodule:: mmdet.utils
+    :members:

docs/zh_cn/article.md

+## 中文解读文案汇总（待更新）
+
+### 1 官方解读文案（v2.x）
+
+#### 1.1 框架解读
+
+- **[轻松掌握 MMDetection 整体构建流程(一)](https://zhuanlan.zhihu.com/p/337375549)**
+- **[轻松掌握 MMDetection 整体构建流程(二)](https://zhuanlan.zhihu.com/p/341954021)**
+- **[轻松掌握 MMDetection 中 Head 流程](https://zhuanlan.zhihu.com/p/343433169)**
+
+#### 1.2 算法解读
+
+- **[轻松掌握 MMDetection 中常用算法(一)：RetinaNet 及配置详解](https://zhuanlan.zhihu.com/p/346198300)**
+- **[轻松掌握 MMDetection 中常用算法(二)：Faster R-CNN|Mask R-CNN](https://zhuanlan.zhihu.com/p/349807581)**
+- [轻松掌握 MMDetection 中常用算法(三)：FCOS](https://zhuanlan.zhihu.com/p/358056615)
+- [轻松掌握 MMDetection 中常用算法(四)：ATSS](https://zhuanlan.zhihu.com/p/358125611)
+- [轻松掌握 MMDetection 中常用算法(五)：Cascade R-CNN](https://zhuanlan.zhihu.com/p/360952172)
+- [轻松掌握 MMDetection 中常用算法(六)：YOLOF](https://zhuanlan.zhihu.com/p/370758213)
+- [轻松掌握 MMDetection 中常用算法(七)：CenterNet](https://zhuanlan.zhihu.com/p/374891478)
+- [轻松掌握 MMDetection 中常用算法(八)：YOLACT](https://zhuanlan.zhihu.com/p/376347955)
+- [轻松掌握 MMDetection 中常用算法(九)：AutoAssign](https://zhuanlan.zhihu.com/p/378581552)
+- [YOLOX 在 MMDetection 中复现全流程解析](https://zhuanlan.zhihu.com/p/398545304)
+- [喂喂喂！你可以减重了！小模型 - MMDetection 新增SSDLite 、 MobileNetV2YOLOV3 两大经典算法](https://zhuanlan.zhihu.com/p/402781143)
+
+#### 1.3 工具解读
+
+- [OpenMMLab 中混合精度训练 AMP 的正确打开方式](https://zhuanlan.zhihu.com/p/375224982)
+- [小白都能看懂！手把手教你使用混淆矩阵分析目标检测](https://zhuanlan.zhihu.com/p/443499860)
+- [MMDetection 图像缩放 Resize 详细说明 OpenMMLab](https://zhuanlan.zhihu.com/p/381117525)
+- [拿什么拯救我的 4G 显卡](https://zhuanlan.zhihu.com/p/430123077)
+- [MMDet居然能用MMCls的Backbone？论配置文件的打开方式](https://zhuanlan.zhihu.com/p/436865195)
+
+#### 1.4 知乎问答
+
+- [COCO数据集上1x模式下为什么不采用多尺度训练?](https://www.zhihu.com/question/462170786/answer/1915119662)
+- [MMDetection中SOTA论文源码中将训练过程中BN层的eval打开?](https://www.zhihu.com/question/471189603/answer/2195540892)
+- [基于PyTorch的MMDetection中训练的随机性来自何处？](https://www.zhihu.com/question/453511684/answer/1839683634)
+- [单阶段、双阶段、anchor-based、anchor-free 这四者之间有什么联系吗？](https://www.zhihu.com/question/428972054/answer/1619925296)
+- [目标检测的深度学习方法，有推荐的书籍或资料吗？](https://www.zhihu.com/question/391577080/answer/1612593817)
+- [大佬们，刚入学研究生，想入门目标检测，有什么学习路线可以入门的？](https://www.zhihu.com/question/343768934/answer/1612580715)
+- [目标检测领域还有什么可以做的？](https://www.zhihu.com/question/280703314/answer/1627885518)
+- [如何看待Transformer在CV上的应用前景，未来有可能替代CNN吗？](https://www.zhihu.com/question/437495132/answer/1686380553)
+- [MMDetection如何学习源码？](https://www.zhihu.com/question/451585041/answer/1832498963)
+- [如何具体上手实现目标检测呢？](https://www.zhihu.com/question/341401981/answer/1848561187)
+
+#### 1.5 其他
+
+- **[不得不知的 MMDetection 学习路线(个人经验版)](https://zhuanlan.zhihu.com/p/369826931)**
+- [OpenMMLab 社区专访之 YOLOX 复现篇](https://zhuanlan.zhihu.com/p/405913343)
+
+### 2 社区解读文案（v2.x）
+
+- [手把手带你实现经典检测网络 Mask R-CNN 的推理](https://zhuanlan.zhihu.com/p/414082071)

docs/zh_cn/conf.py

+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import subprocess
+import sys
+
+import pytorch_sphinx_theme
+
+sys.path.insert(0, os.path.abspath('../../'))
+
+# -- Project information -----------------------------------------------------
+
+project = 'MMDetection'
+copyright = '2018-2021, OpenMMLab'
+author = 'MMDetection Authors'
+version_file = '../../mmdet/version.py'
+
+
+def get_version():
+    with open(version_file, 'r') as f:
+        exec(compile(f.read(), version_file, 'exec'))
+    return locals()['__version__']
+
+
+# The full version, including alpha/beta/rc tags
+release = get_version()
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'myst_parser',
+    'sphinx_markdown_tables',
+    'sphinx_copybutton',
+]
+
+myst_enable_extensions = ['colon_fence']
+myst_heading_anchors = 3
+
+autodoc_mock_imports = [
+    'matplotlib', 'pycocotools', 'terminaltables', 'mmdet.version', 'mmcv.ops'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+# The main toctree document.
+master_doc = 'index'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+# html_theme = 'sphinx_rtd_theme'
+html_theme = 'pytorch_sphinx_theme'
+html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()]
+
+html_theme_options = {
+    'menu': [
+        {
+            'name': 'GitHub',
+            'url': 'https://github.com/open-mmlab/mmdetection'
+        },
+    ],
+    # Specify the language of shared menu
+    'menu_lang':
+    'cn',
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+html_css_files = ['css/readthedocs.css']
+
+language = 'zh_CN'
+
+# -- Extension configuration -------------------------------------------------
+# Ignore >>> when copying code
+copybutton_prompt_text = r'>>> |\.\.\. '
+copybutton_prompt_is_regexp = True
+
+
+def builder_inited_handler(app):
+    subprocess.run(['./stat.py'])
+
+
+def setup(app):
+    app.connect('builder-inited', builder_inited_handler)

docs/zh_cn/get_started.md

+# 开始你的第一步
+
+## 依赖
+
+本节中，我们将演示如何用 PyTorch 准备一个环境。
+
+MMDetection 支持在 Linux，Windows 和 macOS 上运行。它需要 Python 3.7 以上，CUDA 9.2 以上和 PyTorch 1.8 及其以上。
+
+```{note}
+如果你对 PyTorch 有经验并且已经安装了它，你可以直接跳转到[下一小节](#安装流程)。否则，你可以按照下述步骤进行准备。
+```
+
+**步骤 0.** 从[官方网站](https://docs.conda.io/en/latest/miniconda.html)下载并安装 Miniconda。
+
+**步骤 1.** 创建并激活一个 conda 环境。
+
+```shell
+conda create --name openmmlab python=3.8 -y
+conda activate openmmlab
+```
+
+**步骤 2.** 基于 [PyTorch 官方说明](https://pytorch.org/get-started/locally/)安装 PyTorch。
+
+在 GPU 平台上：
+
+```shell
+conda install pytorch torchvision -c pytorch
+```
+
+在 CPU 平台上：
+
+```shell
+conda install pytorch torchvision cpuonly -c pytorch
+```
+
+## 安装流程
+
+我们推荐用户参照我们的最佳实践安装 MMDetection。不过，整个过程也是可定制化的，更多信息请参考[自定义安装](#自定义安装)章节。
+
+### 最佳实践
+
+**步骤 0.** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMEngine](https://github.com/open-mmlab/mmengine) 和 [MMCV](https://github.com/open-mmlab/mmcv)。
+
+```shell
+pip install -U openmim
+mim install mmengine
+mim install "mmcv>=2.0.0"
+```
+
+**注意：** 在 MMCV-v2.x 中，`mmcv-full` 改名为 `mmcv`，如果你想安装不包含 CUDA 算子精简版，可以通过 `mim install "mmcv-lite>=2.0.0rc1"` 来安装。
+
+**步骤 1.** 安装 MMDetection。
+
+方案 a：如果你开发并直接运行 mmdet，从源码安装它：
+
+```shell
+git clone https://github.com/open-mmlab/mmdetection.git
+cd mmdetection
+pip install -v -e .
+# "-v" 指详细说明，或更多的输出
+# "-e" 表示在可编辑模式下安装项目，因此对代码所做的任何本地修改都会生效，从而无需重新安装。
+```
+
+方案 b：如果你将 mmdet 作为依赖或第三方 Python 包，使用 MIM 安装：
+
+```shell
+mim install mmdet
+```
+
+## 验证安装
+
+为了验证 MMDetection 是否安装正确，我们提供了一些示例代码来执行模型推理。
+
+**步骤 1.** 我们需要下载配置文件和模型权重文件。
+
+```shell
+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，那么直接运行以下命令进行验证：
+
+```shell
+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 解析器，复制并粘贴以下代码：
+
+```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` 里，包含有检测框，类别和得分。
+
+### 自定义安装
+
+#### CUDA 版本
+
+在安装 PyTorch 时，你需要指定 CUDA 的版本。如果你不清楚应该选择哪一个，请遵循我们的建议：
+
+- 对于 Ampere 架构的 NVIDIA GPU，例如 GeForce 30 系列以及 NVIDIA A100，CUDA 11 是必需的。
+- 对于更早的 NVIDIA GPU，CUDA 11 是向后兼容 (backward compatible) 的，但 CUDA 10.2 能够提供更好的兼容性，也更加轻量。
+
+请确保你的 GPU 驱动版本满足最低的版本需求，参阅 NVIDIA 官方的 [CUDA 工具箱和相应的驱动版本关系表](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#cuda-major-component-versions__table-cuda-toolkit-driver-versions)。
+
+```{note}
+如果按照我们的最佳实践，安装 CUDA 运行时库就足够了，这是因为不需要在本地编译 CUDA 代码。但如果你希望从源码编译 MMCV，或是开发其他 CUDA 算子，那么就必须安装完整的 CUDA 工具链，参见 [NVIDIA 官网](https://developer.nvidia.com/cuda-downloads)，另外还需要确保该 CUDA 工具链的版本与 PyTorch 安装时的配置相匹配（如用 `conda install` 安装 PyTorch 时指定的 cudatoolkit 版本）。
+```
+
+#### 不使用 MIM 安装 MMEngine
+
+要使用 pip 而不是 MIM 来安装 MMEngine，请遵照 [MMEngine 安装指南](https://mmengine.readthedocs.io/zh_CN/latest/get_started/installation.html)。
+
+例如，你可以通过以下命令安装 MMEngine。
+
+```shell
+pip install mmengine
+```
+
+#### 不使用 MIM 安装 MMCV
+
+MMCV 包含 C++ 和 CUDA 扩展，因此其对 PyTorch 的依赖比较复杂。MIM 会自动解析这些依赖，选择合适的 MMCV 预编译包，使安装更简单，但它并不是必需的。
+
+要使用 pip 而不是 MIM 来安装 MMCV，请遵照 [MMCV 安装指南](https://mmcv.readthedocs.io/zh_CN/2.x/get_started/installation.html)。它需要您用指定 url 的形式手动指定对应的 PyTorch 和 CUDA 版本。
+
+例如，下述命令将会安装基于 PyTorch 1.12.x 和 CUDA 11.6 编译的 MMCV。
+
+```shell
+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）、测试或者推理。
+
+但是，以下功能在该模式下不能使用：
+
+- Deformable Convolution
+- Modulated Deformable Convolution
+- ROI pooling
+- Deformable ROI pooling
+- CARAFE
+- SyncBatchNorm
+- CrissCrossAttention
+- MaskedConv2d
+- Temporal Interlace Shift
+- nms_cuda
+- sigmoid_focal_loss_cuda
+- bbox_overlaps
+
+因此，如果尝试训练/测试/推理包含上述算子的模型，将会报错。下表列出了将会受影响的相关算法。
+
+|                          操作                           |                                           模型                                           |
+| :-----------------------------------------------------: | :--------------------------------------------------------------------------------------: |
+| Deformable Convolution/Modulated Deformable Convolution | DCN、Guided Anchoring、RepPoints、CentripetalNet、VFNet、CascadeRPN、NAS-FCOS、DetectoRS |
+|                      MaskedConv2d                       |                                     Guided Anchoring                                     |
+|                         CARAFE                          |                                          CARAFE                                          |
+|                      SyncBatchNorm                      |                                         ResNeSt                                          |
+
+#### 在 Google Colab 中安装
+
+[Google Colab](https://colab.research.google.com/) 通常已经包含了 PyTorch 环境，因此我们只需要安装 MMEngine，MMCV 和 MMDetection 即可，命令如下：
+
+**步骤 1.** 使用 [MIM](https://github.com/open-mmlab/mim) 安装 [MMEngine](https://github.com/open-mmlab/mmengine) 和 [MMCV](https://github.com/open-mmlab/mmcv)。
+
+```shell
+!pip3 install openmim
+!mim install mmengine
+!mim install "mmcv>=2.0.0,<2.1.0"
+```
+
+**步骤 2.** 使用源码安装 MMDetection。
+
+```shell
+!git clone https://github.com/open-mmlab/mmdetection.git
+%cd mmdetection
+!pip install -e .
+```
+
+**步骤 3.** 验证安装是否成功。
+
+```python
+import mmdet
+print(mmdet.__version__)
+# 预期输出：3.0.0 或其他版本号
+```
+
+```{note}
+在 Jupyter Notebook 中，感叹号 `!` 用于执行外部命令，而 `%cd` 是一个[魔术命令](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-cd)，用于切换 Python 的工作路径。
+```
+
+#### 通过 Docker 使用 MMDetection
+
+我们提供了一个 [Dockerfile](../../docker/Dockerfile) 来构建一个镜像。请确保你的 [docker 版本](https://docs.docker.com/engine/install/) >=19.03。
+
+```shell
+# 基于 PyTorch 1.9，CUDA 11.1 构建镜像
+# 如果你想要其他版本，只需要修改 Dockerfile
+docker build -t mmdetection docker/
+```
+
+用以下命令运行 Docker 镜像：
+
+```shell
+docker run --gpus all --shm-size=8g -it -v {DATA_DIR}:/mmdetection/data mmdetection
+```
+
+### 排除故障
+
+如果你在安装过程中遇到一些问题，请先查看 [FAQ](notes/faq.md) 页面。如果没有找到解决方案，你也可以在 GitHub 上[提出一个问题](https://github.com/open-mmlab/mmdetection/issues/new/choose)。
+
+### 使用多个 MMDetection 版本进行开发
+
+训练和测试的脚本已经在 `PYTHONPATH` 中进行了修改，以确保脚本使用当前目录中的 MMDetection。
+
+要使环境中安装默认版本的 MMDetection 而不是当前正在使用的，可以删除出现在相关脚本中的代码：
+
+```shell
+PYTHONPATH="$(dirname $0)/..":$PYTHONPATH
+```

docs/zh_cn/index.rst

+Welcome to MMDetection's documentation!
+=======================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 开始你的第一步
+
+   overview.md
+   get_started.md
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 使用指南
+
+   user_guides/index.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 进阶教程
+
+   advanced_guides/index.rst
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 迁移版本
+
+   migration/migration.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 接口文档（英文）
+
+   api.rst
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 模型仓库
+
+   model_zoo.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 说明
+
+   notes/contribution_guide.md
+   notes/projects.md
+   notes/faq.md
+   notes/compatibility.md
+
+.. toctree::
+   :maxdepth: 1
+   :caption: 文章
+
+   article.md
+
+.. toctree::
+   :caption: 语言切换
+
+   switch_language.md
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

docs/zh_cn/make.bat

+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/zh_cn/migration/api_and_registry_migration.md

+# 将 API 和注册器从 MMDetection 2.x 迁移至 3.x

docs/zh_cn/migration/config_migration.md

+# 将配置文件从 MMDetection 2.x 迁移至 3.x
+
+MMDetection 3.x 的配置文件与 2.x 相比有较大变化，这篇文档将介绍如何将 2.x 的配置文件迁移到 3.x。
+
+在前面的[配置文件教程](../user_guides/config.md)中，我们以 Mask R-CNN 为例介绍了 MMDetection 3.x 的配置文件结构，这里我们将按同样的结构介绍如何将 2.x 的配置文件迁移至 3.x。
+
+## 模型配置
+
+模型的配置与 2.x 相比并没有太大变化，对于模型的 backbone，neck，head，以及 train_cfg 和 test_cfg，它们的参数与 2.x 版本的参数保持一致。
+
+不同的是，我们在 3.x 版本的模型中新增了 `DataPreprocessor` 模块。
+`DataPreprocessor` 模块的配置位于 `model.data_preprocessor` 中，它用于对输入数据进行预处理，例如对输入图像进行归一化，将不同大小的图片进行 padding 从而组成 batch，将图像从内存中读取到显存中等。这部分配置取代了原本存在于 train_pipeline 和 test_pipeline 中的 `Normalize` 和 `Pad`。
+
+<table class="docutils">
+<tr>
+<td>原配置</td>
+<td>
+
+```python
+# 图像归一化参数
+img_norm_cfg = dict(
+    mean=[123.675, 116.28, 103.53],
+    std=[58.395, 57.12, 57.375],
+    to_rgb=True)
+pipeline=[
+    ...,
+    dict(type='Normalize', **img_norm_cfg),
+    dict(type='Pad', size_divisor=32),  # 图像 padding 到 32 的倍数
+    ...
+]
+```
+
+</td>
+<tr>
+<td>新配置</td>
+<td>
+
+```python
+model = dict(
+    data_preprocessor=dict(
+        type='DetDataPreprocessor',
+        # 图像归一化参数
+        mean=[123.675, 116.28, 103.53],
+        std=[58.395, 57.12, 57.375],
+        bgr_to_rgb=True,
+        # 图像 padding 参数
+        pad_mask=True,  # 在实例分割中，需要将 mask 也进行 padding
+        pad_size_divisor=32)  # 图像 padding 到 32 的倍数
+)
+```
+
+</td>
+</tr>
+</table>
+
+## 数据集和评测器配置
+
+数据集和评测部分的配置相比 2.x 版本有较大的变化。我们将从 Dataloader 和 Dataset，Data transform pipeline，以及评测器配置三个方面介绍如何将 2.x 版本的配置迁移到 3.x 版本。
+
+### Dataloader 和 Dataset 配置
+
+在新版本中，我们将数据加载的设置与 PyTorch 官方的 DataLoader 保持一致，这样可以使用户更容易理解和上手。
+我们将训练、验证和测试的数据加载设置分别放在 `train_dataloader`，`val_dataloader` 和 `test_dataloader` 中，用户可以分别对这些 dataloader 设置不同的参数，其输入参数与 [PyTorch 的 Dataloader](https://pytorch.org/docs/stable/data.html?highlight=dataloader#torch.utils.data.DataLoader) 所需要的参数基本一致。
+
+通过这种方式，我们将 2.x 版本中不可配置的 `sampler`，`batch_sampler`，`persistent_workers` 等参数都放到了配置文件中，使得用户可以更加灵活地设置数据加载的参数。
+
+用户可以通过 `train_dataloader.dataset`，`val_dataloader.dataset` 和 `test_dataloader.dataset` 来设置数据集的配置，它们分别对应 2.x 版本中的 `data.train`，`data.val` 和 `data.test`。
+
+<table class="docutils">
+<tr>
+<td>原配置</td>
+<td>
+
+```python
+data = dict(
+    samples_per_gpu=2,
+    workers_per_gpu=2,
+    train=dict(
+        type=dataset_type,
+        ann_file=data_root + 'annotations/instances_train2017.json',
+        img_prefix=data_root + 'train2017/',
+        pipeline=train_pipeline),
+    val=dict(
+        type=dataset_type,
+        ann_file=data_root + 'annotations/instances_val2017.json',
+        img_prefix=data_root + 'val2017/',
+        pipeline=test_pipeline),
+    test=dict(
+        type=dataset_type,
+        ann_file=data_root + 'annotations/instances_val2017.json',
+        img_prefix=data_root + 'val2017/',
+        pipeline=test_pipeline))
+```
+
+</td>
+<tr>
+<td>新配置</td>
+<td>
+
+```python
+train_dataloader = dict(
+    batch_size=2,
+    num_workers=2,
+    persistent_workers=True,  # 避免每次迭代后 dataloader 重新创建子进程
+    sampler=dict(type='DefaultSampler', shuffle=True),  # 默认的 sampler，同时支持分布式训练和非分布式训练
+    batch_sampler=dict(type='AspectRatioBatchSampler'),  # 默认的 batch_sampler，用于保证 batch 中的图片具有相似的长宽比，从而可以更好地利用显存
+    dataset=dict(
+        type=dataset_type,
+        data_root=data_root,
+        ann_file='annotations/instances_train2017.json',
+        data_prefix=dict(img='train2017/'),
+        filter_cfg=dict(filter_empty_gt=True, min_size=32),
+        pipeline=train_pipeline))
+# 在 3.x 版本中可以独立配置验证和测试的 dataloader
+val_dataloader = dict(
+    batch_size=1,
+    num_workers=2,
+    persistent_workers=True,
+    drop_last=False,
+    sampler=dict(type='DefaultSampler', shuffle=False),
+    dataset=dict(
+        type=dataset_type,
+        data_root=data_root,
+        ann_file='annotations/instances_val2017.json',
+        data_prefix=dict(img='val2017/'),
+        test_mode=True,
+        pipeline=test_pipeline))
+test_dataloader = val_dataloader  # 测试 dataloader 的配置与验证 dataloader 的配置相同，这里省略
+```
+
+</td>
+</tr>
+</table>
+
+### Data transform pipeline 配置
+
+上文中提到，我们将图像 normalize 和 padding 的配置从 `train_pipeline` 和 `test_pipeline` 中独立出来，放到了 `model.data_preprocessor` 中，因此在 3.x 版本的 pipeline 中，我们不再需要 `Normalize` 和 `Pad` 这两个 transform。
+
+同时，我们也对负责数据格式打包的 transform 进行了重构，将 `Collect` 和 `DefaultFormatBundle` 这两个 transform 合并为了 `PackDetInputs`，它负责将 data pipeline 中的数据打包成模型的输入格式，关于输入格式的转换，详见[数据流文档](../advanced_guides/data_flow.md)。
+
+下面以 Mask R-CNN 1x 的 train_pipeline 为例，介绍如何将 2.x 版本的配置迁移到 3.x 版本：
+
+<table class="docutils">
+<tr>
+<td>原配置</td>
+<td>
+
+```python
+img_norm_cfg = dict(
+    mean=[123.675, 116.28, 103.53], std=[58.395, 57.12, 57.375], to_rgb=True)
+train_pipeline = [
+    dict(type='LoadImageFromFile'),
+    dict(type='LoadAnnotations', with_bbox=True),
+    dict(type='Resize', img_scale=(1333, 800), keep_ratio=True),
+    dict(type='RandomFlip', flip_ratio=0.5),
+    dict(type='Normalize', **img_norm_cfg),
+    dict(type='Pad', size_divisor=32),
+    dict(type='DefaultFormatBundle'),
+    dict(type='Collect', keys=['img', 'gt_bboxes', 'gt_labels']),
+]
+```
+
+</td>
+<tr>
+<td>新配置</td>
+<td>
+
+```python
+train_pipeline = [
+    dict(type='LoadImageFromFile'),
+    dict(type='LoadAnnotations', with_bbox=True),
+    dict(type='Resize', scale=(1333, 800), keep_ratio=True),
+    dict(type='RandomFlip', prob=0.5),
+    dict(type='PackDetInputs')
+]
+```
+
+</td>
+</tr>
+</table>
+
+对于 test_pipeline，除了将 `Normalize` 和 `Pad` 这两个 transform 去掉之外，我们也将测试时的数据增强（TTA）与普通的测试流程分开，移除了 `MultiScaleFlipAug`。关于新版的 TTA 如何使用，详见[TTA 文档](../advanced_guides/tta.md)。
+
+下面同样以 Mask R-CNN 1x 的 test_pipeline 为例，介绍如何将 2.x 版本的配置迁移到 3.x 版本：
+
+<table class="docutils">
+<tr>
+<td>原配置</td>
+<td>
+
+```python
+test_pipeline = [
+    dict(type='LoadImageFromFile'),
+    dict(
+        type='MultiScaleFlipAug',
+        img_scale=(1333, 800),
+        flip=False,
+        transforms=[
+            dict(type='Resize', keep_ratio=True),
+            dict(type='RandomFlip'),
+            dict(type='Normalize', **img_norm_cfg),
+            dict(type='Pad', size_divisor=32),
+            dict(type='ImageToTensor', keys=['img']),
+            dict(type='Collect', keys=['img']),
+        ])
+]
+```
+
+</td>
+<tr>
+<td>新配置</td>
+<td>
+
+```python
+test_pipeline = [
+    dict(type='LoadImageFromFile'),
+    dict(type='Resize', scale=(1333, 800), keep_ratio=True),
+    dict(
+        type='PackDetInputs',
+        meta_keys=('img_id', 'img_path', 'ori_shape', 'img_shape',
+                   'scale_factor'))
+]
+```
+
+</td>
+</tr>
+</table>
+
+除此之外，我们还对一些数据增强进行了重构，下表列出了 2.x 版本中的 transform 与 3.x 版本中的 transform 的对应关系：
+
+<table class="docutils">
+<thead>
+  <tr>
+    <th>名称</th>
+    <th>原配置</th>
+    <th>新配置</th>
+  </tr>
+</thead>
+<tbody>
+  <tr>
+    <td>Resize</td>
+<td>
+
+```python
+dict(type='Resize',
+     img_scale=(1333, 800),
+     keep_ratio=True)
+```
+
+</td>
+
+<td>
+
+```python
+dict(type='Resize',
+     scale=(1333, 800),
+     keep_ratio=True)
+```
+
+</td>
+  </tr>
+  <tr>
+    <td>RandomResize</td>
+<td>
+
+```python
+dict(
+    type='Resize',
+    img_scale=[
+        (1333, 640), (1333, 800)],
+    multiscale_mode='range',
+    keep_ratio=True)
+```
+
+</td>
+<td>
+
+```python
+dict(
+    type='RandomResize',
+    scale=[
+        (1333, 640), (1333, 800)],
+    keep_ratio=True)
+```
+
+</td>
+  </tr>
+  <tr>
+    <td>RandomChoiceResize</td>
+<td>
+
+```python
+dict(
+    type='Resize',
+    img_scale=[
+        (1333, 640), (1333, 672),
+        (1333, 704), (1333, 736),
+        (1333, 768), (1333, 800)],
+    multiscale_mode='value',
+    keep_ratio=True)
+```
+
+</td>
+<td>
+
+```python
+dict(
+    type='RandomChoiceResize',
+    scales=[
+        (1333, 640), (1333, 672),
+        (1333, 704), (1333, 736),
+        (1333, 768), (1333, 800)],
+    keep_ratio=True)
+```
+
+</td>
+  </tr>
+
+<tr>
+    <td>RandomFlip</td>
+<td>
+
+```python
+dict(type='RandomFlip',
+     flip_ratio=0.5)
+```
+
+</td>
+<td>
+
+```python
+dict(type='RandomFlip',
+     prob=0.5)
+```
+
+</td>
+  </tr>
+
+</tbody>
+</table>
+
+### 评测器配置
+
+在 3.x 版本中，模型精度评测不再与数据集绑定，而是通过评测器（Evaluator）来完成。
+评测器配置分为 val_evaluator 和 test_evaluator 两部分，其中 val_evaluator 用于验证集评测，test_evaluator 用于测试集评测，对应 2.x 版本中的 evaluation 字段。
+下表列出了 2.x 版本与 3.x 版本中的评测器的对应关系：
+
+<table class="docutils">
+<thead>
+  <tr>
+    <th>评测指标名称</th>
+    <th>原配置</th>
+    <th>新配置</th>
+  </tr>
+</thead>
+<tbody>
+  <tr>
+    <td>COCO</td>
+<td>
+
+```python
+data = dict(
+    val=dict(
+        type='CocoDataset',
+        ann_file=data_root + 'annotations/instances_val2017.json'))
+evaluation = dict(metric=['bbox', 'segm'])
+```
+
+</td>
+
+<td>
+
+```python
+val_evaluator = dict(
+    type='CocoMetric',
+    ann_file=data_root + 'annotations/instances_val2017.json',
+    metric=['bbox', 'segm'],
+    format_only=False)
+```
+
+</td>
+  </tr>
+  <tr>
+    <td>Pascal VOC</td>
+<td>
+
+```python
+data = dict(
+    val=dict(
+        type=dataset_type,
+        ann_file=data_root + 'VOC2007/ImageSets/Main/test.txt'))
+evaluation = dict(metric='mAP')
+```
+
+</td>
+<td>
+
+```python
+val_evaluator = dict(
+    type='VOCMetric',
+    metric='mAP',
+    eval_mode='11points')
+```
+
+</td>
+  </tr>
+  <tr>
+    <td>OpenImages</td>
+<td>
+
+```python
+data = dict(
+    val=dict(
+        type='OpenImagesDataset',
+        ann_file=data_root + 'annotations/validation-annotations-bbox.csv',
+        img_prefix=data_root + 'OpenImages/validation/',
+        label_file=data_root + 'annotations/class-descriptions-boxable.csv',
+        hierarchy_file=data_root +
+        'annotations/bbox_labels_600_hierarchy.json',
+        meta_file=data_root + 'annotations/validation-image-metas.pkl',
+        image_level_ann_file=data_root +
+        'annotations/validation-annotations-human-imagelabels-boxable.csv'))
+evaluation = dict(interval=1, metric='mAP')
+```
+
+</td>
+<td>
+
+```python
+val_evaluator = dict(
+    type='OpenImagesMetric',
+    iou_thrs=0.5,
+    ioa_thrs=0.5,
+    use_group_of=True,
+    get_supercategory=True)
+```
+
+</td>
+  </tr>
+
+<tr>
+    <td>CityScapes</td>
+<td>
+
+```python
+data = dict(
+    val=dict(
+        type='CityScapesDataset',
+        ann_file=data_root +
+        'annotations/instancesonly_filtered_gtFine_val.json',
+        img_prefix=data_root + 'leftImg8bit/val/',
+        pipeline=test_pipeline))
+evaluation = dict(metric=['bbox', 'segm'])
+```
+
+</td>
+<td>
+
+```python
+val_evaluator = [
+    dict(
+        type='CocoMetric',
+        ann_file=data_root +
+        'annotations/instancesonly_filtered_gtFine_val.json',
+        metric=['bbox', 'segm']),
+    dict(
+        type='CityScapesMetric',
+        ann_file=data_root +
+        'annotations/instancesonly_filtered_gtFine_val.json',
+        seg_prefix=data_root + '/gtFine/val',
+        outfile_prefix='./work_dirs/cityscapes_metric/instance')
+]
+```
+
+</td>
+  </tr>
+
+</tbody>
+</table>
+
+## 训练和测试的配置
+
+<table class="docutils">
+<tr>
+<td>原配置</td>
+<td>
+
+```python
+runner = dict(
+    type='EpochBasedRunner',  # 训练循环的类型
+    max_epochs=12)  # 最大训练轮次
+evaluation = dict(interval=2)  # 验证间隔。每 2 个 epoch 验证一次
+```
+
+</td>
+<tr>
+<td>新配置</td>
+<td>
+
+```python
+train_cfg = dict(
+    type='EpochBasedTrainLoop',  # 训练循环的类型，请参考 https://github.com/open-mmlab/mmengine/blob/main/mmengine/runner/loops.py
+    max_epochs=12,  # 最大训练轮次
+    val_interval=2)  # 验证间隔。每 2 个 epoch 验证一次
+val_cfg = dict(type='ValLoop')  # 验证循环的类型
+test_cfg = dict(type='TestLoop')  # 测试循环的类型
+```
+
+</td>
+</tr>
+</table>
+
+## 优化相关配置
+
+优化器以及梯度裁剪的配置都移至 optim_wrapper 字段中。下表列出了 2.x 版本与 3.x 版本中的优化器配置的对应关系：
+
+<table class="docutils">
+<tr>
+<td>原配置</td>
+<td>
+
+```python
+optimizer = dict(
+    type='SGD',  # 随机梯度下降优化器
+    lr=0.02,  # 基础学习率
+    momentum=0.9,  # 带动量的随机梯度下降
+    weight_decay=0.0001)  # 权重衰减
+optimizer_config = dict(grad_clip=None)  # 梯度裁剪的配置，设置为 None 关闭梯度裁剪
+```
+
+</td>
+<tr>
+<td>新配置</td>
+<td>
+
+```python
+optim_wrapper = dict(  # 优化器封装的配置
+    type='OptimWrapper',  # 优化器封装的类型。可以切换至 AmpOptimWrapper 来启用混合精度训练
+    optimizer=dict(  # 优化器配置。支持 PyTorch 的各种优化器。请参考 https://pytorch.org/docs/stable/optim.html#algorithms
+        type='SGD',  # 随机梯度下降优化器
+        lr=0.02,  # 基础学习率
+        momentum=0.9,  # 带动量的随机梯度下降
+        weight_decay=0.0001),  # 权重衰减
+    clip_grad=None,  # 梯度裁剪的配置，设置为 None 关闭梯度裁剪。使用方法请见 https://mmengine.readthedocs.io/en/latest/tutorials/optimizer.html
+    )
+```
+
+</td>
+</tr>
+</table>
+
+学习率的配置也从 lr_config 字段中移至 param_scheduler 字段中。param_scheduler 的配置更贴近 PyTorch 的学习率调整策略，更加灵活。下表列出了 2.x 版本与 3.x 版本中的学习率配置的对应关系：
+
+<table class="docutils">
+<tr>
+<td>原配置</td>
+<td>
+
+```python
+lr_config = dict(
+    policy='step',  # 在训练过程中使用 multi step 学习率策略
+    warmup='linear',  # 使用线性学习率预热
+    warmup_iters=500,  # 到第 500 个 iteration 结束预热
+    warmup_ratio=0.001,  # 学习率预热的系数
+    step=[8, 11],  # 在哪几个 epoch 进行学习率衰减
+    gamma=0.1)  # 学习率衰减系数
+```
+
+</td>
+<tr>
+<td>新配置</td>
+<td>
+
+```python
+param_scheduler = [
+    dict(
+        type='LinearLR',  # 使用线性学习率预热
+        start_factor=0.001, # 学习率预热的系数
+        by_epoch=False,  # 按 iteration 更新预热学习率
+        begin=0,  # 从第一个 iteration 开始
+        end=500),  # 到第 500 个 iteration 结束
+    dict(
+        type='MultiStepLR',  # 在训练过程中使用 multi step 学习率策略
+        by_epoch=True,  # 按 epoch 更新学习率
+        begin=0,   # 从第一个 epoch 开始
+        end=12,  # 到第 12 个 epoch 结束
+        milestones=[8, 11],  # 在哪几个 epoch 进行学习率衰减
+        gamma=0.1)  # 学习率衰减系数
+]
+```
+
+</td>
+</tr>
+</table>
+
+关于其他的学习率调整策略的迁移，请参考 MMEngine 的[学习率迁移文档](https://mmengine.readthedocs.io/zh_CN/latest/migration/param_scheduler.html)。
+
+## 其他配置的迁移
+
+### 保存 checkpoint 的配置
+
+<table class="docutils">
+<thead>
+  <tr>
+    <th>功能</th>
+    <th>原配置</th>
+    <th>新配置</th>
+  </tr>
+</thead>
+<tbody>
+  <tr>
+    <td>设置保存间隔</td>
+<td>
+
+```python
+checkpoint_config = dict(
+    interval=1)
+```
+
+</td>
+
+<td>
+
+```python
+default_hooks = dict(
+    checkpoint=dict(
+        type='CheckpointHook',
+        interval=1))
+```
+
+</td>
+  </tr>
+
+<tr>
+    <td>保存最佳模型</td>
+<td>
+
+```python
+evaluation = dict(
+    save_best='auto')
+```
+
+</td>
+<td>
+
+```python
+default_hooks = dict(
+    checkpoint=dict(
+        type='CheckpointHook',
+        save_best='auto'))
+```
+
+</td>
+  </tr>
+
+<tr>
+    <td>只保留最新的几个模型</td>
+<td>
+
+```python
+checkpoint_config = dict(
+    max_keep_ckpts=3)
+```
+
+</td>
+<td>
+
+```python
+default_hooks = dict(
+    checkpoint=dict(
+        type='CheckpointHook',
+        max_keep_ckpts=3))
+```
+
+</td>
+  </tr>
+
+</tbody>
+</table>
+
+### 日志的配置
+
+3.x 版本中，日志的打印和可视化由 MMEngine 中的 logger 和 visualizer 分别完成。下表列出了 2.x 版本与 3.x 版本中的日志配置的对应关系：
+
+<table class="docutils">
+<thead>
+  <tr>
+    <th>功能</th>
+    <th>原配置</th>
+    <th>新配置</th>
+  </tr>
+</thead>
+<tbody>
+  <tr>
+    <td>设置日志打印间隔</td>
+<td>
+
+```python
+log_config = dict(
+    interval=50)
+```
+
+</td>
+
+<td>
+
+```python
+default_hooks = dict(
+    logger=dict(
+        type='LoggerHook',
+        interval=50))
+# 可选： 配置日志打印数值的平滑窗口大小
+log_processor = dict(
+    type='LogProcessor',
+    window_size=50)
+```
+
+</td>
+  </tr>
+
+<tr>
+    <td>使用 TensorBoard 或 WandB 可视化日志</td>
+<td>
+
+```python
+log_config = dict(
+    interval=50,
+    hooks=[
+        dict(type='TextLoggerHook'),
+        dict(type='TensorboardLoggerHook'),
+        dict(type='MMDetWandbHook',
+             init_kwargs={
+                'project': 'mmdetection',
+                'group': 'maskrcnn-r50-fpn-1x-coco'
+             },
+             interval=50,
+             log_checkpoint=True,
+             log_checkpoint_metadata=True,
+             num_eval_images=100)
+    ])
+```
+
+</td>
+<td>
+
+```python
+vis_backends = [
+    dict(type='LocalVisBackend'),
+    dict(type='TensorboardVisBackend'),
+    dict(type='WandbVisBackend',
+         init_kwargs={
+            'project': 'mmdetection',
+            'group': 'maskrcnn-r50-fpn-1x-coco'
+         })
+]
+visualizer = dict(
+    type='DetLocalVisualizer', vis_backends=vis_backends, name='visualizer')
+```
+
+</td>
+  </tr>
+
+</tbody>
+</table>
+
+关于可视化相关的教程，请参考 MMDetection 的[可视化教程](../user_guides/visualization.md)。
+
+### Runtime 的配置
+
+3.x 版本中 runtime 的配置字段有所调整，具体的对应关系如下：
+
+<table class="docutils">
+<thead>
+  <tr>
+    <th>原配置</th>
+    <th>新配置</th>
+  </tr>
+</thead>
+<tbody>
+
+<tr>
+<td>
+
+```python
+cudnn_benchmark = False
+opencv_num_threads = 0
+mp_start_method = 'fork'
+dist_params = dict(backend='nccl')
+log_level = 'INFO'
+load_from = None
+resume_from = None
+
+
+```
+
+</td>
+<td>
+
+```python
+env_cfg = dict(
+    cudnn_benchmark=False,
+    mp_cfg=dict(mp_start_method='fork',
+                opencv_num_threads=0),
+    dist_cfg=dict(backend='nccl'))
+log_level = 'INFO'
+load_from = None
+resume = False
+```
+
+</td>
+  </tr>
+
+</tbody>
+</table>

docs/zh_cn/migration/dataset_migration.md

+# 将数据集从 MMDetection 2.x 迁移至 3.x

docs/zh_cn/migration/migration.md

+# 从 MMDetection 2.x 迁移至 3.x
+
+MMDetection 3.x 版本是一个重大更新，包含了许多 API 和配置文件的变化。本文档旨在帮助用户从 MMDetection 2.x 版本迁移到 3.x 版本。
+我们将迁移指南分为以下几个部分：
+
+- [配置文件迁移](./config_migration.md)
+- [API 和 Registry 迁移](./api_and_registry_migration.md)
+- [数据集迁移](./dataset_migration.md)
+- [模型迁移](./model_migration.md)
+- [常见问题](./migration_faq.md)
+
+如果您在迁移过程中遇到任何问题，欢迎在 issue 中提出。我们也欢迎您为本文档做出贡献。

docs/zh_cn/migration/migration_faq.md

+# 迁移 FAQ

docs/zh_cn/migration/model_migration.md

+# 将模型从 MMDetection 2.x 迁移至 3.x

docs/zh_cn/model_zoo.md

+# 模型库
+
+## 镜像地址
+
+从 MMDetection V2.0 起，我们只通过阿里云维护模型库。V1.x 版本的模型已经弃用。
+
+## 共同设置
+
+- 所有模型都是在 `coco_2017_train` 上训练，在 `coco_2017_val` 上测试。
+- 我们使用分布式训练。
+- 所有 pytorch-style 的 ImageNet 预训练主干网络来自 PyTorch 的模型库，caffe-style 的预训练主干网络来自 detectron2 最新开源的模型。
+- 为了与其他代码库公平比较，文档中所写的 GPU 内存是8个 GPU 的 `torch.cuda.max_memory_allocated()` 的最大值，此值通常小于 nvidia-smi 显示的值。
+- 我们以网络 forward 和后处理的时间加和作为推理时间，不包含数据加载时间。所有结果通过 [benchmark.py](https://github.com/open-mmlab/mmdetection/blob/main/tools/analysis_tools/benchmark.py) 脚本计算所得。该脚本会计算推理 2000 张图像的平均时间。
+
+## ImageNet 预训练模型
+
+通过 ImageNet 分类任务预训练的主干网络进行初始化是很常见的操作。所有预训练模型的链接都可以在 [open_mmlab](https://github.com/open-mmlab/mmcv/blob/master/mmcv/model_zoo/open_mmlab.json) 中找到。根据 `img_norm_cfg` 和原始权重，我们可以将所有 ImageNet 预训练模型分为以下几种情况：
+
+- TorchVision：torchvision 模型权重，包含 ResNet50, ResNet101。`img_norm_cfg` 为 `dict(mean=[123.675, 116.28, 103.53], std=[58.395, 57.12, 57.375], to_rgb=True)`。
+- Pycls：[pycls](https://github.com/facebookresearch/pycls) 模型权重，包含 RegNetX。`img_norm_cfg` 为 `dict(   mean=[103.530, 116.280, 123.675], std=[57.375, 57.12, 58.395], to_rgb=False)`。
+- MSRA styles：[MSRA](https://github.com/KaimingHe/deep-residual-networks) 模型权重，包含 ResNet50_Caffe，ResNet101_Caffe。`img_norm_cfg` 为 `dict(   mean=[103.530, 116.280, 123.675], std=[1.0, 1.0, 1.0], to_rgb=False)`。
+- Caffe2 styles：现阶段只包含 ResNext101_32x8d。`img_norm_cfg` 为 `dict(mean=[103.530, 116.280, 123.675], std=[57.375, 57.120, 58.395], to_rgb=False)`。
+- Other styles: SSD 的 `img_norm_cfg` 为 `dict(mean=[123.675, 116.28, 103.53], std=[1, 1, 1], to_rgb=True)`，YOLOv3 的 `img_norm_cfg` 为 `dict(mean=[0, 0, 0], std=[255., 255., 255.], to_rgb=True)`。
+
+MMdetection 常用到的主干网络细节如下表所示：
+
+| 模型             | 来源        | 链接                                                                                                                                                                                                | 描述                                                                                                                                                                                                                       |
+| ---------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ResNet50         | TorchVision | [torchvision 中的 ResNet-50](https://download.pytorch.org/models/resnet50-19c8e357.pth)                                                                                                             | 来自 [torchvision 中的 ResNet-50](https://download.pytorch.org/models/resnet50-19c8e357.pth)。                                                                                                                             |
+| ResNet101        | TorchVision | [torchvision 中的 ResNet-101](https://download.pytorch.org/models/resnet101-5d3b4d8f.pth)                                                                                                           | 来自 [torchvision 中的 ResNet-101](https://download.pytorch.org/models/resnet101-5d3b4d8f.pth)。                                                                                                                           |
+| RegNetX          | Pycls       | [RegNetX_3.2gf](https://download.openmmlab.com/pretrain/third_party/regnetx_3.2gf-c2599b0f.pth)，[RegNetX_800mf](https://download.openmmlab.com/pretrain/third_party/regnetx_800mf-1f4be4c7.pth) 等 | 来自 [pycls](https://github.com/facebookresearch/pycls)。                                                                                                                                                                  |
+| ResNet50_Caffe   | MSRA        | [MSRA 中的 ResNet-50](https://download.openmmlab.com/pretrain/third_party/resnet50_caffe-788b5fa3.pth)                                                                                              | 由 [Detectron2 中的 R-50.pkl](https://dl.fbaipublicfiles.com/detectron2/ImageNetPretrained/MSRA/R-50.pkl) 转化的副本。原始权重文件来自 [MSRA 中的原始 ResNet-50](https://github.com/KaimingHe/deep-residual-networks)。    |
+| ResNet101_Caffe  | MSRA        | [MSRA 中的 ResNet-101](https://download.openmmlab.com/pretrain/third_party/resnet101_caffe-3ad79236.pth)                                                                                            | 由 [Detectron2 中的 R-101.pkl](https://dl.fbaipublicfiles.com/detectron2/ImageNetPretrained/MSRA/R-101.pkl) 转化的副本。原始权重文件来自 [MSRA 中的原始 ResNet-101](https://github.com/KaimingHe/deep-residual-networks)。 |
+| ResNext101_32x8d | Caffe2      | [Caffe2 ResNext101_32x8d](https://download.openmmlab.com/pretrain/third_party/resnext101_32x8d-1516f1aa.pth)                                                                                        | 由 [Detectron2 中的 X-101-32x8d.pkl](https://dl.fbaipublicfiles.com/detectron2/ImageNetPretrained/FAIR/X-101-32x8d.pkl) 转化的副本。原始 ResNeXt-101-32x8d 由 FB 使用 Caffe2 训练。                                        |
+
+## Baselines
+
+### RPN
+
+请参考 [RPN](https://github.com/open-mmlab/mmdetection/blob/main/configs/rpn)。
+
+### Faster R-CNN
+
+请参考 [Faster R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/faster_rcnn)。
+
+### Mask R-CNN
+
+请参考 [Mask R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/mask_rcnn)。
+
+### Fast R-CNN (使用提前计算的 proposals)
+
+请参考 [Fast R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/fast_rcnn)。
+
+### RetinaNet
+
+请参考 [RetinaNet](https://github.com/open-mmlab/mmdetection/blob/main/configs/retinanet)。
+
+### Cascade R-CNN and Cascade Mask R-CNN
+
+请参考 [Cascade R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/cascade_rcnn)。
+
+### Hybrid Task Cascade (HTC)
+
+请参考 [HTC](https://github.com/open-mmlab/mmdetection/blob/main/configs/htc)。
+
+### SSD
+
+请参考 [SSD](https://github.com/open-mmlab/mmdetection/blob/main/configs/ssd)。
+
+### Group Normalization (GN)
+
+请参考 [Group Normalization](https://github.com/open-mmlab/mmdetection/blob/main/configs/gn)。
+
+### Weight Standardization
+
+请参考 [Weight Standardization](https://github.com/open-mmlab/mmdetection/blob/main/configs/gn+ws)。
+
+### Deformable Convolution v2
+
+请参考 [Deformable Convolutional Networks](https://github.com/open-mmlab/mmdetection/blob/main/configs/dcn)。
+
+### CARAFE: Content-Aware ReAssembly of FEatures
+
+请参考 [CARAFE](https://github.com/open-mmlab/mmdetection/blob/main/configs/carafe)。
+
+### Instaboost
+
+请参考 [Instaboost](https://github.com/open-mmlab/mmdetection/blob/main/configs/instaboost)。
+
+### Libra R-CNN
+
+请参考 [Libra R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/libra_rcnn)。
+
+### Guided Anchoring
+
+请参考 [Guided Anchoring](https://github.com/open-mmlab/mmdetection/blob/main/configs/guided_anchoring)。
+
+### FCOS
+
+请参考 [FCOS](https://github.com/open-mmlab/mmdetection/blob/main/configs/fcos)。
+
+### FoveaBox
+
+请参考 [FoveaBox](https://github.com/open-mmlab/mmdetection/blob/main/configs/foveabox)。
+
+### RepPoints
+
+请参考 [RepPoints](https://github.com/open-mmlab/mmdetection/blob/main/configs/reppoints)。
+
+### FreeAnchor
+
+请参考 [FreeAnchor](https://github.com/open-mmlab/mmdetection/blob/main/configs/free_anchor)。
+
+### Grid R-CNN (plus)
+
+请参考 [Grid R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/grid_rcnn)。
+
+### GHM
+
+请参考 [GHM](https://github.com/open-mmlab/mmdetection/blob/main/configs/ghm)。
+
+### GCNet
+
+请参考 [GCNet](https://github.com/open-mmlab/mmdetection/blob/main/configs/gcnet)。
+
+### HRNet
+
+请参考 [HRNet](https://github.com/open-mmlab/mmdetection/blob/main/configs/hrnet)。
+
+### Mask Scoring R-CNN
+
+请参考 [Mask Scoring R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/ms_rcnn)。
+
+### Train from Scratch
+
+请参考 [Rethinking ImageNet Pre-training](https://github.com/open-mmlab/mmdetection/blob/main/configs/scratch)。
+
+### NAS-FPN
+
+请参考 [NAS-FPN](https://github.com/open-mmlab/mmdetection/blob/main/configs/nas_fpn)。
+
+### ATSS
+
+请参考 [ATSS](https://github.com/open-mmlab/mmdetection/blob/main/configs/atss)。
+
+### FSAF
+
+请参考 [FSAF](https://github.com/open-mmlab/mmdetection/blob/main/configs/fsaf)。
+
+### RegNetX
+
+请参考 [RegNet](https://github.com/open-mmlab/mmdetection/blob/main/configs/regnet)。
+
+### Res2Net
+
+请参考 [Res2Net](https://github.com/open-mmlab/mmdetection/blob/main/configs/res2net)。
+
+### GRoIE
+
+请参考 [GRoIE](https://github.com/open-mmlab/mmdetection/blob/main/configs/groie)。
+
+### Dynamic R-CNN
+
+请参考 [Dynamic R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/dynamic_rcnn)。
+
+### PointRend
+
+请参考 [PointRend](https://github.com/open-mmlab/mmdetection/blob/main/configs/point_rend)。
+
+### DetectoRS
+
+请参考 [DetectoRS](https://github.com/open-mmlab/mmdetection/blob/main/configs/detectors)。
+
+### Generalized Focal Loss
+
+请参考 [Generalized Focal Loss](https://github.com/open-mmlab/mmdetection/blob/main/configs/gfl)。
+
+### CornerNet
+
+请参考 [CornerNet](https://github.com/open-mmlab/mmdetection/blob/main/configs/cornernet)。
+
+### YOLOv3
+
+请参考 [YOLOv3](https://github.com/open-mmlab/mmdetection/blob/main/configs/yolo)。
+
+### PAA
+
+请参考 [PAA](https://github.com/open-mmlab/mmdetection/blob/main/configs/paa)。
+
+### SABL
+
+请参考 [SABL](https://github.com/open-mmlab/mmdetection/blob/main/configs/sabl)。
+
+### CentripetalNet
+
+请参考 [CentripetalNet](https://github.com/open-mmlab/mmdetection/blob/main/configs/centripetalnet)。
+
+### ResNeSt
+
+请参考 [ResNeSt](https://github.com/open-mmlab/mmdetection/blob/main/configs/resnest)。
+
+### DETR
+
+请参考 [DETR](https://github.com/open-mmlab/mmdetection/blob/main/configs/detr)。
+
+### Deformable DETR
+
+请参考 [Deformable DETR](https://github.com/open-mmlab/mmdetection/blob/main/configs/deformable_detr)。
+
+### AutoAssign
+
+请参考 [AutoAssign](https://github.com/open-mmlab/mmdetection/blob/main/configs/autoassign)。
+
+### YOLOF
+
+请参考 [YOLOF](https://github.com/open-mmlab/mmdetection/blob/main/configs/yolof)。
+
+### Seesaw Loss
+
+请参考 [Seesaw Loss](https://github.com/open-mmlab/mmdetection/blob/main/configs/seesaw_loss)。
+
+### CenterNet
+
+请参考 [CenterNet](https://github.com/open-mmlab/mmdetection/blob/main/configs/centernet)。
+
+### YOLOX
+
+请参考 [YOLOX](https://github.com/open-mmlab/mmdetection/blob/main/configs/yolox)。
+
+### PVT
+
+请参考 [PVT](https://github.com/open-mmlab/mmdetection/blob/main/configs/pvt)。
+
+### SOLO
+
+请参考 [SOLO](https://github.com/open-mmlab/mmdetection/blob/main/configs/solo)。
+
+### QueryInst
+
+请参考 [QueryInst](https://github.com/open-mmlab/mmdetection/blob/main/configs/queryinst)。
+
+### Other datasets
+
+我们还在 [PASCAL VOC](https://github.com/open-mmlab/mmdetection/blob/main/configs/pascal_voc)，[Cityscapes](https://github.com/open-mmlab/mmdetection/blob/main/configs/cityscapes) 和 [WIDER FACE](https://github.com/open-mmlab/mmdetection/blob/main/configs/wider_face) 上对一些方法进行了基准测试。
+
+### Pre-trained Models
+
+我们还通过多尺度训练和更长的训练策略来训练用 ResNet-50 和 [RegNetX-3.2G](https://github.com/open-mmlab/mmdetection/blob/main/configs/regnet) 作为主干网络的 [Faster R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/faster_rcnn) 和 [Mask R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/mask_rcnn)。这些模型可以作为下游任务的预训练模型。
+
+## 速度基准
+
+### 训练速度基准
+
+我们提供 [analyze_logs.py](https://github.com/open-mmlab/mmdetection/blob/main/tools/analysis_tools/analyze_logs.py) 来得到训练中每一次迭代的平均时间。示例请参考 [Log Analysis](https://mmdetection.readthedocs.io/en/latest/useful_tools.html#log-analysis)。
+
+我们与其他流行框架的 Mask R-CNN 训练速度进行比较（数据是从 [detectron2](https://github.com/facebookresearch/detectron2/blob/main/docs/notes/benchmarks.md/) 复制而来）。在 mmdetection 中，我们使用 [mask-rcnn_r50-caffe_fpn_poly-1x_coco_v1.py](https://github.com/open-mmlab/mmdetection/blob/main/configs/mask_rcnn/mask-rcnn_r50-caffe_fpn_poly-1x_coco_v1.py) 进行基准测试。它与 detectron2 的 [mask_rcnn_R_50_FPN_noaug_1x.yaml](https://github.com/facebookresearch/detectron2/blob/main/configs/Detectron1-Comparisons/mask_rcnn_R_50_FPN_noaug_1x.yaml) 设置完全一样。同时，我们还提供了[模型权重](https://download.openmmlab.com/mmdetection/v2.0/benchmark/mask_rcnn_r50_caffe_fpn_poly_1x_coco_no_aug/mask_rcnn_r50_caffe_fpn_poly_1x_coco_no_aug_compare_20200518-10127928.pth)和[训练 log](https://download.openmmlab.com/mmdetection/v2.0/benchmark/mask_rcnn_r50_caffe_fpn_poly_1x_coco_no_aug/mask_rcnn_r50_caffe_fpn_poly_1x_coco_no_aug_20200518_105755.log.json) 作为参考。为了跳过 GPU 预热时间，吞吐量按照100-500次迭代之间的平均吞吐量来计算。
+
+| 框架                                                                                   | 吞吐量 (img/s) |
+| -------------------------------------------------------------------------------------- | -------------- |
+| [Detectron2](https://github.com/facebookresearch/detectron2)                           | 62             |
+| [MMDetection](https://github.com/open-mmlab/mmdetection)                               | 61             |
+| [maskrcnn-benchmark](https://github.com/facebookresearch/maskrcnn-benchmark/)          | 53             |
+| [tensorpack](https://github.com/tensorpack/tensorpack/tree/master/examples/FasterRCNN) | 50             |
+| [simpledet](https://github.com/TuSimple/simpledet/)                                    | 39             |
+| [Detectron](https://github.com/facebookresearch/Detectron)                             | 19             |
+| [matterport/Mask_RCNN](https://github.com/matterport/Mask_RCNN/)                       | 14             |
+
+### 推理时间基准
+
+我们提供 [benchmark.py](https://github.com/open-mmlab/mmdetection/blob/main/tools/analysis_tools/benchmark.py) 对推理时间进行基准测试。此脚本将推理 2000 张图片并计算忽略前 5 次推理的平均推理时间。可以通过设置 `LOG-INTERVAL` 来改变 log 输出间隔（默认为 50）。
+
+```shell
+python tools/benchmark.py ${CONFIG} ${CHECKPOINT} [--log-interval $[LOG-INTERVAL]] [--fuse-conv-bn]
+```
+
+模型库中，所有模型在基准测量推理时间时都没设置 `fuse-conv-bn`, 此设置可以使推理时间更短。
+
+## 与 Detectron2 对比
+
+我们在速度和精度方面对 mmdetection 和 [Detectron2](https://github.com/facebookresearch/detectron2.git) 进行对比。对比所使用的 detectron2 的 commit id 为 [185c27e](https://github.com/facebookresearch/detectron2/tree/185c27e4b4d2d4c68b5627b3765420c6d7f5a659)(30/4/2020)。
+为了公平对比，我们所有的实验都在同一机器下进行。
+
+### 硬件
+
+- 8 NVIDIA Tesla V100 (32G) GPUs
+- Intel(R) Xeon(R) Gold 6148 CPU @ 2.40GHz
+
+### 软件环境
+
+- Python 3.7
+- PyTorch 1.4
+- CUDA 10.1
+- CUDNN 7.6.03
+- NCCL 2.4.08
+
+### 精度
+
+| 模型                                                                                                                            | 训练策略 | Detectron2                                                                                                                             | mmdetection | 下载                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Faster R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/faster_rcnn/faster-rcnn_r50-caffe_fpn_ms-1x_coco.py) | 1x       | [37.9](https://github.com/facebookresearch/detectron2/blob/main/configs/COCO-Detection/faster_rcnn_R_50_FPN_1x.yaml)                   | 38.0        | [model](https://download.openmmlab.com/mmdetection/v2.0/benchmark/faster_rcnn_r50_caffe_fpn_mstrain_1x_coco/faster_rcnn_r50_caffe_fpn_mstrain_1x_coco-5324cff8.pth) \| [log](https://download.openmmlab.com/mmdetection/v2.0/benchmark/faster_rcnn_r50_caffe_fpn_mstrain_1x_coco/faster_rcnn_r50_caffe_fpn_mstrain_1x_coco_20200429_234554.log.json)             |
+| [Mask R-CNN](https://github.com/open-mmlab/mmdetection/blob/main/configs/mask_rcnn/mask-rcnn_r50-caffe_fpn_ms-poly-1x_coco.py)  | 1x       | [38.6 & 35.2](https://github.com/facebookresearch/detectron2/blob/master/configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml) | 38.8 & 35.4 | [model](https://download.openmmlab.com/mmdetection/v2.0/benchmark/mask_rcnn_r50_caffe_fpn_mstrain-poly_1x_coco/mask_rcnn_r50_caffe_fpn_mstrain-poly_1x_coco-dbecf295.pth) \| [log](https://download.openmmlab.com/mmdetection/v2.0/benchmark/mask_rcnn_r50_caffe_fpn_mstrain-poly_1x_coco/mask_rcnn_r50_caffe_fpn_mstrain-poly_1x_coco_20200430_054239.log.json) |
+| [Retinanet](https://github.com/open-mmlab/mmdetection/blob/main/configs/retinanet/retinanet_r50-caffe_fpn_ms-1x_coco.py)        | 1x       | [36.5](https://github.com/facebookresearch/detectron2/blob/master/configs/COCO-Detection/retinanet_R_50_FPN_1x.yaml)                   | 37.0        | [model](https://download.openmmlab.com/mmdetection/v2.0/benchmark/retinanet_r50_caffe_fpn_mstrain_1x_coco/retinanet_r50_caffe_fpn_mstrain_1x_coco-586977a0.pth) \| [log](https://download.openmmlab.com/mmdetection/v2.0/benchmark/retinanet_r50_caffe_fpn_mstrain_1x_coco/retinanet_r50_caffe_fpn_mstrain_1x_coco_20200430_014748.log.json)                     |
+
+### 训练速度
+
+训练速度使用 s/iter 来度量。结果越低越好。
+
+| 模型         | Detectron2 | mmdetection |
+| ------------ | ---------- | ----------- |
+| Faster R-CNN | 0.210      | 0.216       |
+| Mask R-CNN   | 0.261      | 0.265       |
+| Retinanet    | 0.200      | 0.205       |
+
+### 推理速度
+
+推理速度通过单张 GPU 下的 fps(img/s) 来度量，越高越好。
+为了与 Detectron2 保持一致，我们所写的推理时间除去了数据加载时间。
+对于 Mask RCNN，我们去除了后处理中 RLE 编码的时间。
+我们在括号中给出了官方给出的速度。由于硬件差异，官方给出的速度会比我们所测试得到的速度快一些。
+
+| 模型         | Detectron2  | mmdetection |
+| ------------ | ----------- | ----------- |
+| Faster R-CNN | 25.6 (26.3) | 22.2        |
+| Mask R-CNN   | 22.5 (23.3) | 19.6        |
+| Retinanet    | 17.8 (18.2) | 20.6        |
+
+### 训练内存
+
+| 模型         | Detectron2 | mmdetection |
+| ------------ | ---------- | ----------- |
+| Faster R-CNN | 3.0        | 3.8         |
+| Mask R-CNN   | 3.4        | 3.9         |
+| Retinanet    | 3.9        | 3.4         |

docs/zh_cn/notes/compatibility.md

+# MMDetection v2.x 兼容性说明
+
+## MMDetection 2.25.0
+
+为了加入 Mask2Former 实例分割模型，对 Mask2Former 的配置文件进行了重命名 [PR #7571](https://github.com/open-mmlab/mmdetection/pull/7571)：
+
+<table align="center">
+    <thead>
+        <tr align='center'>
+            <td>在 v2.25.0 之前</td>
+            <td>v2.25.0 及之后</td>
+        </tr>
+    </thead>
+    <tbody><tr valign='top'>
+    <th>
+
+```
+'mask2former_xxx_coco.py' 代表全景分割的配置文件
+```
+
+</th>
+    <th>
+
+```
+'mask2former_xxx_coco.py' 代表实例分割的配置文件
+'mask2former_xxx_coco-panoptic.py' 代表全景分割的配置文件
+```
+
+</th></tr>
+  </tbody></table>
+
+## MMDetection 2.21.0
+
+为了支持 CPU 训练，MMCV 中进行批处理的 scatter 的代码逻辑已经被修改。我们推荐使用 MMCV v1.4.4 或更高版本，
+更多信息请参考 [MMCV PR #1621](https://github.com/open-mmlab/mmcv/pull/1621).
+
+## MMDetection 2.18.1
+
+### MMCV compatibility
+
+为了修复 BaseTransformerLayer 中的权重引用问题, MultiheadAttention 中 batch first 的逻辑有所改变。
+我们推荐使用 MMCV v1.3.17 或更高版本。 更多信息请参考 [MMCV PR #1418](https://github.com/open-mmlab/mmcv/pull/1418) 。
+
+## MMDetection 2.18.0
+
+### DIIHead 兼容性
+
+为了支持 QueryInst，在 DIIHead 的返回元组中加入了 attn_feats。
+
+## MMDetection v2.14.0
+
+### MMCV 版本
+
+为了修复 EvalHook 优先级过低的问题，MMCV v1.3.8 中所有 hook 的优先级都重新进行了调整，因此 MMDetection v2.14.0 需要依赖最新的 MMCV v1.3.8 版本。 相关信息请参考[PR #1120](https://github.com/open-mmlab/mmcv/pull/1120) ，相关问题请参考[#5343](https://github.com/open-mmlab/mmdetection/issues/5343) 。
+
+### SSD 兼容性
+
+在 v2.14.0 中，为了使 SSD 能够被更灵活地使用，[PR #5291](https://github.com/open-mmlab/mmdetection/pull/5291) 重构了 SSD 的 backbone、neck 和 head。用户可以使用 tools/model_converters/upgrade_ssd_version.py 转换旧版本训练的模型。
+
+```shell
+python tools/model_converters/upgrade_ssd_version.py ${OLD_MODEL_PATH} ${NEW_MODEL_PATH}
+
+```
+
+- OLD_MODEL_PATH：旧版 SSD 模型的路径。
+- NEW_MODEL_PATH：保存转换后模型权重的路径。
+
+## MMDetection v2.12.0
+
+在 v2.12.0 到 v2.18.0（或以上）版本的这段时间，为了提升通用性和便捷性，MMDetection 正在进行大规模重构。在升级到 v2.12.0 后 MMDetection 不可避免地带来了一些 BC Breaking，包括 MMCV 的版本依赖、模型初始化方式、模型 registry 和 mask AP 的评估。
+
+### MMCV 版本
+
+MMDetection v2.12.0 依赖 MMCV v1.3.3 中新增加的功能，包括：使用 `BaseModule` 统一参数初始化，模型 registry，以及[Deformable DETR](https://arxiv.org/abs/2010.04159) 中的 `MultiScaleDeformableAttn` CUDA 算子。
+注意，尽管 MMCV v1.3.2 已经包含了 MMDet 所需的功能，但是存在一些已知的问题。我们建议用户跳过 MMCV v1.3.2 使用 v1.3.3 版本。
+
+### 统一模型初始化
+
+为了统一 OpenMMLab 项目中的参数初始化方式，MMCV 新增加了 `BaseModule` 类，使用 `init_cfg` 参数对模块进行统一且灵活的初始化配置管理。
+现在用户需要在训练脚本中显式调用 `model.init_weights()` 来初始化模型（例如 [这行代码](https://github.com/open-mmlab/mmdetection/blob/master/tools/train.py#L162) ，在这之前则是在 detector 中进行处理的。
+**下游项目必须相应地更新模型初始化方式才能使用 MMDetection v2.12.0**。请参阅 [PR #4750](https://github.com/open-mmlab/mmdetection/pull/4750) 了解详情。
+
+### 统一模型 registry
+
+为了能够使用在其他 OpenMMLab 项目中实现的 backbone，MMDetection v2.12.0 继承了在 MMCV (#760) 中创建的模型 registry。
+这样，只要 OpenMMLab 项目实现了某个 backbone，并且该项目也使用 MMCV 中的 registry，那么用户只需修改配置即可在 MMDetection 中使用该 backbone，不再需要将代码复制到 MMDetection 中。 更多详细信息，请参阅 [PR #5059](https://github.com/open-mmlab/mmdetection/pull/5059) 。
+
+### Mask AP 评估
+
+在 [PR #4898](https://github.com/open-mmlab/mmdetection/pull/4898) 和 v2.12.0 之前，对小、中、大目标的 mask AP 的评估是基于其边界框区域而不是真正的 mask 区域。
+这导致 `APs` 和 `APm` 变得更高但 `APl` 变得更低，但是不会影响整体的 mask AP。 [PR #4898](https://github.com/open-mmlab/mmdetection/pull/4898) 删除了 mask AP 计算中的 `bbox` ，改为使用 mask 区域。
+新的计算方式不会影响整体的 mask AP 评估，与 [Detectron2](https://github.com/facebookresearch/detectron2/)一致。
+
+## 与 MMDetection v1.x 的兼容性
+
+MMDetection v2.0 经过了大规模重构并解决了许多遗留问题。 MMDetection v2.0 不兼容 v1.x 版本，在这两个版本中使用相同的模型权重运行推理会产生不同的结果。 因此，MMDetection v2.0 重新对所有模型进行了 benchmark，并在 model zoo 中提供了新模型的权重和训练记录。
+
+新旧版本的主要的区别有四方面：坐标系、代码库约定、训练超参和模块设计。
+
+### 坐标系
+
+新坐标系与 [Detectron2](https://github.com/facebookresearch/detectron2/) 一致，
+将最左上角的像素的中心视为坐标原点 (0, 0) 而不是最左上角像素的左上角。 因此 COCO 边界框和分割标注中的坐标被解析为范围 `[0，width]` 和 `[0，height]` 中的坐标。 这个修改影响了所有与 bbox 及像素选择相关的计算，变得更加自然且更加准确。
+
+- 在新坐标系中，左上角和右下角为 (x1, y1) (x2, y2) 的框的宽度及高度计算公式为 `width = x2 - x1` 和 `height = y2 - y1`。
+  在 MMDetection v1.x 和之前的版本中，高度和宽度都多了 `+ 1` 的操作。
+  本次修改包括三部分：
+
+  1. box 回归中的检测框变换以及编码/解码。
+  2. IoU 计算。这会影响 ground truth 和检测框之间的匹配以及 NMS 。但对兼容性的影响可以忽略不计。
+  3. Box 的角点坐标为浮点型，不再取整。这能使得检测结果更为准确，也使得检测框和 RoI 的最小尺寸不再为 1，但影响很小。
+
+- Anchor 的中心与特征图的网格点对齐，类型变为 float。
+  在 MMDetection v1.x 和之前的版本中，anchors 是 `int` 类型且没有居中对齐。
+  这会影响 RPN 中的 Anchor 生成和所有基于 Anchor 的方法。
+
+- ROIAlign 更好地与图像坐标系对齐。新的实现来自 [Detectron2](https://github.com/facebookresearch/detectron2/tree/master/detectron2/layers/csrc/ROIAlign) 。
+  当 RoI 用于提取 RoI 特征时，与 MMDetection v1.x 相比默认情况下相差半个像素。
+  能够通过设置 `aligned=False` 而不是 `aligned=True` 来维持旧版本的设置。
+
+- Mask 的裁剪和粘贴更准确。
+
+  1. 我们使用新的 RoIAlign 来提取 mask 目标。 在 MMDetection v1.x 中，bounding box 在提取 mask 目标之前被取整，裁剪过程是 numpy 实现的。 而在新版本中，裁剪的边界框不经过取整直接输入 RoIAlign。 此实现大大加快了训练速度（每次迭代约加速 0.1 秒，1x schedule 训练 Mask R50 时加速约 2 小时）并且理论上会更准确。
+  2. 在 MMDetection v2.0 中，修改后的 `paste_mask()` 函数应该比之前版本更准确。 此更改参考了 [Detectron2](https://github.com/facebookresearch/detectron2/blob/master/detectron2/structures/masks.py) 中的修改，可以将 COCO 上的 mask AP 提高约 0.5%。
+
+### 代码库约定
+
+- MMDetection v2.0 更改了类别标签的顺序，减少了回归和 mask 分支里的无用参数并使得顺序更加自然（没有 +1 和 -1）。
+  这会影响模型的所有分类层，使其输出的类别标签顺序发生改变。回归分支和 mask head 的最后一层不再为 K 个类别保留 K+1 个通道，类别顺序与分类分支一致。
+
+  - 在 MMDetection v2.0 中，标签 “K” 表示背景，标签 \[0, K-1\] 对应于 K = num_categories 个对象类别。
+
+  - 在 MMDetection v1.x 及之前的版本中，标签 “0” 表示背景，标签 \[1, K\] 对应 K 个类别。
+
+  - **注意**：softmax RPN 的类顺序在 version\<=2.4.0 中仍然和 1.x 中的一样，而 sigmoid RPN 不受影响。从 MMDetection v2.5.0 开始，所有 head 中的类顺序是统一的。
+
+- 不使用 R-CNN 中的低质量匹配。在 MMDetection v1.x 和之前的版本中，`max_iou_assigner` 会在 RPN 和 R-CNN 训练时给每个 ground truth 匹配低质量框。我们发现这会导致最佳的 GT 框不会被分配给某些边界框，
+  因此，在MMDetection v2.0 的 R-CNN 训练中默认不允许低质量匹配。这有时可能会稍微改善 box AP（约为 0.1%）。
+
+- 单独的宽高比例系数。在 MMDetection v1.x 和以前的版本中，`keep_ratio=True` 时比例系数是单个浮点数，这并不准确，因为宽度和高度的比例系数会有一定的差异。 MMDetection v2.0 对宽度和高度使用单独的比例系数，对 AP 的提升约为 0.1%。
+
+- 修改了 config 文件名称的规范。 由于 model zoo 中模型不断增多， MMDetection v2.0 采用新的命名规则：
+
+  ```shell
+  [model]_(model setting)_[backbone]_[neck]_(norm setting)_(misc)_(gpu x batch)_[schedule]_[dataset].py
+  ```
+
+  其中 (`misc`) 包括 DCN 和 GCBlock 等。更多详细信息在 [配置文件说明文档](config.md) 中说明
+
+- MMDetection v2.0 使用新的 ResNet Caffe backbone 来减少加载预训练模型时的警告。新 backbone 中的大部分权重与以前的相同，但没有 `conv.bias`，且它们使用不同的 `img_norm_cfg`。因此，新的 backbone 不会报 `unexpected keys` 的警告。
+
+### 训练超参
+
+训练超参的调整不会影响模型的兼容性，但会略微提高性能。主要有：
+
+- 通过设置 `nms_post=1000` 和 `max_num=1000`，将 nms 之后的 proposal 数量从 2000 更改为 1000。使 mask AP 和 bbox AP 提高了约 0.2%。
+
+- Mask R-CNN、Faster R-CNN 和 RetinaNet 的默认回归损失从 smooth L1 损失更改为 L1 损失，使得 box AP 整体上都有所提升（约 0.6%）。但是，将 L1-loss 用在 Cascade R-CNN 和 HTC 等其他方法上并不能提高性能，因此我们保留这些方法的原始设置。
+
+- 为简单起见，RoIAlign 层的 `sampling_ratio` 设置为 0。略微提升了 AP（约 0.2% 绝对值）。
+
+- 为了提升训练速度，默认设置在训练过程中不再使用梯度裁剪。大多数模型的性能不会受到影响。对于某些模型（例如 RepPoints），我们依旧使用梯度裁剪来稳定训练过程从而获得更好的性能。
+
+- 因为不再默认使用梯度裁剪，默认 warmup 比率从 1/3 更改为 0.001，以使模型训练预热更加平缓。不过我们重新进行基准测试时发现这种影响可以忽略不计。
+
+### 将模型从 v1.x 升级至 v2.0
+
+用户可以使用脚本 `tools/model_converters/upgrade_model_version.py` 来将 MMDetection 1.x 训练的模型转换为 MMDetection v2.0。转换后的模型可以在 MMDetection v2.0 中运行，但性能略有下降（小于 1% AP）。
+详细信息可以在 `configs/legacy` 中找到。
+
+## pycocotools 兼容性
+
+`mmpycocotools` 是 OpenMMLab 维护的 `pycocotools` 的复刻版，适用于 MMDetection 和 Detectron2。
+在 [PR #4939](https://github.com/open-mmlab/mmdetection/pull/4939) 之前，由于 `pycocotools` 和 `mmpycocotool` 具有相同的包名，如果用户已经安装了 `pyccocotools`（在相同环境下先安装了 Detectron2 ），那么 MMDetection 的安装过程会跳过安装 `mmpycocotool`。 导致 MMDetection 缺少 `mmpycocotools` 而报错。
+但如果在 Detectron2 之前安装 MMDetection，则可以在相同的环境下工作。
+[PR #4939](https://github.com/open-mmlab/mmdetection/pull/4939) 弃用 mmpycocotools，使用官方 pycocotools。
+在 [PR #4939](https://github.com/open-mmlab/mmdetection/pull/4939) 之后，用户能够在相同环境下安装 MMDetection 和 Detectron2，不再需要关注安装顺序。

docs/zh_cn/notes/faq.md

+# 常见问题解答
+
+我们在这里列出了使用时的一些常见问题及其相应的解决方案。 如果您发现有一些问题被遗漏，请随时提 PR 丰富这个列表。 如果您无法在此获得帮助，请使用 [issue模板](https://github.com/open-mmlab/mmdetection/blob/main/.github/ISSUE_TEMPLATE/error-report.md/)创建问题，但是请在模板中填写所有必填信息，这有助于我们更快定位问题。
+
+## PyTorch 2.0 支持
+
+MMDetection 目前绝大部分算法已经支持了 PyTorch 2.0 及其 `torch.compile` 功能, 用户只需要安装 MMDetection 3.0.0rc7 及其以上版本即可。如果你在使用中发现有不支持的算法，欢迎给我们反馈。我们也非常欢迎社区贡献者来 benchmark 对比 `torch.compile` 功能所带来的速度提升。
+
+如果你想启动 `torch.compile` 功能，只需要在 `train.py` 或者 `test.py` 后面加上 `--cfg-options compile=True`。 以 RTMDet 为例，你可以使用以下命令启动 `torch.compile` 功能：
+
+```shell
+# 单卡
+python tools/train.py configs/rtmdet/rtmdet_s_8xb32-300e_coco.py  --cfg-options compile=True
+
+# 单机 8 卡
+./tools/dist_train.sh configs/rtmdet/rtmdet_s_8xb32-300e_coco.py 8 --cfg-options compile=True
+
+# 单机 8 卡 + AMP 混合精度训练
+./tools/dist_train.sh configs/rtmdet/rtmdet_s_8xb32-300e_coco.py 8 --cfg-options compile=True --amp
+```
+
+需要特别注意的是，PyTorch 2.0 对于动态 shape 支持不是非常完善，目标检测算法中大部分不仅输入 shape 是动态的，而且 loss 计算和后处理过程中也是动态的，这会导致在开启 `torch.compile` 功能后训练速度会变慢。基于此，如果你想启动 `torch.compile` 功能，则应该遵循如下原则：
+
+1. 输入到网络的图片是固定 shape 的，而非多尺度的
+2. 设置 `torch._dynamo.config.cache_size_limit` 参数。TorchDynamo 会将 Python 字节码转换并缓存，已编译的函数会被存入缓存中。当下一次检查发现需要重新编译时，该函数会被重新编译并缓存。但是如果重编译次数超过预设的最大值（64），则该函数将不再被缓存或重新编译。前面说过目标检测算法中的 loss 计算和后处理部分也是动态计算的，这些函数需要在每次迭代中重新编译。因此将 `torch._dynamo.config.cache_size_limit` 参数设置得更小一些可以有效减少编译时间
+
+在 MMDetection 中可以通过环境变量 `DYNAMO_CACHE_SIZE_LIMIT` 设置 `torch._dynamo.config.cache_size_limit` 参数，以 RTMDet 为例，命令如下所示：
+
+```shell
+# 单卡
+export DYNAMO_CACHE_SIZE_LIMIT = 4
+python tools/train.py configs/rtmdet/rtmdet_s_8xb32-300e_coco.py  --cfg-options compile=True
+
+# 单机 8 卡
+export DYNAMO_CACHE_SIZE_LIMIT = 4
+./tools/dist_train.sh configs/rtmdet/rtmdet_s_8xb32-300e_coco.py 8 --cfg-options compile=True
+```
+
+关于 PyTorch 2.0 的 dynamo 常见问题，可以参考 [这里](https://pytorch.org/docs/stable/dynamo/faq.html)
+
+## 安装
+
+- MMCV 与 MMDetection 的兼容问题: "ConvWS is already registered in conv layer"; "AssertionError: MMCV==xxx is used but incompatible. Please install mmcv>=xxx, \<=xxx."
+
+  MMDetection，MMEngine 和 MMCV 的版本兼容关系如下。请选择合适的版本避免安装错误 。
+
+  | MMDetection 版本 |        MMCV 版本        |      MMEngine 版本       |
+  | :--------------: | :---------------------: | :----------------------: |
+  |       main       |  mmcv>=2.0.0, \<2.2.0   | mmengine>=0.7.1, \<1.0.0 |
+  |      3.3.0       |  mmcv>=2.0.0, \<2.2.0   | mmengine>=0.7.1, \<1.0.0 |
+  |      3.2.0       |  mmcv>=2.0.0, \<2.2.0   | mmengine>=0.7.1, \<1.0.0 |
+  |      3.1.0       |  mmcv>=2.0.0, \<2.1.0   | mmengine>=0.7.1, \<1.0.0 |
+  |      3.0.0       |  mmcv>=2.0.0, \<2.1.0   | mmengine>=0.7.1, \<1.0.0 |
+  |     3.0.0rc6     | mmcv>=2.0.0rc4, \<2.1.0 | mmengine>=0.6.0, \<1.0.0 |
+  |     3.0.0rc5     | mmcv>=2.0.0rc1, \<2.1.0 | mmengine>=0.3.0, \<1.0.0 |
+  |     3.0.0rc4     | mmcv>=2.0.0rc1, \<2.1.0 | mmengine>=0.3.0, \<1.0.0 |
+  |     3.0.0rc3     | mmcv>=2.0.0rc1, \<2.1.0 | mmengine>=0.3.0, \<1.0.0 |
+  |     3.0.0rc2     | mmcv>=2.0.0rc1, \<2.1.0 | mmengine>=0.1.0, \<1.0.0 |
+  |     3.0.0rc1     | mmcv>=2.0.0rc1, \<2.1.0 | mmengine>=0.1.0, \<1.0.0 |
+  |     3.0.0rc0     | mmcv>=2.0.0rc1, \<2.1.0 | mmengine>=0.1.0, \<1.0.0 |
+
+  **注意：**
+
+  1. 如果你希望安装 mmdet-v2.x, MMDetection 和 MMCV 版本兼容表可以在 [这里](https://mmdetection.readthedocs.io/en/stable/faq.html#installation) 找到，请选择合适的版本避免安装错误。
+  2. 在 MMCV-v2.x 中，`mmcv-full` 改名为 `mmcv`，如果你想安装不包含 CUDA 算子的版本，可以选择安装 MMCV 精简版 `mmcv-lite`。
+
+- "No module named 'mmcv.ops'"; "No module named 'mmcv.\_ext'".
+
+  原因是安装了 `mmcv-lite` 而不是 `mmcv`。
+
+  1. `pip uninstall mmcv-lite` 卸载安装的 `mmcv-lite`
+
+  2. 安装 `mmcv` 根据 [安装说明](https://mmcv.readthedocs.io/zh_CN/2.x/get_started/installation.html)。
+
+- 在 Windows 环境下安装过程中遇到 "Microsoft Visual C++ 14.0 or graeter is required" error .
+
+  这个错误发生在 pycotools 的 'pycocotools.\_mask' 扩展构建过程，其原因是缺少了对应 C++ 环境依赖。你需要到微软官方下载[对应工具](https://visualstudio.microsoft.com/zh-hans/visual-cpp-build-tools/)，选择“使用 C++ 的桌面开发”选项安装最小依赖，随后重新安装 pycocotools。
+
+- 使用 albumentations
+
+如果你希望使用 `albumentations`，我们建议使用 `pip install -r requirements/albu.txt`
+或者 `pip install -U albumentations --no-binary qudida,albumentations` 进行安装。
+如果简单地使用 `pip install albumentations>=0.3.2` 进行安装，
+则会同时安装 `opencv-python-headless`（即便已经安装了 `opencv-python` 也会再次安装）。
+我们建议在安装 `albumentations` 后检查环境，以确保没有同时安装 `opencv-python` 和 `opencv-python-headless`，
+因为同时安装可能会导致一些问题。更多细节请参考[官方文档](https://albumentations.ai/docs/getting_started/installation/#note-on-opencv-dependencies) 。
+
+- 在某些算法中出现 ModuleNotFoundError 错误
+
+一些算法或者数据需要额外的依赖，例如 Instaboost、 Panoptic Segmentation、 LVIS dataset 等。请注意错误信息并安装相应的包，例如：
+
+```shell
+# 安装 instaboost 依赖
+pip install instaboostfast
+# 安装 panoptic segmentation 依赖
+pip install git+https://github.com/cocodataset/panopticapi.git
+# 安装 LVIS dataset 依赖
+pip install git+https://github.com/lvis-dataset/lvis-api.git
+```
+
+## 代码
+
+- 修改一些代码后是否需要重新安装 mmdet
+
+如果你遵循最佳实践，即使用 `pip install -v -e .` 安装的 mmdet，则对本地代码所作的任何修改都会生效，无需重新安装
+
+- 如何使用多个 MMDetection 版本进行开发
+
+你可以拥有多个文件夹，例如 mmdet-3.0，mmdet-3.1。
+
+要使环境中安装默认的 MMDetection 而不是当前正在在使用的，可以删除出现在相关脚本中的代码：
+
+```shell
+PYTHONPATH="$(dirname $0)/..":$PYTHONPATH
+```
+
+## PyTorch/CUDA 环境相关
+
+- "RTX 30 series card fails when building MMCV or MMDet"
+
+  1. 临时解决方案为使用命令 `MMCV_WITH_OPS=1 MMCV_CUDA_ARGS='-gencode=arch=compute_80,code=sm_80' pip install -e .` 进行编译。 常见报错信息为 `nvcc fatal : Unsupported gpu architecture 'compute_86'` 意思是你的编译器不支持 sm_86 架构(包括英伟达 30 系列的显卡)的优化，至 CUDA toolkit 11.0 依旧未支持. 这个命令是通过增加宏 `MMCV_CUDA_ARGS='-gencode=arch=compute_80,code=sm_80` 让 nvcc 编译器为英伟达 30 系列显卡进行 `sm_80` 的优化，虽然这有可能会无法发挥出显卡所有性能。
+
+  2. 有开发者已经在 [pytorch/pytorch#47585](https://github.com/pytorch/pytorch/pull/47585) 更新了 PyTorch 默认的编译 flag， 但是我们对此并没有进行测试。
+
+- "invalid device function" 或者 "no kernel image is available for execution".
+
+  1. 检查您正常安装了 CUDA runtime (一般在`/usr/local/`)，或者使用 `nvcc --version` 检查本地版本，有时安装 PyTorch 会顺带安装一个 CUDA runtime，并且实际优先使用 conda 环境中的版本，你可以使用 `conda list cudatoolkit` 查看其版本。
+
+  2. 编译 extension 的 CUDA Toolkit 版本与运行时的 CUDA Toolkit 版本是否相符，
+
+     - 如果您从源码自己编译的，使用 `python mmdet/utils/collect_env.py` 检查编译编译 extension 的 CUDA Toolkit 版本，然后使用 `conda list cudatoolkit` 检查当前 conda 环境是否有 CUDA Toolkit，若有检查版本是否匹配， 如不匹配，更换 conda 环境的 CUDA Toolkit，或者使用匹配的 CUDA Toolkit 中的 nvcc 编译即可，如环境中无 CUDA Toolkit，可以使用 `nvcc -V`。
+
+       等命令查看当前使用的 CUDA runtime。
+
+     - 如果您是通过 pip 下载的预编译好的版本，请确保与当前 CUDA runtime 一致。
+
+  3. 运行 `python mmdet/utils/collect_env.py` 检查是否为正确的 GPU 架构编译的 PyTorch， torchvision， 与 MMCV。 你或许需要设置 `TORCH_CUDA_ARCH_LIST` 来重新安装 MMCV，可以参考 [GPU 架构表](https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#gpu-feature-list),
+     例如， 运行 `TORCH_CUDA_ARCH_LIST=7.0 pip install mmcv` 为 Volta GPU 编译 MMCV。这种架构不匹配的问题一般会出现在使用一些旧型号的 GPU 时候出现， 例如， Tesla K80。
+
+- "undefined symbol" 或者 "cannot open xxx.so".
+
+  1. 如果这些 symbol 属于 CUDA/C++ (如 libcudart.so 或者 GLIBCXX)，使用 `python mmdet/utils/collect_env.py`检查 CUDA/GCC runtime 与编译 MMCV 的 CUDA 版本是否相同。
+  2. 如果这些 symbols 属于 PyTorch，(例如, symbols containing caffe, aten, and TH), 检查当前 Pytorch 版本是否与编译 MMCV 的版本一致。
+  3. 运行 `python mmdet/utils/collect_env.py` 检查 PyTorch， torchvision， MMCV 等的编译环境与运行环境一致。
+
+- setuptools.sandbox.UnpickleableException: DistutilsSetupError("each element of 'ext_modules' option must be an Extension instance or 2-tuple")
+
+  1. 如果你在使用 miniconda 而不是 anaconda，检查是否正确的安装了 Cython 如 [#3379](https://github.com/open-mmlab/mmdetection/issues/3379).
+  2. 检查环境中的 `setuptools`, `Cython`, and `PyTorch` 相互之间版本是否匹配。
+
+- "Segmentation fault".
+
+  1. 检查 GCC 的版本，通常是因为 PyTorch 版本与 GCC 版本不匹配 （例如 GCC \< 4.9 )，我们推荐用户使用 GCC 5.4，我们也不推荐使用 GCC 5.5， 因为有反馈 GCC 5.5 会导致 "segmentation fault" 并且切换到 GCC 5.4 就可以解决问题。
+
+  2. 检查是否正确安装了 CUDA 版本的 PyTorch 。
+
+     ```shell
+     python -c 'import torch; print(torch.cuda.is_available())'
+     ```
+
+     是否返回True。
+
+  3. 如果 `torch` 的安装是正确的，检查是否正确编译了 MMCV。
+
+     ```shell
+     python -c 'import mmcv; import mmcv.ops'
+     ```
+
+  4. 如果 MMCV 与 PyTorch 都被正确安装了，则使用 `ipdb`, `pdb` 设置断点，直接查找哪一部分的代码导致了 `segmentation fault`。
+
+## Training 相关
+
+- "Loss goes Nan"
+
+  1. 检查数据的标注是否正常， 长或宽为 0 的框可能会导致回归 loss 变为 nan，一些小尺寸（宽度或高度小于 1）的框在数据增强（例如，instaboost）后也会导致此问题。 因此，可以检查标注并过滤掉那些特别小甚至面积为 0 的框，并关闭一些可能会导致 0 面积框出现数据增强。
+  2. 降低学习率：由于某些原因，例如 batch size 大小的变化， 导致当前学习率可能太大。 您可以降低为可以稳定训练模型的值。
+  3. 延长 warm up 的时间：一些模型在训练初始时对学习率很敏感，您可以把 `warmup_iters` 从 500 更改为 1000 或 2000。
+  4. 添加 gradient clipping: 一些模型需要梯度裁剪来稳定训练过程。 默认的 `grad_clip` 是 `None`,  你可以在 config 设置 `optimizer_config=dict(_delete_=True, grad_clip=dict(max_norm=35, norm_type=2))`  如果你的 config 没有继承任何包含 `optimizer_config=dict(grad_clip=None)`,  你可以直接设置`optimizer_config=dict(grad_clip=dict(max_norm=35, norm_type=2))`.
+
+- "GPU out of memory"
+
+  1. 存在大量 ground truth boxes 或者大量 anchor 的场景，可能在 assigner 会 OOM。 您可以在 assigner 的配置中设置 `gpu_assign_thr=N`，这样当超过 N 个 GT boxes 时，assigner 会通过 CPU 计算 IOU。
+
+  2. 在 backbone 中设置 `with_cp=True`。 这使用 PyTorch 中的 `sublinear strategy` 来降低 backbone 占用的 GPU 显存。
+
+  3. 使用 `config/fp16` 中的示例尝试混合精度训练。`loss_scale` 可能需要针对不同模型进行调整。
+
+  4. 你也可以尝试使用 `AvoidCUDAOOM` 来避免该问题。首先它将尝试调用 `torch.cuda.empty_cache()`。如果失败，将会尝试把输入类型转换到 FP16。如果仍然失败，将会把输入从 GPUs 转换到 CPUs 进行计算。这里提供了两个使用的例子：
+
+     ```python
+     from mmdet.utils import AvoidCUDAOOM
+
+     output = AvoidCUDAOOM.retry_if_cuda_oom(some_function)(input1, input2)
+     ```
+
+     你也可也使用 `AvoidCUDAOOM` 作为装饰器让代码遇到 OOM 的时候继续运行：
+
+     ```python
+     from mmdet.utils import AvoidCUDAOOM
+
+     @AvoidCUDAOOM.retry_if_cuda_oom
+     def function(*args, **kwargs):
+         ...
+         return xxx
+     ```
+
+- "RuntimeError: Expected to have finished reduction in the prior iteration before starting a new one"
+
+  1. 这个错误出现在存在参数没有在 forward 中使用，容易在 DDP 中运行不同分支时发生。
+  2. 你可以在 config 设置 `find_unused_parameters = True` 进行训练 (会降低训练速度)。
+  3. 你也可以通过在 config 中的 `optimizer_config` 里设置 `detect_anomalous_params=True` 查找哪些参数没有用到，但是需要 MMCV 的版本 >= 1.4.1。
+
+- 训练中保存最好模型
+
+  可以通过配置 `default_hooks = dict(checkpoint=dict(type='CheckpointHook', interval=1, save_best='auto')`开启。在 `auto` 参数情况下会根据返回的验证结果中的第一个 key 作为选择最优模型的依据，你也可以直接设置评估结果中的 key 来手动设置，例如 `save_best='coco/bbox_mAP'`。
+
+- 在 Resume 训练中使用 `ExpMomentumEMAHook`
+
+  如果在训练中使用了 `ExpMomentumEMAHook`，那么 resume 时候不能仅仅通过命令行参数 `--resume-from` 或 `--cfg-options resume_from` 实现恢复模型参数功能例如 `python tools/train.py configs/yolox/yolox_s_8x8_300e_coco.py --resume-from ./work_dir/yolox_s_8x8_300e_coco/epoch_x.pth`。以 `yolox_s` 算法为例，由于 `ExpMomentumEMAHook` 需要重新加载权重，你可以通过如下做法实现：
+
+  ```python
+  # 直接打开 configs/yolox/yolox_s_8x8_300e_coco.py 修改所有 resume_from 字段
+  resume_from=./work_dir/yolox_s_8x8_300e_coco/epoch_x.pth
+  custom_hooks=[...
+      dict(
+          type='ExpMomentumEMAHook',
+          resume_from=./work_dir/yolox_s_8x8_300e_coco/epoch_x.pth,
+          momentum=0.0001,
+          priority=49)
+      ]
+  ```
+
+## Evaluation 相关
+
+- 使用 COCO Dataset 的测评接口时, 测评结果中 AP 或者 AR = -1
+  1. 根据COCO数据集的定义，一张图像中的中等物体与小物体面积的阈值分别为 9216（96\*96）与 1024（32\*32）。
+  2. 如果在某个区间没有检测框 AP 与 AR 认定为 -1.
+
+## Model 相关
+
+- **ResNet style 参数说明**
+
+  ResNet style 可选参数允许 `pytorch` 和 `caffe`，其差别在于 Bottleneck 模块。Bottleneck 是 `1x1-3x3-1x1` 堆叠结构，在 `caffe` 模式模式下 stride=2 参数放置在第一个 `1x1` 卷积处，而 `pyorch` 模式下 stride=2 放在第二个 `3x3` 卷积处。一个简单示例如下：
+
+  ```python
+  if self.style == 'pytorch':
+        self.conv1_stride = 1
+        self.conv2_stride = stride
+  else:
+        self.conv1_stride = stride
+        self.conv2_stride = 1
+  ```
+
+- **ResNeXt 参数说明**
+
+  ResNeXt 来自论文 [`Aggregated Residual Transformations for Deep Neural Networks`](https://arxiv.org/abs/1611.05431). 其引入分组卷积，并且通过变量基数来控制组的数量达到精度和复杂度的平衡，其有两个超参 `baseWidth` 和 `cardinality `来控制内部 Bottleneck 模块的基本宽度和分组数参数。以 MMDetection 中配置名为 `mask_rcnn_x101_64x4d_fpn_mstrain-poly_3x_coco.py` 为例，其中 `mask_rcnn` 代表算法采用 Mask R-CNN，`x101` 代表骨架网络采用 ResNeXt-101，`64x4d`代表 Bottleneck 一共分成 64 组，每组的基本宽度是 4。
+
+- **骨架网络 eval 模式说明**
+
+  因为检测模型通常比较大且输入图片分辨率很高，这会导致检测模型的 batch 很小，通常是 2，这会使得 BatchNorm 在训练过程计算的统计量方差非常大，不如主干网络预训练时得到的统计量稳定，因此在训练是一般都会使用 `norm_eval=True` 模式，直接使用预训练主干网络中的 BatchNorm 统计量，少数使用大 batch 的算法是 `norm_eval=False` 模式，例如 NASFPN。对于没有 ImageNet 预训练的骨架网络，如果 batch 比较小，可以考虑使用 `SyncBN`。

docs/zh_cn/notes/projects.md

+# 基于 MMDetection 的项目
+
+有许多开源项目都是基于 MMDetection 搭建的，我们在这里列举一部分作为样例，展示如何基于 MMDetection 搭建您自己的项目。
+由于这个页面列举的项目并不完全，我们欢迎社区提交 Pull Request 来更新这个文档。
+
+## MMDetection 的拓展项目
+
+一些项目拓展了 MMDetection 的边界，如将 MMDetection 拓展支持 3D 检测或者将 MMDetection 用于部署。
+它们展示了 MMDetection 的许多可能性，所以我们在这里也列举一些。
+
+- [OTEDetection](https://github.com/opencv/mmdetection): OpenVINO training extensions for object detection.
+- [MMDetection3d](https://github.com/open-mmlab/mmdetection3d): OpenMMLab's next-generation platform for general 3D object detection.
+
+## 研究项目
+
+同样有许多研究论文是基于 MMDetection 进行的。许多论文都发表在了顶级的会议或期刊上，或者对社区产生了深远的影响。
+为了向社区提供一个可以参考的论文列表，帮助大家开发或者比较新的前沿算法，我们在这里也遵循会议的时间顺序列举了一些论文。
+MMDetection 中已经支持的算法不在此列。
+
+- Involution: Inverting the Inherence of Convolution for Visual Recognition, CVPR21. [\[paper\]](https://arxiv.org/abs/2103.06255)[\[github\]](https://github.com/d-li14/involution)
+- Multiple Instance Active Learning for Object Detection, CVPR 2021. [\[paper\]](https://openaccess.thecvf.com/content/CVPR2021/papers/Yuan_Multiple_Instance_Active_Learning_for_Object_Detection_CVPR_2021_paper.pdf)[\[github\]](https://github.com/yuantn/MI-AOD)
+- Adaptive Class Suppression Loss for Long-Tail Object Detection, CVPR 2021. [\[paper\]](https://arxiv.org/abs/2104.00885)[\[github\]](https://github.com/CASIA-IVA-Lab/ACSL)
+- Generalizable Pedestrian Detection: The Elephant In The Room, CVPR2021. [\[paper\]](https://arxiv.org/abs/2003.08799)[\[github\]](https://github.com/hasanirtiza/Pedestron)
+- Group Fisher Pruning for Practical Network Compression, ICML2021. [\[paper\]](https://github.com/jshilong/FisherPruning/blob/main/resources/paper.pdf)[\[github\]](https://github.com/jshilong/FisherPruning)
+- Overcoming Classifier Imbalance for Long-tail Object Detection with Balanced Group Softmax, CVPR2020. [\[paper\]](http://openaccess.thecvf.com/content_CVPR_2020/papers/Li_Overcoming_Classifier_Imbalance_for_Long-Tail_Object_Detection_With_Balanced_Group_CVPR_2020_paper.pdf)[\[github\]](https://github.com/FishYuLi/BalancedGroupSoftmax)
+- Coherent Reconstruction of Multiple Humans from a Single Image, CVPR2020. [\[paper\]](https://jiangwenpl.github.io/multiperson/)[\[github\]](https://github.com/JiangWenPL/multiperson)
+- Look-into-Object: Self-supervised Structure Modeling for Object Recognition, CVPR 2020. [\[paper\]](http://openaccess.thecvf.com/content_CVPR_2020/papers/Zhou_Look-Into-Object_Self-Supervised_Structure_Modeling_for_Object_Recognition_CVPR_2020_paper.pdf)[\[github\]](https://github.com/JDAI-CV/LIO)
+- Video Panoptic Segmentation, CVPR2020. [\[paper\]](https://arxiv.org/abs/2006.11339)[\[github\]](https://github.com/mcahny/vps)
+- D2Det: Towards High Quality Object Detection and Instance Segmentation, CVPR2020. [\[paper\]](http://openaccess.thecvf.com/content_CVPR_2020/html/Cao_D2Det_Towards_High_Quality_Object_Detection_and_Instance_Segmentation_CVPR_2020_paper.html)[\[github\]](https://github.com/JialeCao001/D2Det)
+- CentripetalNet: Pursuing High-quality Keypoint Pairs for Object Detection, CVPR2020. [\[paper\]](https://arxiv.org/abs/2003.09119)[\[github\]](https://github.com/KiveeDong/CentripetalNet)
+- Learning a Unified Sample Weighting Network for Object Detection, CVPR 2020. [\[paper\]](http://openaccess.thecvf.com/content_CVPR_2020/html/Cai_Learning_a_Unified_Sample_Weighting_Network_for_Object_Detection_CVPR_2020_paper.html)[\[github\]](https://github.com/caiqi/sample-weighting-network)
+- Scale-equalizing Pyramid Convolution for Object Detection, CVPR2020. [\[paper\]](https://arxiv.org/abs/2005.03101) [\[github\]](https://github.com/jshilong/SEPC)
+- Revisiting the Sibling Head in Object Detector, CVPR2020. [\[paper\]](https://arxiv.org/abs/2003.07540)[\[github\]](https://github.com/Sense-X/TSD)
+- PolarMask: Single Shot Instance Segmentation with Polar Representation, CVPR2020. [\[paper\]](https://arxiv.org/abs/1909.13226)[\[github\]](https://github.com/xieenze/PolarMask)
+- Hit-Detector: Hierarchical Trinity Architecture Search for Object Detection, CVPR2020. [\[paper\]](https://arxiv.org/abs/2003.11818)[\[github\]](https://github.com/ggjy/HitDet.pytorch)
+- ZeroQ: A Novel Zero Shot Quantization Framework, CVPR2020. [\[paper\]](https://arxiv.org/abs/2001.00281)[\[github\]](https://github.com/amirgholami/ZeroQ)
+- CBNet: A Novel Composite Backbone Network Architecture for Object Detection, AAAI2020. [\[paper\]](https://aaai.org/Papers/AAAI/2020GB/AAAI-LiuY.1833.pdf)[\[github\]](https://github.com/VDIGPKU/CBNet)
+- RDSNet: A New Deep Architecture for Reciprocal Object Detection and Instance Segmentation, AAAI2020. [\[paper\]](https://arxiv.org/abs/1912.05070)[\[github\]](https://github.com/wangsr126/RDSNet)
+- Training-Time-Friendly Network for Real-Time Object Detection, AAAI2020. [\[paper\]](https://arxiv.org/abs/1909.00700)[\[github\]](https://github.com/ZJULearning/ttfnet)
+- Cascade RPN: Delving into High-Quality Region Proposal Network with Adaptive Convolution, NeurIPS 2019. [\[paper\]](https://arxiv.org/abs/1909.06720)[\[github\]](https://github.com/thangvubk/Cascade-RPN)
+- Reasoning R-CNN: Unifying Adaptive Global Reasoning into Large-scale Object Detection, CVPR2019. [\[paper\]](http://openaccess.thecvf.com/content_CVPR_2019/papers/Xu_Reasoning-RCNN_Unifying_Adaptive_Global_Reasoning_Into_Large-Scale_Object_Detection_CVPR_2019_paper.pdf)[\[github\]](https://github.com/chanyn/Reasoning-RCNN)
+- Learning RoI Transformer for Oriented Object Detection in Aerial Images, CVPR2019. [\[paper\]](https://arxiv.org/abs/1812.00155)[\[github\]](https://github.com/dingjiansw101/AerialDetection)
+- SOLO: Segmenting Objects by Locations. [\[paper\]](https://arxiv.org/abs/1912.04488)[\[github\]](https://github.com/WXinlong/SOLO)
+- SOLOv2: Dynamic, Faster and Stronger. [\[paper\]](https://arxiv.org/abs/2003.10152)[\[github\]](https://github.com/WXinlong/SOLO)
+- Dense Peppoints: Representing Visual Objects with Dense Point Sets. [\[paper\]](https://arxiv.org/abs/1912.11473)[\[github\]](https://github.com/justimyhxu/Dense-RepPoints)
+- IterDet: Iterative Scheme for Object Detection in Crowded Environments. [\[paper\]](https://arxiv.org/abs/2005.05708)[\[github\]](https://github.com/saic-vul/iterdet)
+- Cross-Iteration Batch Normalization. [\[paper\]](https://arxiv.org/abs/2002.05712)[\[github\]](https://github.com/Howal/Cross-iterationBatchNorm)
+- A Ranking-based, Balanced Loss Function Unifying Classification and Localisation in Object Detection, NeurIPS2020 [\[paper\]](https://arxiv.org/abs/2009.13592)[\[github\]](https://github.com/kemaloksuz/aLRPLoss)

docs/zh_cn/overview.md

+# 概述
+
+本章向您介绍 MMDetection 的整体框架，并提供详细的教程链接。
+
+## 什么是 MMDetection
+
+![图片](https://user-images.githubusercontent.com/12907710/137271636-56ba1cd2-b110-4812-8221-b4c120320aa9.png)
+
+MMDetection 是一个目标检测工具箱，包含了丰富的目标检测、实例分割、全景分割算法以及相关的组件和模块，下面是它的整体框架：
+
+MMDetection 由 7 个主要部分组成，apis、structures、datasets、models、engine、evaluation 和 visualization。
+
+- **apis** 为模型推理提供高级 API。
+- **structures** 提供 bbox、mask 和 DetDataSample 等数据结构。
+- **datasets** 支持用于目标检测、实例分割和全景分割的各种数据集。
+  - **transforms** 包含各种数据增强变换。
+  - **samplers** 定义了不同的数据加载器采样策略。
+- **models** 是检测器最重要的部分，包含检测器的不同组件。
+  - **detectors** 定义所有检测模型类。
+  - **data_preprocessors** 用于预处理模型的输入数据。
+  - **backbones** 包含各种骨干网络。
+  - **necks** 包含各种模型颈部组件。
+  - **dense_heads** 包含执行密集预测的各种检测头。
+  - **roi_heads** 包含从 RoI 预测的各种检测头。
+  - **seg_heads** 包含各种分割头。
+  - **losses** 包含各种损失函数。
+  - **task_modules** 为检测任务提供模块，例如 assigners、samplers、box coders 和 prior generators。
+  - **layers** 提供了一些基本的神经网络层。
+- **engine** 是运行时组件的一部分。
+  - **runner** 为 [MMEngine 的执行器](https://mmengine.readthedocs.io/zh_CN/latest/tutorials/runner.html)提供扩展。
+  - **schedulers** 提供用于调整优化超参数的调度程序。
+  - **optimizers** 提供优化器和优化器封装。
+  - **hooks** 提供执行器的各种钩子。
+- **evaluation** 为评估模型性能提供不同的指标。
+- **visualization** 用于可视化检测结果。
+
+## 如何使用本指南
+
+以下是 MMDetection 的详细指南：
+
+1. 安装说明见[开始你的第一步](get_started.md)。
+
+2. MMDetection 的基本使用方法请参考以下教程。
+
+   - [训练和测试](https://mmdetection.readthedocs.io/zh_CN/latest/user_guides/index.html#train-test)
+
+   - [实用工具](https://mmdetection.readthedocs.io/zh_CN/latest/user_guides/index.html#useful-tools)
+
+3. 参考以下教程深入了解：
+
+   - [基础概念](https://mmdetection.readthedocs.io/zh_CN/latest/advanced_guides/index.html#basic-concepts)
+   - [组件定制](https://mmdetection.readthedocs.io/zh_CN/latest/advanced_guides/index.html#component-customization)
+
+4. 对于 MMDetection 2.x 版本的用户，我们提供了[迁移指南](./migration/migration.md)，帮助您完成新版本的适配。

docs/zh_cn/stat.py

+#!/usr/bin/env python
+import functools as func
+import glob
+import os.path as osp
+import re
+
+import numpy as np
+
+url_prefix = 'https://github.com/open-mmlab/mmdetection/blob/main/'
+
+files = sorted(glob.glob('../configs/*/README.md'))
+
+stats = []
+titles = []
+num_ckpts = 0
+
+for f in files:
+    url = osp.dirname(f.replace('../', url_prefix))
+
+    with open(f, 'r') as content_file:
+        content = content_file.read()
+
+    title = content.split('\n')[0].replace('# ', '').strip()
+    ckpts = set(x.lower().strip()
+                for x in re.findall(r'\[model\]\((https?.*)\)', content))
+
+    if len(ckpts) == 0:
+        continue
+
+    _papertype = [x for x in re.findall(r'\[([A-Z]+)\]', content)]
+    assert len(_papertype) > 0
+    papertype = _papertype[0]
+
+    paper = set([(papertype, title)])
+
+    titles.append(title)
+    num_ckpts += len(ckpts)
+
+    statsmsg = f"""
+\t* [{papertype}] [{title}]({url}) ({len(ckpts)} ckpts)
+"""
+    stats.append((paper, ckpts, statsmsg))
+
+allpapers = func.reduce(lambda a, b: a.union(b), [p for p, _, _ in stats])
+msglist = '\n'.join(x for _, _, x in stats)
+
+papertypes, papercounts = np.unique([t for t, _ in allpapers],
+                                    return_counts=True)
+countstr = '\n'.join(
+    [f'   - {t}: {c}' for t, c in zip(papertypes, papercounts)])
+
+modelzoo = f"""
+# Model Zoo Statistics
+
+* Number of papers: {len(set(titles))}
+{countstr}
+
+* Number of checkpoints: {num_ckpts}
+
+{msglist}
+"""
+
+with open('modelzoo_statistics.md', 'w') as f:
+    f.write(modelzoo)