ai.djl.nn.transformer

Class TransformerBaseBlock

java.lang.Object

ai.djl.nn.AbstractBlock

ai.djl.nn.transformer.TransformerBaseBlock

All Implemented Interfaces:

Block

Direct Known Subclasses:

ScaledDotProductAttentionBlock

public abstract class TransformerBaseBlock
extends AbstractBlock

Utility base class for implementing custom blocks. Provides utilities to handle nested child blocks, parameters and serialization of state.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.LinkedHashMap<java.lang.String,Block>	children All direct children of this Block.
protected java.util.LinkedHashMap<java.lang.String,Parameter>	parameters All direct parameters of this Block.
protected java.util.LinkedHashMap<java.lang.String,java.util.function.Function<Shape[],Shape>>	parameterShapeCallbacks Callbacks to determine the shape of a parameter.
protected int	version The model version of this block, used for checking if parameters are still valid during parameter loading.

Fields inherited from class ai.djl.nn.AbstractBlock

inputNames, inputShapes

Constructor Summary

Constructors

Constructor and Description
TransformerBaseBlock(int version) Builds an empty block with the given version for parameter serialization.

Method Summary

Modifier and Type	Method and Description
protected <B extends Block> B	addChildBlock(java.lang.String name, B block) Adds a child block to this block.
protected <P extends Parameter> P	addParameter(P parameter) Adds a parameter to this block.
protected <P extends Parameter> P	addParameter(P parameter, java.util.function.Function<Shape[],Shape> shapeCallback) Adds a parameter to this block.
protected <P extends Parameter> P	addParameter(P parameter, Shape shape) Adds a parameter to this block.
BlockList	getChildren() Returns a list of all the children of the block.
java.util.List<Parameter>	getDirectParameters() Returns a list of all the direct parameters of the block.
Shape	getParameterShape(java.lang.String name, Shape[] inputShapes) Returns the shape of the specified direct parameter of this block given the shapes of the input to the block.
int	getVersion() Returns the version number to be used for parameter serialization.
Shape[]	initialize(NDManager manager, DataType dataType, Shape... inputShapes) Initializes the parameters of the block.
abstract void	initializeChildBlocks(NDManager manager, DataType dataType, Shape... inputShapes) Initializes the Child blocks of this block.
void	loadParameters(NDManager manager, java.io.DataInputStream is) Loads the parameters from the given input stream.
void	saveParameters(java.io.DataOutputStream os) Writes the parameters of the block to the given outputStream.

Methods inherited from class ai.djl.nn.AbstractBlock

beforeInitialize, cast, clear, describeInput, getParameters, isInitialized, readInputShapes, saveInputShapes, setInitializer, setInitializer

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface ai.djl.nn.Block

forward, forward, getOutputShapes, validateLayout

Field Detail

version

protected int version

The model version of this block, used for checking if parameters are still valid during parameter loading.

children

protected java.util.LinkedHashMap<java.lang.String,Block> children

All direct children of this Block. Keys are names of the blocks. Use the addChildBlock(String, Block) method to add children. All children in this map are automagically loaded / saved.

parameters

protected java.util.LinkedHashMap<java.lang.String,Parameter> parameters

All direct parameters of this Block. Keys are name of the parameters. Use the addParameter(Parameter) method to add children. All parameters in this map are automagically loaded / saved.

parameterShapeCallbacks

protected java.util.LinkedHashMap<java.lang.String,java.util.function.Function<Shape[],Shape>> parameterShapeCallbacks

Callbacks to determine the shape of a parameter. Values may be null in which case extending classes need to override Block.getParameterShape(String, Shape[]) and implement parameter shape resolution manually.

Constructor Detail

TransformerBaseBlock

public TransformerBaseBlock(int version)

Builds an empty block with the given version for parameter serialization.

Parameters:

version - the version to use for parameter serialization.

Method Detail

getVersion

public int getVersion()

Returns the version number to be used for parameter serialization.

Returns:

the version number to be used for parameter serialization

addChildBlock

protected <B extends Block> B addChildBlock(java.lang.String name,
                                            B block)

Adds a child block to this block.

Type Parameters:

B - The type of block

Parameters:

name - Name of the block, must be unique or otherwise existing children with this name are removed, must not be null.

block - The block, must not be null.

Returns:

the block given as a parameter - that way the block can be created and reassigned to a member variable more easily.

addParameter

protected <P extends Parameter> P addParameter(P parameter)

Adds a parameter to this block. If parameters are added with this method, subclasses need to override Block.getParameterShape(String, Shape[]) and return the shapes of parameters themselves.

Type Parameters:

P - the specific parameter subclass

Parameters:

parameter - the parameter to add, not null

Returns:

the parameter passed as arguments to make it easier to create and assign paramters in one line

addParameter

protected <P extends Parameter> P addParameter(P parameter,
                                               Shape shape)

Adds a parameter to this block. If parameters are added with this method, intialization of the parameter works out of the box

Type Parameters:

P - the specific parameter subclass

Parameters:

parameter - the parameter to add, not null

shape - the shape of the parameter

Returns:

the parameter passed as arguments to make it easier to create and assign paramters in one line

addParameter

protected <P extends Parameter> P addParameter(P parameter,
                                               java.util.function.Function<Shape[],Shape> shapeCallback)

Adds a parameter to this block. If parameters are added with this method, intialization of the parameter works out of the box

Type Parameters:

P - the specific parameter subclass

Parameters:

parameter - the parameter to add, not null

shapeCallback - the method to call once the input shape of this block is known to determine the shape of the given parameter

Returns:

the parameter passed as arguments to make it easier to create and assign parameters in one line

getParameterShape

public Shape getParameterShape(java.lang.String name,
                               Shape[] inputShapes)

Description copied from interface: Block

Returns the shape of the specified direct parameter of this block given the shapes of the input to the block.

Parameters:

name - the name of the parameter

inputShapes - the shapes of the input to the block

Returns:

the shape of the parameter specified

getChildren

public BlockList getChildren()

Description copied from interface: Block

Returns a list of all the children of the block.

Returns:

the list of child blocks

initialize

public Shape[] initialize(NDManager manager,
                          DataType dataType,
                          Shape... inputShapes)

Initializes the parameters of the block. This method must be called before calling `forward`.

Parameters:

manager - the NDManager to initialize the parameters

dataType - the datatype of the parameters

inputShapes - the shapes of the inputs to the block

Returns:

the shapes of the outputs of the block

initializeChildBlocks

public abstract void initializeChildBlocks(NDManager manager,
                                           DataType dataType,
                                           Shape... inputShapes)

Initializes the Child blocks of this block.

Parameters:

manager - the manager to use for initialization

dataType - the requested data type

inputShapes - the expected input shapes

getDirectParameters

public java.util.List<Parameter> getDirectParameters()

Description copied from interface: Block

Returns a list of all the direct parameters of the block.

Returns:

the list of Parameter

saveParameters

public void saveParameters(java.io.DataOutputStream os)
                    throws java.io.IOException

Description copied from interface: Block

Writes the parameters of the block to the given outputStream.

Parameters:

os - the outputstream to save the parameters to

Throws:

java.io.IOException - if an I/O error occurs

loadParameters

public void loadParameters(NDManager manager,
                           java.io.DataInputStream is)
                    throws java.io.IOException,
                           MalformedModelException

Description copied from interface: Block

Loads the parameters from the given input stream.

Parameters:

manager - an NDManager to create the parameter arrays

is - the inputstream that stream the parameter values

Throws:

java.io.IOException - if an I/O error occurs

MalformedModelException - if the model file is corrupted or unsupported