Principle:Onnx Onnx Model Serialization

Knowledge Sources	ONNX IR Spec Protocol Buffers
Domains	Serialization, Model_Persistence
Last Updated	2026-02-10 00:00 GMT

Overview

A persistence mechanism that writes in-memory ONNX model representations to disk in various serialization formats.

Description

Model serialization converts an in-memory ModelProto object into a byte stream and writes it to a file. ONNX supports multiple serialization formats: binary protobuf (the default and most compact), text protobuf, JSON, and ONNX textual syntax. The format is determined either explicitly or auto-detected from the file extension. Serialization also handles external data: for models with large tensors, the function can automatically convert tensor data to external files, keeping the model file itself under the 2GB protobuf limit.

This principle is essential for model exchange: once a model is serialized to an .onnx file, it can be loaded by any ONNX-compliant runtime (ONNX Runtime, TensorRT, CoreML, etc.) on any platform.

Usage

Use this principle as the final step in any model creation or transformation workflow. After constructing and validating a model, it must be serialized to disk for deployment or exchange. Use external data mode when model weights exceed 2GB.

Theoretical Basis

Serialization maps the in-memory protobuf object graph to a byte stream:

$\text{serialize}:\text{ModelProto}\to \text{bytes}\to \text{file}$

The serialization pipeline:

1. Optionally convert large tensors to external data references
2. Write external data blobs to separate files
3. Serialize the (now lighter) ModelProto to the chosen format
4. Write the serialized bytes to the output file

Supported formats:

• .onnx / .pb → Binary protobuf (default)
• .onnxtxt → ONNX textual syntax
• .json → JSON protobuf
• .textproto → Text protobuf

Related Pages

Implemented By

• Implementation:Onnx_Onnx_Save_Model

Uses Heuristic

• Heuristic:Onnx_Onnx_Protobuf_2GB_Limit_Workaround