0
# ONNX
1

2
Open Neural Network Exchange (ONNX) is an open ecosystem that empowers AI developers to choose the right tools as their project evolves. ONNX provides an open source format for AI models, both deep learning and traditional ML, defining an extensible computation graph model as well as definitions of built-in operators and standard data types, enabling interoperability between different frameworks and streamlining the path from research to production.
3

4
## Package Information
5

6
- **Package Name**: onnx
7
- **Language**: Python
8
- **Installation**: `pip install onnx`
9

10
## Core Imports
11

12
```python
13
import onnx
14
```
15

16
Import specific components:
17

18
```python
19
from onnx import (
20
    ModelProto, GraphProto, NodeProto, TensorProto,
21
    load_model, save_model, helper, checker
22
)
23
```
24

25
## Version and Constants
26

27
ONNX provides version information and important constants for working with different IR versions and feature stability levels.
28

29
```python { .api }
30
__version__  # Package version string
31
IR_VERSION  # Current ONNX IR version
32
IR_VERSION_2017_10_10  # Historical IR version: 1
33
IR_VERSION_2017_10_30  # Historical IR version: 2
34
IR_VERSION_2017_11_3   # Historical IR version: 3
35
IR_VERSION_2019_1_22   # Historical IR version: 4
36
IR_VERSION_2019_3_18   # Historical IR version: 5
37
IR_VERSION_2019_9_19   # Historical IR version: 6
38
IR_VERSION_2020_5_8    # Historical IR version: 7
39
IR_VERSION_2021_7_30   # Historical IR version: 8
40

41
ONNX_ML                # Boolean indicating ONNX ML support
42
EXPERIMENTAL           # Status constant for experimental features
43
STABLE                 # Status constant for stable features
44

45
# External data management functions
46
def convert_model_to_external_data(
47
    model: ModelProto,
48
    all_tensors_to_one_file: bool = True,
49
    location: str | None = None,
50
    size_threshold: int = 1024,
51
    convert_attribute: bool = False,
52
) -> None
53

54
def load_external_data_for_model(model: ModelProto, base_dir: str) -> None
55

56
def write_external_data_tensors(model: ModelProto, base_dir: str) -> ModelProto
57
```
58

59
Usage example:
60

61
```python
62
import onnx
63
print(f"ONNX version: {onnx.__version__}")
64
print(f"Current IR version: {onnx.IR_VERSION}")
65
print(f"ONNX ML supported: {onnx.ONNX_ML}")
66
```
67

68
## Basic Usage
69

70
```python
71
import onnx
72
from onnx import helper, TensorProto
73

74
# Load an existing ONNX model
75
model = onnx.load_model("path/to/model.onnx")
76

77
# Check if the model is valid
78
onnx.checker.check_model(model)
79

80
# Create a simple computation graph
81
# Define input/output value info
82
X = helper.make_tensor_value_info('X', TensorProto.FLOAT, [3, 2])
83
Y = helper.make_tensor_value_info('Y', TensorProto.FLOAT, [3, 2])
84

85
# Create a node (operation)
86
node_def = helper.make_node(
87
    'Relu',  # node name
88
    ['X'],   # inputs
89
    ['Y'],   # outputs
90
)
91

92
# Create the graph
93
graph_def = helper.make_graph(
94
    [node_def],        # nodes
95
    'test-model',      # name
96
    [X],              # inputs
97
    [Y],              # outputs
98
)
99

100
# Create the model
101
model_def = helper.make_model(graph_def, producer_name='onnx-example')
102

103
# Save the model
104
onnx.save_model(model_def, "relu_model.onnx")
105
```
106

107
## Architecture
108

109
ONNX models follow a hierarchical structure based on protocol buffers:
110

111
- **ModelProto**: Top-level container with metadata, IR version, and computation graph
112
- **GraphProto**: Computation graph containing nodes, inputs, outputs, and initializers
113
- **NodeProto**: Individual operations with operator type, inputs, outputs, and attributes
114
- **ValueInfoProto**: Type and shape information for graph inputs/outputs
115
- **TensorProto**: Tensor data representation with type, shape, and values
116
- **AttributeProto**: Node parameters and configuration options
117

118
This design enables framework interoperability by providing a standard representation for neural networks and machine learning models, supporting conversion between frameworks like PyTorch, TensorFlow, scikit-learn, and deployment runtimes.
119

