get-started-linux.md

   1 # Get Started with OpenVINO™ Deep Learning Deployment Toolkit (DLDT) on Linux*
   2
   3 This guide provides you with the information that will help you to start using the DLDT on Linux*. With this guide you will learn how to:
   4
   5 1. [Configure the Model Optimizer](#configure-the-model-optimizer)
   6 2. [Prepare a model for sample inference:](#prepare-a-model-for-sample-inference)
   7    1. [Download a pre-trained model](#download-a-trained-model)
   8    2. [Convert the model to an Intermediate Representation (IR) with the Model Optimizer](#convert-the-model-to-an-intermediate-representation-with-the-model-optimizer)
   9 3. [Run the Image Classification Sample Application with the model](#run-the-image-classification-sample-application)
  10
  11 ## Prerequisites
  12 1. This guide assumes that you have already cloned the `dldt` repo and successfully built the Inference Engine and Samples using the [build instructions](inference-engine/README.md).
  13 2. The original structure of the repository directories is kept unchanged.
  14
  15 > **NOTE**: Below, the directory to which the `dldt` repository is cloned is referred to as `<DLDT_DIR>`.
  16
  17 ## Configure the Model Optimizer
  18
  19 The Model Optimizer is a Python\*-based command line tool for importing trained models from popular deep learning frameworks such as Caffe\*, TensorFlow\*, Apache MXNet\*, ONNX\* and Kaldi\*.
  20
  21 You cannot perform inference on your trained model without running the model through the Model Optimizer. When you run a pre-trained model through the Model Optimizer, your output is an Intermediate Representation (IR) of the network. The Intermediate Representation is a pair of files that describe the whole model:
  22
  23 - `.xml`: Describes the network topology
  24 - `.bin`: Contains the weights and biases binary data
  25
  26 For more information about the Model Optimizer, refer to the [Model Optimizer Developer Guide](https://docs.openvinotoolkit.org/latest/_docs_MO_DG_Deep_Learning_Model_Optimizer_DevGuide.html).
  27
  28 ### Model Optimizer Configuration Steps
  29
  30 You can choose to either configure all supported frameworks at once **OR** configure one framework at a time. Choose the option that best suits your needs. If you see error messages, make sure you installed all dependencies.
  31
  32 > **NOTE**: Since the TensorFlow framework is not officially supported on CentOS*, the Model Optimizer for TensorFlow can't be configured and ran on those systems.
  33
  34 > **IMPORTANT**: The Internet access is required to execute the following steps successfully. If you have access to the Internet through the proxy server only, please make sure that it is configured in your OS environment.
  35
  36 **Option 1: Configure all supported frameworks at the same time**
  37
  38 1.  Go to the Model Optimizer prerequisites directory:
  39 ```sh
  40 cd <DLDT_DIR>/model_optimizer/install_prerequisites
  41 ```
  42 2.  Run the script to configure the Model Optimizer for Caffe,
  43     TensorFlow, MXNet, Kaldi\*, and ONNX:
  44 ```sh
  45 sudo ./install_prerequisites.sh
  46 ```
  47
  48 **Option 2: Configure each framework separately**
  49
  50 Configure individual frameworks separately **ONLY** if you did not select **Option 1** above.
  51
  52 1.  Go to the Model Optimizer prerequisites directory:
  53 ```sh
  54 cd <DLDT_DIR>/model_optimizer/install_prerequisites
  55 ```
  56 2.  Run the script for your model framework. You can run more than one script:
  57
  58    - For **Caffe**:
  59    ```sh
  60    sudo ./install_prerequisites_caffe.sh
  61    ```
  62
  63    - For **TensorFlow**:
  64    ```sh
  65    sudo ./install_prerequisites_tf.sh
  66    ```
  67
  68    - For **MXNet**:
  69    ```sh
  70    sudo ./install_prerequisites_mxnet.sh
  71    ```
  72
  73    - For **ONNX**:
  74    ```sh
  75    sudo ./install_prerequisites_onnx.sh
  76    ```
  77
  78    - For **Kaldi**:
  79    ```sh
  80    sudo ./install_prerequisites_kaldi.sh
  81    ```
  82 The Model Optimizer is configured for one or more frameworks. Continue to the next session to download and prepare a model for running a sample inference.
  83
  84 ## Prepare a Model for Sample Inference
  85
  86 This paragraph contains the steps to get the pre-trained model for sample inference and to prepare the model's optimized Intermediate Representation that Inference Engine uses.
  87
  88 ### Download a Trained Model
  89
  90 To run the Image Classification Sample you'll need a pre-trained model to run the inference on. This guide will use the public SqueezeNet 1.1 Caffe* model. You can find and download this model manually or use the OpenVINO™ [Model Downloader](https://github.com/opencv/open_model_zoo/tree/master/model_downloader).
  91
  92 With the Model Downloader, you can download other popular public deep learning topologies and the [OpenVINO™ pre-trained models](https://github.com/opencv/open_model_zoo/tree/master/intel_models) prepared for running inference for a wide list of inference scenarios: object detection, object recognition, object re-identification, human pose estimation, action recognition and others.
  93
  94 To download the SqueezeNet 1.1 Caffe* model to a models folder with the Model Downloader:
  95 1. Install the [prerequisites](https://github.com/opencv/open_model_zoo/tree/master/model_downloader#prerequisites).
  96 2. Run the `downloader.py` with specifying the topology name and a `<models_dir>` path. For example to download the model to the `~/public_models` directory:
  97    ```sh
  98    ./downloader.py --name squeezenet1.1 --output_dir ~/public_models
  99    ```
 100    When the model files are successfully downloaded the output similar to the following is printed:
 101    ```sh
 102    ###############|| Downloading topologies ||###############
 103
 104    ========= Downloading /home/username/public_models/classification/squeezenet/1.1/caffe/squeezenet1.1.prototxt
 105
 106    ========= Downloading /home/username/public_models/classification/squeezenet/1.1/caffe/squeezenet1.1.caffemodel
 107    ... 100%, 4834 KB, 3157 KB/s, 1 seconds passed
 108
 109    ###############|| Post processing ||###############
 110
 111    ========= Changing input dimensions in squeezenet1.1.prototxt =========
 112    ```
 113
 114 ### Convert the model to an Intermediate Representation with the Model Optimizer
 115
 116 > **NOTE**: This section assumes that you have configured the Model Optimizer using the instructions from the [Configure the Model Optimizer](#configure-the-model-optimizer) section.
 117
 118 1. Create a `<ir_dir>` directory that will contains the Intermediate Representation (IR) of the model.
 119
 120 2. Inference Engine can perform inference on a [list of supported devices](https://docs.openvinotoolkit.org/latest/_docs_IE_DG_supported_plugins_Supported_Devices.html) using specific device plugins. Different plugins support models of [different precision formats](https://docs.openvinotoolkit.org/latest/_docs_IE_DG_supported_plugins_Supported_Devices.html#supported_model_formats), such as FP32, FP16, INT8. To prepare an IR to run inference on a particular hardware, run the Model Optimizer with the appropriate `--data_type` options:
 121
 122    **For CPU (FP32):**
 123    ```sh
 124    python3 <DLDT_DIR>/model_optimizer/mo.py --input_model <models_dir>/classification/squeezenet/1.1/caffe/squeezenet1.1.caffemodel --data_type FP32 --output_dir <ir_dir>
 125    ```
 126
 127    **For GPU and MYRIAD (FP16):**
 128    ```sh
 129    python3 <DLDT_DIR>/model_optimizer/mo.py --input_model <models_dir>/classification/squeezenet/1.1/caffe/squeezenet1.1.caffemodel --data_type FP16 --output_dir <ir_dir>
 130    ```
 131    After the Model Optimizer script is completed, the produced IR files (`squeezenet1.1.xml`, `squeezenet1.1.bin`) are in the specified `<ir_dir>` directory.
 132
 133 3. Copy the `squeezenet1.1.labels` file from the `<DLDT_DIR>/inference-engine/samples/sample_data/` to the model IR directory. This file contains the classes that ImageNet uses so that the inference results show text instead of classification numbers:
 134    ```sh
 135    cp <DLDT_DIR>/inference-engine/samples/sample_data/squeezenet1.1.labels <ir_dir>
 136    ```
 137
 138 Now you are ready to run the Image Classification Sample Application.
 139
 140 ## Run the Image Classification Sample Application
 141
 142 The Inference Engine sample applications are automatically compiled when you built the Inference Engine using the [build instructions](inference-engine/README.md). The binary files are located in the `<DLDT_DIR>/inference-engine/bin/intel64/Release` directory.
 143
 144 Follow the steps below to run the Image Classification sample application on the prepared IR and with an input image:
 145
 146 1. Go to the samples build directory:
 147    ```sh
 148    cd <DLDT_DIR>/inference-engine/bin/intel64/Release
 149    ```
 150 2. Run the sample executable with specifying the `car.png` file from the `<DLDT_DIR>/inference-engine/samples/sample_data/` directory as an input image, the IR of your model and a plugin for a hardware device to perform inference on:
 151
 152    **For CPU:**
 153    ```sh
 154    ./classification_sample -i <DLDT_DIR>/inference-engine/samples/sample_data/car.png -m <ir_dir>/squeezenet1.1.xml -d CPU
 155    ```
 156
 157    **For GPU:**
 158    ```sh
 159    ./classification_sample -i <DLDT_DIR>/inference-engine/samples/sample_data/car.png -m <ir_dir>/squeezenet1.1.xml -d GPU
 160    ```
 161
 162    **For MYRIAD:**
 163    >**NOTE**: Running inference on VPU devices (Intel® Movidius™ Neural Compute Stick or Intel® Neural Compute Stick 2) with the MYRIAD plugin requires performing [additional hardware configuration steps](inference-engine/README.md#optional-additional-installation-steps-for-the-intel-movidius-neural-compute-stick-and-neural-compute-stick-2).
 164    ```sh
 165    ./classification_sample -i <DLDT_DIR>/inference-engine/samples/sample_data/car.png -m <ir_dir>/squeezenet1.1.xml -d MYRIAD
 166    ```
 167
 168 When the Sample Application completes, you will have the label and confidence for the top-10 categories printed on the screen. Below is a sample output with inference results on CPU:
 169 ```sh
 170 Top 10 results:
 171
 172 Image /home/user/dldt/inference-engine/samples/sample_data/car.png
 173
 174 classid probability label
 175 ------- ----------- -----
 176 817     0.8363345   sports car, sport car
 177 511     0.0946488   convertible
 178 479     0.0419131   car wheel
 179 751     0.0091071   racer, race car, racing car
 180 436     0.0068161   beach wagon, station wagon, wagon, estate car, beach waggon, station waggon, waggon
 181 656     0.0037564   minivan
 182 586     0.0025741   half track
 183 717     0.0016069   pickup, pickup truck
 184 864     0.0012027   tow truck, tow car, wrecker
 185 581     0.0005882   grille, radiator grille
 186
 187
 188 total inference time: 2.6642941
 189 Average running time of one iteration: 2.6642941 ms
 190
 191 Throughput: 375.3339402 FPS
 192
 193 [ INFO ] Execution successful
 194 ```
 195
 196 ## Additional Resources
 197
 198 * [OpenVINO™ Release Notes](https://software.intel.com/en-us/articles/OpenVINO-RelNotes)
 199 * [Inference Engine build instructions](inference-engine/README.md)
 200 * [Introduction to Intel® Deep Learning Deployment Toolkit](https://docs.openvinotoolkit.org/latest/_docs_IE_DG_Introduction.html)
 201 * [Inference Engine Developer Guide](https://docs.openvinotoolkit.org/latest/_docs_IE_DG_Deep_Learning_Inference_Engine_DevGuide.html)
 202 * [Model Optimizer Developer Guide](https://docs.openvinotoolkit.org/latest/_docs_MO_DG_Deep_Learning_Model_Optimizer_DevGuide.html)
 203 * [Inference Engine Samples Overview](https://docs.openvinotoolkit.org/latest/_docs_IE_DG_Samples_Overview.html).