Implementation:Onnx Onnx Replace Constants

Knowledge Sources	Onnx_Onnx
Domains	Model Transformation, Testing Utilities, Memory Optimization
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for reducing the memory footprint of ONNX models by replacing large constant tensors with dynamically generated dummy constants of the same shape, provided by the ONNX library.

Description

The replace_constants.py module provides utilities for replacing large constant tensors in ONNX models with lightweight shape-preserving placeholders. This is particularly valuable for testing model structure, shape inference, and graph transformations without requiring the full memory overhead of actual model weights.

The primary public function is replace_initializer_by_constant_of_shape, which recursively processes an entire ONNX model (including subgraphs in control-flow operators and model-local functions). It handles three input types: ModelProto (processes the graph and all functions), GraphProto (processes initializers, Constant nodes, and subgraph attributes), and FunctionProto (processes Constant nodes within function bodies).

For initializers in GraphProto, tensors exceeding the configurable threshold (default: 128 elements) are replaced with a small initializer holding the shape values and a ConstantOfShape node that generates a tensor of the original shape filled with a configurable value. For Constant nodes, the internal _replace_constant function performs a similar transformation, converting a single Constant node into a two-node sequence: a Constant holding the shape followed by a ConstantOfShape node.

The module offers two additional optimization modes. When use_range=True, the _replace_constant_of_shape_with_range function replaces ConstantOfShape nodes with a sequence of Range, Cast, Div, and Reshape operations, producing tensors with unique non-constant values (useful for debugging and distinguishing tensor elements). The _replace_constant_of_shape_value function allows changing the fill value of all existing ConstantOfShape nodes to a specified value via the value_constant_of_shape parameter.

The function preserves all model metadata including producer name, version, IR version, domain, doc string, metadata properties, and opset imports. It validates opset version requirements (ConstantOfShape requires opset >= 9, Range requires opset >= 11).

Usage

Use this module when working with large ONNX models in memory-constrained environments, such as CI/CD pipelines, unit tests for graph transformations, model structure validation, and development environments. It enables rapid prototyping and testing of model processing tools without downloading or storing full model weights. The function can also be reapplied to previously transformed models to update the fill value or switch between ConstantOfShape and Range modes.

Code Reference

Source Location

• Repository: Onnx_Onnx
• File: onnx/tools/replace_constants.py
• Lines: 1-421

Signature

def replace_initializer_by_constant_of_shape(
    onx: FunctionProto | GraphProto | ModelProto,
    threshold: int = 128,
    ir_version: int | None = None,
    use_range: bool = False,
    value_constant_of_shape: float = 0.5,
) -> FunctionProto | GraphProto | ModelProto: ...

Internal helper functions:

def _replace_constant(
    node: NodeProto, threshold: int, value_constant_of_shape: float
) -> list[NodeProto]: ...

def _replace_constant_of_shape_with_range(
    onx: GraphProto | FunctionProto,
) -> GraphProto | FunctionProto: ...

def _replace_constant_of_shape_value(
    onx: GraphProto | FunctionProto, value_constant_of_shape: float
) -> GraphProto | FunctionProto: ...

Import

from onnx.tools.replace_constants import replace_initializer_by_constant_of_shape

I/O Contract

Inputs

Name	Type	Required	Description
onx	FunctionProto, GraphProto, or ModelProto	Yes	The ONNX model, graph, or function to transform
threshold	int	No	Minimum number of tensor elements before replacement occurs (default: 128)
ir_version	int or None	No	IR version for the model; required for GraphProto/FunctionProto inputs if ir_version <= 3
use_range	bool	No	If True, replaces ConstantOfShape nodes with Range-based sequences producing unique values (default: False)
value_constant_of_shape	float	No	The fill value for generated ConstantOfShape nodes (default: 0.5)

Outputs

Name	Type	Description
result	FunctionProto, GraphProto, or ModelProto	The transformed model/graph/function with large constants replaced by shape-preserving placeholders; same type as input

Usage Examples

import onnx
from onnx.tools.replace_constants import replace_initializer_by_constant_of_shape

# Load a large model
model = onnx.load("large_model.onnx")

# Replace large constants with ConstantOfShape (default threshold: 128 elements)
small_model = replace_initializer_by_constant_of_shape(model)
onnx.save(small_model, "small_model.onnx")

# Use a custom threshold (only replace tensors with more than 1000 elements)
small_model = replace_initializer_by_constant_of_shape(model, threshold=1000)

# Use Range operators instead of ConstantOfShape for unique values
range_model = replace_initializer_by_constant_of_shape(model, use_range=True)

# Set a specific fill value
filled_model = replace_initializer_by_constant_of_shape(
    model, value_constant_of_shape=0.0
)

# Process a graph directly
graph = model.graph
small_graph = replace_initializer_by_constant_of_shape(
    graph, ir_version=model.ir_version
)

# Process a function
for func in model.functions:
    small_func = replace_initializer_by_constant_of_shape(
        func, ir_version=model.ir_version
    )

Related Pages

• Environment:Onnx_Onnx_Python_Runtime_Environment