From 5e17dd7cd4a765e331fa5500b4972822844ed206 Mon Sep 17 00:00:00 2001
From: Zaida Zhou <58739961+zhouzaida@users.noreply.github.com>
Date: Tue, 23 Aug 2022 11:55:18 +0800
Subject: [PATCH] [Docs] Add speed training examples (#408)

* [Docs] Add speed training examples

* refine

* refine

* rename filename

* minor refine
---
 docs/zh_cn/examples/speed_up_training.md | 77 ++++++++++++++++++++++++
 docs/zh_cn/index.rst                     |  6 ++
 2 files changed, 83 insertions(+)
 create mode 100644 docs/zh_cn/examples/speed_up_training.md

diff --git a/docs/zh_cn/examples/speed_up_training.md b/docs/zh_cn/examples/speed_up_training.md
new file mode 100644
index 00000000..131bf88c
--- /dev/null
+++ b/docs/zh_cn/examples/speed_up_training.md
@@ -0,0 +1,77 @@
+# 加速训练
+
+## 分布式训练
+
+MMEngine 支持 CPU、单卡、单机多卡以及多机多卡的训练。当环境中有多张显卡时，我们可以使用以下命令开启单机多卡或者多机多卡的方式从而缩短模型的训练时间。
+
+- 单机多卡
+
+假设当前机器有 8 张显卡，可以使用以下命令开启多卡训练
+
+```bash
+python -m torch.distributed.launch --nproc_per_node=8 examples/train.py --launcher pytorch
+```
+
+如果需要指定显卡的编号，可以设置 `CUDA_VISIBLE_DEVICES` 环境变量，例如使用第 0 和第 3 张卡
+
+```bash
+CUDA_VISIBLE_DEVICES=0,3 python -m torch.distributed.launch --nproc_per_node=2 examples/train.py --launcher pytorch
+```
+
+- 多机多卡
+
+假设有 2 台机器，每台机器有 8 张卡。
+
+第一台机器运行以下命令
+
+```bash
+python -m torch.distributed.launch \
+    --nnodes 8 \
+    --node_rank 0 \
+    --master_addr 127.0.0.1 \
+    --master_port 29500 \
+    --nproc_per_node=8 \
+    examples/train.py --launcher pytorch
+```
+
+第 2 台机器运行以下命令
+
+```bash
+python -m torch.distributed.launch \
+    --nnodes 8 \
+    --node_rank 1 \
+    --master_addr 127.0.0.1 \
+    --master_port 29500 \
+    --nproc_per_node=8 \
+    examples/train.py --launcher pytorch
+```
+
+如果在 slurm 集群运行 MMEngine，只需运行以下命令即可开启 2 机 16 卡的训练
+
+```bash
+srun -p mm_dev \
+    --job-name=test \
+    --gres=gpu:8 \
+    --ntasks=16 \
+    --ntasks-per-node=8 \
+    --cpus-per-task=5 \
+    --kill-on-bad-exit=1 \
+    python examples/train.py --launcher="slurm"
+```
+
+## 混合精度训练
+
+Nvidia 在 Volta 和 Turing 架构中引入 Tensor Core 单元，来支持 FP32 和 FP16 混合精度计算。开启自动混合精度训练后，部分算子的操作精度是 FP16，其余算子的操作精度是 FP32。这样在不改变模型、不降低模型训练精度的前提下，可以缩短训练时间，降低存储需求，因而能支持更大的 batch size、更大模型和尺寸更大的输入的训练。[PyTorch 从 1.6 开始官方支持 amp](https://pytorch.org/blog/accelerating-training-on-nvidia-gpus-with-pytorch-automatic-mixed-precision/)。如果你对自动混合精度的实现感兴趣，可以阅读 [torch.cuda.amp: 自动混合精度详解](https://zhuanlan.zhihu.com/p/348554267)。
+
+MMEngine 提供自动混合精度的封装 [AmpOptimWrapper](https://mmengine.readthedocs.io/zh_cn/latest/api.html#mmengine.optim.AmpOptimWrapper) ，只需在 `optim_wrapper` 设置 `type='AmpOptimWrapper'` 即可开启自动混合精度训练，无需对代码做其他修改。
+
+```python
+runner = Runner(
+    model=ResNet18(),
+    work_dir='./work_dir',
+    train_dataloader=train_dataloader_cfg,
+    optim_wrapper=dict(type='AmpOptimWrapper', optimizer=dict(type='SGD', lr=0.001, momentum=0.9)),
+    train_cfg=dict(by_epoch=True, max_epochs=3),
+)
+runner.train()
+```
diff --git a/docs/zh_cn/index.rst b/docs/zh_cn/index.rst
index 05afd9f4..9656971b 100644
--- a/docs/zh_cn/index.rst
+++ b/docs/zh_cn/index.rst
@@ -25,6 +25,12 @@
    tutorials/logging.md
    tutorials/visualizer.md
 
+.. toctree::
+   :maxdepth: 1
+   :caption: 示例
+
+   examples/speed_up_training.md
+
 .. toctree::
    :maxdepth: 2
    :caption: API 文档