Workflow:Onnx Onnx Model Composition
| Knowledge Sources | |
|---|---|
| Domains | ML_Infrastructure, Model_Composition |
| Last Updated | 2026-02-10 02:30 GMT |
Overview
End-to-end process for combining multiple ONNX models into a single composed model by connecting outputs of one model to inputs of another.
Description
This workflow covers the standard procedure for merging two or more ONNX models into a unified computation graph using the onnx.compose module. It handles namespace collision avoidance through prefix renaming, output-to-input wiring via an I/O map, optional dimension expansion for shape compatibility, and selective output pruning. The result is a single ONNX model that chains or combines the computations of the source models.
Usage
Execute this workflow when you need to:
- Chain a preprocessing model with an inference model into a single deployable artifact
- Combine an encoder model with a decoder model into an end-to-end pipeline
- Merge a feature extraction model with a classification head
- Compose ensemble models from multiple sub-models operating on shared inputs
Execution Steps
Step 1: Load the Source Models
Load the two (or more) ONNX models that will be composed. Inspect their input and output specifications to understand the tensor names, types, and shapes that will be connected.
Key considerations:
- Both models must be valid ONNX models at compatible opset versions
- Examine the input/output names carefully; these will be used to define the I/O mapping
- Note any potential name collisions between the models (node names, edge names, initializer names)
Step 2: Add Namespace Prefixes
Apply unique prefixes to all names in each model to prevent name collisions when their graphs are merged. The prefix function renames inputs, outputs, edges, nodes, initializers, sparse initializers, and value info entries.
Key considerations:
- Choose distinct prefixes for each model (e.g., "encoder/" and "decoder/")
- Prefixing can be done in-place or produce a new model
- The prefix operation can selectively exclude certain name categories if needed
Step 3: Expand Output Dimensions (If Needed)
If the models have incompatible tensor ranks at the connection points (e.g., one model produces unbatched outputs while the other expects batched inputs), insert a dimension of size one at the appropriate axis to align the shapes.
Key considerations:
- This step is only needed when models operate at different batch dimension conventions
- The dimension index parameter specifies where to insert the new axis (typically 0 for batch dimension)
- Verify that the expanded shapes match the downstream model's input requirements
Step 4: Define the I/O Map
Specify which outputs from the first model connect to which inputs in the second model. The I/O map is a list of (output_name, input_name) tuples defining the data-flow connections between models.
Key considerations:
- Output names refer to the first model's outputs (after any prefixing)
- Input names refer to the second model's inputs (after any prefixing)
- A single output can be connected to multiple inputs
- Inputs/outputs not present in the I/O map remain as external inputs/outputs of the combined model
Step 5: Merge the Models
Execute the merge operation to combine the two model graphs into a single unified graph. The merge function validates the I/O map, connects the specified outputs to inputs, and combines all nodes, initializers, and metadata.
Key considerations:
- Optionally specify explicit lists of inputs and outputs for the combined model to prune unused branches
- If outputs are specified, any graph branches not contributing to those outputs are removed
- Name collision checking runs automatically and raises errors if unresolved collisions remain
Step 6: Validate and Save the Composed Model
Run the ONNX checker on the composed model to ensure structural correctness. Apply shape inference to propagate shapes through the combined graph. Save the validated model to disk.
Key considerations:
- Check that the combined model's input and output specifications match expectations
- Shape inference should succeed across the merge boundary if types are compatible
- The composed model can be further composed with additional models in a chain