updata ThesisReproduction_CV (#5355)

docs/ThesisReproduction_CV.md

@@ -11,7 +11,7 @@
 
 ### 1.2 前序工作
 
-基于本文规范复现论文过程中，建议开发者准备以下内容。
+基于本指南复现论文过程中，建议开发者准备以下内容。
 
 * 了解该模型输入输出格式。以AlexNet图像分类任务为例，通过阅读论文与参考代码，了解到模型输入为`[batch_size, 3, 224, 244]`的tensor，类型为`float32`或者`float16`，label为`[batch, ]`的label，类型为`int64`。
 * 准备好训练/验证数据集，用于模型训练与评估
@@ -27,21 +27,21 @@
 
 ### 2.1 流程概览
 
-基于通用的计算机视觉任务，论文复现整体流程图如下所示。
+面对一篇计算机视觉论文，复现该论文的整体流程如下图所示。
 
 ![图片](images/framework.png)
 
+总共包含11个步骤。为了高效复现论文，设置了5个验收节点。如上图中黄色框所示。后续章节会详细介绍上述步骤和验收节点，具体内容安排如下：
 
-总共包含11个步骤，为了高效复现论文，设置了5个验收节点。如上图中黄色框所示。对应地，第3章到第5章的内容安排如下：
-
-* 第3章：介绍11个复现步骤的理论知识以及操作方法
+* 第3章：介绍11个复现步骤的理论知识以及实战
 * 第4章：介绍5个验收节点的自查与验收方法
-* 第5章：针对第3章在复现流程过程中可能出现的问题，在第5章会进行详细介绍。如果还是不能解决问题的话，可以进交流群讨论
+* 第5章：针对复现流程过程中每个步骤可能出现的问题，本章会进行详细介绍。如果还是不能解决问题，可以提ISSUE或进交流群讨论
 
 
-### 2.2 reprod_log whl包使用说明
+### 2.2 reprod_log whl包
 
-`reprod_log`是用于论文复现赛自动化测试和验收的工具，源代码地址在：[https://github.com/WenmuZhou/reprod_log](https://github.com/WenmuZhou/reprod_log)。主要功能包括：
+#### 2.2.1 reprod_log工具简介
+`reprod_log`是用于论文复现赛中辅助自查和验收工具。该工具源代码地址在：[https://github.com/WenmuZhou/reprod_log](https://github.com/WenmuZhou/reprod_log)。主要功能如下：
 
 * 存取指定节点的输入输出tensor
 * 基于文件的tensor读写
@@ -96,9 +96,9 @@
                 * diff_threshold (float): 阈值，如果diff大于该阈值，则核验失败，默认为`1e-6`
                 * path (str): 日志保存的路径，默认为`./diff.txt`
 
-### 2.3 使用demo
+#### 2.2.2 reprod_log使用demo
 
-下面基于代码：[https://github.com/littletomatodonkey/AlexNet-Prod/tree/master/pipeline/reprod_log_demo](https://github.com/littletomatodonkey/AlexNet-Prod/tree/master/pipeline/reprod_log_demo)，给出详细的工具包API使用功能。
+下面基于代码：[https://github.com/littletomatodonkey/AlexNet-Prod/tree/master/pipeline/reprod_log_demo](https://github.com/littletomatodonkey/AlexNet-Prod/tree/master/pipeline/reprod_log_demo)，给出如何使用该工具。
 
 文件夹中包含`write_log.py`和`check_log_diff.py`文件，其中`write_log.py`中给出了`ReprodLogger`类的使用方法，`check_log_diff.py`给出了`ReprodDiffHelper`类的使用方法，依次运行两个python文件，使用下面的方式运行代码。
 
@@ -123,9 +123,9 @@ python3.7 check_log_diff.py
 
 可以看出：对于key为`demo_test_1`的矩阵，由于diff为0，小于设置的阈值`1e-6`，核验成功；对于key为`demo_test_2`的矩阵，由于diff为0.33，大于设置的阈值`1e-6`，核验失败。
 
-### 2.4 论文复现赛自动化测试
+#### 2.2.3 reprod_log在论文复现中应用
 
-假设基于上述工具的结果记录模块，产出下面若干文件
+在论文复现中，基于reprod_log的结果记录模块，产出下面若干文件
 ```
 log_reprod
 ├── forward_paddle.npy
@@ -140,7 +140,7 @@ log_reprod
 ├── train_align_benchmark.npy # PaddlePaddle提供的参考评估指标
 ```
 
-使用该工具中的`ReprodDiffHelper`模块，产出下面的日志文件。
+基于reprod_log的`ReprodDiffHelper`模块，产出下面5个日志文件。
 
 ```
 ├── forward_diff.log     # forward_paddle.npy与forward_torch.npy生成的diff结果文件
@@ -150,79 +150,11 @@ log_reprod
 ├── train_align_diff.log # train_align_paddle.npy与train_align_benchmark.npy生成的diff结果文件
 ```
 
-5个结果文件中，会显示基于`repod_log`的检查结果。
-
-下面以后续的前向对齐为例，介绍下基于`repord_log`工具对齐的检查流程。其中与`reprod_log`工具有关的部分都是需要开发者需要去添加的部分。
-
-具体代码地址为：[https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/pipeline/Step1/AlexNet_paddle/forward_alexnet.py](https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/pipeline/Step1/AlexNet_paddle/forward_alexnet.py)。
-
-下载代码后，按照下面的步骤运行脚本。
-
-```shell
-# 进入文件夹
-cd pipeline/Step1/
-# 下载预训练模型
-wget -P ../weights https://paddle-model-ecology.bj.bcebos.com/model/alexnet_reprod/alexnet_paddle.pdparams
-wget -P ../weights https://paddle-model-ecology.bj.bcebos.com/model/alexnet_reprod/alexnet-owt-7be5be79.pth
-
-# 生成paddle的前向数据
-cd AlexNet_paddle/ && python3.7 forward_alexnet.py
-# 生成torch的前向数据
-cd ../AlexNet_torch && python3.7 forward_alexnet.py
-# 对比生成log
-cd ..
-python3.7 check_step1.py
-```
-
-以PaddlePaddle为例，`forward_alexnet.py`的具体代码如下所示。
-
-```python
-import numpy as np
-import paddle
-# 导入模型
-from paddlevision.models.alexnet import alexnet
-# 导入reprod_log中的ReprodLogger类
-from reprod_log import ReprodLogger
-
-reprod_logger = ReprodLogger()
-# 组网并初始化
-model = alexnet(pretrained="../../weights/alexnet_paddle.pdparams" num_classes=1000)
-model.eval()
-# 读入fake data并转换为tensor，这里也可以固定seed在线生成fake data
-fake_data = np.load("../../fake_data/fake_data.npy")
-fake_data = paddle.to_tensor(fake_data)
-# 模型前向
-out = model(fake_data)
-# 保存前向结果，对于不同的任务，需要开发者添加。
-reprod_logger.add("logits", fake_data.cpu().detach().numpy())
-reprod_logger.save("forward_paddle.npy")
-```
-
-diff检查的代码可以参考：[check_step1.py](https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/pipeline/Step1/check_step1.py)，具体代码如下所示。
-
-```python
-# https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/pipeline/Step1/check_step1.py
-# 使用reprod_log排查diff
-from reprod_log import ReprodDiffHelper
-if __name__ == "__main__":
-    diff_helper = ReprodDiffHelper()
-    torch_info = diff_helper.load_info("AlexNet_torch/forward_torch.npy")
-    paddle_info = diff_helper.load_info("AlexNet_paddle/forward_paddle.npy")
-    diff_helper.compare_info(torch_info, paddle_info)
-    diff_helper.report(path="forward_diff.log")
-```
-
-产出日志如下。
-
-```
-2021-09-27 10:35:46,172 - reprod_log.utils - INFO - logits:
-2021-09-27 10:35:46,173 - reprod_log.utils - INFO -     mean diff: check passed: True, value: 0.0
-2021-09-27 10:35:46,173 - reprod_log.utils - INFO - diff check passed
-```
+上述文件的生成代码都需要开发者进行开发，验收时需要提供上面罗列的所有文件（不需要提供产生这些文件的可运行程序）以及完整的模型训练评估程序和日志。
+AlexNet-Prod项目提供了基于reprod_log的5个验收点对齐验收示例，具体代码地址为：[https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/pipeline/](https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/pipeline/)，
+每个文件夹中的README.md文档提供了使用说明。
 
-平均绝对误差为0，测试通过。
-
-## 3. 论文复现赛操作流程规范
+## 3. 论文复现理论知识以及实战
 
 ### 3.1 模型结构对齐
 
@@ -230,23 +162,40 @@ if __name__ == "__main__":
 
 * 网络结构代码转换
 * 权重转换
-* 给定完全相同输入，生成tensor，验证模型的正确性
+* 模型组网正确性验证
 
 下面详细介绍这3个部分。
 
 #### 3.1.1 网络结构代码转换
 
-由于PyTorch的API和PaddlePaddle的API非常相似，所以组网部分代码直接手动转换即可。如果是PaddlePaddle没有的API，可以尝试用多种API来组合，高优的API如果希望获得支持，也可以提给PaddlePaddle团队提[ISSUE](https://github.com/PaddlePaddle/Paddle/issues)。API对应的列表也可以参考：[PyTorch-PaddlePaddle API映射表](https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/08_api_mapping/pytorch_api_mapping_cn.html)。
+**【基本流程】**
+
+由于PyTorch的API和PaddlePaddle的API非常相似，可以参考[PyTorch-PaddlePaddle API映射表](https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/08_api_mapping/pytorch_api_mapping_cn.html)
+，组网部分代码直接进行手动转换即可。
+
+**【注意事项】**
+
+如果遇到PaddlePaddle没有的API，可以尝试用多种API来组合，也可以给PaddlePaddle团队提[ISSUE](https://github.com/PaddlePaddle/Paddle/issues)，获得支持。
 
-对于AlexNet，PyTorch实现为: [alexnet-pytorch](https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/AlexNet-torch/torchvision/models/alexnet.py)， 复现的PaddlePaddle实现为: [alexnet-paddle](https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/AlexNet-paddle/paddlevision/models/alexnet.py)。
+**【实战】**
+
+对于AlexNet网络结构的PyTorch实现 [alexnet-pytorch](https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/AlexNet-torch/torchvision/models/alexnet.py)，[alexnet-paddle](https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/AlexNet-paddle/paddlevision/models/alexnet.py) 提供了网络结构代码转换为PaddlePaddle的实现。
 
 #### 3.1.2 权重转换
 
+**【基本流程】**
+
 组网代码转换完成之后，需要对模型权重进行转换，如果PyTorch repo中已经提供权重，那么可以直接下载并进行后续的转换；如果没有提供，则可以基于PyTorch代码，随机生成一个初始化权重(定义完model以后，使用`torch.save()` API保存模型权重)，然后进行权重转换。
 
+**【注意事项】**
+
+在权重转换的时候，需要注意`paddle.nn.Linear`以及`paddle.nn.BatchNorm2D`等API的权重保存格式和名称等与PyTorch稍有diff，具体内容可以参考`5.1章节`。
+
+**【实战】**
+
 AlexNet的代码转换脚本可以在这里查看：[https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/pipeline/weights/torch2paddle.py](https://github.com/littletomatodonkey/AlexNet-Prod/blob/master/pipeline/weights/torch2paddle.py)，核心函数如下所示。
 
-注：运行该代码需要首先下载PyTorch的AlexNet预训练模型到该目录下，下载地址为：[https://download.pytorch.org/models/alexnet-owt-7be5be79.pth](https://download.pytorch.org/models/alexnet-owt-7be5be79.pth)
+注意：运行该代码需要首先下载PyTorch的AlexNet预训练模型到该目录下，下载地址为：[https://download.pytorch.org/models/alexnet-owt-7be5be79.pth](https://download.pytorch.org/models/alexnet-owt-7be5be79.pth)
 
 ```python
 # https://github.com/littletomatodonkey/AlexNet-Prod/blob/d7b1977c2043a346b3fee0039949d5334fb990a3/pipeline/weights/torch2paddle.py#L6
@@ -277,27 +226,32 @@ transfer()
 
 运行完成之后，会在这里生成`alexnet_paddle.pdparams`文件，为PaddlePaddle的预训练模型。
 
-在权重转换的时候，需要注意`paddle.nn.Linear`以及`paddle.nn.BatchNorm2D`等API的权重保存格式和名称等与PyTorch稍有diff，具体内容可以参考`5.1章节`。
-
 
 #### 3.1.3 模型组网正确性验证
 
-* 操作流程
+**【基本流程】**
+
     * 定义PyTorch模型，加载权重，固定seed，基于numpy生成随机数，转换为PyTorch可以处理的tensor，送入网络，获取输出，使用reprod_log保存结果。
     * 定义PaddlePaddle模型，加载权重，固定seed，基于numpy生成随机数，转换为PaddlePaddle可以处理的tensor，送入网络，获取输出，使用reprod_log保存结果。
     *  使用reprod_log排查diff，小于阈值，即可完成自测。
-* 注意事项
+    
+**【注意事项】**
+
     * 模型在前向对齐验证时，需要调用`model.eval()`方法，保证组网中的随机量被关闭，比如BatchNorm、Dropout等。
-    * 给定相同的输入数据，为保证可复现性，建议随机数生成时，固定seed进行生成。
-    * 输出diff可以使用`np.mean(np.abs(o1 - o2))`进行计算，一般小于1e-6的话，可以认为前向没有问题。
-    * 如果最终输出结果diff较大，可以使用二分的方法进行排查，比如说ResNet50，包含1个stem、4个res-stage、global avg-pooling以及最后的fc层，那么完成模型组网和权重转换之后，如果模型输出没有对齐，可以尝试输出中间某一个res-stage的tensor进行对比，如果相同，则向后进行排查；如果不同，则继续向前进行排查，以此类推，直到找到导致没有对齐的操作。
+    * 给定相同的输入数据，为保证可复现性，如果有随机数生成，固定相关的随机种子。
+    * 输出diff可以使用`np.mean(np.abs(o1 - o2))`进行计算，一般小于1e-6的话，可以认为前向没有问题。如果最终输出结果diff较大，可以使用二分的方法进行排查，比如说ResNet50，包含1个stem、4个res-stage、global avg-pooling以及最后的fc层，那么完成模型组网和权重转换之后，如果模型输出没有对齐，可以尝试输出中间某一个res-stage的tensor进行对比，如果相同，则向后进行排查；如果不同，则继续向前进行排查，以此类推，直到找到导致没有对齐的操作。
 
+**【实战】**
 
-### 3.2 验证/测试集数据读取对齐
+AlexNet模型组网正确性验证可以参考如下示例代码：
+[https://github.com/littletomatodonkey/AlexNet-Prod/tree/master/pipeline/Step1](https://github.com/littletomatodonkey/AlexNet-Prod/tree/master/pipeline/Step1)
 
+### 3.2 验证/测试集数据读取对齐
 
 #### 3.2.1 数据集类Dataset复现方法
 
+**【基本流程】**
+
 对于一个数据集，一般有以下一些信息需要重点关注
 
 * 数据集名称、下载地址
@@ -305,9 +259,11 @@ transfer()
 * 数据集标注格式、标注信息
 * 数据集通用的预处理方法
 
-PaddlePaddle中数据集类为`paddle.io.Dataset`，PyTorch中对应为`torch.utils.data.Dataset`，二者功能一致，在绝大多数情况下，可以使用该类构建数据集。它是描述Dataset方法和行为的抽象类，在具体实现的时候，需要继承这个基类，实现其中的`__getitem__`和`__len__`方法。更多使用细节可以参考论文中的说明。
+PaddlePaddle中数据集相关的API为`paddle.io.Dataset`，PyTorch中对应为`torch.utils.data.Dataset`，二者功能一致，在绝大多数情况下，可以使用该类构建数据集。它是描述Dataset方法和行为的抽象类，在具体实现的时候，需要继承这个基类，实现其中的`__getitem__`和`__len__`方法。除了参考代码中相关实现，也可以参考待复现论文中的说明。
 
-论文中一般会提供数据集的名称以及基本信息。复现过程中，我们在下载完数据之后，建议先检查下是否和论文中描述一致，否则可能存在的问题有：
+**【注意事项】**
+
+此外，论文中一般会提供数据集的名称以及基本信息。复现过程中，我们在下载完数据之后，建议先检查下是否和论文中描述一致，否则可能存在的问题有：
 
 * 数据集年份不同，比如论文中使用了MS-COCO2014数据集，但是我们下载的是MS-COCO2017数据集，如果不对其进行检查，可能会导致我们最终训练的数据量等与论文中有diff
 * 数据集使用方式不同，有些论文中，可能只是抽取了该数据集的子集进行方法验证，此时需要注意抽取方法，需要保证抽取出的子集完全相同
@@ -318,6 +274,9 @@ PaddlePaddle中数据集类为`paddle.io.Dataset`，PyTorch中对应为`torch.ut
 * 有些自定义的数据处理方法，如果不涉及到深度学习框架的部分，可以直接复用。
 * 对于特定任务中的数据预处理方法，比如说图像分类、检测、分割等，如果没有现成的API可以调用，可以参考官方模型套件中的一些实现方法，比如PaddleClas、PaddleDetection、PaddleSeg等。
 
+**【实战】**
+
+
 #### 3.2.2 数据加载器Dataloader复现方法
 
 复现完Dataset之后，可以构建Dataloader，对数据进行组batch、批处理，送进网络进行计算。
@@ -392,9 +351,6 @@ INFO:reprod_log.utils:  mean diff: check passed: True, value: 0.0
 INFO:reprod_log.utils:diff check passed
 ```
 
-
-
-
 ### 3.3 评估指标对齐
 
 #### 3.3.1 复现方法
@@ -751,7 +707,7 @@ python3.7 -m paddle.distributed.launch \
 注意：这里8卡训练时，虽然单卡的batch size没有变化(32)，但是总卡的batch size相当于是单卡的8倍，因此学习率也设置为了单卡时的8倍。
 
 
-## 4. 验收点与验收方法
+## 4. 验收节点自查与验收方法
 
 ### 4.1 模型结构对齐验收方法