MXNet to ONNX export tutorial #12297

Roshrini · 2018-08-22T21:15:52Z

Description

Example showing how to use MXNet to ONNX exporter
@aaronmarkham

Checklist

Essentials

Changes are complete (i.e. I finished coding on this PR)
Code is well-documented:
For user-facing API changes, API doc string has been updated.
For new C++ functions in header files, their functionalities and arguments are documented.
For new examples, README.md is added to explain the what the example does, the source of the dataset, expected performance on test set and reference to the original paper if applicable
Check the API doc at http://mxnet-ci-doc.s3-accelerate.dualstack.amazonaws.com/PR-$PR_ID/$BUILD_ID/index.html
To the my best knowledge, examples are either not affected by this change, or have been fixed to be compatible with this change

anirudhacharya · 2018-08-22T21:41:56Z

tests/tutorials/test_tutorials.py

@@ -124,6 +124,9 @@ def test_nlp_cnn():
 def test_onnx_super_resolution():
    assert _test_tutorial_nb('onnx/super_resolution')

+def test_onnx_export_mxnet_to_onnx():
+    assert _test_tutorial_nb('onnx/export_mxnet_to_onnx')


these tests are currently disabled from running on the nightly test run.

Fails CI build if new test not added in test_tutorials. If this is currently disabled, do we need it as a part of CI lint check? @marcoabreu

anirudhacharya · 2018-08-22T21:44:27Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+checker.check_graph(model_proto.graph)
+```
+
+This method confirms exported model protobuf is valid. Now, the model is ready to be imported in other frameworks for inference!


it verifies that the proto file is as per the ONNX specification, but do you think we should perform inference on the serialized model on any of the frameworks to ensure that the model parameters and model structure was serialized properly?

Definitely good to have! We can extend this tutorial later to show inference with other frameworks or add another tutorial to show end to end usecase.

anirudhacharya · 2018-08-22T21:45:37Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+converted_model_path = onnx_mxnet.export_model(sym, params, [input_shape], np.float32, onnx_file)
+```
+
+This API returns path of the converted model which you can use further to import in other frameworks.


.. which you can later use to import the model into other frameworks.

