Implementation:Onnx Onnx Compose Merge Models

Knowledge Sources	ONNX ONNX Compose API
Domains	Model_Composition, Graph_Transformation
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for combining two ONNX models into a single composed model provided by the ONNX compose module.

Description

The merge_models function combines two ModelProto objects into one by connecting outputs of the first model to inputs of the second model according to a user-specified I/O map. It validates opset compatibility, optionally applies namespace prefixes, delegates to merge_graphs for the graph-level merge, then combines metadata properties and local functions. The resulting model is automatically validated with checker.check_model before being returned.

Usage

Import this function when you need to compose two ONNX models into a pipeline. Both models must share the same IR version and opset imports. Use the prefix1/prefix2 parameters for automatic namespace prefixing, or apply add_prefix manually beforehand.

Code Reference

Source Location

• Repository: onnx
• File: onnx/compose.py
• Lines: 297-440

Signature

def merge_models(
    m1: ModelProto,
    m2: ModelProto,
    io_map: list[tuple[str, str]],
    inputs: list[str] | None = None,
    outputs: list[str] | None = None,
    prefix1: str | None = None,
    prefix2: str | None = None,
    name: str | None = None,
    doc_string: str | None = None,
    producer_name: str | None = "onnx.compose.merge_models",
    producer_version: str | None = "1.0",
    domain: str | None = "",
    model_version: int | None = 1,
) -> ModelProto:
    """Combines two ONNX models into a single one.

    Args:
        m1: First model.
        m2: Second model.
        io_map: Pairs of (output_from_m1, input_of_m2) to connect.
        inputs: Optional subset of inputs for the merged model.
        outputs: Optional subset of outputs for the merged model.
        prefix1: Optional prefix for all names in m1.
        prefix2: Optional prefix for all names in m2.
        name: Optional name for the merged graph.
        doc_string: Optional doc string for the merged graph.
        producer_name: Producer name metadata.
        producer_version: Producer version metadata.
        domain: Model domain.
        model_version: Model version number.

    Returns:
        Merged and validated ModelProto.
    """

Import

from onnx import compose

I/O Contract

Inputs

Name	Type	Required	Description
m1	ModelProto	Yes	First model (upstream)
m2	ModelProto	Yes	Second model (downstream)
io_map	list[tuple[str, str]]	Yes	Output-to-input connection pairs
inputs	list[str] or None	No	Subset of inputs for merged model (default: all)
outputs	list[str] or None	No	Subset of outputs for merged model (default: all)
prefix1	str or None	No	Namespace prefix for m1 names
prefix2	str or None	No	Namespace prefix for m2 names

Outputs

Name	Type	Description
return	ModelProto	Merged, validated model containing both graphs

Usage Examples

Basic Model Composition

import onnx
from onnx import compose

# Load two models
encoder = onnx.load_model("encoder.onnx")
decoder = onnx.load_model("decoder.onnx")

# Connect encoder output to decoder input
merged = compose.merge_models(
    encoder,
    decoder,
    io_map=[("encoder_output", "decoder_input")],
    prefix1="enc_",
    prefix2="dec_",
)

onnx.save_model(merged, "encoder_decoder.onnx")

Pipeline with Multiple Connections

from onnx import compose

# Connect multiple outputs to inputs
merged = compose.merge_models(
    preprocessor,
    classifier,
    io_map=[
        ("features", "input_features"),
        ("mask", "attention_mask"),
    ],
    prefix1="pre_",
    prefix2="cls_",
    name="full_pipeline",
)

Related Pages

Implements Principle

• Principle:Onnx_Onnx_Model_Merging

Requires Environment

• Environment:Onnx_Onnx_Python_Runtime_Environment