图像分类
========

1 简介
----

图像分类模块，提供各种主流的卷积神经网络用于进行图像分类任务的训练，目前已经支持的模型有：

-  ResNet系列

-  SE-ResNet系列

-  Inception系列

-  Vgg系列

-  MobileNet系列

-  EfficientNet系列

-  DarkNet系列

### Benchmark

| Model                | EasyVisionTop1 Acc | EasyVisionTop5 Acc |
| -------------------- | ------------------ | ------------------ |
| resnet_v1a_18        | 70.94              | 89.88              |
| resnet_v1a_34        | 74.26              | 91.97              |
| resnet_v1_50         | 75.20              | 92.20              |
| resnet_v1a_50        | 77.34              | 93.64              |
| resnet_v1b_50        | 77.52              | 93.76              |
| resnet_v1c_50        | 77.90              | 94.12              |
| resnet_v1d_50        | 79.01              | 94.51              |
| resnet_v1_101        | 76.40              | 92.89              |
| resnet_v1a_101       | 78.26              | 93.97              |
| resnet_v1b_101       | 79.05              | 94.60              |
| resnet_v1c_101       | 79.49              | 94.74              |
| resnet_v1d_101       | 80.36              | 95.04              |
| resnet_v1_152        | 76.80              | 93.17              |
| resnet_v1a_152       | 79.16              | 94.69              |
| resnet_v1b_152       | 79.52              | 94.81              |
| resnet_v1c_152       | 79.93              | 94.91              |
| resnet_v1d_152       | 80.48              | 95.31              |
|                      |                    |                    |
| SE-Resnet-v1-50      | 77.51              | 93.6               |
| SE-Resnet-v1-101     | 78.28              | 94.24              |
| SE-Resnet-v1-152     | 78.58              | 94.41              |
|                      |                    |                    |
| inception-v1         | 69.8               | 89.6               |
| inception-v2         | 73.9               | 91.8               |
| inception-v3         | 78.0               | 93.9               |
| inception-v4         | 80.2               | 95.2               |
|                      |                    |                    |
| mobilenet-v1-1.0_224 | 70.7               | 89.5               |
| mobilenet-v2-1.0_224 | 70.1               | 89.5               |
| mobilenet-v3-1.0_224 | 75.4               | 92.7               |
|                      |                    |                    |
| efficientnet-b0      | 0.7750             | 0.9360             |
| efficientnet-b1      | 0.7957             | 0.9437             |
| efficientnet-b2      | 0.8044             | 0.9503             |
| efficientnet-b3      | 0.8188             | 0.9566             |
| efficientnet-b4      | 0.8330             | 0.9640             |
| efficientnet-b5      | 0.8431             | 0.9694             |
| efficientnet-b6      | 0.8477             | 0.9713             |
| efficientnet-b7      | 0.8516             | 0.9725             |
| efficientnet-b8      | 0.8545             | 0.8524             |
|                      |                    |                    |
| darknet53            | 0.7664             | 0.9342             |
| cspdarknet53-mish    | 0.7794             | 0.9425             |



## 2 使用示例

下面我们以使用cifar10数据集，训练resnet_v1d_50模型为例，介绍如何训练一个分类模型



### 2.1 数据准备

cifar10我们已经提供了转换好的tfrecord， 下载cifar10到 `data` 文件夹下

```bash
ossutil cp -r oss://pai-vision-data-hz/data/cifar10/ data/cifar10
```

下载resnet50预训练模型到`pretrained_models`文件夹下

```bash
ossutil cp -r oss://pai-vision-data-hz/pretrained_models/resnet_v1d_50/ pretrained_models/resnet_v1d_50
```



### 2.2 模型训练

#### 2.2.1 文件配置形式

