Workflow:Onnx Onnx Version Conversion
| Knowledge Sources | |
|---|---|
| Domains | ML_Infrastructure, Model_Migration |
| Last Updated | 2026-02-10 02:30 GMT |
Overview
End-to-end process for converting an ONNX model from one opset version to another within the default operator domain.
Description
This workflow covers the procedure for migrating ONNX models between different opset versions of the default domain ("" or "ai.onnx"). The version converter applies a chain of per-operator adapters that transform nodes from the source opset to the target opset, handling operator renames, attribute changes, input/output modifications, and decompositions. Both upgrading (lower to higher opset) and downgrading (higher to lower opset) are supported for operators with registered adapters.
Usage
Execute this workflow when you need to:
- Upgrade a model's opset to use newer operator features or meet a runtime's minimum opset requirement
- Downgrade a model's opset for compatibility with an older ONNX runtime that does not support the latest opset
- Standardize models from different sources to a common opset version before combining them
- Test model behavior across different opset versions during development
Execution Steps
Step 1: Load the Source Model
Load the ONNX model that needs version conversion. Inspect its current opset version from the opset_import field to understand the starting point for conversion.
Key considerations:
- The model must be a valid ONNX model; run the checker first if uncertain
- Note the current opset version from the model's opset_import declarations
- The version converter only handles the default domain ("" / "ai.onnx"); other domains are passed through unchanged
Step 2: Determine the Target Opset Version
Identify the target opset version based on the requirements of the downstream runtime or toolchain. Consult the ONNX versioning table to map between ONNX release versions, IR versions, and opset versions.
Key considerations:
- Not all opset transitions are supported; the converter requires registered adapters for each operator that changed between versions
- Some operators may not have adapters for downgrading, limiting backward conversion
- The target version must be a positive integer corresponding to a valid opset version
Step 3: Run the Version Converter
Apply the version converter to transform the model from its current opset to the target opset. The converter serializes the model, applies the C++ conversion engine with registered adapters, and deserializes the result.
Key considerations:
- The converter raises a ConvertError if a required adapter is missing for any operator in the model
- The conversion modifies operator nodes, potentially changing op_type names, attribute names/values, and input/output configurations
- The converter operates on the entire model graph, including subgraphs in control flow operators
Step 4: Validate the Converted Model
Run the ONNX checker on the converted model to verify that the conversion produced a valid model at the target opset version. Optionally apply shape inference to ensure type and shape information is consistent after conversion.
Key considerations:
- Some conversions may change the graph structure (e.g., decomposing one operator into multiple)
- Shape inference should be re-run after conversion since intermediate shapes may have changed
Step 5: Save the Converted Model
Persist the converted model to disk. The saved model will declare the target opset version in its opset_import field.
Key considerations:
- Verify the saved model's opset_import matches the intended target version
- Consider maintaining the original model as a backup before overwriting