0
# Model I/O Operations
1

2
Core functions for loading and saving ONNX models from various sources including files, streams, and binary data. These functions support multiple serialization formats and external data storage for large models.
3

4
## Capabilities
5

6
### Model Loading
7

8
Load ONNX models from files, file-like objects, or string data with support for external data loading and format detection.
9

10
```python { .api }
11
def load_model(
12
    f: IO[bytes] | str | os.PathLike,
13
    format: _SupportedFormat | None = None,
14
    load_external_data: bool = True,
15
) -> ModelProto:
16
    """
17
    Loads a serialized ModelProto into memory.
18

19
    Parameters:
20
    - f: can be a file-like object (has "read" function) or a string/PathLike containing a file name
21
    - format: The serialization format. When it is not specified, it is inferred
22
        from the file extension when ``f`` is a path. If not specified _and_
23
        ``f`` is not a path, 'protobuf' is used. The encoding is assumed to
24
        be "utf-8" when the format is a text format.
25
    - load_external_data: Whether to load the external data.
26
        Set to True if the data is under the same directory of the model.
27
        If not, users need to call :func:`load_external_data_for_model`
28
        with directory to load external data from.
29

30
    Returns:
31
    ModelProto: Loaded in-memory ModelProto.
32
    """
33

34
def load_model_from_string(
35
    s: bytes | str,
36
    format: _SupportedFormat = _DEFAULT_FORMAT,
37
) -> ModelProto:
38
    """
39
    Loads a binary string (bytes) that contains serialized ModelProto.
40

41
    Parameters:
42
    - s: a string, which contains serialized ModelProto
43
    - format: The serialization format. When it is not specified, it is inferred
44
        from the file extension when ``f`` is a path. If not specified _and_
45
        ``f`` is not a path, 'protobuf' is used. The encoding is assumed to
46
        be "utf-8" when the format is a text format.
47

48
    Returns:
49
    ModelProto: Loaded in-memory ModelProto.
50
    """
51
```
52

53
### Tensor Loading
54

55
Load individual tensors from files or string data, useful for loading model weights or intermediate results.
56

57
```python { .api }
58
def load_tensor(
59
    f: IO[bytes] | str | os.PathLike,
60
    format: _SupportedFormat | None = None,
61
) -> TensorProto:
62
    """
63
    Loads a serialized TensorProto into memory.
64

65
    Parameters:
66
    - f: can be a file-like object (has "read" function) or a string/PathLike containing a file name
67
    - format: The serialization format. When it is not specified, it is inferred
68
        from the file extension when ``f`` is a path. If not specified _and_
69
        ``f`` is not a path, 'protobuf' is used. The encoding is assumed to
70
        be "utf-8" when the format is a text format.
71

72
    Returns:
73
    TensorProto: Loaded in-memory TensorProto.
74
    """
75

76
def load_tensor_from_string(
77
    s: bytes,
78
    format: _SupportedFormat = _DEFAULT_FORMAT,
79
) -> TensorProto:
80
    """
81
    Loads a binary string (bytes) that contains serialized TensorProto.
82

83
    Parameters:
84
    - s: a string, which contains serialized TensorProto
85
    - format: The serialization format. When it is not specified, it is inferred
86
        from the file extension when ``f`` is a path. If not specified _and_
87
        ``f`` is not a path, 'protobuf' is used. The encoding is assumed to
88
        be "utf-8" when the format is a text format.
89

90
    Returns:
91
    TensorProto: Loaded in-memory TensorProto.
92
    """
93
```
94

95
### Model Saving
96

97
Save ONNX models to files with support for external data storage, compression, and format selection.
98

99
```python { .api }
100
def save_model(
101
    proto: ModelProto | bytes,
102
    f: IO[bytes] | str | os.PathLike,
103
    format: _SupportedFormat | None = None,
104
    *,
105
    save_as_external_data: bool = False,
106
    all_tensors_to_one_file: bool = True,
107
    location: str | None = None,
108
    size_threshold: int = 1024,
109
    convert_attribute: bool = False,
110
) -> None:
111
    """
112
    Saves the ModelProto to the specified path and optionally, serialize tensors with raw data as external data before saving.
113

114
    Parameters:
115
    - proto: should be a in-memory ModelProto
116
    - f: can be a file-like object (has "write" function) or a string containing
117
    a file name or a pathlike object
118
    - format: The serialization format. When it is not specified, it is inferred
119
        from the file extension when ``f`` is a path. If not specified _and_
120
        ``f`` is not a path, 'protobuf' is used. The encoding is assumed to
121
        be "utf-8" when the format is a text format.
122
    - save_as_external_data: If true, save tensors to external file(s).
123
    - all_tensors_to_one_file: Effective only if save_as_external_data is True.
124
        If true, save all tensors to one external file specified by location.
125
        If false, save each tensor to a file named with the tensor name.
126
    - location: Effective only if save_as_external_data is true.
127
        Specify the external file that all tensors to save to.
128
        Path is relative to the model path.
129
        If not specified, will use the model name.
130
    - size_threshold: Effective only if save_as_external_data is True.
131
        Threshold for size of data. Only when tensor's data is >= the size_threshold it will be converted
132
        to external data. To convert every tensor with raw data to external data set size_threshold=0.
133
    - convert_attribute: Effective only if save_as_external_data is True.
134
        If true, convert all tensors to external data
135
        If false, convert only non-attribute tensors to external data
136
    """
137
```
138

