Implementation:Onnx Onnx Backend Base

Knowledge Sources	Onnx_Onnx
Domains	Backend Interface, Model Execution
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for defining the base abstract interface for ONNX backend implementations provided by the ONNX library.

Description

The onnx/backend/base.py module defines the foundational classes and utilities that all ONNX backend implementations must extend to execute ONNX models. A backend is any system that can take an ONNX model, process inputs, perform computation, and return outputs.

The module provides several key components:

DeviceType defines device type constants (CPU = 0, CUDA = 1). Device parses device strings like "CPU", "CUDA", or "CUDA:1" into a type and optional device_id.

BackendRep is the handle returned by a backend after preparing a model for execution. It exposes a run() method that accepts inputs and returns a tuple of results. Backend implementations override this class to hold compiled or optimized model state.

Backend is the main base class defining the backend interface contract. It provides class methods: is_compatible() to check if a model is supported, prepare() to compile/optimize a model and return a BackendRep, run_model() for one-off execution, run_node() for executing a single operator, and supports_device() for device support queries. The default prepare() implementation validates the model using onnx.checker.check_model() before returning. The run_node() method validates node definitions using onnx.checker.check_node() with optional opset version context.

The namedtupledict() utility creates named tuples that also support dictionary-style string key access, accommodating output names that may not be valid Python identifiers.

Usage

Use these base classes when implementing a new ONNX backend runtime. Subclass Backend and override prepare(), run_model(), and run_node() to provide actual computation. For repeated model execution, use the prepare/run pattern: call prepare() once to get a BackendRep, then call run() multiple times with different inputs.

Code Reference

Source Location

• Repository: Onnx_Onnx
• File: onnx/backend/base.py

Signature

class DeviceType:
    _Type = NewType("_Type", int)
    CPU: _Type = _Type(0)
    CUDA: _Type = _Type(1)

class Device:
    def __init__(self, device: str) -> None: ...

class BackendRep:
    def run(self, inputs: Any, **kwargs: Any) -> tuple[Any, ...]: ...

class Backend:
    @classmethod
    def is_compatible(cls, model: ModelProto, device: str = "CPU", **kwargs: Any) -> bool: ...
    @classmethod
    def prepare(cls, model: ModelProto, device: str = "CPU", **kwargs: Any) -> BackendRep | None: ...
    @classmethod
    def run_model(cls, model: ModelProto, inputs: Any, device: str = "CPU", **kwargs: Any) -> tuple[Any, ...]: ...
    @classmethod
    def run_node(cls, node: NodeProto, inputs: Any, device: str = "CPU",
                 outputs_info: Sequence[tuple[numpy.dtype, tuple[int, ...]]] | None = None,
                 **kwargs: dict[str, Any]) -> tuple[Any, ...] | None: ...
    @classmethod
    def supports_device(cls, device: str) -> bool: ...

def namedtupledict(typename: str, field_names: Sequence[str], *args: Any, **kwargs: Any) -> type[tuple[Any, ...]]: ...

Import

from onnx.backend.base import Backend, BackendRep, Device, DeviceType, namedtupledict

I/O Contract

Inputs

Name	Type	Required	Description
model	ModelProto	Yes	The ONNX model to execute (for prepare, run_model, is_compatible)
node	NodeProto	Yes	A single ONNX node to execute (for run_node)
inputs	Any	Yes	Input data for model or node execution
device	str	No	Target device string, defaults to "CPU". Format: "DEVICE_TYPE" or "DEVICE_TYPE:DEVICE_ID"
outputs_info	Sequence[tuple[numpy.dtype, tuple[int, ...]]] or None	No	Output element types and shapes for run_node
opset_version	int (via kwargs)	No	Opset version for node validation in run_node

Outputs

Name	Type	Description
BackendRep	BackendRep	Prepared model handle returned by prepare(), used for repeated execution
results	tuple[Any, ...]	Tuple of output values from run_model() or BackendRep.run()
is_compatible	bool	Whether the model is compatible with the backend
supports_device	bool	Whether the backend supports the given device

Usage Examples

from onnx.backend.base import Backend, BackendRep, Device

# Parse a device string
device = Device("CUDA:1")
print(device.type)       # 1 (CUDA)
print(device.device_id)  # 1

# Subclass Backend for a custom runtime
class MyBackend(Backend):
    @classmethod
    def prepare(cls, model, device="CPU", **kwargs):
        super().prepare(model, device, **kwargs)  # validates model
        return MyBackendRep(model)

    @classmethod
    def supports_device(cls, device):
        return Device(device).type == DeviceType.CPU

# One-off model execution
results = MyBackend.run_model(model, inputs)

# Repeated execution with prepare
rep = MyBackend.prepare(model)
results1 = rep.run(inputs1)
results2 = rep.run(inputs2)

Related Pages

• Environment:Onnx_Onnx_Python_Runtime_Environment