From 47b4dd41f7b1bf32147305419b5084edaa0c35d3 Mon Sep 17 00:00:00 2001 From: Vinitra Swamy Date: Wed, 12 Dec 2018 17:32:07 -0800 Subject: [PATCH 1/6] doc updates for grammar and explanations for opset versioning --- README.md | 62 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 39 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 574102a9..40befdd2 100644 --- a/README.md +++ b/README.md @@ -12,14 +12,10 @@ ONNXMLTools enables you to convert models from different machine learning toolki * Keras * LightGBM (through its scikit-learn interface) -(To convert Tensorflow models to ONNX, see [tensorflow-onnx](https://github.com/onnx/tensorflow-onnx)) -(To convert ONNX model to Core ML, see [onnx-coreml](https://github.com/onnx/onnx-coreml))\ -If you want the converted model is compatible with certain ONNX version, -please specify the target_opset parameter on invoking convert function, -and the following Keras converter example code shows how it works. +To convert Tensorflow models to ONNX, see [tensorflow-onnx](https://github.com/onnx/tensorflow-onnx). ## Install -You can install latest release of ONNXMLTools from pypi: +You can install latest release of ONNXMLTools from [PyPi](https://pypi.org/project/onnxmltools/): ``` pip install onnxmltools ``` @@ -27,17 +23,23 @@ or install from source: ``` pip install git+https://github.com/onnx/onnxmltools ``` -If you choose to install `onnxmltools` from its source code, you must set an environment variable `ONNX_ML=1` before installing `onnx` package. +If you choose to install `onnxmltools` from its source code, you must set the environment variable `ONNX_ML=1` before installing the `onnx` package. ## Dependencies -This package uses ONNX, NumPy, and ProtoBuf. If you are converting a model from scikit-learn, Apple Core ML, Keras, or LightGBM, you need the following packages installed respectively: +This package relies on ONNX, NumPy, and ProtoBuf. If you are converting a model from scikit-learn, Core ML, Keras, or LightGBM, you will need an environment with the respective package installed from the list below: 1. scikit-learn 2. CoreMLTools -3. Keras (version 2.0.8 or higher) with corresponding Tensorflow version +3. Keras (version 2.0.8 or higher) with the corresponding Tensorflow version 4. LightGBM (scikit-learn interface) -## Examples -Here is a simple example to convert a Core ML model: +# Examples + +## Converting Models +If you want the converted ONNX model to be compatible with a certain ONNX version, please specify the target_opset parameter upon invoking the convert function. The following Keras model conversion example demonstrates this below. You can identify the mapping from ONNX Operator Sets (referred to as opsets) to ONNX versions in the [versioning documentation](https://github.com/onnx/onnx/blob/master/docs/Versioning.md#released-versions). + +### CoreML -> ONNX Conversion +Here is a simple code snippet to convert a Core ML model into an ONNX model. + ```python import onnxmltools import coremltools @@ -54,7 +56,10 @@ onnxmltools.utils.save_text(onnx_model, 'example.json') # Save as protobuf onnxmltools.utils.save_model(onnx_model, 'example.onnx') ``` -Next, we show a simple usage of the Keras converter. + +### Keras -> ONNX Conversion +Next, we show an example of converting a Keras model into an ONNX model with `target_opset=7`, which corresponds to ONNX version 1.2. + ```python import onnxmltools from keras.layers import Input, Dense, Add @@ -81,23 +86,35 @@ mapped2_2 = sub_model2(input2) sub_sum = Add()([mapped1_2, mapped2_2]) keras_model = Model(inputs=[input1, input2], output=sub_sum) -# Convert it! -onnx_model = onnxmltools.convert_keras(keras_model, target_opset=8) # target_opset is optional +# Convert it! The target_opset parameter is optional. +onnx_model = onnxmltools.convert_keras(keras_model, target_opset=7) ``` -# Tests converted models +### Checking the ONNX Operator Set (opset) of your converted model + +You can check the opset of your ONNX model using [Netron](https://github.com/lutzroeder/Netron), a viewer for Neural Network models. Alternatively, you could identify your converted model's opset version through the following line of code: -*onnxmltools* converts models in ONNX format which +``` +# add line here +``` + +If the result from checking your ONNX model's opset above is smaller than the `target_opset` number you passed into the onnxmltools.convert function, do not be worried. Note that the ONNXMLTools converter works by looking at each operator in your original framework's model and identifying the respective ONNX opset in which it has most recently been updated. It then takes the maximum over all of the operators used in your new ONNX model to result in the converted model's opset number. + +Let's take a model with two operators. If Operator A was most recently updated in Opset 6, and Operator B was most recently updated in Opset 7, the ONNX model's opset will always be 7, even if you request target_opset=8. Documentation for the [ONNX Model format] and more examples for converting models from different frameworks can be found in the [ONNX tutorials](https://github.com/onnx/tutorials) repository. + +# Testing model converters + +*onnxmltools* converts models into the ONNX format which can be then used to compute predictions with the -backend of your choice. However, there exists a way +backend of your choice. There exists a way to automatically check every converter with [onnxruntime](https://pypi.org/project/onnxruntime/) or [onnxruntime-gpu](https://pypi.org/project/onnxruntime-gpu/). ## Test all existing converters -This process requires to clone the *onnxmltools* repository. +This process requires the user to clone the *onnxmltools* repository. The following command runs all unit tests and generates dumps of models, inputs, expected outputs and converted models in folder ``TESTDUMP``. @@ -106,8 +123,8 @@ in folder ``TESTDUMP``. python tests/main.py DUMP ``` -It requires *onnxruntime*, *numpy* for most of the models, -*pandas* for transform related to text features, +It requires *onnxruntime*, *numpy* for most models, +*pandas* for transforms related to text features, and *scipy* for sparse features. One test also requires *keras* to test a custom operator. That means *sklearn* or any machine learning library is requested. @@ -115,16 +132,15 @@ It requires *onnxruntime*, *numpy* for most of the models, ## Add a new converter Once the converter is implemented, a unit test is added -to test it works. At the end of the unit test, function +to confirm that it works. At the end of the unit test, function *dump_data_and_model* or any equivalent function must be called to dump the expected output and the converted model. Once these file are generated, a corresponding test must be added in *tests_backend* to compute the prediction with the runtime. - # License [MIT License](LICENSE) ## Acknowledgments -The package was developed by the following engineers and data scientists at Microsoft starting from winter 2017: Zeeshan Ahmed, Wei-Sheng Chin, Aidan Crook, Xavier Dupre, Costin Eseanu, Tom Finley, Lixin Gong, Scott Inglis, Pei Jiang, Ivan Matantsev, Prabhat Roy, M. Zeeshan Siddiqui, Shouheng Yi, Shauheen Zahirazami, Yiwen Zhu, Du Li, Xuan Li, Wenbing Li +This package was developed by the following engineers and data scientists at Microsoft starting from winter 2017: Zeeshan Ahmed, Wei-Sheng Chin, Aidan Crook, Xavier Dupre, Costin Eseanu, Tom Finley, Lixin Gong, Scott Inglis, Pei Jiang, Ivan Matantsev, Prabhat Roy, M. Zeeshan Siddiqui, Shouheng Yi, Shauheen Zahirazami, Yiwen Zhu, Du Li, Xuan Li, Wenbing Li, Vinitra Swamy. From da94b076f530f0cd37927c3a8b2e5c93a8904645 Mon Sep 17 00:00:00 2001 From: Vinitra Swamy Date: Tue, 18 Dec 2018 15:20:14 -0800 Subject: [PATCH 2/6] removing contribution names, as per PR suggestion --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 40befdd2..a1422dcf 100644 --- a/README.md +++ b/README.md @@ -142,5 +142,3 @@ with the runtime. # License [MIT License](LICENSE) -## Acknowledgments -This package was developed by the following engineers and data scientists at Microsoft starting from winter 2017: Zeeshan Ahmed, Wei-Sheng Chin, Aidan Crook, Xavier Dupre, Costin Eseanu, Tom Finley, Lixin Gong, Scott Inglis, Pei Jiang, Ivan Matantsev, Prabhat Roy, M. Zeeshan Siddiqui, Shouheng Yi, Shauheen Zahirazami, Yiwen Zhu, Du Li, Xuan Li, Wenbing Li, Vinitra Swamy. From af79165545cef83aff8de384d380d161b113da85 Mon Sep 17 00:00:00 2001 From: Vinitra Swamy Date: Thu, 3 Jan 2019 11:03:09 -0800 Subject: [PATCH 3/6] adding details, fixing minor formatting errors --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a1422dcf..a6addc6c 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ This package relies on ONNX, NumPy, and ProtoBuf. If you are converting a model # Examples ## Converting Models -If you want the converted ONNX model to be compatible with a certain ONNX version, please specify the target_opset parameter upon invoking the convert function. The following Keras model conversion example demonstrates this below. You can identify the mapping from ONNX Operator Sets (referred to as opsets) to ONNX versions in the [versioning documentation](https://github.com/onnx/onnx/blob/master/docs/Versioning.md#released-versions). +If you want the converted ONNX model to be compatible with a certain ONNX version, please specify the target_opset parameter upon invoking the convert function. The following Keras model conversion example demonstrates this below. You can identify the mapping from ONNX Operator Sets (referred to as opsets) to ONNX releases in the [versioning documentation](https://github.com/onnx/onnx/blob/master/docs/Versioning.md#released-versions). ### CoreML -> ONNX Conversion Here is a simple code snippet to convert a Core ML model into an ONNX model. @@ -58,7 +58,7 @@ onnxmltools.utils.save_model(onnx_model, 'example.onnx') ``` ### Keras -> ONNX Conversion -Next, we show an example of converting a Keras model into an ONNX model with `target_opset=7`, which corresponds to ONNX version 1.2. +Next, we show an example of converting a Keras model into an ONNX model with `target_opset=7`, which corresponds to ONNX release version 1.2. ```python import onnxmltools @@ -91,9 +91,10 @@ onnx_model = onnxmltools.convert_keras(keras_model, target_opset=7) ``` -### Checking the ONNX Operator Set (opset) of your converted model -You can check the opset of your ONNX model using [Netron](https://github.com/lutzroeder/Netron), a viewer for Neural Network models. Alternatively, you could identify your converted model's opset version through the following line of code: +### Checking the ONNX Operator Set of your converted model + +You can check the Operator Set (opset) of your converted ONNX model using [Netron](https://github.com/lutzroeder/Netron), a viewer for Neural Network models. Alternatively, you could identify your converted model's opset version through the following line of code: ``` # add line here @@ -101,7 +102,7 @@ You can check the opset of your ONNX model using [Netron](https://github.com/lut If the result from checking your ONNX model's opset above is smaller than the `target_opset` number you passed into the onnxmltools.convert function, do not be worried. Note that the ONNXMLTools converter works by looking at each operator in your original framework's model and identifying the respective ONNX opset in which it has most recently been updated. It then takes the maximum over all of the operators used in your new ONNX model to result in the converted model's opset number. -Let's take a model with two operators. If Operator A was most recently updated in Opset 6, and Operator B was most recently updated in Opset 7, the ONNX model's opset will always be 7, even if you request target_opset=8. Documentation for the [ONNX Model format] and more examples for converting models from different frameworks can be found in the [ONNX tutorials](https://github.com/onnx/tutorials) repository. +For example, let's consider a model with two operators, Abs and Add. As of December 2018, [Abs](https://github.com/onnx/onnx/blob/master/docs/Operators.md#abs) was most recently updated in Opset 6, and [Add](https://github.com/onnx/onnx/blob/master/docs/Operators.md#add) was most recently updated in Opset 7. Therefore, the ONNX model's opset will always be 7, even if you request target_opset=8. Documentation for the [ONNX Model format](https://github.com/onnx/onnx) and more examples for converting models from different frameworks can be found in the [ONNX tutorials](https://github.com/onnx/tutorials) repository. # Testing model converters From 34446cca8ac9ec7fe6be0dfc5ad01e103ea484a1 Mon Sep 17 00:00:00 2001 From: Vinitra Swamy Date: Thu, 3 Jan 2019 13:32:57 -0800 Subject: [PATCH 4/6] added code for checking onnx model version and finished explanation of why target opset might be larger than the model's actual opset --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index a6addc6c..e3d56e80 100644 --- a/README.md +++ b/README.md @@ -91,30 +91,30 @@ onnx_model = onnxmltools.convert_keras(keras_model, target_opset=7) ``` +# Testing model converters -### Checking the ONNX Operator Set of your converted model +*onnxmltools* converts models into the ONNX format which +can be then used to compute predictions with the +backend of your choice. + +### Checking the Operator Set / Version of your converted ONNX model You can check the Operator Set (opset) of your converted ONNX model using [Netron](https://github.com/lutzroeder/Netron), a viewer for Neural Network models. Alternatively, you could identify your converted model's opset version through the following line of code: ``` -# add line here +onnx_model.opset_import[0].version ``` -If the result from checking your ONNX model's opset above is smaller than the `target_opset` number you passed into the onnxmltools.convert function, do not be worried. Note that the ONNXMLTools converter works by looking at each operator in your original framework's model and identifying the respective ONNX opset in which it has most recently been updated. It then takes the maximum over all of the operators used in your new ONNX model to result in the converted model's opset number. +If the result from checking your ONNX model's opset is **smaller** than the `target_opset` number you passed into the onnxmltools.convert function, do not be alarmed. Note that the ONNXMLTools converter works by converting each operator individually and finding the ONNX version / corresponding opset that it was most recently updated in. Once all of the operators are converted, the resultant ONNX model has the maximal opset version of all of its operators, which could be less than or equal to `target_opset`. -For example, let's consider a model with two operators, Abs and Add. As of December 2018, [Abs](https://github.com/onnx/onnx/blob/master/docs/Operators.md#abs) was most recently updated in Opset 6, and [Add](https://github.com/onnx/onnx/blob/master/docs/Operators.md#add) was most recently updated in Opset 7. Therefore, the ONNX model's opset will always be 7, even if you request target_opset=8. Documentation for the [ONNX Model format](https://github.com/onnx/onnx) and more examples for converting models from different frameworks can be found in the [ONNX tutorials](https://github.com/onnx/tutorials) repository. +To illustrate this concretely, let's consider a model with two operators, Abs and Add. As of December 2018, [Abs](https://github.com/onnx/onnx/blob/master/docs/Operators.md#abs) was most recently updated in Opset 6, and [Add](https://github.com/onnx/onnx/blob/master/docs/Operators.md#add) was most recently updated in Opset 7. Therefore, the converted ONNX model's opset will always be 7, even if you request target_opset=8. The operator set was defined this way to ensure backwards compatibility. Documentation for the [ONNX Model format](https://github.com/onnx/onnx) and more examples for converting models from different frameworks can be found in the [ONNX tutorials](https://github.com/onnx/tutorials) repository. -# Testing model converters +### Test all existing converters -*onnxmltools* converts models into the ONNX format which -can be then used to compute predictions with the -backend of your choice. There exists a way +There exists a way to automatically check every converter with [onnxruntime](https://pypi.org/project/onnxruntime/) or [onnxruntime-gpu](https://pypi.org/project/onnxruntime-gpu/). - -## Test all existing converters - This process requires the user to clone the *onnxmltools* repository. The following command runs all unit tests and generates dumps of models, inputs, expected outputs and converted models From 0b633054506992feb081027d9f96a99a123a4251 Mon Sep 17 00:00:00 2001 From: Vinitra Swamy Date: Thu, 3 Jan 2019 13:42:00 -0800 Subject: [PATCH 5/6] minor formatting and wording updates --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index e3d56e80..37f68b47 100644 --- a/README.md +++ b/README.md @@ -32,12 +32,10 @@ This package relies on ONNX, NumPy, and ProtoBuf. If you are converting a model 3. Keras (version 2.0.8 or higher) with the corresponding Tensorflow version 4. LightGBM (scikit-learn interface) -# Examples - -## Converting Models +# Converting Models If you want the converted ONNX model to be compatible with a certain ONNX version, please specify the target_opset parameter upon invoking the convert function. The following Keras model conversion example demonstrates this below. You can identify the mapping from ONNX Operator Sets (referred to as opsets) to ONNX releases in the [versioning documentation](https://github.com/onnx/onnx/blob/master/docs/Versioning.md#released-versions). -### CoreML -> ONNX Conversion +## CoreML to ONNX Conversion Here is a simple code snippet to convert a Core ML model into an ONNX model. ```python @@ -57,7 +55,7 @@ onnxmltools.utils.save_text(onnx_model, 'example.json') onnxmltools.utils.save_model(onnx_model, 'example.onnx') ``` -### Keras -> ONNX Conversion +## Keras to ONNX Conversion Next, we show an example of converting a Keras model into an ONNX model with `target_opset=7`, which corresponds to ONNX release version 1.2. ```python @@ -97,19 +95,21 @@ onnx_model = onnxmltools.convert_keras(keras_model, target_opset=7) can be then used to compute predictions with the backend of your choice. -### Checking the Operator Set / Version of your converted ONNX model +## Checking the operator set version of your converted ONNX model -You can check the Operator Set (opset) of your converted ONNX model using [Netron](https://github.com/lutzroeder/Netron), a viewer for Neural Network models. Alternatively, you could identify your converted model's opset version through the following line of code: +You can check the operator set of your converted ONNX model using [Netron](https://github.com/lutzroeder/Netron), a viewer for Neural Network models. Alternatively, you could identify your converted model's opset version through the following line of code. ``` -onnx_model.opset_import[0].version +opset_version = onnx_model.opset_import[0].version ``` -If the result from checking your ONNX model's opset is **smaller** than the `target_opset` number you passed into the onnxmltools.convert function, do not be alarmed. Note that the ONNXMLTools converter works by converting each operator individually and finding the ONNX version / corresponding opset that it was most recently updated in. Once all of the operators are converted, the resultant ONNX model has the maximal opset version of all of its operators, which could be less than or equal to `target_opset`. +If the result from checking your ONNX model's opset is *smaller* than the `target_opset` number you passed into the onnxmltools.convert function, do not be alarmed. The ONNXMLTools converter works by converting each operator individually and finding the corresponding ONNX opset version that it was most recently updated in. Once all of the operators are converted, the resultant ONNX model has the maximal opset version from all of its operators, which will be less than or equal to `target_opset`. + +To illustrate this concretely, let's consider a model with two operators, Abs and Add. As of December 2018, [Abs](https://github.com/onnx/onnx/blob/master/docs/Operators.md#abs) was most recently updated in Opset 6, and [Add](https://github.com/onnx/onnx/blob/master/docs/Operators.md#add) was most recently updated in Opset 7. Therefore, the converted ONNX model's opset will always be 7, even if you request target_opset=8. The operator set was defined this way to ensure backwards compatibility. -To illustrate this concretely, let's consider a model with two operators, Abs and Add. As of December 2018, [Abs](https://github.com/onnx/onnx/blob/master/docs/Operators.md#abs) was most recently updated in Opset 6, and [Add](https://github.com/onnx/onnx/blob/master/docs/Operators.md#add) was most recently updated in Opset 7. Therefore, the converted ONNX model's opset will always be 7, even if you request target_opset=8. The operator set was defined this way to ensure backwards compatibility. Documentation for the [ONNX Model format](https://github.com/onnx/onnx) and more examples for converting models from different frameworks can be found in the [ONNX tutorials](https://github.com/onnx/tutorials) repository. +Documentation for the [ONNX Model format](https://github.com/onnx/onnx) and more examples for converting models from different frameworks can be found in the [ONNX tutorials](https://github.com/onnx/tutorials) repository. -### Test all existing converters +## Test all existing converters There exists a way to automatically check every converter with From 48cf6ae645937a28332587817d070b0a38c9b491 Mon Sep 17 00:00:00 2001 From: Vinitra Swamy Date: Thu, 3 Jan 2019 13:54:33 -0800 Subject: [PATCH 6/6] text size changes and minor spacing + content clarity edits --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 37f68b47..b48bf26f 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ This package relies on ONNX, NumPy, and ProtoBuf. If you are converting a model 3. Keras (version 2.0.8 or higher) with the corresponding Tensorflow version 4. LightGBM (scikit-learn interface) -# Converting Models +# Examples If you want the converted ONNX model to be compatible with a certain ONNX version, please specify the target_opset parameter upon invoking the convert function. The following Keras model conversion example demonstrates this below. You can identify the mapping from ONNX Operator Sets (referred to as opsets) to ONNX releases in the [versioning documentation](https://github.com/onnx/onnx/blob/master/docs/Versioning.md#released-versions). ## CoreML to ONNX Conversion @@ -86,7 +86,6 @@ keras_model = Model(inputs=[input1, input2], output=sub_sum) # Convert it! The target_opset parameter is optional. onnx_model = onnxmltools.convert_keras(keras_model, target_opset=7) - ``` # Testing model converters @@ -103,9 +102,9 @@ You can check the operator set of your converted ONNX model using [Netron](https opset_version = onnx_model.opset_import[0].version ``` -If the result from checking your ONNX model's opset is *smaller* than the `target_opset` number you passed into the onnxmltools.convert function, do not be alarmed. The ONNXMLTools converter works by converting each operator individually and finding the corresponding ONNX opset version that it was most recently updated in. Once all of the operators are converted, the resultant ONNX model has the maximal opset version from all of its operators, which will be less than or equal to `target_opset`. +If the result from checking your ONNX model's opset is smaller than the `target_opset` number you specified in the onnxmltools.convert function, do not be alarmed. The ONNXMLTools converter works by converting each operator to the ONNX format individually and finding the corresponding opset version that it was most recently updated in. Once all of the operators are converted, the resultant ONNX model has the maximal opset version of all of its operators. -To illustrate this concretely, let's consider a model with two operators, Abs and Add. As of December 2018, [Abs](https://github.com/onnx/onnx/blob/master/docs/Operators.md#abs) was most recently updated in Opset 6, and [Add](https://github.com/onnx/onnx/blob/master/docs/Operators.md#add) was most recently updated in Opset 7. Therefore, the converted ONNX model's opset will always be 7, even if you request target_opset=8. The operator set was defined this way to ensure backwards compatibility. +To illustrate this concretely, let's consider a model with two operators, Abs and Add. As of December 2018, [Abs](https://github.com/onnx/onnx/blob/master/docs/Operators.md#abs) was most recently updated in opset 6, and [Add](https://github.com/onnx/onnx/blob/master/docs/Operators.md#add) was most recently updated in opset 7. Therefore, the converted ONNX model's opset will always be 7, even if you request `target_opset=8`. The converter behavior was defined this way to ensure backwards compatibility. Documentation for the [ONNX Model format](https://github.com/onnx/onnx) and more examples for converting models from different frameworks can be found in the [ONNX tutorials](https://github.com/onnx/tutorials) repository. @@ -141,5 +140,4 @@ be added in *tests_backend* to compute the prediction with the runtime. # License -[MIT License](LICENSE) - +[MIT License](LICENSE) \ No newline at end of file