Package ai.djl

Interface Model

  • All Superinterfaces:
    java.lang.AutoCloseable
    All Known Implementing Classes:
    BaseModel, ZooModel
    public interface Model
extends java.lang.AutoCloseable
    A model is a collection of artifacts that is created by the training process.

    A deep learning model usually contains the following parts:

    • the Block of operations to run
    • the Parameters that are trained
    • Input/Output information: input and output parameter names, shape, etc.
    • Other artifacts such as a synset for classification that would be used during pre-processing and post-processing

    For loading a pre-trained model, see load(Path, String)

    For training a model, see Trainer.

    For running inference with a model, see Predictor.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default void cast​(DataType dataType)
      Casts the model to support a different precision level.
      void close()
      ai.djl.util.PairList<java.lang.String,​Shape> describeInput()
      Returns the input descriptor of the model.
      ai.djl.util.PairList<java.lang.String,​Shape> describeOutput()
      Returns the output descriptor of the model.
      java.net.URL getArtifact​(java.lang.String name)
      Finds an artifact resource with a given name in the model.
      <T> T getArtifact​(java.lang.String name, java.util.function.Function<java.io.InputStream,​T> function)
      Attempts to load the artifact using the given function and cache it if the specified artifact is not already cached.
      java.io.InputStream getArtifactAsStream​(java.lang.String name)
      Finds an artifact resource with a given name in the model.
      java.lang.String[] getArtifactNames()
      Returns the artifact names associated with the model.
      Block getBlock()
      Gets the block from the Model.
      DataType getDataType()
      Returns the standard data type used within the model.
      java.nio.file.Path getModelPath()
      Returns the directory from where the model is loaded.
      java.lang.String getName()
      Gets the model name.
      NDManager getNDManager()
      Gets the NDManager from the model.
      java.util.Map<java.lang.String,​java.lang.String> getProperties()
      Returns the model's properties.
      java.lang.String getProperty​(java.lang.String key)
      Returns the property of the model based on property name.
      default java.lang.String getProperty​(java.lang.String key, java.lang.String defValue)
      Returns the property of the model based on property name.
      default void load​(java.io.InputStream is)
      Loads the model from the InputStream.
      void load​(java.io.InputStream is, java.util.Map<java.lang.String,​?> options)
      Loads the model from the InputStream with the options provided.
      default void load​(java.nio.file.Path modelPath)
      Loads the model from the modelPath.
      default void load​(java.nio.file.Path modelPath, java.lang.String prefix)
      Loads the model from the modelPath and the given name.
      void load​(java.nio.file.Path modelPath, java.lang.String prefix, java.util.Map<java.lang.String,​?> options)
      Loads the model from the modelPath with the name and options provided.
      static Model newInstance​(java.lang.String name)
      Creates an empty model instance.
      static Model newInstance​(java.lang.String name, Device device)
      Creates an empty model instance on the specified Device.
      static Model newInstance​(java.lang.String name, Device device, java.lang.String engineName)
      Creates an empty model instance on the specified Device and engine.
      static Model newInstance​(java.lang.String name, java.lang.String engineName)
      Creates an empty model instance on the specified Device and engine.
      default <I,​O>
      Predictor<I,​O>      		 newPredictor​(Translator<I,​O> translator)
      Creates a new Predictor based on the model on the current device.
      <I,​O>
      Predictor<I,​O>      		 newPredictor​(Translator<I,​O> translator, Device device)
      Creates a new Predictor based on the model.
      Trainer newTrainer​(TrainingConfig trainingConfig)
      Creates a new Trainer instance for a Model.
      default void quantize()
      Converts the model to use a lower precision quantized network.
      void save​(java.nio.file.Path modelPath, java.lang.String newModelName)
      Saves the model to the specified modelPath with the name provided.
      void setBlock​(Block block)
      Sets the block for the Model for training and inference.
      void setDataType​(DataType dataType)
      Sets the standard data type used within the model.
      void setProperty​(java.lang.String key, java.lang.String value)
      Sets a property to the model.

    • Method Detail

      • newInstance

        static Model newInstance​(java.lang.String name)
        Creates an empty model instance.
        Parameters:
        name - the model name
        Returns:
        a new Model instance

      • newInstance

        static Model newInstance​(java.lang.String name,
                         Device device)
        Creates an empty model instance on the specified Device.
        Parameters:
        name - the model name
        device - the device to load the model onto
        Returns:
        a new model instance

      • newInstance

        static Model newInstance​(java.lang.String name,
                         java.lang.String engineName)
        Creates an empty model instance on the specified Device and engine.
        Parameters:
        name - the model name
        engineName - the name of the engine
        Returns:
        a new model instance

      • newInstance

        static Model newInstance​(java.lang.String name,
                         Device device,
                         java.lang.String engineName)
        Creates an empty model instance on the specified Device and engine.
        Parameters:
        name - the model name
        device - the device to load the model onto
        engineName - the name of the engine
        Returns:
        a new model instance

      • load

        default void load​(java.nio.file.Path modelPath)
           throws java.io.IOException,
                  MalformedModelException
        Loads the model from the modelPath.
        Parameters:
        modelPath - the directory or file path of the model location
        Throws:
        java.io.IOException - when IO operation fails in loading a resource
        MalformedModelException - if model file is corrupted

      • load

        default void load​(java.nio.file.Path modelPath,
                  java.lang.String prefix)
           throws java.io.IOException,
                  MalformedModelException
        Loads the model from the modelPath and the given name.
        Parameters:
        modelPath - the directory or file path of the model location
        prefix - the model file name or path prefix
        Throws:
        java.io.IOException - when IO operation fails in loading a resource
        MalformedModelException - if model file is corrupted

      • load

        void load​(java.nio.file.Path modelPath,
          java.lang.String prefix,
          java.util.Map<java.lang.String,​?> options)
   throws java.io.IOException,
          MalformedModelException
        Loads the model from the modelPath with the name and options provided.
        Parameters:
        modelPath - the directory or file path of the model location
        prefix - the model file name or path prefix
        options - engine specific load model options, see documentation for each engine
        Throws:
        java.io.IOException - when IO operation fails in loading a resource
        MalformedModelException - if model file is corrupted

      • load

        default void load​(java.io.InputStream is)
           throws java.io.IOException,
                  MalformedModelException
        Loads the model from the InputStream.
        Parameters:
        is - the InputStream to load the model from
        Throws:
        java.io.IOException - when IO operation fails in loading a resource
        MalformedModelException - if model file is corrupted

      • load

        void load​(java.io.InputStream is,
          java.util.Map<java.lang.String,​?> options)
   throws java.io.IOException,
          MalformedModelException
        Loads the model from the InputStream with the options provided.
        Parameters:
        is - the InputStream to load the model from
        options - engine specific load model options, see documentation for each engine
        Throws:
        java.io.IOException - when IO operation fails in loading a resource
        MalformedModelException - if model file is corrupted

      • save

        void save​(java.nio.file.Path modelPath,
          java.lang.String newModelName)
   throws java.io.IOException
        Saves the model to the specified modelPath with the name provided.
        Parameters:
        modelPath - the directory or file path of the model location
        newModelName - the new model name to be saved, use null to keep original model name
        Throws:
        java.io.IOException - when IO operation fails in loading a resource

      • getModelPath

        java.nio.file.Path getModelPath()
        Returns the directory from where the model is loaded.
        Returns:
        the directory of the model location

      • getBlock

        Block getBlock()
        Gets the block from the Model.
        Returns:
        the Block

      • setBlock

        void setBlock​(Block block)
        Sets the block for the Model for training and inference.
        Parameters:
        block - the Block used in Model

      • getName

        java.lang.String getName()
        Gets the model name.
        Returns:
        name of the model

      • getProperties

        java.util.Map<java.lang.String,​java.lang.String> getProperties()
        Returns the model's properties.
        Returns:
        the model's properties

      • getProperty

        java.lang.String getProperty​(java.lang.String key)
        Returns the property of the model based on property name.
        Parameters:
        key - the name of the property
        Returns:
        the value of the property

      • getProperty

        default java.lang.String getProperty​(java.lang.String key,
                                     java.lang.String defValue)
        Returns the property of the model based on property name.
        Parameters:
        key - the name of the property
        defValue - the default value if key not found
        Returns:
        the value of the property

      • setProperty

        void setProperty​(java.lang.String key,
                 java.lang.String value)
        Sets a property to the model.

        properties will be saved/loaded with model, user can store some information about the model in here.

        Parameters:
        key - the name of the property
        value - the value of the property

      • newTrainer

        Trainer newTrainer​(TrainingConfig trainingConfig)
        Creates a new Trainer instance for a Model.
        Parameters:
        trainingConfig - training configuration settings
        Returns:
        the Trainer instance

      • newPredictor

        default <I,​O> Predictor<I,​O> newPredictor​(Translator<I,​O> translator)
        Creates a new Predictor based on the model on the current device.
        Type Parameters:
        I - the input object for pre-processing
        O - the output object from postprocessing
        Parameters:
        translator - the object used for pre-processing and postprocessing
        Returns:
        an instance of Predictor

      • newPredictor

        <I,​O> Predictor<I,​O> newPredictor​(Translator<I,​O> translator,
                                              Device device)
        Creates a new Predictor based on the model.
        Type Parameters:
        I - the input object for pre-processing
        O - the output object from postprocessing
        Parameters:
        translator - the object used for pre-processing and postprocessing
        device - the device to use for prediction
        Returns:
        an instance of Predictor

      • describeInput

        ai.djl.util.PairList<java.lang.String,​Shape> describeInput()
        Returns the input descriptor of the model.

        It contains the information that can be extracted from the model, usually name, shape, layout and DataType.

        Returns:
        a PairList of String and Shape

      • describeOutput

        ai.djl.util.PairList<java.lang.String,​Shape> describeOutput()
        Returns the output descriptor of the model.

        It contains the output information that can be obtained from the model.

        Returns:
        a PairList of String and Shape

      • getArtifactNames

        java.lang.String[] getArtifactNames()
        Returns the artifact names associated with the model.
        Returns:
        an array of artifact names

      • getArtifact

        <T> T getArtifact​(java.lang.String name,
                  java.util.function.Function<java.io.InputStream,​T> function)
           throws java.io.IOException
        Attempts to load the artifact using the given function and cache it if the specified artifact is not already cached.

        Model will cache loaded artifact, so the user doesn't need to keep tracking it. 

        
 String synset = model.getArtifact("synset.txt", k -> IOUtils.toString(k)));
        Type Parameters:
        T - the type of the returned artifact object
        Parameters:
        name - the name of the desired artifact
        function - the function to load the artifact
        Returns:
        the current (existing or computed) artifact associated with the specified name, or null if the computed value is null
        Throws:
        java.io.IOException - when IO operation fails in loading a resource
        java.lang.ClassCastException - if the cached artifact cannot be cast to the target class

      • getArtifact

        java.net.URL getArtifact​(java.lang.String name)
                  throws java.io.IOException
        Finds an artifact resource with a given name in the model.
        Parameters:
        name - the name of the desired artifact
        Returns:
        a URL object or null if no artifact with this name is found
        Throws:
        java.io.IOException - when IO operation fails in loading a resource

      • getArtifactAsStream

        java.io.InputStream getArtifactAsStream​(java.lang.String name)
                                 throws java.io.IOException
        Finds an artifact resource with a given name in the model.
        Parameters:
        name - the name of the desired artifact
        Returns:
        a InputStream object or null if no resource with this name is found
        Throws:
        java.io.IOException - when IO operation fails in loading a resource

      • setDataType

        void setDataType​(DataType dataType)
        Sets the standard data type used within the model.
        Parameters:
        dataType - the standard data type to use

      • getDataType

        DataType getDataType()
        Returns the standard data type used within the model.
        Returns:
        the standard data type used within the model

      • cast

        default void cast​(DataType dataType)
        Casts the model to support a different precision level.

        For example, you can cast the precision from Float to Int

        Parameters:
        dataType - the target dataType you would like to cast to

      • quantize

        default void quantize()
        Converts the model to use a lower precision quantized network.

        Quantization converts the network to use int8 data type where possible for smaller model size and faster computation without too large a drop in accuracy. See original paper.

      • close

        void close()
        Specified by:
        close in interface java.lang.AutoCloseable