Using the Model Optimizer to Convert MXNet* Models

Introduction

NOTE: The OpenVINO™ toolkit was formerly known as the Intel® Computer Vision SDK.

The Model Optimizer is a cross-platform command-line tool that facilitates the transition between the training and deployment environment, performs static model analysis, and adjusts deep learning models for optimal execution on end-point target devices.

The Model Optimizer process assumes you have a network model trained using a supported frameworks. The scheme below illustrates the typical workflow for deploying a trained deep learning model:

A summary of the steps for optimizing and deploying a model that was trained with the MXNet* framework:

1. Configure the Model Optimizer for MXNet* (MXNet was used to train your model).
2. Convert a MXNet model to produce an optimized Intermediate Representation (IR) of the model based on the trained network topology, weights, and biases values.
3. Test the model in the Intermediate Representation format using the Inference Engine in the target environment via provided Inference Engine validation application or sample applications.
4. Integrate the Inference Engine in your application to deploy the model in the target environment.

Model Optimizer Workflow

The Model Optimizer process assumes you have a network model that was trained with one of the supported frameworks. The workflow is:

1. Configure Model Optimizer for the TensorFlow* framework running the configuration bash script (Linux*) or batch file (Windows*) from the <INSTALL_DIR>/deployment_tools/model_optimizer/install_prerequisites folder:
   • install_prerequisites_mxnet.sh
   • install_prerequisites_mxnet.bat

   For more details on configuring the Model Optimizer, see Configure the Model Optimizer.

2. Provide as input a trained model that contains the certain topology, described in the .json file, and the adjusted weights and biases, described in .params. 
3. Convert the MXNet* model to optimized Intermediate Representation.

The Model Optimizer produces as output an Intermediate Representation (IR) of the network can be read, loaded, and inferred with the Inference Engine. The Inference Engine API offers a unified API across a number of supported Intel® platforms. The Intermediate Representation is a pair of files that describe the whole model:

• .xml: Describes the network topology
• .bin: Contains the weights and biases binary data

Supported Topologies

The table below shows the supported models, with the links to the symbol and parameters.

Converting an MXNet* Model

To convert an MXNet model:

1. Go to the <INSTALL_DIR>/deployment_tools/model_optimizer directory.
2. To convert an MXNet* model contained in a model-file-symbol.json and model-file-0000.params, run the Model Optimizer launch script mo.py, specifying a path to the input model file:

   python3 mo_mxnet.py --input_model model-file-0000.params

Two groups of parameters are available to convert your model:

• Framework-agnostic parameters: These parameters are used to convert any model trained in any supported framework.
• MXNet-specific parameters: Parameters used to convert only MXNet* models

Using Framework-Agnostic Conversion Parameters

The following list provides the framework agnostic parameters. The MXNet-specific list is further down in this document.

Optional arguments:
 -h, --help            Shows this help message and exit
  --framework {tf,caffe,mxnet}
                        Name of the framework used to train the input model.
Framework-agnostic parameters:
  --input_model INPUT_MODEL, -w INPUT_MODEL, -m INPUT_MODEL
                        Tensorflow*: a file with a pre-trained model (binary
                        or text .pb file after freezing). Caffe*: a model
                        proto file with model weights
  --model_name MODEL_NAME, -n MODEL_NAME
                        Model_name parameter passed to the final create_ir
                        transform. This parameter is used to name a network in
                        a generated IR and output .xml/.bin files.
  --output_dir OUTPUT_DIR, -o OUTPUT_DIR
                        Directory that stores the generated IR. By default, it
                        is the directory from where the Model Optimizer is
                        launched.
  --input_shape INPUT_SHAPE
                        Input shape that should be fed to an input node of the
                        model. Shape is defined in the '[N,C,H,W]' or
                        '[N,H,W,C]' format, where the order of dimensions
                        depends on the framework input layout of the model.
                        For example, [N,C,H,W] is used for Caffe* models and
                        [N,H,W,C] for TensorFlow* models. Model Optimizer
                        performs necessary transforms to convert the shape to
                        the layout acceptable by Inference Engine. Two types
                        of brackets are allowed to enclose the dimensions:
                        [...] or (...). The shape should not contain undefined
                        dimensions (? or -1) and should fit the dimensions
                        defined in the input operation of the graph.
  --scale SCALE, -s SCALE
                        All input values coming from original network inputs
                        will be divided by this value. When a list of inputs
                        is overridden by the --input parameter, this scale is
                        not applied for any input that does not match with the
                        original input of the model.
  --reverse_input_channels
                        Switches the input channels order from RGB to BGR.
                        Applied to original inputs of the model when and only
                        when a number of channels equals 3
  --log_level {CRITICAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}
                        Logger level
  --input INPUT         The name of the input operation of the given model.
                        Usually this is a name of the input placeholder of the
                        model.
  --output OUTPUT       The name of the output operation of the model. For
                        TensorFlow*, do not add :0 to this name.
  --mean_values MEAN_VALUES, -ms MEAN_VALUES
                        Mean values to be used for the input image per
                        channel. Shape is defined in the '(R,G,B)' or
                        '[R,G,B]' format. The shape should not contain
                        undefined dimensions (? or -1). The order of the
                        values is the following: (value for a RED channel,
                        value for a GREEN channel, value for a BLUE channel)
  --scale_values SCALE_VALUES
                        Scale values to be used for the input image per
                        channel. Shape is defined in the '(R,G,B)' or
                        '[R,G,B]' format. The shape should not contain
                        undefined dimensions (? or -1). The order of the
                        values is the following: (value for a RED channel,
                        value for a GREEN channel, value for a BLUE channel)
  --data_type {FP16,FP32,half,float}
                        Data type for input tensor values.
  --disable_fusing      Turns off fusing of linear operations to Convolution
  --disable_gfusing     Turns off fusing of grouped convolutions
  --extensions EXTENSIONS
                        Directory or list of directories with extensions. To
                        disable all extensions including those that are placed
                        at the default location, pass an empty string.
  --batch BATCH, -b BATCH
                        Input batch size
  --version             Version of Model Optimizer

