tessl/pypi-onnx
Open Neural Network Exchange for AI model interoperability and machine learning frameworks
—
Pending
model-construction.mddocs/
Model Construction
Helper functions for programmatically creating ONNX models, graphs, nodes, tensors, and type definitions. These functions provide the building blocks for constructing valid ONNX models with proper protocol buffer structure.
Capabilities
Model and Graph Creation
Create complete ONNX models and computation graphs with proper metadata and structure.
def make_model(graph: GraphProto, **kwargs: Any) -> ModelProto:
"""
Construct a ModelProto
Parameters:
- graph: *make_graph* returns
- **kwargs: any attribute to add to the returned instance
Returns:
ModelProto
"""
def make_model_gen_version(graph: GraphProto, **kwargs: Any) -> ModelProto:
"""
An extension of make_model that infers an IR_VERSION for the model,
if not specified, using a best-effort-basis.
Parameters:
- graph: GraphProto representing the computation graph
- **kwargs: Additional model metadata
Returns:
ModelProto: ONNX model with generated version info
"""
def make_graph(
nodes: Sequence[NodeProto],
name: str,
inputs: Sequence[ValueInfoProto],
outputs: Sequence[ValueInfoProto],
initializer: Optional[Sequence[TensorProto]] = None,
doc_string: Optional[str] = None,
value_info: Optional[Sequence[ValueInfoProto]] = None,
sparse_initializer: Optional[Sequence[SparseTensorProto]] = None,
) -> GraphProto:
"""
Construct a GraphProto
Parameters:
- nodes: list of NodeProto
- name: graph name
- inputs: list of ValueInfoProto
- outputs: list of ValueInfoProto
- initializer: list of TensorProto
- doc_string: graph documentation
- value_info: list of ValueInfoProto
- sparse_initializer: list of SparseTensorProto
Returns:
GraphProto
"""
def make_operatorsetid(domain: str, version: int) -> OperatorSetIdProto:
"""
Construct an OperatorSetIdProto.
Parameters:
- domain: The domain of the operator set id
- version: Version of operator set id
Returns:
OperatorSetIdProto
"""
def make_opsetid(domain: str, version: int) -> OperatorSetIdProto:
"""
Alias for make_operatorsetid. Construct an OperatorSetIdProto.
Parameters:
- domain: The domain of the operator set id
- version: Version of operator set id
Returns:
OperatorSetIdProto
"""
def make_function(
domain: str,
fname: str,
inputs: List[str],
outputs: List[str],
nodes: List[NodeProto],
opset_imports: List[OperatorSetIdProto],
attributes: Optional[List[str]] = None,
**kwargs: Any,
) -> FunctionProto:
"""
Construct a FunctionProto for user-defined functions.
Parameters:
- domain: Function domain
- fname: Function name
- inputs: List of input names
- outputs: List of output names
- nodes: List of nodes in function body
- opset_imports: List of required opset imports
- attributes: Optional list of function attributes
- **kwargs: Additional function metadata
Returns:
FunctionProto: User-defined function representation
"""
def set_model_props(model: ModelProto, dict_value: Dict[str, str]) -> None:
"""
Set model properties from a dictionary.
Parameters:
- model: ModelProto to modify
- dict_value: Dictionary of property key-value pairs
"""Version Constants
Important constants for version handling and model construction:
VERSION_TABLE # List of ONNX version mapping tuples (release, IR, ai.onnx, ai.onnx.ml)
OP_SET_ID_VERSION_MAP # Map from (domain, version) to IR version requirements
def find_min_ir_version_for(
opsetidlist: List[OperatorSetIdProto],
ignore_unknown: bool = False
) -> int:
"""
Given list of opset ids, determine minimum IR version required.
Parameters:
- opsetidlist: List of OperatorSetIdProto
- ignore_unknown: If True, ignore unknown domains
Returns:
int: Minimum required IR version
"""Node Creation
Create computation nodes representing operations in the ONNX graph.
def make_node(
op_type: str,
inputs: Sequence[str],
outputs: Sequence[str],
name: Optional[str] = None,
doc_string: Optional[str] = None,
domain: Optional[str] = None,
**kwargs: Any,
) -> NodeProto:
"""
Construct a NodeProto.
Parameters:
- op_type: The name of the operator to construct
- inputs: list of input names
- outputs: list of output names
- name: optional unique identifier for NodeProto
- doc_string: optional documentation string for NodeProto
- domain: optional domain for NodeProto.
If it's None, we will just use default domain (which is empty)
- **kwargs: the attributes of the node. The acceptable values
are documented in :func:`make_attribute`.
Returns:
NodeProto
"""Tensor Creation
Create tensor representations for model weights, constants, and data.
def make_tensor(
name: str, data_type: int, dims: Sequence[int], vals: Any, raw: bool = False
) -> TensorProto:
"""
Make a TensorProto with specified arguments. If raw is False, this
function will choose the corresponding proto field to store the
values based on data_type. If raw is True, use "raw_data" proto
field to store the values, and values should be of type bytes in
this case.
Parameters:
- name: tensor name
- data_type: a value such as onnx.TensorProto.FLOAT
- dims: shape
- vals: values
- raw: if True, vals contains the serialized content of the tensor,
otherwise, vals should be a list of values of the type defined by *data_type*
Returns:
TensorProto
"""
def make_sparse_tensor(values, indices, dims, name=None):
"""
Create a SparseTensorProto from sparse data.
Parameters:
- values: TensorProto containing non-zero values
- indices: TensorProto containing indices of non-zero values
- dims: List of integers representing tensor shape
- name: Optional name for the sparse tensor
Returns:
SparseTensorProto: Sparse tensor representation
"""
def make_sequence(name: str, elem_type: int, values: List[Any]) -> SequenceProto:
"""
Create a SequenceProto from a list of values.
Parameters:
- name: Sequence name
- elem_type: Element data type
- values: List of values to include in sequence
Returns:
SequenceProto: Sequence representation
"""
def make_map(name: str, key_type: int, keys: List[Any], values: List[Any]) -> MapProto:
"""
Create a MapProto from keys and values.
Parameters:
- name: Map name
- key_type: Key data type
- keys: List of keys
- values: List of corresponding values
Returns:
MapProto: Map representation
"""
def make_optional(name: str, elem_type: Optional[TypeProto], value: Any = None) -> OptionalProto:
"""
Create an OptionalProto that may contain a value.
Parameters:
- name: Optional name
- elem_type: Element type (None for empty optional)
- value: Optional value to store
Returns:
OptionalProto: Optional representation
"""Type System
Create type definitions for tensor, sequence, map, and optional types.
def make_tensor_type_proto(elem_type, shape, elem_type_name=""):
"""
Create a TypeProto for tensor types.
Parameters:
- elem_type: Element data type (e.g., TensorProto.FLOAT)
- shape: List of dimensions (use None for unknown dimensions)
- elem_type_name: Optional name for custom element types
Returns:
TypeProto: Tensor type specification
"""
def make_sparse_tensor_type_proto(elem_type, shape, elem_type_name=""):
"""
Create a TypeProto for sparse tensor types.
Parameters:
- elem_type: Element data type
- shape: List of dimensions
- elem_type_name: Optional name for custom element types
Returns:
TypeProto: Sparse tensor type specification
"""
def make_sequence_type_proto(inner_type_proto):
"""
Create a TypeProto for sequence types.
Parameters:
- inner_type_proto: TypeProto for sequence elements
Returns:
TypeProto: Sequence type specification
"""
def make_map_type_proto(key_type, value_type):
"""
Create a TypeProto for map types.
Parameters:
- key_type: Key data type (must be string or integral type)
- value_type: TypeProto for map values
Returns:
TypeProto: Map type specification
"""
def make_optional_type_proto(inner_type_proto):
"""
Create a TypeProto for optional types.
Parameters:
- inner_type_proto: TypeProto for optional value
Returns:
TypeProto: Optional type specification
"""Value Info Creation
Create value information for graph inputs, outputs, and intermediate values.
def make_tensor_value_info(
name: str,
elem_type: int,
shape: Optional[Sequence[Union[str, int, None]]],
doc_string: str = "",
shape_denotation: Optional[List[str]] = None,
) -> ValueInfoProto:
"""
Makes a ValueInfoProto based on the data type and shape.
Parameters:
- name: Name of the value
- elem_type: Element data type
- shape: List of dimensions (use None for unknown dimensions)
- doc_string: Human-readable documentation
- shape_denotation: Optional shape denotation
Returns:
ValueInfoProto: Value information for tensors
"""
def make_sparse_tensor_value_info(name, elem_type, shape, doc_string="", elem_type_name=""):
"""
Create a ValueInfoProto for sparse tensor values.
Parameters:
- name: Name of the value
- elem_type: Element data type
- shape: List of dimensions
- doc_string: Human-readable documentation
- elem_type_name: Optional name for custom element types
Returns:
ValueInfoProto: Value information for sparse tensors
"""
def make_tensor_sequence_value_info(name, elem_type, shape, doc_string="", elem_type_name=""):
"""
Create a ValueInfoProto for tensor sequence values.
Parameters:
- name: Name of the value
- elem_type: Element data type for sequence elements
- shape: Shape of individual tensors in sequence
- doc_string: Human-readable documentation
- elem_type_name: Optional name for custom element types
Returns:
ValueInfoProto: Value information for tensor sequences
"""
def make_empty_tensor_value_info(name):
"""
Create an empty ValueInfoProto for tensors with unknown type/shape.
Parameters:
- name: Name of the value
Returns:
ValueInfoProto: Empty value information
"""
def make_value_info(name, type_proto, doc_string=""):
"""
Create a ValueInfoProto from a TypeProto.
Parameters:
- name: Name of the value
- type_proto: TypeProto specifying the type
- doc_string: Human-readable documentation
Returns:
ValueInfoProto: Value information
"""Attribute Creation
Create node attributes for operator parameters and configuration.
def make_attribute(key, value, doc_string=""):
"""
Create an AttributeProto from a value.
Parameters:
- key: Attribute name
- value: Attribute value (int, float, string, list, or tensor)
- doc_string: Human-readable documentation
Returns:
AttributeProto: Node attribute
"""
def make_attribute_ref(key, ref_attr_name, doc_string=""):
"""
Create an AttributeProto that references another attribute.
Parameters:
- key: Attribute name
- ref_attr_name: Name of referenced attribute
- doc_string: Human-readable documentation
Returns:
AttributeProto: Attribute reference
"""
def get_attribute_value(attr):
"""
Extract the actual value from an AttributeProto.
Parameters:
- attr: AttributeProto to extract value from
Returns:
Any: The attribute value in appropriate Python type
"""
def get_node_attr_value(node, attr_name):
"""
Get attribute value from a node by name.
Parameters:
- node: NodeProto to get attribute from
- attr_name: Name of the attribute to retrieve
Returns:
Any: The attribute value, or None if not found
"""Function Creation
Create user-defined functions for custom operations.
def make_function(domain, fname, inputs, outputs, nodes, opset_imports=None,
attributes=None, doc_string=""):
"""
Create a FunctionProto representing a user-defined function.
Parameters:
- domain: Function domain namespace
- fname: Function name
- inputs: List of input parameter names
- outputs: List of output parameter names
- nodes: List of NodeProto representing function body
- opset_imports: List of operator set imports
- attributes: List of function attributes
- doc_string: Human-readable documentation
Returns:
FunctionProto: User-defined function
"""Data Type Utilities
Utilities for working with tensor data types and conversions.
def tensor_dtype_to_np_dtype(tensor_dtype):
"""
Convert ONNX tensor data type to NumPy dtype.
Parameters:
- tensor_dtype: ONNX tensor data type (e.g., TensorProto.FLOAT)
Returns:
numpy.dtype: Corresponding NumPy data type
"""
def np_dtype_to_tensor_dtype(np_dtype):
"""
Convert NumPy dtype to ONNX tensor data type.
Parameters:
- np_dtype: NumPy data type
Returns:
int: ONNX tensor data type constant
"""
def tensor_dtype_to_string(tensor_dtype):
"""
Convert tensor data type to string representation.
Parameters:
- tensor_dtype: ONNX tensor data type
Returns:
str: String representation of the data type
"""
def get_all_tensor_dtypes():
"""
Get all supported ONNX tensor data types.
Returns:
list: List of all supported tensor data type constants
"""Training Information
Create training-specific information for models that support training workflows.
def make_training_info(
algorithm: GraphProto,
algorithm_bindings: AssignmentBindingType,
initialization: Optional[GraphProto],
initialization_bindings: Optional[AssignmentBindingType],
) -> TrainingInfoProto:
"""
Construct a TrainingInfoProto for training-enabled models.
Parameters:
- algorithm: GraphProto representing the training algorithm
- algorithm_bindings: Binding assignments for algorithm parameters
- initialization: Optional initialization graph
- initialization_bindings: Optional binding assignments for initialization
Returns:
TrainingInfoProto: Training information protocol buffer
"""Float Conversion Utilities
Specialized functions for converting between float32 and various reduced-precision formats.
def float32_to_bfloat16(fval: float, truncate: bool = False) -> int:
"""
Convert a float32 value to bfloat16 format (as int).
Parameters:
- fval: Float32 value to convert
- truncate: If True, use simple truncation; if False, use round-to-nearest-even
Returns:
int: Bfloat16 value as integer representation
"""
def float32_to_float8e4m3(
fval: float,
scale: float = 1.0,
fn: bool = True,
uz: bool = False,
saturate: bool = True,
) -> int:
"""
Convert a float32 value to float8 e4m3 format (as int).
Parameters:
- fval: Float32 value to convert
- scale: Scale factor to divide fval before conversion
- fn: No infinite values (must be True)
- uz: No negative zero
- saturate: Convert out-of-range values to max instead of NaN
Returns:
int: Float8 e4m3 value as integer representation
"""
def float32_to_float8e5m2(
fval: float,
scale: float = 1.0,
fn: bool = False,
uz: bool = False,
saturate: bool = True,
) -> int:
"""
Convert a float32 value to float8 e5m2 format (as int).
Parameters:
- fval: Float32 value to convert
- scale: Scale factor to divide fval before conversion
- fn: No infinite values
- uz: No negative zero
- saturate: Convert out-of-range values to max instead of NaN
Returns:
int: Float8 e5m2 value as integer representation
"""Version Management
Utilities for managing ONNX version compatibility and operator sets.
VERSION_TABLE = ... # List of version compatibility information
def create_op_set_id_version_map(table):
"""
Create operator set version mapping from compatibility table.
Parameters:
- table: Version compatibility table
Returns:
dict: Mapping of operator set domains to versions
"""
def find_min_ir_version_for(**kwargs):
"""
Find minimum IR version required for given operators or features.
Parameters:
- **kwargs: Features or operators to check version requirements for
Returns:
int: Minimum required IR version
"""Printing and Inspection Utilities
Functions for creating human-readable representations of ONNX objects.
def printable_attribute(attr):
"""
Create human-readable string representation of an attribute.
Parameters:
- attr: AttributeProto to represent
Returns:
str: Human-readable attribute representation
"""
def printable_type(t):
"""
Create human-readable string representation of a type.
Parameters:
- t: TypeProto to represent
Returns:
str: Human-readable type representation
"""
def printable_value_info(v):
"""
Create human-readable string representation of value info.
Parameters:
- v: ValueInfoProto to represent
Returns:
str: Human-readable value info representation
"""
def printable_tensor_proto(t):
"""
Create human-readable string representation of a tensor.
Parameters:
- t: TensorProto to represent
Returns:
str: Human-readable tensor representation
"""
def printable_node(node, **kwargs):
"""
Create human-readable string representation of a node.
Parameters:
- node: NodeProto to represent
- **kwargs: Additional formatting options
Returns:
str: Human-readable node representation
"""
def printable_graph(graph, prefix=""):
"""
Create human-readable string representation of a graph.
Parameters:
- graph: GraphProto to represent
- prefix: Prefix for indentation
Returns:
str: Human-readable graph representation
"""Usage Examples
Building a Simple Neural Network
import onnx
from onnx import helper, TensorProto
import numpy as np
# Define input and output
X = helper.make_tensor_value_info('X', TensorProto.FLOAT, [1, 3, 224, 224])
Y = helper.make_tensor_value_info('Y', TensorProto.FLOAT, [1, 1000])
# Create weight tensor
weight_data = np.random.randn(64, 3, 7, 7).astype(np.float32)
weight = helper.make_tensor('conv_weight', TensorProto.FLOAT,
weight_data.shape, weight_data.flatten())
# Create convolution node
conv_node = helper.make_node(
'Conv',
inputs=['X', 'conv_weight'],
outputs=['conv_out'],
kernel_shape=[7, 7],
strides=[2, 2],
pads=[3, 3, 3, 3]
)
# Create ReLU activation
relu_node = helper.make_node('Relu', ['conv_out'], ['relu_out'])
# Create global average pooling
pool_node = helper.make_node('GlobalAveragePool', ['relu_out'], ['pool_out'])
# Create fully connected layer
fc_weight = np.random.randn(1000, 64).astype(np.float32)
fc_weight_tensor = helper.make_tensor('fc_weight', TensorProto.FLOAT,
fc_weight.shape, fc_weight.flatten())
fc_node = helper.make_node('MatMul', ['pool_out', 'fc_weight'], ['Y'])
# Create graph
graph_def = helper.make_graph(
[conv_node, relu_node, pool_node, fc_node],
'simple_cnn',
[X],
[Y],
[weight, fc_weight_tensor]
)
# Create model
model_def = helper.make_model(graph_def, producer_name='onnx-example')
# Save model
onnx.save_model(model_def, 'simple_cnn.onnx')Creating Custom Types and Attributes
import onnx
from onnx import helper, TensorProto
# Create a node with various attribute types
node = helper.make_node(
'CustomOp',
inputs=['input'],
outputs=['output'],
# Various attribute types
int_attr=42,
float_attr=3.14,
string_attr="hello",
ints_attr=[1, 2, 3],
floats_attr=[1.0, 2.0, 3.0],
strings_attr=["a", "b", "c"]
)
# Create complex type information
sequence_type = helper.make_sequence_type_proto(
helper.make_tensor_type_proto(TensorProto.FLOAT, [None, 128])
)
map_type = helper.make_map_type_proto(
TensorProto.STRING,
helper.make_tensor_type_proto(TensorProto.FLOAT, [None])
)
optional_type = helper.make_optional_type_proto(
helper.make_tensor_type_proto(TensorProto.INT64, [None])
)Install with Tessl CLI
npx tessl i tessl/pypi-onnx