120
## Capabilities
121

122
### Model I/O Operations
123

124
Core functions for loading and saving ONNX models from various sources including files, streams, and binary data, with support for external data storage and multiple serialization formats.
125

126
[Model I/O](./model-io.md)
127

128
### Model Construction
129

130
Helper functions for programmatically creating ONNX models, graphs, nodes, tensors, and type definitions with proper protocol buffer structure and validation.
131

132
[Model Construction](./model-construction.md)
133

134
### Model Validation
135

136
Comprehensive validation functions to verify ONNX model correctness, including graph structure, node compatibility, type consistency, and operator definitions.
137

138
[Model Validation](./model-validation.md)
139

140
### Shape Inference
141

142
Automatic shape and type inference for model graphs, enabling optimization and validation of tensor shapes throughout the computation graph.
143

144
[Shape Inference](./shape-inference.md)
145

146
### NumPy Integration
147

148
Bidirectional conversion between ONNX tensors and NumPy arrays, supporting all ONNX data types including specialized formats like bfloat16 and float8 variants.
149

150
[NumPy Integration](./numpy-integration.md)
151

152
### Model Composition
153

154
Functions for merging and composing multiple ONNX models or graphs, enabling modular model construction and complex pipeline creation.
155

156
[Model Composition](./model-composition.md)
157

158
### Operator Definitions
159

160
Access to ONNX operator schemas, type definitions, and version compatibility information for all supported operators across different domains.
161

162
[Operator Definitions](./operator-definitions.md)
163

164
### Text Parsing and Printing
165

166
Convert between ONNX protocol buffer representations and human-readable text formats for debugging, serialization, and model inspection.
167

168
[Text Processing](./text-processing.md)
169

170
### Version Conversion
171

172
Convert ONNX models between different IR versions and operator set versions to maintain compatibility across framework versions.
173

174
[Version Conversion](./version-conversion.md)
175

176
### Model Hub Integration
177

178
Access to the ONNX Model Zoo for downloading pre-trained models, including model metadata and test data for validation.
179

180
[Model Hub](./model-hub.md)
181

182
### Backend Integration
183

184
Abstract interfaces for implementing ONNX model execution backends, enabling custom runtime integration and testing frameworks.
185

186
[Backend Integration](./backend-integration.md)
187

188
### Reference Implementation
189

190
Complete reference implementation of ONNX operators for testing, validation, and educational purposes.
191

192
[Reference Implementation](./reference-implementation.md)
193

194
## Protocol Buffer Types
195

196
```python { .api }
197
class ModelProto:
198
    """ONNX model representation with computation graph and metadata"""
199

200
class GraphProto:
201
    """Computation graph with nodes, inputs, outputs, and initializers"""
202

203
class NodeProto:
204
    """Individual operation with operator type, inputs, and outputs"""
205

206
class TensorProto:
207
    """Tensor data with type, shape, and values"""
208

209
class ValueInfoProto:
210
    """Type and shape information for graph values"""
211

212
class AttributeProto:
213
    """Node attributes and parameters"""
214

215
class FunctionProto:
216
    """User-defined function representation"""
217

218
class TypeProto:
219
    """Type system definitions for tensors, sequences, maps, and optionals"""
220

221
class OperatorSetIdProto:
222
    """Operator set identifier with domain and version"""
223

224
class OperatorProto:
225
    """Operator definition protocol buffer"""
226

227
class OperatorSetProto:
228
    """Collection of operators for a specific opset version"""
229

230
class OperatorStatus:
231
    """Enumeration for operator status (experimental, stable)"""
232

233
class StringStringEntryProto:
234
    """Key-value string pairs for metadata"""
235

236
class TensorAnnotation:
237
    """Tensor annotation for quantization and optimization hints"""
238

239
class TrainingInfoProto:
240
    """Training-specific information for model execution"""
241

242
class Version:
243
    """Version information protocol buffer"""
244

245
class SparseTensorProto:
246
    """Sparse tensor representation with values, indices, and shape"""
247

248
class MapProto:
249
    """Map container for key-value pairs"""
250

251
class SequenceProto:
252
    """Sequence container for ordered collections"""
253

254
class OptionalProto:
255
    """Optional container that may or may not contain a value"""
256
```