inference-engine/tools/calibration_tool/README.md

   1 # OpenVINO™ Calibration Tool
   2 Inference Engine Calibration Tool calibrates a given FP32 model so that you can run calibrated model in low-precision 8-bit integer mode while keeping the input data of this model in the original precision.
   3 Inference Engine Calibration Tool is a Python\* command-line tool, which imports Python types from the `openvino.tools.calibration` package.
   4
   5 Please, refer to https://docs.openvinotoolkit.org for details.
   6
   7 ## Hardware requirements
   8 Hardware requirements depend on a model. Typically for public models RAM memory size has to be not less then 16Gb, drive has to have not less then 30 Gb free space independently on operation system. Temporary directory is used to cache layers output during calibration.
   9
  10 ## Usage
  11 The Calibration Tool is configured in the same way as the Accuracy Checker. You can also use additional command-line arguments to define calibration-specific parameters.
  12
  13 ### Command-Line Arguments for the Accuracy Checker Tool reused in Calibration Tool
  14 | Argument                                     | Type   | Description                                             |
  15 | -------------------------------------------- | ------ | ------------------------------------------------------- |
  16 | -c, --config                                 | string | Required. Path to the YML file with local configuration |
  17 | -d, --definitions                            | string | Optional. Path to the YML file with definitions         |
  18 | -m, --models                                 | string | Optional. Prefix path to the models and weights         |
  19 | -s, --source                                 | string | Optional. Prefix path to the data source                |
  20 | -a, --annotations                            | string | Optional. Pefix path to the converted annotations and datasets meta data |
  21 | -e, --extensions                             | string | Optional. Prefix path to extensions folder              |
  22 | --cpu_extensions_mode, --cpu-extensions-mode | string | Optional. specified preferable set of processor instruction for automatic searching cpu extension lib: `avx2` or `sse4` |
  23 | -C, --converted_models, --converted-models   | string | Optional. Directory to store Model Optimizer converted models. Used for DLSDK launcher only |
  24 | -M, --model_optimizer, --model-optimizer     | string | Optional. Path to model optimizer caffe directory       |
  25 | --tf_custom_op_config_dir, --tf-custom-op-config-dir | string | Optional. Path to directory with tensorflow custom operation configuration files for model optimizer |
  26 | --tf_obj_detection_api_pipeline_config_path, --tf-obj-detection-api-pipeline-config-path | string | Optional. Path to directory with tensorflow object detection api pipeline configuration files for model optimizer |
  27 | --progress                                   | string | Optional. Progress reporter: `bar`, `print` or `None`   |
  28 | -td, --target_devices, --target-devices      | string | Optional. Space-separated list of devices for infer     |
  29 | -tt, --target_tags, --target-tags | string   | Optional. Space-separated list of launcher tags for infer        |
  30
  31 ### Specific Command Line Arguments for Calibration Tool
  32 | Argument                          | Type   | Description                                               |
  33 | --------------------------------- | ------ | --------------------------------------------------------- |
  34 | -p, --precision                   | string | Optional. Precision to calibrate. Default value is INT8   |
  35 | --ignore_layer_types, --ignore-layer-types | string | Optional. Layer types list which will be skipped during quantization |
  36 | --ignore_layer_types_path, --ignore-layer-types-path | string | Optional. Ignore layer types file path |
  37 | --ignore_layer_names, --ignore-layer-names | string | Optional. Layer names list which will be skipped during quantization |
  38 | --ignore_layer_names_path, --ignore-layer-names-path | string | Optional. Ignore layer names file path |
  39 | --batch_size, --batch-size        | integer| Optional. Batch size value. If not specified, the batch size value is determined from IR |
  40 | -th, --threshold                  | float | Optional. Accuracy drop of quantized model should not exceed this threshold. Should be pointer in percents without percent sign. (1% is default) |
  41 | -ic, --benchmark_iterations_count, --benchmark-iterations-count | integer | Optional. Benchmark itertations count. (1000 is default) |
  42 | -mn, --metric_name, --metric-name | string | Optional. Metric name used during calibration |
  43 | -mt, --metric_type, --metric-type | string | Optional. Metric type used during calibration |
  44 | -o, --output_dir, --output-dir    | string | Optional. Directory to store converted models. Original model directory is used if not defined |
  45
  46 ## Model calibration flow
  47
  48 ### Introduction
  49 Calibration tool read original FP32 model, calibration dataset and create low precision model. Low precision model has two differences from original model:
  50 1. Per channel statistics are defined. Statistics have minimum and maximum values for each layer and each channel. Model statistics are stored in Inference Engine intermediate representation file (IR) in XML format.
  51 2. `quantization_level` layer attribute is defined. The attribute defines precision which is used during inference.
  52
  53 ### Prerequisites
  54 * Model: Tensorflow\* Inception v1. You can download the model from here: https://github.com/tensorflow/models/tree/master/research/slim
  55 * Dataset: ImageNet. You can download ImageNet from here: http://www.image-net.org/download.php
  56 * YML configuration files: you can find YML configuration files and YML definition file which are used below in `configs` directory:
  57   - `definitions.yml` - definition file
  58   - `inception_v1.yml` - configuration file for Tensorflow\* Inception v1 model
  59   - `ncf_config.yml` - configuration file for NCF model in OpenVINO\* Inference Engine Intermediate Representation format
  60   - `ssd_mobilenet_v1_coco.yml` - configuration file for Tensorflow\* SSD Mobilenet v1 model
  61   - `unet2d.yml` - configuration file for Unet2D mode in in OpenVINO\* Inference Engine Intermediate Representation format
  62
  63 If you have custom topology with not supported accuracy metric or not suported custom dataset then you should add some components implementation in `openvino.tools.accuracy_checker` Python\* package yourself. Refer to `openvino.tools.accuracy_checker` documentation how to implement metric and dataset support.
  64
  65 There are steps to calibrate and evaluate result model:
  66 - Step #1. Convert data annotation files
  67 - Optional step for low precision model performance estimation.
  68 - Step #2. Calibration
  69 - Step #3. Result model evaluation
  70
  71 Additional optional step before calibration is available to rough estimate possible INT8 performance.
  72
  73 ### Step #1. Convert data annotation files
  74 Calibration dataset is subset of training dataset. Use Convert Annotation Tool to convert ImageNet\* dataset to Calibration Tool readable data annotation files. Data annotation files describe subset of images which are used during calibration. Command line:
  75 ```sh
  76 python convert_annotation.py imagenet --annotation_file /datasets/ImageNet/val.txt --labels_file /datasets/ImageNet/synset_words.txt -ss 2000 -o ~/annotations -a imagenet.pickle -m imagenet.json
  77 ```
  78
  79 > **NOTE:** For simplicity all command line tools in below steps use the same command line arguments. In practice [Collect Statistics Tool](./inference-engine/tools/collect_statistics_tool/README.md) uses calibration dataset, but [Accuracy Checker Tool](./inference-engine/tools/accuracy_checker_tool/README.md) has to use whole validation dataset.
  80
  81
  82 | Argument           | Type   | Description                                                                       |
  83 | -------------------| ------ | --------------------------------------------------------------------------------- |
  84 | --config           | string | Path to the YML file with local configuration                                     |
  85 | -d                 | string | Path to the YML file with definitions                                             |
  86 | -M                 | string | Path to model optimizer directory                                                 |
  87 | --models           | string | Prefix path to the models and weights                                             |
  88 | --source           | string | Prefix path to the data source                                                    |
  89 | --annotations      | string | Pefix path to the converted annotations and datasets meta data                    |
  90 | --converted_models | string | Directory to store Model Optimizer converted models. Used for DLSDK launcher only |
  91
  92
  93 ### Optional step for low precision model performance estimation.
  94 Before calibration you can roughly estimate low presition performance with [Collect Statistics Tool](./inference-engine/tools/collect_statistics_tool/README.md).
  95
  96 [Collect Statistics Tool](./inference-engine/tools/collect_statistics_tool/README.md) ignores metric in YML configuration file but you can use the same command line arguments.
  97
  98 Command line:
  99
 100 ```sh
 101 python collect_statistics.py --config ~/inception_v1.yml -d ~/defenitions.yml -M /home/user/intel/openvino/deployment_tools/model_optimizer --models ~/models --source /media/user/calibration/datasets --annotations ~/annotations --converted_models ~/models
 102 ```
 103
 104 Result model has statistics which allow to infer this model in INT8 precision. To measure performance you can use [Benchmark Tool](./inference-engine/tools/benchmark_tool/README.md).
 105
 106 ### Step #2. Calibration
 107 During calibration process, the model is ajusted for efficient quantization and minimization of accuracy drop on calibration dataset. Calibration tool produces calibrated model which will be executed in low precision 8 bit quantzed mode after loading into CPU plugin.
 108
 109 [Calibration Tool](./inference-engine/tools/calibration_tool/README.md) has flexible and extensible mechanism of enabling new data set and metrics. Each network has its own dedicated network metric and dataset where network was trained. Dataset description and network metrics can be reused for different network.
 110
 111 To plug new dataset you need to develop YML file. To develop new metric you need to develop Python\* module implementing metric and describe in YML. Please, refer to [Accuracy Checker Tool](./inference-engine/tools/accuracy_checker_tool/README.md) for details.
 112
 113
 114 Command line example:
 115 ```sh
 116 python calibrate.py --config ~/inception_v1.yml --definition ~/defenitions.yml -M /home/user/intel/openvino/deployment_tools/model_optimizer --tf_custom_op_config_dir ~/tf_custom_op_configs --models ~/models --source /media/user/calibration/datasets --annotations ~/annotations
 117 ```
 118
 119 ### Step #3. Result model evaluation
 120 After calibration of the model it worse to evaluate network accuracy on whole validation set using [Accuracy Checker Tool](./inference-engine/tools/accuracy_checker_tool/README.md).
 121
 122 #### Step #3.1 Check accuracy
 123 Command line:
 124 ```sh
 125 python accuracy_check.py --config ~/inception_v1.yml -d ~/defenitions.yml -M /home/user/intel/openvino/deployment_tools/model_optimizer --tf_custom_op_config_dir ~/tf_custom_op_configs --models ~/models --source /media/user/calibration/datasets --annotations ~/annotations -tf dlsdk -td CPU
 126 ```
 127
 128 #### Step #3.2 Check performance
 129 Use `benchmark_app` command line tool to measure latency and throughput for synchronous and asynchronous modes. Note, please, `benchmark_app` command line tool uses converted OpenVINO\* Intermediate Representation model.
 130
 131 Command line for synchronous mode:
 132
 133 ```sh
 134 ./benchmark_app -i <path_to_image>/inputImage.bmp -m <path_to_model>/inception_v1.xml -d CPU -api sync
 135 ```
 136
 137 Command line for the asynchronous mode:
 138 ```sh
 139 ./benchmark_app -i <path_to_image>/inputImage.bmp -m <path_to_model>/inception_v1.xml -d CPU -api async
 140 ```
 141
 142 #### Optional step to check performance
 143 You can use Python\* [Benchmark Tool](./inference-engine/tools/benchmark_tool/README.md) command line tool to quickly check performance with the same command line arguments and configuration YML files as for [Calibration Tool](./inference-engine/tools/calibration_tool/README.md).
 144
 145 Command line:
 146 ```sh
 147 python benchmark.py --config ~/inception_v1.yml -d ~/defenitions.yml -M /home/user/intel/openvino/deployment_tools/model_optimizer --tf_custom_op_config_dir ~/tf_custom_op_configs --models ~/models --source /media/user/calibration/datasets --annotations ~/annotations --converted_models ~/models
 148 ```
 149