onnx

ONNX serializes neural network models to a standardized binary format using Protocol Buffers (protobuf), with a versioned operator schema system that enables forward/backward compatibility across framework versions. The architecture uses onnx.proto definitions that map to in-memory IR (Intermediate Representation) objects, allowing models trained in PyTorch, TensorFlow, or other frameworks to be persisted and loaded with operator semantics preserved through operator versioning and domain-based namespacing.

ONNX implements a type and shape inference system that traverses the computation graph, propagating tensor shapes and data types through operators using operator schema definitions. The inference engine uses partial evaluation to compute constant folding and data propagation rules defined in operator schemas (via type_inference_function and shape_inference_function), enabling static analysis of model outputs without executing the model. This is implemented in C++ (onnx/defs/data_type_utils.cc) with Python bindings for accessibility.

ONNX supports function bodies (FunctionProto) that enable defining custom operators as compositions of primitive ONNX operators. Functions are stored in the model's opset_import and can be referenced like built-in operators. This enables operator abstraction, code reuse, and domain-specific operator definitions without requiring C++ kernel implementations. Function bodies are expanded during model execution or compilation, enabling optimization of composed operators.

ONNX uses CMake for cross-platform building with automatic protobuf code generation (onnx/gen_proto.py), Python extension building via setuptools, and platform-specific configuration for Windows, Linux, and macOS. The build system generates C++ bindings for Python (onnx_cpp2py_export), compiles operator schema definitions, and produces platform-specific wheels with abi3 compatibility for Python 3.12+. Build configuration is managed through CMakeLists.txt with external dependency management for protobuf and googletest.

ONNX implements comprehensive CI/CD workflows (.github/workflows/main.yml) that run automated tests across multiple Python versions and platforms, perform code quality checks (linting, type checking), and orchestrate releases to PyPI. The pipeline includes backend test execution, security scanning, and compliance automation. Release orchestration handles version bumping, changelog generation, and wheel building for multiple platforms.

ONNX provides a reference implementation (onnx/reference/ops/) that executes ONNX models using NumPy-based operator kernels, enabling model inference without external runtimes. The reference implementation is used for testing, validation, and as a fallback for operators not optimized in production runtimes. It supports all standard ONNX operators and provides numerical accuracy baseline for comparing against optimized implementations.

ONNX maintains a global operator schema registry (onnx/defs/operator_sets.h) that stores versioned definitions for 200+ operators across multiple domains (ai.onnx, ai.onnx.ml, ai.onnx.training, com.microsoft, etc.). Each operator definition includes input/output signatures, type constraints, attributes, and inference functions. The registry supports operator versioning (opset versions 1-21+) allowing operators to evolve while maintaining backward compatibility; deprecated operators are marked but remain available for legacy models.

ONNX provides a Python API (onnx/helper.py, onnx/compose.py) for programmatic graph construction and manipulation, enabling developers to create models by instantiating NodeProto objects, connecting them via ValueInfoProto edges, and composing them into GraphProto structures. The API supports node insertion, edge rewiring, subgraph extraction, and graph merging operations. Internally, graphs are represented as directed acyclic graphs (DAGs) where nodes are operators and edges are named tensor values; the composition API abstracts protobuf manipulation.

ONNX implements a comprehensive model checker (onnx/checker.py, onnx/onnx_cpp2py_export/checker.pyi) that validates model structure, operator compatibility, and graph consistency. The checker verifies that all operators are registered in the schema registry, input/output types match operator constraints, tensor shapes are consistent across connections, and graph structure is acyclic. Validation is performed via C++ implementation with Python bindings, enabling fast checking of large models.

ONNX provides numpy_helper.py for bidirectional conversion between NumPy arrays and ONNX TensorProto objects, with automatic dtype mapping between NumPy and ONNX data types (float32, int64, bool, etc.). The helper functions enable embedding NumPy arrays as model initializers (constant tensors) and extracting tensor data from models for inspection or testing. This is essential for model construction workflows where weights are typically represented as NumPy arrays.

ONNX includes a textual syntax parser and printer that converts between binary ModelProto format and human-readable text representation, enabling model inspection and debugging. The parser (implemented in C++) converts text syntax into protobuf structures, while the printer converts ModelProto objects back to text. This is useful for model visualization, version control in text format, and manual model editing.

ONNX provides a comprehensive backend test framework (onnx/backend/test/) that enables testing of ONNX runtime implementations against a reference specification. The framework includes test case generation utilities that create operator-level test cases with input/output data, a reference implementation for validating operator behavior, and infrastructure for running tests across different backends. Test cases are generated from operator definitions and stored as serialized ONNX models with associated input/output data.

ONNX implements external_data_helper.py to handle models larger than protobuf's 2GB serialization limit by splitting tensor data into separate files. Large tensors are stored as external data references (ExternalDataProto) while the model structure remains in the main .onnx file. This enables serialization of multi-gigabyte models while maintaining the ONNX format specification. The helper provides transparent loading and saving of models with external data.

ONNX implements a versioning system where operators evolve through opset versions (currently opset 1-21+), with each version representing a snapshot of operator definitions. The system tracks operator changes (signature changes, attribute additions, deprecations) across versions, enabling models to specify which opset version they target. This allows new operator versions to be introduced without breaking existing models. Opset versions are managed globally (ai.onnx domain) and per-domain (ai.onnx.ml, com.microsoft, etc.).