Complete Numpy API for ONNX#

The numpy API is meant to simplofy the creation of ONNX graphs by using functions very similar to what numpy implements. This page only makes a list of the available functions. A tutorial is available at Numpy to ONNX: Create ONNX graphs with an API similar to numpy. This API was first added to mlprodict in version 0.6.

Introduction
Signatures
Decorators
OnnxNumpyCompiler
OnnxVar
Registration
Available functions implemented with ONNX operators
ONNX functions executed python ONNX runtime

Introduction #

Converting custom code into ONNX is not necessarily easy. One big obstacle is ONNX does not represent all numpy functions with a single operator. One possible option is to provide a numpy API to ONNX. That’s the purpose of wrapper onnxnumpy. It takes a function written with functions following the same signature as numpy and provides a way to execute them with an ONNX runtime. In the below example, custom_fct creates an ONNX graph, the wrapper loads it in a runtime and runs it everytime the function is called.

<<<

import numpy
from typing import Any
from mlprodict.npy import onnxnumpy_default, NDArray
import mlprodict.npy.numpy_onnx_impl as nxnp


@onnxnumpy_default
def custom_fct(x: NDArray[Any, numpy.float32],
               ) -> NDArray[Any, numpy.float32]:
    "onnx numpy abs"
    return nxnp.abs(x) + numpy.float32(1)


x = numpy.array([[6.1, -5], [3.5, -7.8]], dtype=numpy.float32)
y = custom_fct(x)
print(y)

>>>

    [[7.1 6. ]
     [4.5 8.8]]

Annotations are mandatory to indicate inputs and outputs type. The decorator returns a function which is strict about types as opposed to numpy. This approach is similar to what tensorflow with autograph.

Signatures #

mlprodict.npy.NDArray (self, args, kwargs)

Used to annotation ONNX numpy functions.

ShapeType (params)

Stores shape information.

mlprodict.npy.NDArraySameType (self, dtypes = None)

Shortcut to simplify signature description.

mlprodict.npy.NDArraySameTypeSameShape (self, dtypes = None)

Shortcut to simplify signature description.

mlprodict.npy.NDArrayType (self, dtypes = None, dtypes_out = None, n_optional = None, nvars = False)

Shortcut to simplify signature description.

mlprodict.npy.onnx_numpy_annotation.NDArrayTypeSameShape (self, dtypes = None, dtypes_out = None, n_optional = None, nvars = False)

Shortcut to simplify signature description.

Decorators #

mlprodict.npy.onnxnumpy (op_version = None, runtime = None, signature = None)

Decorator to declare a function implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxnumpy_default (fct)

Decorator with options to declare a function implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxnumpy_np (op_version = None, runtime = None, signature = None)

Decorator to declare a function implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxsklearn_class (method_name, op_version = None, runtime = None, signature = None, method_names = None, overwrite = True)

Decorator to declare a converter for a class derivated from scikit-learn, implementing inference method and using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxsklearn_classifier (op_version = None, runtime = None, signature = None, register_class = None, overwrite = True)

Decorator to declare a converter for a classifier implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxsklearn_cluster (op_version = None, runtime = None, signature = None, register_class = None, overwrite = True)

Decorator to declare a converter for a cluster implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxsklearn_regressor (op_version = None, runtime = None, signature = None, register_class = None, overwrite = True)

Decorator to declare a converter for a regressor implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxsklearn_transformer (op_version = None, runtime = None, signature = None, register_class = None, overwrite = True)

Decorator to declare a converter for a transformer implemented using numpy syntax but executed with ONNX operators.

OnnxNumpyCompiler #

mlprodict.npy.OnnxNumpyCompiler (self, fct, op_version = None, runtime = None, signature = None, version = None, fctsig = None)

Implements a class which runs onnx graph.

to_onnx (self, kwargs)

Returns the ONNX graph for the wrapped function. It takes additional arguments to distinguish between multiple graphs. This happens when a function needs to support multiple type.

mlprodict.npy.FctVersion (self, args, kwargs)

Identifies a version of a function based on its arguments and its parameters.

as_string (self)

Returns a single string identifier.

as_tuple (self)

Returns a single tuple for the version.

as_tuple_with_sep (self, sep)

Returns a single tuple for the version.

OnnxVar #

mlprodict.npy.onnx_variable.OnnxVar (self, inputs, op = None, select_output = None, dtype = None, kwargs)

Variables used into onnx computation.

astype (self, dtype)

Cast

copy (self)

Returns a copy of self (use of Identity node).

flatten (self, axis = 0)

Flattens a matrix (see numpy.ndarray.flatten).

not_ (self)

Not.

reshape (self, shape)

Reshape

set_onnx_name (self, name_type)

Forces this variable to get this name during

to_algebra (self, op_version = None)

Converts the variable into an operator.

mlprodict.npy.onnx_variable.MultiOnnxVar (self, inputs, op = None, dtype = None, kwargs)

Class used to return multiple OnnxVar at the same time.

to_algebra (self, op_version = None)

Converts the variable into an operator.

mlprodict.npy.onnx_variable.TupleOnnxAny

Registration #

mlprodict.npy.update_registered_converter_npy (model, alias, convert_fct, shape_fct = None, overwrite = True, parser = None, options = None)

Registers or updates a converter for a new model so that it can be converted when inserted in a scikit-learn pipeline. This function assumes the converter is written as a function decoarated with onnxsklearn_transformer.

Available functions implemented with ONNX operators #

All functions are implemented in two submodules:

numpy function: module npy.numpy_onnx_impl
machine learned models: module npy.numpy_onnx_impl_skl

ONNX functions executed python ONNX runtime #

Same function as above, the import goes from from mlprodict.npy.numpy_onnx_impl import <function-name> to from mlprodict.npy.numpy_onnx_pyrt import <function-name>. These function are usually not used except in unit test or as reference for more complex functions. See the source on github, numpy_onnx_pyrt.py and numpy_onnx_pyrt_skl.py.

scikit-learn API and ONNX graph in pipelines

Xop API