ONNX (Open Neural Network Exchange)

Warnings

• breaking The `model hub integration` feature was removed in ONNX v1.21.0. If your workflow relied on this integration, you will need to update your code to remove references to it. [cite: github_release_v1.21.0]
  Fix: Remove any code referencing the defunct model hub integration. Consult ONNX documentation for alternative model management or sharing methods.
• gotcha Incompatible ONNX Opset Versions: Models created with a specific ONNX opset version (e.g., opset 13) may not be compatible with older runtimes or frameworks that do not support that opset. This can lead to conversion failures or unexpected behavior during inference.
  Fix: Always verify that the ONNX opset version used for exporting or creating the model aligns with the supported versions of your target runtime or framework. Use `helper.make_opsetid('', <version_number>)` to explicitly set the opset.
• gotcha Unsupported Operations or Custom Layers: When converting models from deep learning frameworks (e.g., PyTorch, TensorFlow) to ONNX, certain custom layers or framework-specific operations may not have direct equivalents in the ONNX operator set. This will cause conversion to fail or produce incorrect models.
  Fix: Reimplement unsupported operations using ONNX-compatible alternatives or define custom ONNX operators if the functionality is critical and cannot be approximated. Consult the ONNX operator schema for available operations.
• gotcha Shape and Dimension Mismatches: ONNX requires strict tensor shape definitions. Models relying on dynamic input shapes or having inconsistent batch size definitions between frameworks can lead to validation or runtime errors.
  Fix: Explicitly define input shapes, and consider using fixed dimensions when possible during export. For dynamic shapes, ensure they are correctly specified in the ONNX graph using symbolic dimensions.
• gotcha Missing 'ml_dtypes' dependency: Starting around ONNX v1.19.0, `ml_dtypes` became a crucial dependency for handling advanced data types. If you are using `onnx` with `onnxruntime` (especially versions like 1.24) and encounter a `ModuleNotFoundError` for `ml_dtypes`, it means this dependency is missing.
  Fix: Explicitly install the `ml_dtypes` package: `pip install ml_dtypes`.

Install

• pip install onnx Install latest stable version

Imports

• onnx

  import onnx

• onnx.helper

  from onnx import helper

• onnx.checker

  from onnx import checker

• TensorProto

  from onnx import TensorProto

  TensorProto is directly available from the top-level 'onnx' package in recent versions; old imports might point to internal proto structures which can change.

Quickstart

This quickstart demonstrates how to programmatically create a simple ONNX model (Y = X + A), validate it using `onnx.checker`, and then save it to a `.onnx` file using the ONNX Python API. It also shows how to load the model back for inspection.

import onnx
from onnx import helper, checker, TensorProto
import numpy as np
import os

# Create a simple ONNX model: Y = X + A
# Define model inputs and outputs
X = helper.make_tensor_value_info('X', TensorProto.FLOAT, [None, 2])
A = helper.make_tensor_value_info('A', TensorProto.FLOAT, [2])
Y = helper.make_tensor_value_info('Y', TensorProto.FLOAT, [None, 2])

# Create a node for the Add operation
node_def = helper.make_node(
    'Add',
    inputs=['X', 'A'],
    outputs=['Y'],
)

# Create the graph
graph_def = helper.make_graph(
    [node_def],
    'simple-add-model',
    [X, A],
    [Y],
)

# Create the model with specified opset_imports (e.g., opset 13)
# Opset 13 is commonly used and widely supported.
model_def = helper.make_model(
    graph_def,
    producer_name='onnx-example',
    opset_imports=[helper.make_opsetid('', 13)]
)

# Check the model for validity
checker.check_model(model_def)
print('Model is valid!')

# Save the model to a file
model_path = 'simple_add_model.onnx'
onnx.save(model_def, model_path)
print(f'Model saved to {model_path}')

# Optional: Load the model back and print its structure
loaded_model = onnx.load(model_path)
print('\nLoaded model:\n', loaded_model.graph.node)

# Clean up the created file
# os.remove(model_path)