Workflow:Onnx Onnx Model Creation
| Knowledge Sources | |
|---|---|
| Domains | ML_Infrastructure, Model_Building |
| Last Updated | 2026-02-10 02:30 GMT |
Overview
End-to-end process for programmatically constructing ONNX models from scratch using the Python helper API.
Description
This workflow covers the standard procedure for building ONNX models entirely in Python. It uses the onnx.helper module to construct the model's computation graph node-by-node, from defining input/output tensor specifications, through creating operator nodes and assembling them into a graph, to validating and saving the final model. The workflow can also use the onnx.parser module to construct models from a concise textual representation instead of the programmatic helper API.
Usage
Execute this workflow when you need to create an ONNX model without converting from another framework. Common scenarios include:
- Building custom operator graphs for testing or benchmarking ONNX runtimes
- Constructing minimal reproducible models for debugging
- Generating synthetic models for conformance testing
- Prototyping new operator combinations before full framework integration
Execution Steps
Step 1: Define Input and Output Specifications
Declare the tensor value information for all model inputs and outputs. Each specification includes the tensor name, element data type (e.g., FLOAT, INT64), and shape dimensions. Shapes may include symbolic dimensions for dynamic axes (e.g., batch size).
Key considerations:
- Use TensorProto data type constants (FLOAT, INT64, DOUBLE, etc.) for element types
- Shape dimensions can be integers for static sizes or strings for symbolic/dynamic dimensions
- Every input and output the graph exposes must have a corresponding ValueInfoProto
Step 2: Create Operator Nodes
Construct individual computation nodes using the node builder. Each node specifies the operator type (e.g., MatMul, Add, Relu), its input tensor names, output tensor names, and any operator-specific attributes. Intermediate tensor names serve as edges connecting nodes in the graph.
Key considerations:
- Operator names must match registered ONNX operator types for the target opset version
- Input and output names create implicit data-flow edges between nodes
- Attributes are operator-specific parameters (e.g., kernel_size, axis, epsilon)
- Constant tensors can be defined as initializers rather than separate Constant nodes
Step 3: Assemble the Graph
Combine all nodes, inputs, outputs, and initializers into a named graph structure. The graph defines the complete computation topology. Initializers provide constant weight and bias values embedded directly in the model.
Key considerations:
- Node ordering in the list does not strictly matter; the runtime resolves execution order from data dependencies
- Initializers that match an input name provide default values for that input
- The graph name is metadata and does not affect execution
Step 4: Build the Model
Wrap the graph into a complete ModelProto, specifying the IR version, opset imports, and optional metadata (producer name, model version, documentation string). The opset import declares which version of the ONNX operator set the model targets.
Key considerations:
- The opset version must be compatible with all operators used in the graph
- Multiple opset imports can be specified for different domains (e.g., default domain and ai.onnx.ml)
- The IR version is typically set automatically based on the opset table
Step 5: Validate the Model
Run the model through the ONNX checker to verify structural correctness. The checker validates IR version compatibility, opset imports, node operator schemas, tensor types, and graph connectivity. Optionally run shape inference to propagate type and shape information through intermediate values.
Key considerations:
- Validation catches schema mismatches, missing inputs, type conflicts, and malformed attributes
- Shape inference adds value_info entries for intermediate tensors, which aids downstream tools
- The full_check option additionally runs shape inference as part of validation
Step 6: Save the Model
Serialize the validated model to disk in the ONNX binary protobuf format (or other supported formats like JSON or text protobuf). The save function handles format detection from the file extension.
Key considerations:
- The default format is binary protobuf (.onnx extension)
- For models exceeding 2GB, tensors must be saved as external data
- Alternative formats include textproto, JSON, and ONNX text syntax