ExternalTensor

class onnx_ir.ExternalTensor(location: PathLike | str, offset: int | None, length: int | None, dtype: DataType, *, shape: Shape, name: str, doc_string: str | None = None, metadata_props: dict[str, str] | None = None, base_dir: PathLike | str = '')

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().

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.

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

property base_dir: str | PathLike

display(*, page: bool = False) → None

Pretty print the object.

Parameters:

page – Whether to page the output.

property doc_string: str | None

The documentation string.

property dtype: DataType

invalidate() → None

Invalidate the tensor.

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

property length: int | None

property location: str | PathLike

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 metadata_props: dict[str, str]

property name: str | None

The name of the tensor.

property nbytes: int

The number of bytes in the tensor.

numpy() → ndarray

Return the tensor as a numpy array.

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

property offset: int | None

property path: str

release() → None

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

property shape: Shape

property size: int

The number of elements in the tensor.

tobytes() → bytes

Return the bytes of the tensor.

This will load the tensor into memory.

valid() → bool

Check if the tensor is valid.

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