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

Modifier and Type	Method and 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.lang.String	getProperty(java.lang.String key) Gets the property of the model based on property name.
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.
<I,O> Predictor<I,O>	newPredictor(Translator<I,O> translator) 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

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

getProperty

java.lang.String getProperty(java.lang.String key)

Gets the property of the model based on property name.

Parameters:

key - the name of the property

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

getNDManager

NDManager getNDManager()

Gets the NDManager from the model.

Returns:

the NDManager

newTrainer

Trainer newTrainer(TrainingConfig trainingConfig)

Creates a new Trainer instance for a Model.

Parameters:

trainingConfig - training configuration settings

Returns:

the Trainer instance

newPredictor

<I,O> Predictor<I,O> newPredictor(Translator<I,O> translator)

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

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