add tutorial en doc

be531fa0 · shippingwang · c161c9c8 · be531fa0 · be531fa0 · be531fa0
6 changed file
--- a/docs/en/tutorials/config.md
+++ b/docs/en/tutorials/config.md
+#Configuration
+
+---
+
+## Introduction
+
+This document introduces the configuration(filed in config/*.yaml) of PaddleClas.
+
+## Filed in config/*.yaml
+
+### Basic
+
+| name | detail | default value | optional value |
+|:---:|:---:|:---:|:---:|
+| mode | mode | "train" | ["train"," valid"] |
+| architecture | model name | "ResNet50_vd" | one of 23 architectures |
+| pretrained_model | pretrained model path | "" | Str |
+| model_save_dir | model stored path | "" | Str |
+| classes_num | class number | 1000 | int |
+| total_images | total images | 1281167 | int |
+| save_interval | save interval | 1 | int |
+| validate | whether to validate when training | TRUE | bool |
+| valid_interval | valid interval | 1 | int |
+| epochs | epoch |  | int |
+| topk | K value | 5 | int |
+| image_shape | image size | [3，224，224] | list, shape: (3,) |
+| use_mix | whether to use mixup | False | ['True', 'False'] |
+| ls_epsilon | label_smoothing epsilon value| 0 | float |
+
+### Optimizer & Learning rate
+
+learning rate
+
+| name | detail | default value |Optional value |
+|:---:|:---:|:---:|:---:|
+| function | decay type | "Linear" | ["Linear", "Cosine", <br> "Piecewise", "CosineWarmup"] |
+| params.lr | initial learning rate | 0.1 | float |
+| params.decay_epochs | milestone in piecewisedecay |  | list |
+| params.gamma | gamma in piecewisedecay | 0.1 | float |
+| params.warmup_epoch | warmup epoch | 5 | int |
+| parmas.steps | decay steps in lineardecay | 100 | int |
+| params.end_lr | end lr in lineardecay | 0 | float |
+
+optimizer
+
+| name | detail | default value | optional value |
+|:---:|:---:|:---:|:---:|
+| function | optimizer name | "Momentum" | ["Momentum", "RmsProp"] |
+| params.momentum | momentum value | 0.9 | float |
+| regularizer.function | regularizer method name | "L2" | ["L1", "L2"] |
+| regularizer.factor | regularizer factor | 0.0001 | float |
+
+### reader
+
+| name | detail |
+|:---:|:---:|
+| batch_size | batch size |
+| num_workers | worker number |
+| file_list | train list path |
+| data_dir | train  dataset path |
+| shuffle_seed | seed |
+
+processing
+
+| function name | attribute name | detail |
+|:---:|:---:|:---:|
+| DecodeImage | to_rgb | decode to RGB |
+|  | to_np | to numpy |
+|  | channel_first | Channel first |
+| RandCropImage | size | random crop |
+| RandFlipImage | | random flip |
+| NormalizeImage | scale | normalize image |
+|  | mean | mean |
+|  | std | std |
+|  | order | order |
+| ToCHWImage |  | to CHW |
+| CropImage | size | crop size |
+| ResizeImage | resize_short | resize according to short size |
+
+mix preprocessing
+
+| name| detail|
+|:---:|:---:|
+| MixupOperator.alpha | alpha value in mixup|
--- a/docs/en/tutorials/data.md
+++ b/docs/en/tutorials/data.md
+# Data
+
+---
+
+## 1. Introducation
+This document introduces the preparation of ImageNet1k and flowers102
+
+## 2. Dataset
+
+Dataset | train dataset size | valid dataset size | category |
+:------:|:---------------:|:---------------------:|:--------:|
+[flowers102](https://www.robots.ox.ac.uk/~vgg/data/flowers/102/)|1k | 6k | 102 |
+[ImageNet1k](http://www.image-net.org/challenges/LSVRC/2012/)|1.2M| 50k | 1000 |
+
+* Data format
+
+Please follow the steps mentioned below to organize data, include train_list.txt and val_list.txt
+
+```shell
+# delimiter: "space"
+
+ILSVRC2012_val_00000001.JPEG 65
+...
+
+```
+### ImageNet1k
+After downloading data, please organize the data dir as below
+
+```bash
+PaddleClas/dataset/imagenet/
+|_ train/
+|  |_ n01440764
+|  |  |_ n01440764_10026.JPEG
+|  |  |_ ...
+|  |_ ...
+|  |
+|  |_ n15075141
+|     |_ ...
+|     |_ n15075141_9993.JPEG
+|_ val/
+|  |_ ILSVRC2012_val_00000001.JPEG
+|  |_ ...
+|  |_ ILSVRC2012_val_00050000.JPEG
+|_ train_list.txt
+|_ val_list.txt
+```
+### Flowers102 Dataset
+
+Download [Data](https://www.robots.ox.ac.uk/~vgg/data/flowers/102/) then decompress:
+
+```shell
+jpg/
+setid.mat
+imagelabels.mat
+```
+
+Please put all the files under ```PaddleClas/dataset/flowers102```
+
+generate generate_flowers102_list.py and train_list.txt和val_list.txt
+
+```bash
+python generate_flowers102_list.py jpg train > train_list.txt
+python generate_flowers102_list.py jpg valid > val_list.txt
+
+```
+
+Please organize data dir as below
+
+```bash
+PaddleClas/dataset/flowers102/
+|_ jpg/
+|  |_ image_03601.jpg
+|  |_ ...
+|  |_ image_02355.jpg
+|_ train_list.txt
+|_ val_list.txt
+```
--- a/docs/en/tutorials/getting_started.md
+++ b/docs/en/tutorials/getting_started.md
+# 开始使用
+---
+请事先参考[安装指南](install.md)配置运行环境，并根据[数据说明](./data.md)文档准备ImageNet1k数据，本章节下面所有的实验均以ImageNet1k数据集为例。
+
+## 一、设置环境变量
+
+**设置PYTHONPATH环境变量：**
+
+```bash
+export PYTHONPATH=path_to_PaddleClas:$PYTHONPATH
+```
+
+## 二、模型训练与评估
+
+PaddleClas 提供模型训练与评估脚本：`tools/train.py`和`tools/eval.py`
+
+### 2.1 模型训练
+
+按照如下方式启动模型训练。
+
+```bash
+# PaddleClas通过launch方式启动多卡多进程训练
+# 通过设置FLAGS_selected_gpus 指定GPU运行卡号
+
+python -m paddle.distributed.launch \
+    --selected_gpus="0,1,2,3" \
+    tools/train.py \
+        -c ./configs/ResNet/ResNet50_vd.yaml
+```
+
+- 输出日志示例如下：
+
+```
+epoch:0    train    step:13    loss:7.9561    top1:0.0156    top5:0.1094    lr:0.100000    elapse:0.193
+```
+
+可以通过添加-o参数来更新配置：
+
+```bash
+python -m paddle.distributed.launch \
+    --selected_gpus="0,1,2,3" \
+    tools/train.py \
+        -c ./configs/ResNet/ResNet50_vd.yaml \
+        -o use_mix=1 \
+	--vdl_dir=./scalar/
+
+```
+
+- 输出日志示例如下：
+
+```
+epoch:0    train    step:522    loss:1.6330    lr:0.100000    elapse:0.210
+```
+
+也可以直接修改模型对应的配置文件更新配置。具体配置参数参考[配置文档](config.md)。
+
+训练期间可以通过VisualDL实时观察loss变化，启动命令如下：
+
+```bash
+visualdl --logdir ./scalar --host <host_IP> --port <port_num>
+
+```
+
+
+### 2.2 模型微调
+
+* [30分钟玩转PaddleClas](./quick_start.md)中包含大量模型微调的示例，可以参考该章节在特定的数据集上进行模型微调。
+
+### 2.3 模型评估
+
+```bash
+python tools/eval.py \
+    -c ./configs/eval.yaml \
+    -o ARCHITECTURE.name="ResNet50_vd" \
+    -o pretrained_model=path_to_pretrained_models
+```
+可以更改configs/eval.yaml中的`ARCHITECTURE.name`字段和pretrained_model字段来配置评估模型，也可以通过-o参数更新配置。
+
+**注意：** 加载预训练模型时，需要指定预训练模型的前缀，例如预训练模型参数所在的文件夹为`output/ResNet50_vd/19`，预训练模型参数的名称为`output/ResNet50_vd/19/ppcls.pdparams`，则`pretrained_model`参数需要指定为`output/ResNet50_vd/19/ppcls`，PaddleClas会自动补齐`.pdparams`的后缀。
+
+## 三、模型推理
+
+PaddlePaddle提供三种方式进行预测推理，接下来介绍如何用预测引擎进行推理：
+首先，对训练好的模型进行转换：
+
+```bash
+python tools/export_model.py \
+    --model=模型名字 \
+    --pretrained_model=预训练模型路径 \
+    --output_path=预测模型保存路径
+
+```
+之后，通过预测引擎进行推理：
+```bash
+python tools/infer/predict.py \
+    -m model文件路径 \
+    -p params文件路径 \
+    -i 图片路径 \
+    --use_gpu=1 \
+    --use_tensorrt=True
+```
+更多使用方法和推理方式请参考[分类预测框架](../extension/paddle_inference.md)。
--- a/docs/en/tutorials/index.rst
+++ b/docs/en/tutorials/index.rst
-tutorials
+初级使用
 ================================

 .. toctree::
   :maxdepth: 1
   
   install.md
+   quick_start.md
+   data.md
   getting_started.md
-   config.md
+   config.md
\ No newline at end of file
--- a/docs/en/tutorials/install.md
+++ b/docs/en/tutorials/install.md
+# Installation
+
+---
+
+## Introducation
+
+This document introduces how to install PaddleClas and its requirements.
+
+## Install PaddlePaddle
+
+Python 3.5, CUDA 9.0, CUDNN7.0 nccl2.1.2 and later version are required at first, For now, PaddleClas only support training on the GPU device. Please follow the instructions in the [Installation](http://www.paddlepaddle.org.cn/install/quick) if the PaddlePaddle on the device is lower than v1.7
+
+Install PaddlePaddle
+
+```bash
+pip install paddlepaddle-gpu --upgrade
+```
+
+or compile from source code, please refer to [Installation](http://www.paddlepaddle.org.cn/install/quick).
+
+Verify Installation
+
+```python
+import paddle.fluid as fluid
+fluid.install_check.run_check()
+```
+
+Check PaddlePaddle version：
+
+```bash
+python -c "import paddle; print(paddle.__version__)"
+```
+
+Note:
+- Make sure the compiled version is later than v1.7
+- Indicate **WITH_DISTRIBUTE=ON** when compiling, Please refer to [Instruction](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/install/Tables.html#id3) for more details.
+
+
+## Install PaddleClas
+
+**Clone PaddleClas: **
+
+```
+cd path_to_clone_PaddleClas
+git clone https://github.com/PaddlePaddle/PaddleClas.git
+```
+
+**Install requirements**
+
+
+```
+pip install --upgrade -r requirements.txt
+```
--- a/docs/en/tutorials/quick_start.md
+++ b/docs/en/tutorials/quick_start.md
+# Trial in 30mins
+
+Based on the flowers102 dataset, it takes only 30 mins to experience PaddleClas, include training varieties of backbone and pretrained model, SSLD distillation, and multiple data augmentation, Please refer to [Installation](install.md) to install at first.
+
+
+## Preparation
+
+* enter insatallation dir
+
+```
+cd path_to_PaddleClas
+```
+
+* enter `dataset/flowers102`, download and decompress flowers102 dataset.
+
+```shell
+cd dataset/flowers102
+wget https://www.robots.ox.ac.uk/~vgg/data/flowers/102/102flowers.tgz
+wget https://www.robots.ox.ac.uk/~vgg/data/flowers/102/imagelabels.mat
+wget https://www.robots.ox.ac.uk/~vgg/data/flowers/102/setid.mat
+tar -xf 102flowers.tgz
+```
+
+* create train/val/test label files
+
+```shell
+python generate_flowers102_list.py jpg train > train_list.txt
+python generate_flowers102_list.py jpg valid > val_list.txt
+python generate_flowers102_list.py jpg test > extra_list.txt
+cat train_list.txt extra_list.txt > train_extra_list.txt
+```
+
+**Note:** In order to offer more data to SSLD training task, train_list.txt and extra_list.txt will merge into train_extra_list.txft
+
+* return `PaddleClas` dir
+
+```
+cd ../../
+```
+
+## Environment
+
+### Set PYTHONPATH
+
+```bash
+export PYTHONPATH=./:$PYTHONPATH
+```
+
+### Download pretrained model
+
+
+```bash
+python tools/download.py -a ResNet50_vd -p ./pretrained -d True
+python tools/download.py -a ResNet50_vd_ssld -p ./pretrained -d True
+python tools/download.py -a MobileNetV3_large_x1_0 -p ./pretrained -d True
+```
+
+Paramters：
+ `architecture`(shortname: a): model name.
+ `path`(shortname: p) download path.
+ `decompress`(shortname: d) whether to decompress.
+
+
+
+* All experiments are running on the NVIDIA® Tesla® V100 sigle card.
+
+
+## Training
+
+### Train from scratch
+
+* Train ResNet50_vd
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/ResNet50_vd.yaml
+
+```
+
+The validation `Top1 Acc` curve is showmn below.
+
+![](../../images/quick_start/r50_vd_acc.png)
+
+
+### Finetune - ResNet50_vd pretrained model (Acc 79.12\%)
+
+* finetune ResNet50_vd_ model pretrained on the 1000-class Imagenet dataset
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/ResNet50_vd_finetune.yaml
+
+```
+
+The validation `Top1 Acc` curve is shown below
+
+![](../../images/quick_start/r50_vd_pretrained_acc.png)
+
+Compare with training from scratch, it improve by 65\% to 94.02\%
+
+
+### SSLD finetune - ResNet50_vd_ssld pretrained model (Acc 82.39\%)
+
+Note: when finetuning model, which has been trained by SSLD, please use smaller learning rate in the middle of net.
+
+```yaml
+ARCHITECTURE:
+    name: 'ResNet50_vd'
+    params:
+        lr_mult_list: [0.1, 0.1, 0.2, 0.2, 0.3]
+pretrained_model: "./pretrained/ResNet50_vd_ssld_pretrained"
+```
+
+Tringing script
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/ResNet50_vd_ssld_finetune.yaml
+```
+
+Compare with finetune on the 79.12% pretrained model, it improve by 0.9% to 95%.
+
+
+### More architecture - MobileNetV3
+
+Training script
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/MobileNetV3_large_x1_0_finetune.yaml
+```
+
+Compare with ResNet50_vd pretrained model, it decrease by 5% to 90%. Different architecture generates different performance, actually it is a task-oriented decision to apply the best performance model, should consider the inference time, storage, heterogeneous device, etc.
+
+
+### RandomErasing
+
+Data augmentation works when training data is small.
+
+Training script
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/ResNet50_vd_ssld_random_erasing_finetune.yaml
+```
+
+It improves by 1.27\% to 96.27\%
+
+* Save ResNet50_vd pretrained model to experience next chapter.
+
+```shell
+cp -r output/ResNet50_vd/19/  ./pretrained/flowers102_R50_vd_final/
+```
+
+### Distillation
+
+* Use extra_list.txt as unlabeled data, Note:
+    * Samples in the `extra_list.txt` and `val_list.txt` don't have intersection
+    * Because of in the source code, label information is unused, This is still unlabeled distillation
+    * Teacher model use the pretrained_model trained on the flowers102 dataset, and student model use the MobileNetV3_large_x1_0 pretrained model(Acc 75.32\%) trained on the ImageNet1K dataset
+
+
+```yaml
+total_images: 7169
+ARCHITECTURE:
+    name: 'ResNet50_vd_distill_MobileNetV3_large_x1_0'
+pretrained_model:
+    - "./pretrained/flowers102_R50_vd_final/ppcls"
+    - "./pretrained/MobileNetV3_large_x1_0_pretrained/”
+TRAIN:
+    file_list: "./dataset/flowers102/train_extra_list.txt"
+```
+
+Final training script
+
+```shell
+export CUDA_VISIBLE_DEVICES=0
+python -m paddle.distributed.launch \
+    --selected_gpus="0" \
+    tools/train.py \
+        -c ./configs/quick_start/R50_vd_distill_MV3_large_x1_0.yaml
+```
+
+It significantly imporve by 6.47% to 96.47% with more unlabeled data and teacher model.
+
+### All accuracy
+
+
+|Configuration | Top1 Acc |
+|- |:-: |
+| ResNet50_vd.yaml | 0.2735 |
+| MobileNetV3_large_x1_0_finetune.yaml | 0.9000 |
+| ResNet50_vd_finetune.yaml | 0.9402 |
+| ResNet50_vd_ssld_finetune.yaml | 0.9500 |
+| ResNet50_vd_ssld_random_erasing_finetune.yaml | 0.9627 |
+| R50_vd_distill_MV3_large_x1_0.yaml | 0.9647 |
+
+
+The whole accuracy curves are shown below
+
+
+![](../../images/quick_start/all_acc.png)
+
+
+
+* **NOTE**: As flowers102 is a small dataset, validatation accuracy maybe float 1%.
+
+* Please refer to [Getting_started](./getting_started) for more details