yobx.to_onnx#

yobx.to_onnx(model: Any, args: Any = None, input_names: Sequence[str] | None = None, dynamic_shapes: Any | None = None, target_opset: int | Dict[str, int] = 21, verbose: int = 0, large_model: bool = False, external_threshold: int = 1024, filename: str | None = None, return_optimize_report: bool = False, **kwargs: Any) → Any[source]#

Convert any supported model type to ONNX.

This is the unified top-level entry point. It inspects model and args to decide which backend converter to call:

  • torch — when model is a torch.nn.Module or torch.fx.GraphModule. Delegates to yobx.torch.to_onnx(). Any extra kwargs are forwarded verbatim; see that function for the full list of accepted parameters (as_function, options, dispatcher, dynamic_shapes, export_options, function_options, …).

  • scikit-learn — when model is a sklearn.base.BaseEstimator. Delegates to yobx.sklearn.to_onnx(). Extra kwargs include builder_cls, extra_converters, function_options, convert_options, …

  • TensorFlow / Keras — when model is a tf.Module (including Keras models and layers). Delegates to yobx.tensorflow.to_onnx(). Extra kwargs include builder_cls, extra_converters, …

  • LiteRT / TFLite — when model is bytes (raw flatbuffer) or a str / os.PathLike whose path ends with ".tflite". Delegates to yobx.litert.to_onnx(). Extra kwargs include builder_cls, extra_converters, subgraph_index, … Note: filename is not supported by this backend and is silently ignored.

  • SQL / DataFrame / NumPy callable — when model is a plain str (SQL query), a Python callable(), or a polars.LazyFrame. Delegates to yobx.sql.to_onnx(). Extra kwargs include custom_functions, builder_cls, …

Parameters:

  • model – the model to convert; see dispatch rules above.

  • args – input arguments passed to the selected converter. For torch this is a sequence of torch.Tensor objects. For sklearn / tensorflow / litert this is a tuple of numpy.ndarray objects. For SQL / DataFrame this is a {column: dtype} mapping or a numpy.ndarray (numpy-function tracing).

  • input_names – optional list of names for the ONNX graph input tensors. Supported by all backends.

  • dynamic_shapes –

    optional specification of dynamic (symbolic) dimensions. The exact format and default behaviour differ by backend:

    • torch — follows torch.export.export() conventions: a dict mapping input names to per-axis torch.export.Dim objects, or a tuple with one entry per input. None means no dynamic dimensions (all shapes are fixed).

    • sklearn / tensorflow / litert — a tuple of {axis: dim_name} dicts, one per input. None means axis 0 is treated as dynamic (batch dimension) for every input, while all other axes remain static.

    • sql (numpy callable) — same {axis: dim_name} tuple format. None lets the backend apply its own default (typically axis 0 dynamic). Ignored for SQL strings and DataFrame-tracing callables.

  • target_opset – ONNX opset version to target. Either an integer for the default domain (""), or a Dict[str, int] mapping domain names to opset versions (e.g. {"": 21, "ai.onnx.ml": 5}). Defaults to DEFAULT_TARGET_OPSET.

  • verbose – verbosity level (0 = silent). Supported by all backends.

  • large_model – if True the returned ExportArtifact stores tensors as external data rather than embedding them inside the proto. Supported by all backends.

  • external_threshold – when large_model is True, tensors whose element count exceeds this threshold are stored externally. Supported by all backends.

  • filename – if set, the exported ONNX model is saved to this path. Supported by torch, sklearn, tensorflow, and sql backends. Not supported by the LiteRT backend (ignored when model is a .tflite file or raw flatbuffer bytes).

  • return_optimize_report – if True, the returned ExportArtifact has its report attribute populated with per-pattern optimization statistics. Supported by all backends.

  • kwargs – additional backend-specific keyword arguments forwarded verbatim to the selected converter. See the backend-specific to_onnx functions listed above for their full parameter lists.

Returns:

ExportArtifact wrapping the exported ONNX proto together with an ExportReport.

Example — scikit-learn (batch dimension fixed):

import numpy as np
from sklearn.linear_model import LinearRegression
from yobx import to_onnx

X = np.random.randn(20, 4).astype(np.float32)
y = X[:, 0] + X[:, 1]
reg = LinearRegression().fit(X, y)
artifact = to_onnx(reg, (X,))

Example — scikit-learn (explicit dynamic batch dimension):

import numpy as np
from sklearn.linear_model import LinearRegression
from yobx import to_onnx

X = np.random.randn(20, 4).astype(np.float32)
y = X[:, 0] + X[:, 1]
reg = LinearRegression().fit(X, y)
# Mark axis 0 (batch) as dynamic for input 0:
artifact = to_onnx(reg, (X,), dynamic_shapes=({0: "batch"},))

Example — PyTorch (dynamic batch dimension via torch.export.Dim):

import torch
from yobx import to_onnx

class Neuron(torch.nn.Module):
    def __init__(self):
        super().__init__()
        self.linear = torch.nn.Linear(4, 2)
    def forward(self, x):
        return torch.relu(self.linear(x))

model = Neuron()
x = torch.randn(3, 4)
batch = torch.export.Dim("batch", min=1, max=256)
artifact = to_onnx(model, (x,), dynamic_shapes={"x": {0: batch}})

Example — SQL:

import numpy as np
from yobx import to_onnx

artifact = to_onnx(
    "SELECT a + b AS total FROM t WHERE a > 0",
    {"a": np.float32, "b": np.float32},
)
On this page

This Page