Classe de pilote permettant de piloter l'inférence de modèle avec TensorFlow Lite.
Remarque: Si vous n'avez pas besoin d'accéder à l'une des fonctionnalités "expérimentales" de l'API ci-dessous, préférez utiliser InterpréterApi et InternerFactory plutôt que d'utiliser directement Interpréteur.
Un Interpreter
encapsule un modèle TensorFlow Lite pré-entraîné dans lequel des opérations sont exécutées pour l'inférence de modèle.
Par exemple, si un modèle n'accepte qu'une seule entrée et ne renvoie qu'un seul résultat :
try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
interpreter.run(input, output);
}
Si un modèle accepte plusieurs entrées ou sorties :
Object[] inputs = {input0, input1, ...};
Map<Integer, Object> map_of_indices_to_outputs = new HashMap<>();
FloatBuffer ith_output = FloatBuffer.allocateDirect(3 * 2 * 4); // Float tensor, shape 3x2x4.
ith_output.order(ByteOrder.nativeOrder());
map_of_indices_to_outputs.put(i, ith_output);
try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
interpreter.runForMultipleInputsOutputs(inputs, map_of_indices_to_outputs);
}
Si un modèle accepte ou produit des Tensors de chaîne :
String[] input = {"foo", "bar"}; // Input tensor shape is [2].
String[][] output = new String[3][2]; // Output tensor shape is [3, 2].
try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
interpreter.runForMultipleInputsOutputs(input, output);
}
Notez qu'il existe une distinction entre la forme [] et la forme[1]. Pour les sorties du Tensor de chaîne scalaire :
String[] input = {"foo"}; // Input tensor shape is [1].
ByteBuffer outputBuffer = ByteBuffer.allocate(OUTPUT_BYTES_SIZE); // Output tensor shape is [].
try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
interpreter.runForMultipleInputsOutputs(input, outputBuffer);
}
byte[] outputBytes = new byte[outputBuffer.remaining()];
outputBuffer.get(outputBytes);
// Below, the `charset` can be StandardCharsets.UTF_8.
String output = new String(outputBytes, charset);
L'ordre des entrées et des sorties est déterminé lors de la conversion du modèle TensorFlow en modèle TensorFlowLite avec Toco, de même que les formes par défaut des entrées.
Lorsque les entrées sont fournies sous forme de tableaux (multidimensionnels), le ou les Tensors d'entrée correspondants sont implicitement redimensionnés en fonction de la forme du tableau. Lorsque les entrées sont fournies en tant que types Buffer
, aucun redimensionnement implicite n'est effectué. L'appelant doit s'assurer que la taille en octets de Buffer
correspond à celle du Tensor correspondant, ou qu'il doit d'abord redimensionner le Tensor via resizeInput(int, int[])
. Les informations sur la forme et le type de Tensor peuvent être obtenues via la classe Tensor
, disponible via getInputTensor(int)
et getOutputTensor(int)
.
AVERTISSEMENT:Les instances Interpreter
ne sont pas thread-safe. Un Interpreter
possède des ressources qui doivent être explicitement libérées en appelant close()
.
La bibliothèque TFLite est conçue avec l'API NDK 19. Cela peut fonctionner pour les niveaux d'API Android inférieurs à 19, mais n'est pas garanti.
Classes imbriquées
classe | Interpreter.Options | Classe d'options permettant de contrôler le comportement de l'interpréteur au moment de l'exécution. |
Constructeurs publics
Interpréteur(options Fichier modelFile et Interpreter.Options)
Initialise un
Interpreter et spécifie des options de personnalisation du comportement de l'interpréteur. |
|
Interpréteur(ByteBuffer byteBuffer)
Initialise un
Interpreter avec le ByteBuffer d'un fichier de modèle. |
|
Interpréteur(options ByteBuffer byteBuffer, Interpreter.Options)
Initialise un
Interpreter avec l'élément ByteBuffer d'un fichier de modèle et un ensemble d'éléments Interpreter.Options personnalisés. |
Méthodes publiques
void |
allocateTensors()
Met à jour explicitement les allocations pour tous les Tensors, si nécessaire.
|
void |
close()
Libérez les ressources associées à l'instance
InterpreterApi . |
int |
getInputIndex(String opName)
Récupère l'index d'une entrée en fonction du nom d'opération de l'entrée.
|
Tensor |
getInputTensor(int inputIndex)
Récupère le Tensor associé à l'index d'entrée fourni.
|
int |
getInputTensorCount()
Récupère le nombre de Tensors d'entrée.
|
Tensor |
getInputTensorFromSignature(String inputName, String signatureKey)
Récupère le Tensor associé au nom d'entrée et au nom de la méthode de signature fournis.
|
Long |
getLastNativeInferenceDurationNanoseconds()
Renvoie le temps d'inférence natif.
|
int |
getOutputIndex(String opName)
Récupère l'index d'une sortie en fonction du nom d'opération de la sortie.
|
Tensor |
getOutputTensor(int outputIndex)
Récupère le Tensor associé à l'index de sortie fourni.
|
int |
getOutputTensorCount()
Récupère le nombre de Tensors de sortie.
|
Tensor |
getOutputTensorFromSignature(String outputName, String signatureKey)
Récupère le Tensor associé au nom de sortie fourni dans une méthode de signature spécifique.
|
Chaîne[] |
getSignatureInputs(String signatureKey)
Récupère la liste des entrées SignatureDefs pour la méthode
signatureKey . |
Chaîne[] |
getSignatureKeys()
Récupère la liste des noms de méthodes exportées SignatureDef disponibles dans le modèle.
|
Chaîne[] |
getSignatureOutputs(String signatureKey)
Récupère la liste des sorties SignatureDefs pour la méthode
signatureKey . |
void |
resetVariableTensors()
Avancé: rétablit la valeur par défaut de tous les Tensors variables.
|
void |
resizeInput(int idx, int[] dims, boolean strict)
Redimensionne idx-ième entrée du modèle natif en fonction des dimensions données.
|
void |
resizeInput(int idx, int[] diminue)
Redimensionne idx-ième entrée du modèle natif en fonction des dimensions données.
|
void | |
void |
runForMultipleInputsOutputs(entrées Object[], Map<Integer, Sorties Object>)
Exécute l'inférence de modèle si le modèle reçoit plusieurs entrées ou renvoie plusieurs sorties.
|
void |
runSignature(Map<Chaîne, entrées Objet>, Carte<Chaîne, Sorties d'Objet>)
Identique à
runSignature(Map, Map, String) , mais ne nécessite pas de transmettre de signatureKey, en supposant que le modèle possède un élément SignatureDef. |
void | |
void |
setCancelled(valeur booléenne annulée)
Avancé: interrompt l'inférence au milieu d'un appel à
run(Object, Object) . |
Méthodes héritées
Constructeurs publics
public Interprète (Fichier modelFile)
Initialise un Interpreter
.
Paramètres
modelFile | un fichier d'un modèle TF Lite pré-entraîné. |
---|
Génère
IllegalArgumentException | Si modelFile n'encode pas de modèle TensorFlow Lite valide.
|
---|
public Interprète (options Fichier modelFile, Interpreter.Options)
Initialise un Interpreter
et spécifie des options de personnalisation du comportement de l'interpréteur.
Paramètres
modelFile | un fichier d'un modèle TF Lite pré-entraîné |
---|---|
options | Un ensemble d'options permettant de personnaliser le comportement de l'interprète |
Génère
IllegalArgumentException | Si modelFile n'encode pas de modèle TensorFlow Lite valide.
|
---|
public Interprète (ByteBuffer byteBuffer)
Initialise un Interpreter
avec le ByteBuffer
d'un fichier de modèle.
Le ByteBuffer ne doit pas être modifié après la construction d'un Interpreter
. Le ByteBuffer
peut être soit un MappedByteBuffer
qui mappe en mémoire un fichier de modèle, soit un ByteBuffer
direct de nativeOrder() qui contient le contenu en octets d'un modèle.
Paramètres
byteBuffer |
---|
Génère
IllegalArgumentException | si byteBuffer n'est pas une MappedByteBuffer ni une ByteBuffer directe de nativeOrder.
|
---|
public Interprète (options ByteBuffer byteBuffer, Interpreter.Options)
Initialise un Interpreter
avec l'élément ByteBuffer
d'un fichier de modèle et un ensemble d'éléments Interpreter.Options
personnalisés.
Le ByteBuffer
ne doit pas être modifié après la construction d'un Interpreter
. Le ByteBuffer
peut être soit un MappedByteBuffer
qui mappe en mémoire un fichier de modèle, soit un ByteBuffer
direct de nativeOrder() qui contient le contenu en octets d'un modèle.
Paramètres
byteBuffer | |
---|---|
options |
Génère
IllegalArgumentException | si byteBuffer n'est pas une MappedByteBuffer ni une ByteBuffer directe de nativeOrder.
|
---|
Méthodes publiques
public vide allocateTensors ()
Met à jour explicitement les allocations pour tous les Tensors, si nécessaire.
Cette opération propage les formes et les allocations de mémoire pour les Tensors dépendants à l'aide de la ou des formes de Tensor d'entrée fournies.
Remarque: Cet appel est *purement facultatif*. L'allocation de Tensors se fait automatiquement lors de l'exécution si des Tensors d'entrée ont été redimensionnés. Cet appel est particulièrement utile pour déterminer les formes des Tensors de sortie avant d'exécuter le graphe, par exemple
interpreter.resizeInput(0, new int[]{1, 4, 4, 3}));
interpreter.allocateTensors();
FloatBuffer input = FloatBuffer.allocate(interpreter.getInputTensor(0).numElements());
// Populate inputs...
FloatBuffer output = FloatBuffer.allocate(interpreter.getOutputTensor(0).numElements());
interpreter.run(input, output)
// Process outputs...
Remarque: Certains graphes ont des sorties de forme dynamique. Dans ce cas, la forme de sortie peut ne pas se propager complètement tant que l'inférence n'est pas exécutée.
public void close ()
Libérez les ressources associées à l'instance InterpreterApi
.
public int getInputIndex (String opName)
Récupère l'index d'une entrée en fonction du nom d'opération de l'entrée.
Paramètres
opName |
---|
public Tensor getInputTensor (int inputIndex)
Récupère le Tensor associé à l'index d'entrée fourni.
Paramètres
inputIndex |
---|
public int getInputTensorCount ()
Récupère le nombre de Tensors d'entrée.
public Tensor getInputTensorFromSignature (String inputName, String signatureKey)
Récupère le Tensor associé au nom d'entrée et au nom de la méthode de signature fournis.
AVERTISSEMENT: Cette API est expérimentale et susceptible d'être modifiée.
Paramètres
inputName | Saisissez le nom dans la signature. |
---|---|
signatureKey | La clé de signature identifiant la SignatureDef peut être nulle si le modèle possède une seule signature. |
Génère
IllegalArgumentException | si inputName ou signatureKey est nul ou vide, ou si un nom non valide a été fourni.
|
---|
public int getOutputIndex (String opName)
Récupère l'index d'une sortie en fonction du nom d'opération de la sortie.
Paramètres
opName |
---|
public Tensor getOutputTensor (int outputIndex)
Récupère le Tensor associé à l'index de sortie fourni.
Remarque: Il est possible que les détails du Tensor de sortie (par exemple, la forme) ne soient entièrement renseignés qu'après l'exécution de l'inférence. Si vous avez besoin de mettre à jour les détails *avant* d'exécuter l'inférence (par exemple, après avoir redimensionné un Tensor d'entrée, ce qui peut invalider les formes de Tensor de sortie), utilisez allocateTensors()
pour déclencher explicitement l'allocation et la propagation des formes. Notez que, pour les graphiques dont les formes de sortie dépendent des *valeurs* d'entrée, il est possible que la forme de sortie ne soit pas entièrement déterminée avant l'exécution de l'inférence.
Paramètres
outputIndex |
---|
public int getOutputTensorCount ()
Récupère le nombre de Tensors de sortie.
public Tensor getOutputTensorFromSignature (String outputName, String signatureKey)
Récupère le Tensor associé au nom de sortie fourni dans une méthode de signature spécifique.
Remarque: Il est possible que les détails du Tensor de sortie (par exemple, la forme) ne soient entièrement renseignés qu'après l'exécution de l'inférence. Si vous avez besoin de mettre à jour les détails *avant* d'exécuter l'inférence (par exemple, après avoir redimensionné un Tensor d'entrée, ce qui peut invalider les formes de Tensor de sortie), utilisez allocateTensors()
pour déclencher explicitement l'allocation et la propagation des formes. Notez que, pour les graphiques dont les formes de sortie dépendent des *valeurs* d'entrée, il est possible que la forme de sortie ne soit pas entièrement déterminée avant l'exécution de l'inférence.
AVERTISSEMENT: Cette API est expérimentale et susceptible d'être modifiée.
Paramètres
outputName | Nom de sortie dans la signature. |
---|---|
signatureKey | La clé de signature identifiant la SignatureDef peut être nulle si le modèle possède une seule signature. |
Génère
IllegalArgumentException | si outputName ou signatureKey est nul ou vide, ou si un nom non valide a été fourni.
|
---|
public String[] getSignatureInputs (String signatureKey)
Récupère la liste des entrées SignatureDefs pour la méthode signatureKey
.
AVERTISSEMENT: Cette API est expérimentale et susceptible d'être modifiée.
Paramètres
signatureKey |
---|
public String[] getSignatureKeys ()
Récupère la liste des noms de méthodes exportées SignatureDef disponibles dans le modèle.
AVERTISSEMENT: Cette API est expérimentale et susceptible d'être modifiée.
public String[] getSignatureOutputs (String signatureKey)
Récupère la liste des sorties SignatureDefs pour la méthode signatureKey
.
AVERTISSEMENT: Cette API est expérimentale et susceptible d'être modifiée.
Paramètres
signatureKey |
---|
public void resetVariableTensors ()
Avancé: rétablit la valeur par défaut de tous les Tensors variables.
Si un Tensor variable n'est associé à aucun tampon, il sera réinitialisé.
AVERTISSEMENT: Cette API est expérimentale et susceptible d'être modifiée.
public vide resizeInput (int idx, int[] dims, boolean strict)
Redimensionne idx-ième entrée du modèle natif en fonction des dimensions données.
Lorsque l'attribut "strict" est défini sur "True", seules des dimensions inconnues peuvent être redimensionnées. Les dimensions inconnues sont indiquées par "-1" dans le tableau renvoyé par Tensor.shapeSignature().
Paramètres
idx | |
---|---|
dims | |
strict |
public void resizeInput (int idx, int[] dims)
Redimensionne idx-ième entrée du modèle natif en fonction des dimensions données.
Paramètres
idx | |
---|---|
dims |
public void run (entrée objet, sortie objet)
Exécute l'inférence de modèle si le modèle n'accepte qu'une seule entrée et ne fournit qu'une seule sortie.
Avertissement: L'API est plus efficace si un Buffer
(de préférence direct, mais pas obligatoire) est utilisé comme type de données d'entrée/sortie. Nous vous conseillons d'utiliser Buffer
pour alimenter et récupérer les données primitives, et améliorer ainsi les performances. Les types Buffer
concrets suivants sont acceptés:
ByteBuffer
: compatible avec n'importe quel type de Tensor primitif sous-jacent.FloatBuffer
: compatible avec les Tensors flottants.IntBuffer
: compatible avec les Tensors int32.LongBuffer
: compatible avec les Tensors int64.
Buffer
) ou en tant qu'entrées scalaires.Paramètres
entrée | un tableau, un tableau multidimensionnel ou un Buffer de types primitifs, y compris "int", "float", "long" et "byte". Buffer est le moyen privilégié pour transmettre de grandes quantités de données d'entrée pour les types primitifs, tandis que les types de chaîne nécessitent l'utilisation du chemin d'entrée d'un tableau (multidimensionnel). Lorsqu'un Buffer est utilisé, son contenu doit rester inchangé jusqu'à la fin de l'inférence de modèle, et l'appelant doit s'assurer que Buffer se trouve à la position de lecture appropriée. Une valeur null n'est autorisée que si l'appelant utilise un Delegate qui permet l'interopérabilité de la poignée de tampon, et que ce tampon a été lié à la Tensor d'entrée. |
---|---|
sortie | un tableau multidimensionnel de données de sortie, ou un Buffer de types primitifs, y compris int, float, long et byte. Lorsqu'un Buffer est utilisé, l'appelant doit s'assurer qu'il est défini sur la position d'écriture appropriée. Une valeur nulle est autorisée. Elle est utile dans certains cas, par exemple si l'appelant utilise un Delegate qui permet l'interopérabilité de la poignée de tampon et que ce tampon a été lié à la Tensor de sortie (voir également Interpreter.Options#setAllowBufferHandleOutput(boolean)), ou si le graphique présente des sorties de manière dynamique et que l'appelant doit interroger la sortie du Tensor de sortie une fois l'inférence appelée Tensor (via le Tensor de sortie).Tensor.asReadOnlyBuffer() |
public void runForMultipleInputsOutputs (entrées Object[], Map<Entier, Objets> sorties)
Exécute l'inférence de modèle si le modèle reçoit plusieurs entrées ou renvoie plusieurs sorties.
Avertissement: L'API est plus efficace si des Buffer
(de préférence directs, mais non obligatoires) sont utilisés comme types de données d'entrée/sortie. Nous vous conseillons d'utiliser Buffer
pour alimenter et récupérer les données primitives, et améliorer ainsi les performances. Les types Buffer
concrets suivants sont acceptés:
ByteBuffer
: compatible avec n'importe quel type de Tensor primitif sous-jacent.FloatBuffer
: compatible avec les Tensors flottants.IntBuffer
: compatible avec les Tensors int32.LongBuffer
: compatible avec les Tensors int64.
Buffer
) ou en tant qu'entrées scalaires.
Remarque: Les valeurs null
pour les éléments individuels de inputs
et outputs
ne sont autorisées que si l'appelant utilise un Delegate
qui permet l'interopérabilité de la poignée de tampon, et que ce tampon a été lié aux Tensor
(s) d'entrée ou de sortie correspondants.
Paramètres
cachées | un tableau de données d'entrée. Les entrées doivent être dans le même ordre que les entrées du modèle. Chaque entrée peut être un tableau, un tableau multidimensionnel ou un Buffer de types primitifs, y compris int, float, long et byte. Buffer est le moyen privilégié pour transmettre des données d'entrée volumineuses, tandis que les types de chaînes nécessitent l'utilisation du chemin d'entrée du tableau (multidimensionnel). Lorsque Buffer est utilisé, son contenu doit rester inchangé jusqu'à la fin de l'inférence de modèle, et l'appelant doit s'assurer que Buffer se trouve à la position de lecture appropriée. |
---|---|
sorties | une map mappant les index de sortie à des tableaux multidimensionnels de données de sortie ou à des Buffer de types primitifs, y compris int, float, long et byte. Il lui suffit de conserver les entrées pour les sorties à utiliser. Lorsqu'un Buffer est utilisé, l'appelant doit s'assurer qu'il est défini sur la position d'écriture appropriée. La carte peut être vide dans les cas où l'une ou l'autre des poignées de tampon sont utilisées pour les données de Tensor de sortie, ou lorsque les sorties sont mises en forme dynamiquement et que l'appelant doit interroger la forme Tensor de sortie après l'appel de l'inférence, en récupérant les données directement à partir du Tensor de sortie (via Tensor.asReadOnlyBuffer() ). |
public void runSignature (Map<String, Object> entrées, Map<Chaîne, Objet>)
Identique à runSignature(Map, Map, String)
, mais ne nécessite pas de transmettre de signatureKey, en supposant que le modèle possède un élément SignatureDef. Si le modèle comporte plusieurs SignatureDef, il génère une exception.
AVERTISSEMENT: Cette API est expérimentale et susceptible d'être modifiée.
Paramètres
cachées | |
---|---|
sorties |
public void runSignature (Map<String, Object> entrées, Map<String, Objet>, String signatureKey)
Exécute l'inférence de modèle basée sur SignatureDef fournie via signatureKey
.
Consultez run(Object, Object)
pour en savoir plus sur les types de données d'entrée et de sortie autorisés.
AVERTISSEMENT: Cette API est expérimentale et susceptible d'être modifiée.
Paramètres
cachées | Mappage entre un nom d'entrée dans SignatureDef et un objet d'entrée. |
---|---|
sorties | Mappage entre le nom de la sortie dans SignatureDef et les données de sortie. Ce champ peut être vide si l'appelant souhaite interroger les données Tensor directement après l'inférence (par exemple, si la forme de sortie est dynamique ou si des poignées de tampon de sortie sont utilisées). |
signatureKey | Clé de signature identifiant le SignatureDef. |
Génère
IllegalArgumentException | si inputs est nul ou vide, si outputs ou signatureKey est nul, ou si une erreur se produit lors de l'exécution de l'inférence.
|
---|
public void setCancelled (boolean cancelled)
Avancé: interrompt l'inférence au milieu d'un appel à run(Object, Object)
.
Un indicateur d'annulation est défini sur "true" lorsque cette fonction est appelée. L'interpréteur vérifie l'indicateur entre les appels d'opérations. S'il a la valeur true
, il arrête l'exécution. L'interpréteur restera à l'état "Annulé" jusqu'à ce qu'il soit explicitement "annulé" par setCancelled(false)
.
AVERTISSEMENT: Cette API est expérimentale et susceptible d'être modifiée.
Paramètres
annulé | true pour annuler l'inférence de la manière la plus optimale possible ; false pour la reprendre. |
---|
Génère
IllegalStateException | si l'interpréteur n'est pas initialisé avec l'option annulable, qui est désactivée par défaut. |
---|