diff --git a/docs/en/tutorials/config.md b/docs/en/tutorials/config.md new file mode 100644 index 0000000000000000000000000000000000000000..e5eb40139ad775dbd9f796e1a0118d848c9ddc01 --- /dev/null +++ b/docs/en/tutorials/config.md @@ -0,0 +1,84 @@ +#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",
"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| diff --git a/docs/en/tutorials/data.md b/docs/en/tutorials/data.md new file mode 100644 index 0000000000000000000000000000000000000000..ca4387c179f27cff54f7d62e7aef9f05c60394b6 --- /dev/null +++ b/docs/en/tutorials/data.md @@ -0,0 +1,77 @@ +# 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 +``` diff --git a/docs/en/tutorials/getting_started.md b/docs/en/tutorials/getting_started.md new file mode 100644 index 0000000000000000000000000000000000000000..8790faf9c037d9f5b7902eff96eabc922759bba8 --- /dev/null +++ b/docs/en/tutorials/getting_started.md @@ -0,0 +1,102 @@ +# 开始使用 +--- +请事先参考[安装指南](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 --port + +``` + + +### 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)。 diff --git a/docs/en/tutorials/index.rst b/docs/en/tutorials/index.rst index e763bccba0a46d851c8421ac8df4f4ef737eab67..1b3c3a53178e8e8c6ddcd2e82c1f87342be46933 100644 --- a/docs/en/tutorials/index.rst +++ b/docs/en/tutorials/index.rst @@ -1,9 +1,11 @@ -tutorials +初级使用 ================================ .. toctree:: :maxdepth: 1 install.md + quick_start.md + data.md getting_started.md - config.md + config.md \ No newline at end of file diff --git a/docs/en/tutorials/install.md b/docs/en/tutorials/install.md new file mode 100644 index 0000000000000000000000000000000000000000..b79f397b3052cc1bdb514c499c0c5219edf22f52 --- /dev/null +++ b/docs/en/tutorials/install.md @@ -0,0 +1,53 @@ +# 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 +``` diff --git a/docs/en/tutorials/quick_start.md b/docs/en/tutorials/quick_start.md new file mode 100644 index 0000000000000000000000000000000000000000..746d2c51ef57801421833b81a9ac152c4f506e01 --- /dev/null +++ b/docs/en/tutorials/quick_start.md @@ -0,0 +1,223 @@ +# 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