skl2onnx: Convert Scikit-learn Models to ONNX

Warnings

• breaking Version 1.19.0.1 (released as 0.19.0 on PyPI) was incomplete. Users attempting to install or use this specific version should instead use 1.19.1 or later to avoid issues.
  Fix: Install `skl2onnx==1.19.1` or a more recent version like `pip install skl2onnx`.
• breaking The minimum supported version of scikit-learn has increased over time. As of skl2onnx 1.17.0, older scikit-learn versions (<1.1) are no longer tested, and prior to 1.16.0, versions < 1.0 were not tested.
  Fix: Ensure your scikit-learn installation is up-to-date, preferably `scikit-learn>=1.1`, to maintain compatibility and receive tested support.
• deprecated The `onnxconverter-common` dependency was removed in skl2onnx version 1.19.1. If you had custom converters or logic relying directly on components from this library through skl2onnx, you will need to update your code.
  Fix: Review your custom converter implementations and update them to use `skl2onnx`'s internal utilities or directly depend on `onnxconverter-common` if still needed for other purposes.
• gotcha When converting a model using `convert_sklearn`, you must provide `initial_types` to define the input schema (names, types, and shapes). Failing to do so or providing incorrect types will lead to conversion errors. While `to_onnx` can infer this from sample data (e.g., `X[:1]`), understanding expected input types is crucial for robust conversions.
  Fix: Always pass a small sample of your input data (e.g., `X[:1]`) to `to_onnx` for inference, or explicitly define `initial_types` (e.g., `[('input', FloatTensorType([None, n_features]))]`) for `convert_sklearn`.
• gotcha Specify the `target_opset` parameter during conversion for better compatibility. While skl2onnx will choose the latest tested opset if not specified, it's recommended to set it explicitly (e.g., `target_opset=14` or higher for broader compatibility with modern ONNX Runtimes). skl2onnx 1.17.0 supports up to opset 21, and 1.20.0 up to opset 22.
  Fix: Add `target_opset=N` (e.g., `target_opset=22`) to your `to_onnx` or `convert_sklearn` call, aligning with your ONNX Runtime version's capabilities.
• gotcha For classification models, the output includes probabilities in a 'ZipMap' format by default, which might not be universally supported or desired for all deployment targets. Some platforms (e.g., BigQuery ML) require disabling this feature.
  Fix: Pass `options={id(model): {'zipmap': False}}` to your `to_onnx` or `convert_sklearn` call to disable ZipMap output for classification models if needed.
• gotcha skl2onnx has limitations on certain scikit-learn features and models. Sparse data support is limited, and models that perform iterative numerical optimization during inference (like NMF or LDA) are generally not supported for conversion.
  Fix: Consult the `skl2onnx` documentation's 'Supported scikit-learn Models' and 'Advanced scenarios' sections for a comprehensive list of supported models and known limitations, especially regarding sparse inputs or complex transformers.

Install

• pip install skl2onnx onnx onnxruntime Install core packages

Imports

• to_onnx

  from skl2onnx import to_onnx

  This is the primary function for converting a scikit-learn model, automatically inferring input types from example data.
• convert_sklearn

  from skl2onnx import convert_sklearn

  This function provides more explicit control over conversion, requiring 'initial_types' to be specified manually.
• FloatTensorType

  from skl2onnx.common.data_types import FloatTensorType

  Essential for defining input data types, especially when using 'convert_sklearn'.

Quickstart

This quickstart demonstrates how to train a simple RandomForestClassifier from scikit-learn, convert it to the ONNX format using `skl2onnx.to_onnx`, save the ONNX model to a file, and then load it with ONNX Runtime for inference. It highlights the typical workflow from training to ONNX-based prediction.

import numpy as np
from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestClassifier
from skl2onnx import to_onnx
import onnxruntime as rt

# 1. Train a scikit-learn model
iris = load_iris()
X, y = iris.data, iris.target
X = X.astype(np.float32) # ONNX typically uses float32
model = RandomForestClassifier(n_estimators=10, random_state=42)
model.fit(X, y)

# 2. Convert the scikit-learn model to ONNX format
# `X[:1]` is used to infer the input types and shapes
onx_model = to_onnx(model, X[:1])

# 3. Save the ONNX model to a file
with open("rf_iris.onnx", "wb") as f:
    f.write(onx_model.SerializeToString())

# 4. Load and make predictions with ONNX Runtime
sess = rt.InferenceSession("rf_iris.onnx", providers=["CPUExecutionProvider"])
input_name = sess.get_inputs()[0].name
output_names = [output.name for output in sess.get_outputs()]

# Make a prediction
predictions = sess.run(output_names, {input_name: X[0:1].astype(np.float32)})

print(f"Original model prediction: {model.predict(X[0:1])}")
print(f"ONNX Runtime prediction (label): {predictions[0]}")
print(f"ONNX Runtime prediction (probabilities): {predictions[1]}")