ExternalTensor¶

class onnx_ir.ExternalTensor(location, offset, length, dtype, *, shape, name, doc_string=None, metadata_props=None, base_dir='')¶

An immutable concrete tensor with its data store on disk.

This class uses memory mapping to avoid loading the tensor into memory, when the data type is supported by numpy. Otherwise, the tensor is loaded into memory lazily when accessed.

Calling shape does not incur IO. Checking shape before loading the tensor is recommended if IO overhead and memory usage is a concern.

To obtain an array, call numpy(). To obtain the bytes, call tobytes(). To write the data to a file, call tofile().

The location must be a relative path conforming to the ONNX specification. Given the correct base_dir, the path is computed to be the full path to the data file. Users should expect that the path always leads to the correct file. At initialization, paths are not checked. It is the user’s responsibility to ensure the paths are valid and accessible.

Parameters:

location (os.PathLike | str)
offset (int | None)
length (int | None)
dtype (_enums.DataType)
shape (Shape)
name (str)
doc_string (str | None)
metadata_props (dict[str, str] | None)
base_dir (os.PathLike | str)

location¶: The location of the data file. It is the path relative to the base directory.

base_dir¶: The base directory for the external data. It is used to resolve relative paths. At serialization, only the location is serialized into the “location” field of the TensorProto.

path¶: The path to the data file. This is computed by joining base_dir and location.

offset¶: The offset in bytes from the start of the file.

length¶: The length of the data in bytes.

dtype¶: The data type of the tensor.

shape¶: The shape of the tensor.

name¶: The name of the tensor. It must be specified.

doc_string¶: The documentation string.

metadata_props¶: The metadata properties.

raw¶

display(*, page=False)¶

Pretty print the object.

Parameters:: page (bool) – Whether to page the output.
Return type:: None

invalidate()[source]¶

Invalidate the tensor.

The external tensor is invalidated when the data is known to be corrupted or deleted.

Return type:: None

property meta: MetadataStore¶

The metadata store for intermediate analysis.

Write to the metadata_props if you would like the metadata to be serialized to the ONNX proto.

property nbytes: int¶: The number of bytes in the tensor.

numpy()[source]¶

Return the tensor as a numpy array.

The data will be memory mapped into memory and will not taken up physical memory space.

Return type:: ndarray

release()[source]¶

Delete all references to the memory buffer and close the memory-mapped file.

Return type:: None

property size: int¶: The number of elements in the tensor.

tobytes()[source]¶

Return the bytes of the tensor.

This will load the tensor into memory.

Security: file access is gated by _load() which calls _check_path_containment() to enforce path containment.

Return type:: bytes

tofile(file)[source]¶

Write the external tensor bytes to a binary file-like object.

Regular files use copy_file_range when the platform and filesystem support it. Other destinations use a bounded userspace buffer.

Parameters:: file – A file-like object with a write method. Objects that also provide fileno, flush, tell, and seek may use the kernel-copy fast path.
Return type:: None

valid()[source]¶

Check if the tensor is valid.

The external tensor is valid if it has not been invalidated.

Return type:: bool