Serialization

Save a model and any Proto class

This ONNX graph needs to be serialized into one contiguous memory buffer. Method SerializeToString is available in every ONNX objects.

with open("model.onnx", "wb") as f:
    f.write(onnx_model.SerializeToString())

This method has the following signature.

class onnx.ModelProto
SerializeToString()

Serializes the message to a string, only for initialized messages.

Every Proto class implements method SerializeToString. Therefore the following code works with any class described in page Protos.

with open("proto.pb", "wb") as f:
    f.write(proto.SerializeToString())

Next example shows how to save a NodeProto.

from onnx import NodeProto

node = NodeProto()
node.name = "example-type-proto"
node.op_type = "Add"
node.input.extend(["X", "Y"])
node.output.extend(["Z"])

with open("node.pb", "wb") as f:
    f.write(node.SerializeToString())

Load a model

Following function only automates the loading of a class ModelProto. Next sections shows how to restore any other proto class.

onnx.load(f: IO[bytes] | str | PathLike, format: Literal['protobuf', 'textproto', 'onnxtxt', 'json'] | str | None = None, load_external_data: bool = True) → ModelProto

Loads a serialized ModelProto into memory.

Parameters:

  • f – can be a file-like object (has “read” function) or a string/PathLike containing a file name

  • format – The serialization format. When it is not specified, it is inferred from the file extension when f is a path. If not specified _and_ f is not a path, ‘protobuf’ is used. The encoding is assumed to be “utf-8” when the format is a text format.

  • load_external_data – Whether to load the external data. Set to True if the data is under the same directory of the model. If not, users need to call load_external_data_for_model() with directory to load external data from.

Returns:

Loaded in-memory ModelProto.

from onnx import load

onnx_model = load("model.onnx")

Or:

from onnx import load

with open("model.onnx", "rb") as f:
    onnx_model = load(f)

Next function does the same from a bytes array.

onnx.load_model_from_string(s: bytes | str, format: Literal['protobuf', 'textproto', 'onnxtxt', 'json'] | str = 'protobuf') → ModelProto[source]

Loads a binary string (bytes) that contains serialized ModelProto.

Parameters:

  • s – a string, which contains serialized ModelProto

  • format – The serialization format. When it is not specified, it is inferred from the file extension when f is a path. If not specified _and_ f is not a path, ‘protobuf’ is used. The encoding is assumed to be “utf-8” when the format is a text format.

Returns:

Loaded in-memory ModelProto.

Load a Proto

Proto means here any type containing data including a model, a tensor, a sparse tensor, any class listed in page Protos. The user must know the type of the data he needs to restore and then call method ParseFromString. protobuf does not store any information about the class of the saved data. Therefore, this class must be known before restoring an object.

class onnx.ModelProto
ParseFromString()

Parses a serialized message into the current message.

Next example shows how to restore a NodeProto.

from onnx import NodeProto

tp2 = NodeProto()
with open("node.pb", "rb") as f:
    content = f.read()

tp2.ParseFromString(content)

print(tp2)

input: "X"
input: "Y"
output: "Z"
name: "example-type-proto"
op_type: "Add"

A shortcut exists for TensorProto:

onnx.load_tensor_from_string(s: bytes, format: Literal['protobuf', 'textproto', 'onnxtxt', 'json'] | str = 'protobuf') → TensorProto[source]

Loads a binary string (bytes) that contains serialized TensorProto.

Parameters:

  • s – a string, which contains serialized TensorProto

  • format – The serialization format. When it is not specified, it is inferred from the file extension when f is a path. If not specified _and_ f is not a path, ‘protobuf’ is used. The encoding is assumed to be “utf-8” when the format is a text format.

Returns:

Loaded in-memory TensorProto.