Model Downloader and other automation tools

This directory contains scripts that automate certain model-related tasks based on configuration files in the models' directories.

Please use these tools instead of attempting to parse the configuration files directly. Their format is undocumented and may change in incompatible ways in future releases.

Prerequisites

  1. Install Python (version 3.5.2 or higher)
  2. Install the tools' dependencies with the following command:
python3 -mpip install --user -r ./requirements.in

For the model converter, you will also need to install the OpenVINO™ toolkit and the prerequisite libraries for Model Optimizer. See the OpenVINO toolkit documentation for details.

If you using models from PyTorch or Caffe2 framework, you will also need to use intermediate conversion to ONNX format. To use automatic conversion install additional dependencies.

For models from PyTorch:

python3 -mpip install --user -r ./requirements-pytorch.in

For models from Caffe2:

python3 -mpip install --user -r ./requirements-caffe2.in

When running the model downloader with Python 3.5.x on macOS, you may encounter an error similar to the following:

requests.exceptions.SSLError: [...] (Caused by SSLError(SSLError(1, '[SSL: TLSV1_ALERT_PROTOCOL_VERSION]

tlsv1 alert protocol version (_ssl.c:719)'),))

You can work around this by installing additional packages:

python3 -mpip install --user 'requests[security]'

Alternatively, upgrade to Python 3.6 or a later version.

Model downloader usage

The basic usage is to run the script like this:

./downloader.py --all

This will download all models. The --all option can be replaced with other filter options to download only a subset of models. See the "Shared options" section.

By default, the script will download models into a directory tree rooted in the current directory. To download into a different directory, use the -o/--output_dir option:

./downloader.py --all --output_dir my/download/directory

You may use --precisions flag to specify comma separated precisions of weights to be downloaded.

./downloader.py --name face-detection-retail-0004 --precisions FP16,INT8

By default, the script will attempt to download each file only once. You can use the --num_attempts option to change that and increase the robustness of the download process:

./downloader.py --all --num_attempts 5 # attempt each download five times

You can use the --cache_dir option to make the script use the specified directory as a cache. The script will place a copy of each downloaded file in the cache, or, if it is already there, retrieve it from the cache instead of downloading it again.

./downloader.py --all --cache_dir my/cache/directory

The cache format is intended to remain compatible in future Open Model Zoo versions, so you can use a cache to avoid redownloading most files when updating Open Model Zoo.

By default, the script outputs progress information as unstructured, human-readable text. If you want to consume progress information programmatically, use the --progress_format option:

./downloader.py --all --progress_format=json

When this option is set to json, the script's standard output is replaced by a machine-readable progress report, whose format is documented in the "JSON progress report format" section. This option does not affect errors and warnings, which will still be printed to the standard error stream in a human-readable format.

You can also set this option to text to explicitly request the default text format.

See the "Shared options" section for information on other options accepted by the script.

JSON progress report format

This section documents the format of the progress report produced by the script when the --progress_format=json option is specified.

The report consists of a sequence of events, where each event is represented by a line containing a JSON-encoded object. Each event has a member with the name $type whose value determines the type of the event, as well as which additional members it contains.

The following event types are currently defined:

Additional event types and members may be added in the future.

Tools parsing the machine-readable format should avoid relying on undocumented details. In particular:

Model converter usage

The basic usage is to run the script like this:

./converter.py --all

This will convert all models into the Inference Engine IR format. Models that were originally in that format are ignored. Models in PyTorch and Caffe2 formats will be converted in ONNX format first.

The --all option can be replaced with other filter options to convert only a subset of models. See the "Shared options" section.

The current directory must be the root of a download tree created by the model downloader. To specify a different download tree path, use the -d/--download_dir option:

./converter.py --all --download_dir my/download/directory

By default, the converted models are placed into the download tree. To place them into a different directory tree, use the -o/--output_dir option:

./converter.py --all --output_dir my/output/directory

>Note: models in intermediate format are placed to this directory too.

By default, the script will produce models in every precision that is supported for conversion. To only produce models in a specific precision, use the --precisions option:

./converter.py --all --precisions=FP16

If the specified precision is not supported for a model, that model will be skipped.

The script will attempt to locate Model Optimizer using the environment variables set by the OpenVINO™ toolkit's setupvars.sh/setupvars.bat script. You can override this heuristic with the --mo option:

./converter.py --all --mo my/openvino/path/model_optimizer/mo.py

You can add extra Model Optimizer arguments to the ones specified in the model configuration by using the --add_mo_arg option. The option can be repeated to add multiple arguments:

./converter.py --name=caffenet --add_mo_arg=--reverse_input_channels --add_mo_arg=--silent

By default, the script will run Model Optimizer using the same Python executable that was used to run the script itself. To use a different Python executable, use the -p/--python option:

./converter.py --all --python my/python

The script can run multiple conversion commands concurrently. To enable this, use the -j/--jobs option:

./converter.py --all -j8 # run up to 8 commands at a time

The argument to the option must be either a maximum number of concurrently executed commands, or "auto", in which case the number of CPUs in the system is used. By default, all commands are run sequentially.

The script can print the conversion commands without actually running them. To do this, use the --dry_run option:

./converter.py --all --dry_run

See the "Shared options" section for information on other options accepted by the script.

Model quantizer usage

Before you run the model quantizer, you must prepare a directory with the datasets required for the quantization process. This directory will be referred to as <DATASET_DIR> below. See the "Dataset directory layout" section for information on the expected contents of that directory.

The basic usage is to run the script like this:

./quantizer.py --all --dataset_dir <DATASET_DIR>

This will quantize all models for which quantization is supported. Other models are ignored.

The --all option can be replaced with other filter options to quantize only a subset of models. See the "Shared options" section.

The current directory must be the root of a tree of model files create by the model converter. To specify a different model tree path, use the --model_dir option:

./quantizer.py --all --dataset_dir <DATASET_DIR> --model_dir my/model/directory

By default, the quantized models are placed into the same model tree. To place them into a different directory tree, use the -o/--output_dir option:

./quantizer.py --all --dataset_dir <DATASET_DIR> --output_dir my/output/directory

By default, the script will produce models in every precision that is supported as a quantization output. To only produce models in a specific precision, use the --precisions option:

./quantizer.py --all --dataset_dir <DATASET_DIR> --precisions=FP16-INT8

The script will attempt to locate Post-Training Optimization Toolkit using the environment variables set by the OpenVINO™ toolkit's setupvars.sh/setupvars.bat script. You can override this heuristic with the --pot option:

./quantizer.py --all --dataset_dir <DATASET_DIR> --pot my/openvino/path/post_training_optimization_toolkit/main.py

By default, the script will run Post-Training Optimization Toolkit using the same Python executable that was used to run the script itself. To use a different Python executable, use the -p/--python option:

./quantizer.py --all --dataset_dir <DATASET_DIR> --python my/python

It's possible to specify a target device for Post-Training Optimization Toolkit to optimize for, by using the --target_device option:

./quantizer.py --all --dataset_dir <DATASET_DIR> --target_device VPU

The supported values are those accepted by the "target_device" option in Post-Training Optimization Toolkit's config files. If this option is unspecified, Post-Training Optimization Toolkit's default is used.

The script can print the quantization commands without actually running them. To do this, use the --dry_run option:

./quantizer.py --all --dataset_dir <DATASET_DIR> --dry_run

With this option specified, the configuration file for Post-Training Optimization Toolkit will still be created, so that you can inspect it.

See the "Shared options" section for information on other options accepted by the script.

Dataset directory layout

Currently, all models for which quantization is supported require the ILSVRC 2012 validation dataset. This means that <DATASET_DIR> must contain the following entries:

Model information dumper usage

The basic usage is to run the script like this:

./info_dumper.py --all

This will print to standard output information about all models.

The only options accepted by the script are those described in the "Shared options" section.

The script's output is a JSON array, each element of which is a JSON object describing a single model. Each such object has the following keys:

Shared options

The are certain options that all tools accept.

-h/--help can be used to print a help message:

./TOOL.py --help

There are several mutually exclusive filter options that select the models the tool will process:

./TOOL.py --all
./TOOL.py --name 'mtcnn-p,densenet-*'

See https://docs.python.org/3/library/fnmatch.html for a full description of the pattern syntax.

./TOOL.py --list my.lst

The file must contain one pattern per line. The pattern syntax is the same as for the --name option. Blank lines and comments starting with # are ignored. For example:

mtcnn-p
densenet-* # get all DenseNet variants

To see the available models, you can use the --print_all option. When this option is specified, the tool will print all model names defined in the configuration file and exit:

$ ./TOOL.py --print_all
action-recognition-0001-decoder
action-recognition-0001-encoder
age-gender-recognition-retail-0013
driver-action-recognition-adas-0002-decoder
driver-action-recognition-adas-0002-encoder
emotions-recognition-retail-0003
face-detection-adas-0001
face-detection-adas-binary-0001
face-detection-retail-0004
face-detection-retail-0005
[...]

Either --print_all or one of the filter options must be specified.


OpenVINO is a trademark of Intel Corporation or its subsidiaries in the U.S. and/or other countries.

Copyright © 2018-2019 Intel Corporation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.