Interface Model
-
- All Superinterfaces:
java.lang.AutoCloseable
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
Parameter
s 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 theNDManager
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.io.InputStream is)
Loads the model from theInputStream
.void
load(java.io.InputStream is, java.util.Map<java.lang.String,?> options)
Loads the model from theInputStream
with the options provided.default void
load(java.nio.file.Path modelPath)
Loads the model from themodelPath
.default void
load(java.nio.file.Path modelPath, java.lang.String prefix)
Loads the model from themodelPath
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 themodelPath
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 specifiedDevice
.static Model
newInstance(java.lang.String name, Device device, java.lang.String engineName)
Creates an empty model instance on the specifiedDevice
and engine.static Model
newInstance(java.lang.String name, java.lang.String engineName)
Creates an empty model instance on the specifiedDevice
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 newTrainer
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 specifiedmodelPath
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 specifiedDevice
.- Parameters:
name
- the model namedevice
- 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 specifiedDevice
and engine.- Parameters:
name
- the model nameengineName
- 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 specifiedDevice
and engine.- Parameters:
name
- the model namedevice
- the device to load the model ontoengineName
- 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 themodelPath
.- Parameters:
modelPath
- the directory or file path of the model location- Throws:
java.io.IOException
- when IO operation fails in loading a resourceMalformedModelException
- 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 themodelPath
and the given name.- Parameters:
modelPath
- the directory or file path of the model locationprefix
- the model file name or path prefix- Throws:
java.io.IOException
- when IO operation fails in loading a resourceMalformedModelException
- 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 themodelPath
with the name and options provided.- Parameters:
modelPath
- the directory or file path of the model locationprefix
- the model file name or path prefixoptions
- engine specific load model options, see documentation for each engine- Throws:
java.io.IOException
- when IO operation fails in loading a resourceMalformedModelException
- if model file is corrupted
-
load
default void load(java.io.InputStream is) throws java.io.IOException, MalformedModelException
Loads the model from theInputStream
.- Parameters:
is
- theInputStream
to load the model from- Throws:
java.io.IOException
- when IO operation fails in loading a resourceMalformedModelException
- 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 theInputStream
with the options provided.- Parameters:
is
- theInputStream
to load the model fromoptions
- engine specific load model options, see documentation for each engine- Throws:
java.io.IOException
- when IO operation fails in loading a resourceMalformedModelException
- 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 specifiedmodelPath
with the name provided.- Parameters:
modelPath
- the directory or file path of the model locationnewModelName
- 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
-
setBlock
void setBlock(Block block)
Sets the block for the Model for training and inference.- Parameters:
block
- theBlock
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 propertyvalue
- the value of the property
-
newTrainer
Trainer newTrainer(TrainingConfig trainingConfig)
Creates a newTrainer
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-processingO
- 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-processingO
- the output object from postprocessing- Parameters:
translator
- the object used for pre-processing and postprocessingdevice
- 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 artifactfunction
- 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 resourcejava.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 ornull
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 ornull
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 interfacejava.lang.AutoCloseable
-
-