# ResNet50 部署手册

本文档介绍了如何在墨芯 AI 加速卡上使用 SOLA 部署 ResNet50 模型。

## 模型概览

关于 ResNet50 模型介绍可以参考 [Deep Residual Learning for Image Recognition](https://arxiv.org/abs/1512.03385) 。

### 模型信息
* 输入: RGB 图片, 分辨率处理为 224(h)x224(w)
* 输出: 图片分类标签
* data type: int8 / bf16

### 数据信息
数据来源：[ImageNet Large Scale Visual Recognition Challenge 2012 (ILSVRC2012)](https://image-net.org/challenges/LSVRC/2012/2012-downloads.php) - Validation Images

本示例参照 MLPerf Offline 模式运行，一次性加载所有图片预处理数据，再进行分批推理。

MLPref Offline ResNet50 输入输出数据如下:
* 总图片数量: 50000
* 输入:
  * uint8: [ 50000, 224, 224, 3 ] dtype=uint8, 以二进制格式保存
  * bf16: [ 50000, 224, 224, 8 ] dtype=bf16, 以二进制格式保存
* 输出: [ 50000, 1024 ] dtype=int64, 以二进制格式保存


## 流程介绍

部署模型分为四个步骤：下载、编译、运行、验证，每个步骤都提供了对应的默认脚本。

下载：`prepare.sh`

编译：`build.sh`

运行：`run.sh`

验证：`verify.sh`

你也可以参考以下步骤手动部署模型。

### 部署步骤

1. 下载模型和数据集

   可以执行以下脚本下载模型依赖，下载后会自动下载执行所需文件：
    ```bash
    ./prepare.sh
    ```
   `prepare.sh` 默认下载文件包括： 
   - resnet50 uint8 模型
   - resnet50 bf16 模型
   - resnet50 uint8 预处理数据集和标签

   因 resnet50 bf16 预处理数据太大（8.3G），如果需要测试 resnet50 bf16，请自行下载 resnet50 bf16 预处理数据，通过以下命令下载和解压：
   ```bash
   # 下载
   wget -P data/ https://moffett-oss-bucket01.oss-cn-shenzhen.aliyuncs.com/sola-demo/resnet50/resnet50_data_bf16.tar.gz
   
   # 解压
   tar -xzf data/resnet50_data_bf16.tar.gz -C data/resnet50_data
   ```

   如果需要从原始图片开始生成模型执行所需的预处理数据，可以遵循下列步骤：
    ```bash
    # 1. 自行下载所需测试的原始图片的数据集，图片和标签按照如下方式存放
    data/resnet50_demo/ILSVRC2012_img_val/XXXX.JPEG
    data/resnet50_demo/ILSVRC2012_validation_ground_truth_caffe.txt
    
    # 2. 手动执行预处理命令（需要 python 环境，激活方式见主目录 README.md）
    python -s scripts/gen.py --image_dir data/resnet50_demo/ILSVRC2012_img_val --val_map_path data/resnet50_demo/ILSVRC2012_validation_ground_truth_caffe.txt --cache_dir data/resnet50_data/ --duplicate 1
    ```
   
2. 编译部署代码

    ```bash
    ./build.sh
    ```

3. 运行

   可以执行以下脚本运行，默认运行 resnet50 uint8 版本：
    ```bash
    ./run.sh
    ```
   或者按照以下指令运行：
   ```bash
   usage: ./build/resnet50 --module=string --inputs=string --labels=string [options] ... 
   options:
     -m, --module         module file path (string)
     -i, --inputs         input file path (string)
     -o, --labels         label file path (string)
     -d, --devices        select devices (string [=all])
     -f, --format         running mode: broadcast / split (string [=broadcast])
     -c, --count          count of duplication (int [=1])
     -b, --batch          run batch size (int [=4])
     -v, --verify_path    save verification result json path (string [=])
     -?, --help           print this message
   ```
   其中`-d`可以指定运行设备（使用`,`分割），`-f`指定运行模式（broadcast/split），`-c`指定运行次数，`-b`指定需要运行的 batch size（4的倍数），如：
   ```bash
   # 在 device 0 上按照 batch size 4 进行推理
   ./build/resnet50 -m data/resnet50_demo/rn50_uint8.bin -i data/resnet50_data/input_224_uint8_NHWC -o data/resnet50_data/labels_224_uint8_NHWC -d 0 -f broadcast -c 1 -b 4 -v data/verification.json
   # 在 device 0 上按照 batch size 32 进行推理
   ./build/resnet50 -m data/resnet50_demo/rn50_uint8.bin -i data/resnet50_data/input_224_uint8_NHWC -o data/resnet50_data/labels_224_uint8_NHWC -d 0 -f broadcast -c 1 -b 32 -v data/verification.json
   # 在 device 0,1,2 上按照 batch size 4 进行推理
   ./build/resnet50 -m data/resnet50_demo/rn50_uint8.bin -i data/resnet50_data/input_224_uint8_NHWC -o data/resnet50_data/labels_224_uint8_NHWC -d 0,1,2 -f broadcast -c 1 -b 4 -v data/verification.json
   ```
   如需运行 resnet50 bf16 版本，首先确保已经下载步骤 1 中的 bf16 预处理数据，然后通过如下指令运行：
   ```bash
   usage: ./build/resnet50_bf16 --module=string --inputs=string --labels=string [options] ... 
   options:
     -m, --module         module file path (string)
     -i, --inputs         input file path (string)
     -o, --labels         label file path (string)
     -d, --devices        select devices (string [=all])
     -f, --format         running mode: broadcast / split (string [=broadcast])
     -c, --count          count of duplication (int [=1])
     -b, --batch          run batch size (int [=4])
     -v, --verify_path    save verification result json path (string [=])
     -?, --help           print this message
   ```
   ```bash
   # 在 device 0 上按照 batch size 8 推理 (bf16 要求 batch size 为 8 的倍数) resnet50 bf16
   ./build/resnet50_bf16 -m data/resnet50_demo/rn50_bf16.bin -i data/resnet50_data/input_224_bf16_NHWC -o data/resnet50_data/labels_224_bf16_NHWC -d 0 -f broadcast -c 1 -b 8 -v data/verification.json
   ```
   
4. 验证结果

    ```bash
    ./verify.sh
    ```

### 测试结果参考

以下为单device的测试结果参考：

| model    | data type | batch size | accuracy | performance |
|----------|-----------|------------|----------|-------------|
| ResNet50 | int8      | 4          | 76.4280% |  26501 FPS  |
| ResNet50 | int8      | 16         | 76.4280% |  25983 FPS  |
| ResNet50 | int8      | 32         | 76.4280% |  26115 FPS  |
| ResNet50 | int8      | 64         | 76.4280% |  26132 FPS  |
| ResNet50 | int8      | 128        | 76.4280% |  24883 FPS  |
| ResNet50 | int8      | 256        | 76.4280% |  24138 FPS  |
| ResNet50 | bf16      | 8          | 77.7160% |   4349 FPS  |
| ResNet50 | bf16      | 16         | 77.7160% |   4464 FPS  |
| ResNet50 | bf16      | 32         | 77.7160% |   4464 FPS  |
| ResNet50 | bf16      | 64         | 77.7160% |   4419 FPS  |
| ResNet50 | bf16      | 128        | 77.7160% |   4465 FPS  |
| ResNet50 | bf16      | 256        | 77.7160% |   4448 FPS  |