aaronmarkham · 2018-08-22T23:15:16Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+[Open Neural Network Exchange (ONNX)](https://github.com/onnx/onnx) provides an open source format for AI models. It defines an extensible computation graph model, as well as definitions of built-in operators and standard data types.
+
+In this tutorial, we will show how you can save MXNet models to ONNX format.


the ONNX format.

aaronmarkham · 2018-08-22T23:15:54Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+In this tutorial, we will show how you can save MXNet models to ONNX format.
+
+Current MXNet-ONNX import and export operator support and coverage can be found [here](https://cwiki.apache.org/confluence/display/MXNET/ONNX+Operator+Coverage).


operators (plural)

Also, try linking to more context than (here). Say like:
MXNet-ONNX operators coverage and features are updated regularly. Visit the ONNX operator coverage page for the latest information.

aaronmarkham · 2018-08-22T23:19:24Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+In this tutorial we will:
+
+- learn how to use MXNet to ONNX exporter on pretrained models


how about one sentence? Unless you're thinking of adding more bullets....

aaronmarkham · 2018-08-22T23:19:42Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+- learn how to use MXNet to ONNX exporter on pretrained models
+
+## Pre-requisite


Prerequisites

aaronmarkham · 2018-08-22T23:21:08Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+To run the tutorial you will need to have installed the following python modules:
+- [MXNet == 1.3.0](http://mxnet.incubator.apache.org/install/index.html)
+- [onnx](https://github.com/onnx/onnx) v1.2.1 (follow the install guide)
+MXNet ONNX importer and exporter follows version 7 of ONNX operator set.


I'm not sure what this means. I see you want ONNX v1.2.1, but there's yet another version to know about within ONNX? Would I get v1.2.1 then have to download an operator set that is version 7? Maybe this is TMI?

v1.2.1 comes with opset 7 which we currently support. Made it more clear

aaronmarkham · 2018-08-22T23:26:16Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+This is useful if we are training a model. At the end of training, we just need to invoke the `export_model` function and provide sym and params objects as inputs with other attributes to save the model in ONNX format.
+
+#### MXNet's exported json and params files:


I'd number this 2

aaronmarkham · 2018-08-22T23:26:32Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+This is useful if we have pre-trained models and we want to convert them to ONNX format.
+
+In this tutorial, we will show second usecase to convert pretrained model to ONNX format:


aaronmarkham · 2018-08-22T23:27:11Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+```python
+# Downloaded input symbol and params files
+sym = 'resnet-18-symbol.json'


At this point I'm thinking I was supposed to manually download the files from the zoo. Is that right?

we downloaded files before. we will use those now

aaronmarkham · 2018-08-22T23:29:17Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+## Check validity of ONNX model
+
+Now we can check validity of the converted ONNX model by using ONNX checker tool as follows:


...by using ONNX checker tool. The tool will validate the model by checking if the content contains valid protobuf:

aaronmarkham · 2018-08-22T23:30:39Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+checker.check_graph(model_proto.graph)
+```
+
+This method confirms exported model protobuf is valid. Now, the model is ready to be imported in other frameworks for inference!


Any comment on what to do if the check fails or common reasons why it might fail?

Also, is there a call to action or next steps?

Roshrini · 2018-08-23T01:12:46Z

@aaronmarkham Addressed the comments.

aaronmarkham

Just a few more updates needed.

aaronmarkham · 2018-08-23T16:03:14Z

docs/tutorials/onnx/export_mxnet_to_onnx.md


-## Pre-requisite
+## Prerequisite


Make plural

aaronmarkham · 2018-08-23T16:08:13Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

-From the above API description, we can see that export_model API accepts 2 kinds of inputs:
-
-#### MXNet sym, params objects:
+From the above API description, we can see that export_model API accepts two kinds of inputs:


that the export_model

aaronmarkham · 2018-08-23T16:09:11Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

@@ -95,6 +95,8 @@ model_proto = onnx.load(converted_model_path)
 checker.check_graph(model_proto.graph)
 ```

+If the converted protobuf format doesn't qualify to ONNX proto specifications, the checker will throw errors but in this case it successfully passes. 


errors, but

Roshrini · 2018-08-23T16:22:26Z

@aaronmarkham Thanks for reviewing. Addressed new comments :)

sandeep-krishnamurthy

Thanks for this tutorial @Roshrini !

sandeep-krishnamurthy · 2018-08-23T16:07:16Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+MXNet-ONNX operators coverage and features are updated regularly. Visit the [ONNX operator coverage](https://cwiki.apache.org/confluence/display/MXNET/ONNX+Operator+Coverage) page for the latest information.
+
+In this tutorial we will learn how to use MXNet to ONNX exporter on pre-trained models.


nit: In this tutorial, we will..

making hyper link to API spec for mxnet-to-onnx exporter will be useful.

sandeep-krishnamurthy · 2018-08-23T16:08:25Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+## Prerequisite
+
+To run the tutorial you will need to have installed the following python modules:
+- [MXNet == 1.3.0](http://mxnet.incubator.apache.org/install/index.html)


>= to make this tutorial relevant going forward ?

sandeep-krishnamurthy · 2018-08-23T16:09:53Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+To run the tutorial you will need to have installed the following python modules:
+- [MXNet == 1.3.0](http://mxnet.incubator.apache.org/install/index.html)
+- [onnx](https://github.com/onnx/onnx) v1.2.1 (follow the install guide)


Please link to install guide. May be this? https://github.com/onnx/onnx#installation

sandeep-krishnamurthy · 2018-08-23T16:12:11Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+## Downloading a model from the MXNet model zoo
+
+We download a pre-trained model, in this case ResNet-18 model, trained on [ImageNet](http://www.image-net.org/) from the [MXNet Model Zoo](http://data.mxnet.io/models/imagenet/).


We download the pre-trained ResNet-18 ImageNet model from MXNet Model Zoo

sandeep-krishnamurthy · 2018-08-23T16:16:50Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+## MXNet to ONNX exporter API
+
+We can check MXNet's ONNX `export_model` API usage as follows: 


Let us describe the MXNet's export_model to ONNX API.

sandeep-krishnamurthy · 2018-08-23T16:17:16Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+```python
+help(onnx_mxnet.export_model)
+```
+


Do you want to show the output here?

sandeep-krishnamurthy · 2018-08-23T16:18:44Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+help(onnx_mxnet.export_model)
+```
+
+From the above API description, we can see that export_model API accepts two kinds of inputs:


export_model API can accept the MXNet model in one of the following two ways.

sandeep-krishnamurthy · 2018-08-23T16:21:28Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+2. MXNet's exported json and params files:
+    * This is useful if we have pre-trained models and we want to convert them to ONNX format.
+
+In this tutorial, we will show second use case to convert pre-trained model to ONNX format:


Since we have downloaded a pre-trained model files, we will use the export_model API by passing the path for symbol and params files.

sandeep-krishnamurthy · 2018-08-23T16:23:00Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+## How to use MXNet to ONNX exporter API
+
+We will use downloaded files and define input variables.


We will use the downloaded pre-trained model files (sym, params)...

sandeep-krishnamurthy · 2018-08-23T16:24:05Z

docs/tutorials/onnx/export_mxnet_to_onnx.md

+
+```python
+# Downloaded input symbol and params files
+sym = 'resnet-18-symbol.json'


will be more clear that this is file path if we use - './resnet-18-symbol.json' etc. Thoughts?

I think it will be more explicit. Changed it.

Roshrini · 2018-08-23T16:53:53Z

@sandeep-krishnamurthy Thanks for reviewing. Addressed comments.

sandeep-krishnamurthy

Thanks!
LGTM

* mxnet to onnx export tutorial added * test added * addressing review comment * comments addressed * few more fixes * addressing comments * addressing comments * retrigger build

Roshrini requested a review from szha as a code owner August 22, 2018 21:15

anirudhacharya reviewed Aug 22, 2018

View reviewed changes

aaronmarkham suggested changes Aug 22, 2018

View reviewed changes

sandeep-krishnamurthy added Doc ONNX pr-awaiting-review PR is waiting for code review labels Aug 23, 2018

aaronmarkham suggested changes Aug 23, 2018

View reviewed changes

Roshrini force-pushed the onnx_export_tutorial branch from 6100d0e to 798e273 Compare August 23, 2018 16:21

sandeep-krishnamurthy reviewed Aug 23, 2018

View reviewed changes

Roshrini force-pushed the onnx_export_tutorial branch from 798e273 to 01734dc Compare August 23, 2018 16:46

Roshrini added 7 commits August 23, 2018 09:46

mxnet to onnx export tutorial added

e5ce3a6

test added

fde6795

addressing review comment

1500594

comments addressed

52fb50f

few more fixes

055a02c

addressing comments

01734dc

addressing comments

70cdf41

retrigger build

aa43aba

aaronmarkham approved these changes Aug 23, 2018

View reviewed changes

sandeep-krishnamurthy approved these changes Aug 23, 2018

View reviewed changes

sandeep-krishnamurthy added pr-awaiting-merge Review and CI is complete. Ready to Merge and removed pr-awaiting-review PR is waiting for code review labels Aug 23, 2018

sandeep-krishnamurthy merged commit cc30fab into apache:master Aug 23, 2018

Roshrini deleted the onnx_export_tutorial branch November 15, 2018 18:17


		[Open Neural Network Exchange (ONNX)](https://github.com/onnx/onnx) provides an open source format for AI models. It defines an extensible computation graph model, as well as definitions of built-in operators and standard data types.

		In this tutorial, we will show how you can save MXNet models to ONNX format.


		In this tutorial, we will show how you can save MXNet models to ONNX format.

		Current MXNet-ONNX import and export operator support and coverage can be found [here](https://cwiki.apache.org/confluence/display/MXNET/ONNX+Operator+Coverage).


		In this tutorial we will:

		- learn how to use MXNet to ONNX exporter on pretrained models


		- learn how to use MXNet to ONNX exporter on pretrained models

		## Pre-requisite


		This is useful if we are training a model. At the end of training, we just need to invoke the `export_model` function and provide sym and params objects as inputs with other attributes to save the model in ONNX format.

		#### MXNet's exported json and params files:


		This is useful if we have pre-trained models and we want to convert them to ONNX format.

		In this tutorial, we will show second usecase to convert pretrained model to ONNX format:


		## Check validity of ONNX model

		Now we can check validity of the converted ONNX model by using ONNX checker tool as follows:


		MXNet-ONNX operators coverage and features are updated regularly. Visit the [ONNX operator coverage](https://cwiki.apache.org/confluence/display/MXNET/ONNX+Operator+Coverage) page for the latest information.

		In this tutorial we will learn how to use MXNet to ONNX exporter on pre-trained models.


		## Downloading a model from the MXNet model zoo

		We download a pre-trained model, in this case ResNet-18 model, trained on [ImageNet](http://www.image-net.org/) from the [MXNet Model Zoo](http://data.mxnet.io/models/imagenet/).


		## MXNet to ONNX exporter API

		We can check MXNet's ONNX `export_model` API usage as follows:


		## How to use MXNet to ONNX exporter API

		We will use downloaded files and define input variables.

MXNet to ONNX export tutorial #12297

MXNet to ONNX export tutorial #12297

Conversation

Roshrini commented Aug 22, 2018 • edited Loading

Description

Checklist

Essentials

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Roshrini commented Aug 23, 2018

aaronmarkham left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Roshrini commented Aug 23, 2018

sandeep-krishnamurthy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Roshrini commented Aug 23, 2018

sandeep-krishnamurthy left a comment

Choose a reason for hiding this comment

Roshrini commented Aug 22, 2018 •

edited

Loading