运行如下python代码即可启动文件配置形式的训练评估流程，样例配置文件参见[sample_config](../sample_config.html#)，配置文件参数说明参见[proto文档](../proto.html)。如果你使用了自定义的配置文件，把`easy_vision.RESNET50_FINETUNE_PRETRAINED_MODELS_SAMPLE_CONFIG` 替换为你的配置文件路径即可。

```python
import easy_vision
easy_vision.train_and_evaluate(easy_vision.RESNET50_FINETUNE_PRETRAINED_MODELS_SAMPLE_CONFIG)
```



#### 2.2.2 参数配置训练

运行如下python代码即可启动参数配置形式的训练评估流程

```python
import easy_vision
param_config = """
	--model_type Classification
  --backbone  resnet_v1d_50
  --num_classes 10
  --num_epochs 1
  --model_dir experiments/cifar10/resnet50_imagenet_pretrain
  --use_pretrained_model true
  --train_data data/cifar10/cifar10_train_part_*.tfrecord
  --test_data data/cifar10/cifar10_test.tfrecord
  --train_batch_size 96
  --test_batch_size 96
  --image_size 224
  --lr_type manual_step
  --initial_learning_rate 0.001
  --learning_rates 0.0003 0.0001
  --decay_epochs 35 40
  --save_checkpoint_epochs 5
  --staircase true"""
easy_vision.train_and_evaluate_with_param_config(param_config)
```

param_config 包含若干模型配置参数，格式遵循python argparser格式，各参数具体说明如下，所有字符串均不需要加引号

| 参数名称 | <div style="width:290px">参数描述</div> | 参数值格式 | 默认值 |
| --- | --- | --- | --- |
| model_type | 训练模型类型 | 字符串，可选范围<br />Classification | 无，必选参数 |
| backbone | 识别模型的网络名称 | 字符串格式，可取值范围：<br />vgg_16<br />vgg_19<br />inception_v1<br />inception_v2<br />inception_v3<br />inception_v4<br />mobilenet_v1<br />mobilenet_v2<br />mobilenet_v3<br />resnet_v1_50<br />resnet_v1_101<br />resnet_v1_152<br />resnet_v2_50<br />resnet_v2_101<br />resnet_v2_152<br />resnet_v1a_18<br />resnet_v1a_34<br />resnet_v1a_50<br />resnet_v1a_101<br />resnet_v1a_152<br />resnet_v1b_50<br />resnet_v1b_101<br />resnet_v1b_152<br />resnet_v1c_50<br />resnet_v1c_101<br />resnet_v1c_152<br />resnet_v1d_50<br />resnet_v1d_101<br />resnet_v1d_152<br />efficientnet-b0<br />efficientnet-b1<br />efficientnet-b2<br />efficientnet-b3<br />efficientnet-b4<br />efficientnet-b5<br />efficientnet-b6<br />efficientnet-b7<br />efficientnet-b8<br /> | "inception_v4" |
| weight_decay | l2 regularization的大小 | 浮点 | 1e-4 |
| num_classes | 分类类别数目 | 整型 | 无，必选参数 |
| image_size | 图片resize后大小 | 整型 例如224 | 224 |
| use_crop | 是否使用crop进行数据增强 | 布尔型<br /> | true |
| crop_min_area | 随机crop时候需要crop框满足与原图重叠的最小阈值 | 浮点 | 0.7 |
| eval_each_category | 是否针对每个类别单独做评估 | 布尔型 | false |
|  |  |  |  |
| optimizer | 优化方法，其中momentum就是sgd | 字符串，可选方法如下：<br />momentum<br />adam | momentum |
| lr_type | <div style="width:290px">学习率调整策略<br />exponential_decay, 指数衰减，详细参考[tf.train.exponential_decay ](https://www.tensorflow.org/api_docs/python/tf/train/exponential_decay)<br /><br />polynomial_decay, 多项式衰减，详细参考[tf.train.polynomial_decay](https://www.tensorflow.org/api_docs/python/tf/train/polynomial_decay)， 其中num_steps自动设置为总的训练迭代次数，end_learning_rate为initial_learning_rate的千分之一manual_step， 人工指定各阶段的学习率，通过decay_epochs 指定需要调整学习率的迭代轮数，通过learning_rates指定对应迭代轮数使用的学习率<br /><br />cosine_decay，通过余弦曲线调制学习率变化，最终会降到0。详细参考[论文](https://arxiv.org/abs/1608.03983)，通过decay_epochs 指定需要调整学习率的迭代轮数</div> | 字符串，可选方法如下：<br />exponential_decay<br />polynomial_decay<br />manual_step<br />cosine_decay | exponential_decay |
| initial_learning_rate | 初始学习率 | 浮点数 | 0.01 |
| decay_epochs | 如果使用exponential_decay, 参数对应 [tf.train.exponential_decay]()中的decay_steps，后端会自动根据训练数据总数把decay_epochs转换为decay_steps。例如数值可填：10，一般是总epoch数的1/2。<br /><br />如果使用manual_step， 参数表示需要调整学习率的迭代轮数， "16 18"表示在16epoch 18 epoch对学习率进行调整。一般这两个值取总设置的总epoch的8/10、9/10 | 整数列表<br />20 <br />20 40 60 | 20 |
| decay_factor | [tf.train.exponential_decay ](https://www.tensorflow.org/api_docs/python/tf/train/exponential_decay)中的decay_factor | 浮点数 | 0.95 |
| staircase | [tf.train.exponential_decay ](https://www.tensorflow.org/api_docs/python/tf/train/exponential_decay)中的staircase | 布尔 | true |
| power | [tf.train.polynomial_decay](https://www.tensorflow.org/api_docs/python/tf/train/polynomial_decay) 中的power | float | 0.9 |
| learning_rates | manual_step学习率调整策略中使用的参数，表示在指定epoch 学习率调整为多少. 如果您指定的调整epoch有两个，则需要在此也填写两个对应的学习率。例：decay_epoches为20 40，此处填写0.001 0.0001，则代表在20epoch学习率调整为0.001，40epoch学习率调整为0.0001。建议这几次调整的学习率是初始学习率的1/10、1/100、1/1000...... | manual_step学习率调整策略中使用的参数，表示在指定epoch 学习率调整为多少 | 浮点列表 |
| lr_warmup | 是否对学习率做warmup | 布尔 | false |
| lr_warm_up_epochs | 学习率warmup的轮数 | 浮点型 | 1 |
| train_data | 训练数据文件oss路径 | oss://path/to/train_*.tfrecord | 无，必选参数 |
| test_data | 训练过程中评估数据oss路径 | oss://path/to/test_*.tfrecord | 无，必选参数 |
| train_batch_size | 训练batch_size | 整型， 例如32 | 无，必选参数 |
| test_batch_size | 评估batch_size | 整型， 例如32 | 无，必选参数 |
| train_num_readers | 训练数据并发读取线程数 | 整型 | 4 |
| model_dir | 训练所用oss目录 | oss://path/to/model | 无，必选参数 |
| pretrained_model | 预训练模型oss路径，如果提供，会在此模型基础上finetune | oss://pai-vision-data-hz/pretrained_models/inception_v4.ckpt | "" |
| use_pretrained_model | 是否使用预训练模型 | 布尔型 | true |
| num_epochs | 训练迭代轮数，1表示所有训练数据过了一遍 | 整型  40 | 无，必选参数 |
| num_test_example | 训练过程中评估数据条目数， -1表示使用所有测试数据集数据 | 整型，例如2000 | 可选，默认-1 |
| num_visualizations | 评估过程可视化显示的样本数目 | 整型 | 10 |
| save_checkpoint_epochs | 保存checkpoint的频率，以epoch为单位， 1表示每过一遍训练数据保存一次checkpoint | 整型 | 1 |
| save_summary_epochs | 保存summary的频率，以epoch为单位， 0.01 表示每过1%训练数据保存一次summary | 浮点 | 0.01 |
| num_train_images | 总的训练样本数，如果使用自己生成的tfrecord需要提供该信息 | 整型 | 可选，默认0 |
| label_map_path | 类别映射文件，如果使用自己生成的tfrecord需要提供该信息 | 字符串 | 可选，默认"" |