139
### Tensor Saving
140

141
Save individual tensors to files with format selection and serialization options.
142

143
```python { .api }
144
def save_tensor(
145
    proto: TensorProto,
146
    f: IO[bytes] | str | os.PathLike,
147
    format: _SupportedFormat | None = None,
148
) -> None:
149
    """
150
    Saves the TensorProto to the specified path.
151

152
    Parameters:
153
    - proto: should be a in-memory TensorProto
154
    - f: can be a file-like object (has "write" function) or a string
155
    containing a file name or a pathlike object.
156
    - format: The serialization format. When it is not specified, it is inferred
157
        from the file extension when ``f`` is a path. If not specified _and_
158
        ``f`` is not a path, 'protobuf' is used. The encoding is assumed to
159
        be "utf-8" when the format is a text format.
160
    """
161
```
162

163
### External Data Management
164

165
Manage external data files for large models, enabling efficient storage and loading of large tensors.
166

167
```python { .api }
168
def load_external_data_for_model(model, base_dir):
169
    """
170
    Load external data for all tensors in a model.
171

172
    Parameters:
173
    - model: ModelProto with external data references
174
    - base_dir: Directory path containing external data files
175

176
    Returns:
177
    None (modifies model in-place)
178
    """
179

180
def convert_model_to_external_data(model, all_tensors_to_one_file=True, 
181
                                   location=None, size_threshold=1024, 
182
                                   convert_attribute=False):
183
    """
184
    Convert model tensors to external data format.
185

186
    Parameters:
187
    - model: ModelProto to convert
188
    - all_tensors_to_one_file: Save all tensors to single file
189
    - location: External file location
190
    - size_threshold: Minimum size for external storage
191
    - convert_attribute: Convert attribute tensors to external data
192

193
    Returns:
194
    None (modifies model in-place)
195
    """
196

197
def write_external_data_tensors(model, filepath):
198
    """
199
    Write external data tensors to files.
200

201
    Parameters:
202
    - model: ModelProto with external data references
203
    - filepath: Base path for external data files
204

205
    Returns:
206
    ModelProto: Updated model with external data written
207
    """
208
```
209

210
### Legacy Aliases
211

212
Backward compatibility aliases for common loading and saving operations.
213

214
```python { .api }
215
load = load_model  # Alias for load_model
216
load_from_string = load_model_from_string  # Alias for load_model_from_string
217
save = save_model  # Alias for save_model
218
```
219

220
## Usage Examples
221

222
### Basic Model Loading and Saving
223

224
```python
225
import onnx
226

227
# Load a model from file
228
model = onnx.load_model("path/to/model.onnx")
229

230
# Save the model to a new location
231
onnx.save_model(model, "path/to/new_model.onnx")
232

233
# Load model from binary data
234
with open("model.onnx", "rb") as f:
235
    binary_data = f.read()
236
model = onnx.load_model_from_string(binary_data)
237
```
238

239
### External Data Handling
240

241
```python
242
import onnx
243

244
# Load model with external data
245
model = onnx.load_model("large_model.onnx", load_external_data=True)
246

247
# Save model with external data for tensors > 1KB
248
onnx.save_model(model, "output_model.onnx", 
249
                save_as_external_data=True,
250
                size_threshold=1024)
251

252
# Convert existing model to use external data
253
onnx.convert_model_to_external_data(model, 
254
                                    all_tensors_to_one_file=True,
255
                                    location="weights.bin")
256
```
257

258
### Format Handling
259

260
```python
261
import onnx
262

263
# Load with specific format
264
model = onnx.load_model("model.txt", format="textproto")
265

266
# Save in text format for debugging
267
onnx.save_model(model, "debug_model.txt", format="textproto")
268

269
# Auto-detect format from file extension
270
model = onnx.load_model("model.onnx")  # Detects protobuf format
271
onnx.save_model(model, "output.json", format="json")  # JSON format
272
```