Bump version to v0.3.0 (open-mmlab#135)

* [Feature] Add function to meet mmdeploy support (open-mmlab#102) * add init_model function for mmdeploy * fix lint * add unittest for init_xxx_model * fix lint * mv test_inference.py to test_apis directory * [Feature] Add function to meet mmdeploy support (open-mmlab#102) * add init_model function for mmdeploy * fix lint * add unittest for init_xxx_model * fix lint * mv test_inference.py to test_apis directory * [Refactor] Delete redundant `set_random_seed` function (open-mmlab#104) * refactor set_random_seed * add unittests * fix unittests error * fix lint * avoid bc breaking * [Feature] Add diff seeds to diff ranks and set torch seed in worker_init_fn (open-mmlab#113) * add init_random_seed * Set diff seed to diff workers * [Feature] Add multi machine dist_train (open-mmlab#114) * support multi nodes * update training doc * fix lints * remove fixed seed * fix ddp wrapper registry (open-mmlab#128) * [Docs] Add brief installation steps in README(_zh-CN).md (open-mmlab#121) * Add brief installation * add brief installtion ref to mmediting pr#816 Co-authored-by: caoweihan <caoweihan@sensetime.com> * [BUG]Fix bugs in pruner (open-mmlab#126) * fix bugs in pruner when pruning models with shared modules * pruner can trace models with dilation conv2d * fix deploy_subnet * fix add_pruning_attrs * fix bugs in modify_forward * fix lint * fix StructurePruner * test tracing models with shared modules Co-authored-by: caoweihan <caoweihan@sensetime.com> * [Docs]Add some more details to docs (open-mmlab#133) * add docs for dataset * add cfg-options for distillation * fix docs Co-authored-by: caoweihan <caoweihan@sensetime.com> * reset norm running status after prepare_from_supernet (open-mmlab#81) * [Improvement]Sync train api (open-mmlab#115) Co-authored-by: caoweihan <caoweihan@sensetime.com> * [Feature]Support Relational Knowledge Distillation (open-mmlab#127) * add rkd * add rkd pytest * add rkd configs * fix readme * fix rkd * split rkd loss to distance-wise and angle-wise losses * rename rkd losses * add rkd metaflie * add rkd related links * rename rkd metafile and add to model index * delete cifar100 Co-authored-by: caoweihan <caoweihan@sensetime.com> Co-authored-by: pppppM <gjf_mail@126.com> Co-authored-by: qiufeng <44188071+wutongshenqiu@users.noreply.github.com> Co-authored-by: wutongshenqiu <690364065@qq.com> Co-authored-by: whcao <41630003+HIT-cwh@users.noreply.github.com> Co-authored-by: caoweihan <caoweihan@sensetime.com>
pppppM · Apr 2, 2022 · 5329362 · 5329362
1 parent 9cf76b3
commit 5329362
Show file tree

Hide file tree

Showing 39 changed files with 1,408 additions and 90 deletions.
diff --git a/README.md b/README.md
@@ -77,7 +77,19 @@ Results and models are available in the [model zoo](/docs/en/model_zoo.md).
 
 ## Installation
 
-Please refer to [get_started.md](/docs/en/get_started.md) for installation.
+MMRazor depends on [PyTorch](https://pytorch.org/) and [MMCV](https://github.com/open-mmlab/mmcv).
+Below are quick steps for installation.
+Please refer to [get_started.md](/docs/en/get_started.md) for more detailed instruction and [dataset_prepare.md](docs/en/dataset_prepare.md) for dataset preparation.
+
+```shell
+conda create -n open-mmlab python=3.8 pytorch=1.10 cudatoolkit=11.3 torchvision -c pytorch -y
+conda activate open-mmlab
+pip3 install openmim
+mim install mmcv-full
+git clone https://github.com/open-mmlab/mmrazor.git
+cd mmrazor
+pip install -v -e .  # or "python setup.py develop"
+```
 
 ## Getting Started
 Please refer to [train.md](/docs/en/train.md) and [test.md](/docs/en/test.md) for the basic usage of MMRazor. There are also tutorials:

diff --git a/README_zh-CN.md b/README_zh-CN.md
@@ -103,7 +103,18 @@ v0.1.0 版本已经在 2021.12.23 发布
 
 ## 安装
 
-请参考 [get_started.md](/docs/en/get_started.md) 进行安装。
+MMRazor 依赖 [PyTorch](https://pytorch.org/) 和 [MMCV](https://github.com/open-mmlab/mmcv)，以下是安装的简要步骤。
+更详细的安装指南请参考 [get_started.md](/docs/en/get_started.md)，并参考[dataset_prepare.md](docs/en/dataset_prepare.md)准备数据。
+
+```shell
+conda create -n open-mmlab python=3.8 pytorch=1.10 cudatoolkit=11.3 torchvision -c pytorch -y
+conda activate open-mmlab
+pip3 install openmim
+mim install mmcv-full
+git clone https://github.com/open-mmlab/mmrazor.git
+cd mmrazor
+pip install -v -e .  # or "python setup.py develop"
+```
 
 ## 快速入门
 请参考 [get_started.md](/docs/en/get_started.md) 学习 MMRazor 的基本使用。 我们也提供了一些进阶教程:

diff --git a/configs/distill/rkd/README.md b/configs/distill/rkd/README.md
@@ -0,0 +1,42 @@
+# RKD
+
+
+
+> [Relational Knowledge Distillation](https://arxiv.org/abs/1904.05068)
+
+<!-- [ALGORITHM] -->
+## Abstract
+Knowledge distillation aims at transferring knowledge acquired
+in one model (a teacher) to another model (a student) that is
+typically smaller. Previous approaches can be expressed as
+a form of training the student to mimic output activations of
+individual data examples represented by the teacher. We introduce
+a novel approach, dubbed relational knowledge distillation (RKD),
+that transfers mutual relations of data examples instead.
+For concrete realizations of RKD, we propose distance-wise and
+angle-wise distillation losses that penalize structural differences
+in relations. Experiments conducted on different tasks show that the
+proposed method improves educated student models with a significant margin.
+In particular for metric learning, it allows students to outperform their
+teachers' performance, achieving the state of the arts on standard benchmark datasets.
+
+![pipeline](/docs/en/imgs/model_zoo/rkd/pipeline.png)
+
+## Results and models
+### Classification
+|Location|Dataset|Teacher|Student|Acc|Acc(T)|Acc(S)|Config | Download |
+:--------:|:---------:|:---------:|:---------:|:---------:|:---------:|:---------:|:------:|:---------|
+| neck     |ImageNet|[resnet34](https://github.com/open-mmlab/mmclassification/blob/master/configs/resnet/resnet34_8xb32_in1k.py)|[resnet18](https://github.com/open-mmlab/mmclassification/blob/master/configs/resnet/resnet18_8xb32_in1k.py)| 70.23 |    73.62 |    69.90  |[config](./rkd_neck_resnet34_resnet18_8xb32_in1k.py)|[teacher](https://download.openmmlab.com/mmclassification/v0/resnet/resnet34_b16x8_cifar10_20210528-a8aa36a6.pth) &#124;[model](https://download.openmmlab.com/mmrazor/v0.3/distill/rkd/rkd_neck_resnet34_resnet18_8xb32_in1k_acc-70.23_20220401-f25700ac.pth) &#124; [log](https://download.openmmlab.com/mmrazor/v0.3/distill/rkd/rkd_neck_resnet34_resnet18_8xb32_in1k_20220312_130419.log.json)|
+
+
+
+## Citation
+```latex
+@inproceedings{park2019relational,
+  title={Relational knowledge distillation},
+  author={Park, Wonpyo and Kim, Dongju and Lu, Yan and Cho, Minsu},
+  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
+  pages={3967--3976},
+  year={2019}
+}
+```
diff --git a/configs/distill/rkd/metafile.yml b/configs/distill/rkd/metafile.yml
@@ -0,0 +1,31 @@
+Collections:
+  - Name: RKD
+    Metadata:
+      Training Data:
+        - ImageNet-1k
+    Paper:
+      URL: https://arxiv.org/abs/1904.05068
+      Title: Relational Knowledge Distillation
+    README: configs/distill/rkd/README.md
+    Code:
+      URL: https://github.com/open-mmlab/mmrazor/blob/v0.3.0/mmrazor/models/losses/relation_kd.py
+      Version: v0.3.0
+    Converted From:
+      Code: https://github.com/lenscloth/RKD
+Models:
+  - Name: rkd_neck_resnet34_resnet18_8xb32_in1k
+    In Collection: RKD
+    Metadata:
+      Location: neck
+      Student: R-18
+      Teacher: R-34
+      Teacher Checkpoint: https://download.openmmlab.com/mmclassification/v0/resnet/resnet34_8xb32_in1k_20210831-f257d4e6.pth
+    Results:
+      - Task: Image Classification
+        Dataset: ImageNet-1k
+        Metrics:
+          Top 1 Accuracy: 70.23
+          Top 1 Accuracy:(S): 69.90
+          Top 1 Accuracy:(T): 73.62
+    Config: configs/distill/rkd/rkd_neck_resnet34_resnet18_8xb32_in1k.py
+    Weights: https://download.openmmlab.com/mmrazor/v0.3/distill/rkd/rkd_neck_resnet34_resnet18_8xb32_in1k_acc-70.23_20220401-f25700ac.pth
diff --git a/configs/distill/rkd/rkd_neck_resnet34_resnet18_8xb32_in1k.py b/configs/distill/rkd/rkd_neck_resnet34_resnet18_8xb32_in1k.py
@@ -0,0 +1,79 @@
+_base_ = [
+    '../../_base_/datasets/mmcls/imagenet_bs32.py',
+    '../../_base_/schedules/mmcls/imagenet_bs256.py',
+    '../../_base_/mmcls_runtime.py'
+]
+
+# model settings
+student = dict(
+    type='mmcls.ImageClassifier',
+    backbone=dict(
+        type='ResNet',
+        depth=18,
+        num_stages=4,
+        out_indices=(3, ),
+        style='pytorch'),
+    neck=dict(type='GlobalAveragePooling'),
+    head=dict(
+        type='LinearClsHead',
+        num_classes=1000,
+        in_channels=512,
+        loss=dict(type='CrossEntropyLoss', loss_weight=1.0),
+        topk=(1, 5),
+    ))
+
+# teacher settings
+teacher_ckpt = 'https://download.openmmlab.com/mmclassification/v0/resnet/resnet34_8xb32_in1k_20210831-f257d4e6.pth'  # noqa: E501
+
+teacher = dict(
+    type='mmcls.ImageClassifier',
+    init_cfg=dict(type='Pretrained', checkpoint=teacher_ckpt),
+    backbone=dict(
+        type='ResNet',
+        depth=34,
+        num_stages=4,
+        out_indices=(3, ),
+        style='pytorch'),
+    neck=dict(type='GlobalAveragePooling'),
+    head=dict(
+        type='LinearClsHead',
+        num_classes=1000,
+        in_channels=512,
+        loss=dict(type='CrossEntropyLoss', loss_weight=1.0),
+        topk=(1, 5),
+    ))
+
+# algorithm setting
+algorithm = dict(
+    type='GeneralDistill',
+    architecture=dict(
+        type='MMClsArchitecture',
+        model=student,
+    ),
+    with_student_loss=True,
+    with_teacher_loss=False,
+    distiller=dict(
+        type='SingleTeacherDistiller',
+        teacher=teacher,
+        teacher_trainable=False,
+        teacher_norm_eval=True,
+        components=[
+            dict(
+                student_module='neck.gap',
+                teacher_module='neck.gap',
+                losses=[
+                    dict(
+                        type='DistanceWiseRKD',
+                        name='distance_wise_loss',
+                        loss_weight=25.0,
+                        with_l2_norm=True),
+                    dict(
+                        type='AngleWiseRKD',
+                        name='angle_wise_loss',
+                        loss_weight=50.0,
+                        with_l2_norm=True),
+                ])
+        ]),
+)
+
+find_unused_parameters = True
diff --git a/docs/en/dataset_prepare.md b/docs/en/dataset_prepare.md
@@ -0,0 +1,7 @@
+## Prepare datasets
+
+Currently our algorithms support [mmclassification](https://mmclassification.readthedocs.io/en/latest/),
+[mmdetection](https://mmdetection.readthedocs.io/en/latest/) and
+[mmsegmentation](https://mmsegmentation.readthedocs.io/en/latest/).
+Before running our algorithms, you may need to prepare the datasets according
+to the instructions in the corresponding document.
diff --git a/docs/en/imgs/model_zoo/rkd/pipeline.png b/docs/en/imgs/model_zoo/rkd/pipeline.png
diff --git a/docs/en/test.md b/docs/en/test.md
@@ -8,10 +8,20 @@ To test nas method, you can use following command
 python tools/${task}/test_${task}.py ${CONFIG_FILE} ${CHECKPOINT_PATH} --cfg-options algorithm.mutable_cfg=${MUTABLE_CFG_PATH} [optional arguments]
 ```
 
+- `task`: one of ``mmcls``、``mmdet`` and ``mmseg``
 - `MUTABLE_CFG_PATH`: Path of `mutable_cfg`. `mutable_cfg` represents **config for mutable of the subnet searched out**, used to specify different subnets for testing. An example for `mutable_cfg` can be found [here](https://github.com/open-mmlab/mmrazor/blob/master/configs/nas/spos/SPOS_SHUFFLENETV2_330M_IN1k_PAPER.yaml).
 
 The usage of optional arguments are the same as corresponding tasks like mmclassification, mmdetection and mmsegmentation.
 
+For example,
+
+<pre>
+python tools/mmcls/test_mmcls.py \
+  configs/nas/spos/spos_subnet_shufflenetv2_8xb128_in1k.py \
+  <em>your_subnet_checkpoint_path</em> \
+  --cfg-options algorithm.mutable_cfg=configs/nas/spos/SPOS_SHUFFLENETV2_330M_IN1k_PAPER.yaml
+</pre>
+
 ## Pruning
 
 ### Split Checkpoint(Optional)
@@ -27,6 +37,15 @@ python tools/model_converters/split_checkpoint.py ${CONFIG_FILE} ${CHECKPOINT_PA
 retrain a slimmable model, your command will be like `--cfg-options algorithm.channel_cfg=cfg1,cfg2,cfg3`.
 And your command here should be `--channel-cfgs cfg1 cfg2 cfg3`. The order of them should be the same.
 
+For example,
+
+<pre>
+python tools/model_converters/split_checkpoint.py \
+  configs/pruning/autoslim/autoslim_mbv2_subnet_8xb256_in1k.py \
+  <em>your_retraining_checkpoint_path</em> \
+  --channel-cfgs configs/pruning/autoslim/AUTOSLIM_MBV2_530M_OFFICIAL.yaml configs/pruning/autoslim/AUTOSLIM_MBV2_320M_OFFICIAL.yaml configs/pruning/autoslim/AUTOSLIM_MBV2_220M_OFFICIAL.yaml
+</pre>
+
 ### Test
 
 To test pruning method, you can use following command
@@ -35,12 +54,33 @@ To test pruning method, you can use following command
 python tools/${task}/test_${task}.py ${CONFIG_FILE} ${CHECKPOINT_PATH} --cfg-options algorithm.channel_cfg=${CHANNEL_CFG_PATH} [optional arguments]
 ```
 
+- `task`: one of ``mmcls``、``mmdet`` and ``mmseg``
 - `CHANNEL_CFG_PATH`: Path of `channel_cfg`. `channel_cfg` represents **config for channel of the subnet searched out**, used to specify different subnets for testing. An example for `channel_cfg` can be found [here](https://github.com/open-mmlab/mmrazor/blob/master/configs/pruning/autoslim/AUTOSLIM_MBV2_220M_OFFICIAL.yaml), and the usage can be found [here](https://github.com/open-mmlab/mmrazor/blob/master/configs/pruning/autoslim/README.md#test-a-subnet).
 
+For example,
+
+<pre>
+python ./tools/mmcls/test_mmcls.py \
+  configs/pruning/autoslim/autoslim_mbv2_subnet_8xb256_in1k.py \
+  <em>your_splitted_checkpoint_path</em> --metrics accuracy \
+  --cfg-options algorithm.channel_cfg=configs/pruning/autoslim/AUTOSLIM_MBV2_530M_OFFICIAL.yaml
+</pre>
+
+
 ## Distillation
 
 To test distillation method, you can use the following command
 
 ```bash
 python tools/${task}/test_${task}.py ${CONFIG_FILE} ${CHECKPOINT_PATH} [optional arguments]
 ```
+
+- `task`: one of ``mmcls``、``mmdet`` and ``mmseg``
+
+For example,
+
+<pre>
+python ./tools/mmseg/test_mmseg.py \
+  configs/distill/cwd/cwd_cls_head_pspnet_r101_d8_pspnet_r18_d8_512x1024_cityscapes_80k.py \
+  <em>your_splitted_checkpoint_path</em> --show
+</pre>