Note: The Model Optimizer does not revert input channels from RGB to BGR by default, as it did in the 2017 R3 Beta release. Instead, manually specify the command-line parameter to perform the reversion: --reverse_input_channels

Command-Line Interface (CLI) Examples Using Framework-Agnostic Parameters

• Launching the Model Optimizer for model.params with debug log level: Use this to better understand what is happening internally when a model is converted:

  python3 mo_mxnet.py --input_model model.params --log_level DEBUG

• Launching the Model Optimizer for model.params with the output Intermediate Representation called result.xml and result.bin that are placed in the specified ../../models/:

  python3 mo_mxnet.py --input_model model.params --model_name result --output_dir ../../models/

• Launching the Model Optimizer for model.params and providing scale values for a single input:

  python3 mo_mxnet.py --input_model model.params --scale_values [59,59,59]

• Launching the Model Optimizer for model.caffemodel with two inputs with two sets of scale values for each input. A number of sets of scale/mean values should be exactly the same as the number of inputs of the given model:

  python3 mo_mxnet.py --input_model model.params --input data,rois --scale_values [59,59,59],[5,5,5]

• Launching the Model Optimizer for model.params with specified input layer (data), changing the shape of the input layer to [1,3,224,224], and specifying the name of the output layer:

  python3 mo_mxet.py --input_model model.params --input data --input_shape [1,3,224,224] --output pool5

• Launching the Model Optimizer for model.params with disabled fusing for linear operations with convolution, set by the --disable_fusing flag, and grouped convolutions, set by the --disable_gfusing flag: 

  python3 mo_mxnet.py --input_model model.params --disable_fusing --disable_gfusing

• Launching the Model Optimizer for model.caffemodel, reversing the channels order between RGB and BGR, specifying mean values for the input and the precision of the Intermediate Representation to be FP16:

  python3 mo_mxnet.py --input_model model.params --reverse_input_channels --mean_values [255,255,255] --data_type FP16

• Launching the Model Optimizer for model.params with extensions from specified directories. In particular, from /home/ and from /home/some/other/path.
  In addition, the following command shows how to pass the mean file to the Intermediate Representation. The mean file must be in a binaryproto format:

  python3 mo_mxnet.py --input_model model.params --extensions /home/,/some/other/path/ --mean_file mean_file.binaryproto

Using MXNet*-Specific Conversion Parameters

The following list provides the MXNet*-specific parameters. 

Mxnet-specific parameters:
  --nd_prefix_name ND_PREFIX_NAME
                        Prefix name for args.nd and argx.nd files.
  --pretrained_model_name PRETRAINED_MODEL_NAME
                        Name of pretrained model without extension and epoch
                        number which will be merged with args.nd and argx.nd
                        files.

Custom Layer Definition

Internally, when you run the Model Optimizer, it loads the model, goes through the topology, and tries to find each layer type in a list of known layers. Custom layers are layers that are not included in the list of known layers. If your topology contains any layers that are not in this list of known layers, the Model Optimizer classifies them as custom.

Supported Layers and the Mapping to Intermediate Representation Layers

The current version of the Model Optimizer for MXNet does not support models that contain custom layers. The general recommendation is to cut the model to remove the custom layer, and then reconvert the cut model, without the custom layer. If the custom layer is the last layer in the topology, then the processing logic can be made on the level of the Inference Engine sample that you will use when inferring the model.

Frequently Asked Questions (FAQ)

The Model Optimizer provides explanatory messages if it is unable to run to completion due to issues like typographical errors, incorrectly used options, or other issues. The message describes the potential cause of the problem and gives a link to the Model Optimizer FAQ. The FAQ has instructions on how to resolve most issues. The FAQ also includes links to relevant sections in the Model Optimizer Developer Guide to help you understand what went wrong. The FAQ is here: https://software.intel.com/en-us/articles/OpenVINO-ModelOptimizer#FAQ.

Summary

In this document, you learned:

• Basic information about how the Model Optimizer works with MXNet* models
• Which MXNet* models are supported
• How to convert a trained MXNet* model using the Model Optimizer with both framework-agnostic and MXNet-specific command-line options

Legal Information

You may not use or facilitate the use of this document in connection with any infringement or other legal analysis concerning Intel products described herein. You agree to grant Intel a non-exclusive, royalty-free license to any patent claim thereafter drafted which includes subject matter disclosed herein.

No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document.

All information provided here is subject to change without notice. Contact your Intel representative to obtain the latest Intel product specifications and roadmaps.

The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.

Intel technologies’ features and benefits depend on system configuration and may require enabled hardware, software or service activation. Learn more at http://www.intel.com/ or from the OEM or retailer.

No computer system can be absolutely secure.

Intel, Arria, Core, Movidia, Pentium, Xeon, and the Intel logo are trademarks of Intel Corporation in the U.S. and/or other countries.

OpenCL and the OpenCL logo are trademarks of Apple Inc. used with permission by Khronos

*Other names and brands may be claimed as the property of others.

Copyright © 2018, Intel Corporation. All rights reserved.