Linux	Windows

简介

ONNXMLTools 允许您将来自不同机器学习工具包的模型转换为 ONNX。目前支持以下工具包

• Tensorflow（tf2onnx转换器的封装）
• scikit-learn（skl2onnx转换器的封装）
• Apple Core ML
• Spark ML（实验性）
• LightGBM
• libsvm
• XGBoost
• H2O
• CatBoost

Pytorch 有其内置的ONNX导出器，请在此处查看详细信息 这里。

安装

您可以从 PyPi 安装ONNXMLTools的最新版本

pip install onnxmltools

或从源代码安装

pip install git+https://github.com/microsoft/onnxconverter-common
pip install git+https://github.com/onnx/onnxmltools

如果您选择从源代码安装 onnxmltools，在安装 onnx 包之前，您必须设置环境变量 ONNX_ML=1。

依赖关系

此软件包依赖于ONNX、NumPy和ProtoBuf。如果您正在从scikit-learn、Core ML、Keras、LightGBM、SparkML、XGBoost、H2O、CatBoost或LibSVM转换模型，您将需要一个包含以下列表中相应软件包安装的环境

1. scikit-learn
2. CoreMLTools（版本3.1或更低）
3. Keras（版本2.0.8或更高）与相应的Tensorflow版本
4. LightGBM
5. SparkML
6. XGBoost
7. libsvm
8. H2O
9. CatBoost

ONNXMLTools已在Python 3.7+上进行了测试。

示例

如果您希望转换后的ONNX模型与某个ONNX版本兼容，请在调用convert函数时指定target_opset参数。以下Keras模型转换示例展示了这一点。您可以在版本说明文档中识别ONNX操作集（简称opsets）到ONNX发布的映射。

Keras到ONNX转换

接下来，我们将展示一个示例，将Keras模型转换为具有target_opset=7的ONNX模型，这对应于ONNX发布版本1.2。

import onnxmltools
from keras.layers import Input, Dense, Add
from keras.models import Model

# N: batch size, C: sub-model input dimension, D: final model's input dimension
N, C, D = 2, 3, 3

# Define a sub-model, it will become a part of our final model
sub_input1 = Input(shape=(C,))
sub_mapped1 = Dense(D)(sub_input1)
sub_model1 = Model(inputs=sub_input1, outputs=sub_mapped1)

# Define another sub-model, it will become a part of our final model
sub_input2 = Input(shape=(C,))
sub_mapped2 = Dense(D)(sub_input2)
sub_model2 = Model(inputs=sub_input2, outputs=sub_mapped2)

# Define a model built upon the previous two sub-models
input1 = Input(shape=(D,))
input2 = Input(shape=(D,))
mapped1_2 = sub_model1(input1)
mapped2_2 = sub_model2(input2)
sub_sum = Add()([mapped1_2, mapped2_2])
keras_model = Model(inputs=[input1, input2], outputs=sub_sum)

# Convert it! The target_opset parameter is optional.
onnx_model = onnxmltools.convert_keras(keras_model, target_opset=7)

CoreML到ONNX转换

以下是一个简单的代码片段，用于将Core ML模型转换为ONNX模型。

import onnxmltools
import coremltools

# Load a Core ML model
coreml_model = coremltools.utils.load_spec('example.mlmodel')

# Convert the Core ML model into ONNX
onnx_model = onnxmltools.convert_coreml(coreml_model, 'Example Model')

# Save as protobuf
onnxmltools.utils.save_model(onnx_model, 'example.onnx')

H2O到ONNX转换

以下是一个代码片段，用于将H2O MOJO模型转换为ONNX模型。唯一的前提是您必须在本地文件系统中保存一个MOJO模型。

import onnxmltools

# Convert the Core ML model into ONNX
onnx_model = onnxmltools.convert_h2o('/path/to/h2o/gbm_mojo.zip')

# Save as protobuf
onnxmltools.utils.save_model(onnx_model, 'h2o_gbm.onnx')

测试模型转换器

onnxmltools将模型转换为ONNX格式，然后可以使用您选择的任何后端进行预测。

检查转换后ONNX模型的操作集版本

您可以使用Netron（一个神经网络模型查看器）检查您转换后的ONNX模型的操作集。或者，您可以通过以下代码行识别转换模型的opset版本。

opset_version = onnx_model.opset_import[0].version

如果检查您的ONNX模型opset的结果小于在onnxmltools.convert函数中指定的target_opset数字，请放心，这可能是预期行为。ONNXMLTools转换器通过将每个操作符单独转换为ONNX格式并找到最近更新的对应opset版本来工作。一旦所有操作符都已转换，生成的ONNX模型的opset版本将是所有操作符的最大opset版本。

为了具体说明这一点，让我们考虑一个有两个操作符（Abs和Add）的模型。截至2018年12月，Abs在opset 6中最近更新，Add在opset 7中最近更新。因此，即使您请求target_opset=8，转换后的ONNX模型的opset版本也始终为7。转换器行为被定义为这种方式，以确保向后兼容性。

有关ONNX模型格式的文档以及将模型从不同框架转换的更多示例，可以在ONNX教程仓库中找到。

测试所有现有转换器

所有转换器单元测试都可以生成原始模型和转换后的模型，并使用onnxruntime或onnxruntime-gpu自动进行检查。单元测试用例都是正常的Python单元测试用例，您可以使用pytest命令行运行它，例如

python -m pytest --ignore .\tests\

对于大多数模型，需要onnxruntime和numpy，对于与文本特征相关的转换，需要pandas，对于稀疏特征需要scipy。一个测试还需要keras来测试自定义操作符。这意味着需要sklearn或任何机器学习库。

添加新的转换器

一旦实现转换器，就添加单元测试以确认其工作。在单元测试结束时，必须调用函数dump_data_and_model或任何等效函数以转储预期输出和转换后的模型。一旦生成这些文件，就必须在tests_backend中添加相应的测试来计算运行时的预测。

许可协议

Apache License v2.0