ONNXMLTools

Warnings

• gotcha ONNXMLTools itself does not include the framework-specific converter packages (e.g., `skl2onnx`, `onnx_lightgbm`, `tf2onnx`). You must install these separately for the respective conversion functions to work.
  Fix: Install the required converter package alongside `onnxmltools`. For example, for LightGBM models, use `pip install onnxmltools onnx_lightgbm lightgbm`.
• gotcha The `initial_types` parameter is mandatory for most conversion functions and defines the input tensor's name, type, and shape. Incorrect specification is a common source of errors.
  Fix: Carefully define `initial_types` using data types like `FloatTensorType`, `Int64TensorType`, etc., from `onnxmltools.convert.common.data_types`. Ensure the shape (e.g., `[None, num_features]`) matches your model's expected input.
• breaking Opset version compatibility is crucial. Choosing a `target_opset` that is too low might not support newer model features, while a `target_opset` that is too high might not be supported by your ONNX Runtime version.
  Fix: Align `target_opset` with the capabilities of your ONNX Runtime environment and the features used in your original model. Consult the ONNX operator schema for supported opsets.
• gotcha For binary classification models, the output shape (e.g., probabilities) can sometimes vary between `[N, 1]` and `[N, 2]`, leading to discrepancies with expected ONNX Runtime outputs.
  Fix: Explicitly check the output tensor shape after conversion and adjust post-processing logic if necessary. Newer versions of `onnxmltools` and underlying converters aim to standardize this, but vigilance is recommended.

Install

• pip install onnxmltools Base Installation
• pip install onnxmltools onnx_lightgbm onnx_xgboost skl2onnx tf2onnx sparkml2onnx Installation with common converters

Imports

• convert_lightgbm

  from onnxmltools import convert_lightgbm

  While onnxmltools exposes conversion functions like `convert_lightgbm` directly, the corresponding framework-specific converter package (e.g., `onnx_lightgbm`) must be installed separately for the function to work.
• FloatTensorType

  from onnxmltools.convert.common.data_types import FloatTensorType

  Used to define the input tensor types and shapes required by ONNX conversion functions.

Quickstart

This quickstart demonstrates converting a simple LightGBM classifier into the ONNX format. It highlights the use of `convert_lightgbm` and the importance of defining `initial_types` and `target_opset`. Remember to install `lightgbm`, `onnx`, and `onnx_lightgbm` separately for this to run.

import lightgbm as lgb
from onnxmltools import convert_lightgbm
from onnxmltools.convert.common.data_types import FloatTensorType
from onnx.checker import check_model
from onnx import save
import numpy as np

# Ensure required packages are installed
try:
    import lightgbm # noqa: F401
    import onnx_lightgbm # noqa: F401
    import onnx # noqa: F401
except ImportError as e:
    print(f"Skipping quickstart: Missing dependency. Please install lightgbm, onnx, and onnx_lightgbm. Error: {e}")
    exit()

# 1. Train a LightGBM model
X = np.array([[0, 0], [1, 1], [2, 2], [3, 3]], dtype=np.float32)
y = np.array([0, 1, 1, 0], dtype=np.int32)
gbm = lgb.LGBMClassifier(n_estimators=3, max_depth=2, learning_rate=0.1, random_state=42)
gbm.fit(X, y)

# 2. Define initial types for ONNX conversion
# 'None' in FloatTensorType([None, 2]) means variable batch size
initial_type = [('float_input', FloatTensorType([None, 2]))]

# 3. Convert to ONNX format, specifying a target opset (e.g., 17)
target_opset = 17 # Or a lower opset depending on ONNX Runtime compatibility
onnx_model = convert_lightgbm(gbm, initial_types=initial_type, target_opset=target_opset)

# 4. Check the ONNX model for validity
check_model(onnx_model)

# 5. Save the ONNX model to a file
save(onnx_model, "lightgbm_model.onnx")

print("LightGBM model successfully converted to lightgbm_model.onnx")