Record Class SafeTensors

java.lang.Object
java.lang.Record
smile.deep.tensor.SafeTensors
Record Components:
tensors - the name-to-tensor map.
metadata - the free-form string-to-string metadata map.
public record SafeTensors(Map<String,Tensor> tensors, Map<String,String> metadata) extends Record
Safetensors is a simple format for storing tensors safely (as opposed to pickle) with zero-copy reads. This class implements reading and writing the safetensors binary format.
See Also:

  • Constructor Details

    • SafeTensors

      public SafeTensors(Map<String,Tensor> tensors, Map<String,String> metadata)
      Creates an instance of a SafeTensors record class.
      Parameters:
      tensors - the value for the tensors record component
      metadata - the value for the metadata record component

  • Method Details

    • read

      public static SafeTensors read(String path, Device device) throws IOException
      Reads a safetensors file from disk, materialising every tensor.
      Parameters:
      path - the file path to read.
      device - the device on which to store the loaded tensors.
      Returns:
      the parsed safetensors file.
      Throws:
      IOException - if an I/O error occurs.

    • read

      public static SafeTensors read(String path, Device device, Collection<String> include) throws IOException
      Reads selected tensors from a safetensors file.

      Each tensor is loaded with a positioned FileChannel.read(ByteBuffer) of its data_offsets range. The data region is not memory-mapped as a whole, so shards larger than Integer.MAX_VALUE bytes (common for multi-gigabyte LLM checkpoints) load correctly. Bit-identical dtypes (F16/BF16/F32/integers/…) are copied straight into LibTorch storage and may exceed Integer.MAX_VALUE bytes. Dtypes that require element-wise decoding (F8_*) still require a Java ByteBuffer and therefore ≤ Integer.MAX_VALUE bytes.

      Parameters:
      path - the file path to read.
      device - the device on which to store the loaded tensors.
      include - when non-null, only tensors whose names are in this collection are materialised; null loads all tensors.
      Returns:
      the parsed safetensors subset (metadata is always populated).
      Throws:
      IOException - if an I/O error occurs.

    • listTensors

      public static List<String> listTensors(String path) throws IOException
      Returns the tensor names declared in a safetensors header without loading any tensor data. Suitable for building a weight map from a single large checkpoint file.
      Parameters:
      path - the safetensors file path.
      Returns:
      tensor names in header order (excluding __metadata__).
      Throws:
      IOException - if an I/O error occurs.

    • write

      public void write(String path) throws IOException
      Writes this SafeTensors object to a file.

      The file is created (or truncated) at path. The layout is identical to the format described in read(String, Device): an 8-byte little-endian header-length prefix, a UTF-8 JSON header, and then the raw little-endian tensor bytes. __metadata__ is written first in the JSON object when the metadata map is non-empty.

      Unsigned integer types are serialised by reinterpreting the bit pattern through the corresponding signed type, which preserves the raw bytes without any numeric conversion. ScalarType.Half and ScalarType.BFloat16 tensors are converted element-wise to float32 and their bits are re-encoded. F8 types follow the same float32 intermediate and then re-encode via the respective E4M3FN / E5M2 format rules.

      Parameters:
      path - the file path to write.
      Throws:
      IOException - if an I/O error occurs.
      UnsupportedOperationException - if a tensor has a dtype that cannot be serialised.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • tensors

      public Map<String,Tensor> tensors()
      Returns the value of the tensors record component.
      Returns:
      the value of the tensors record component

    • metadata

      public Map<String,String> metadata()
      Returns the value of the metadata record component.
      Returns:
      the value of the metadata record component