Interpreter

public final class Interprète

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ète(fichier modelFile)
Initialise un Interpreter.
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
run(entrée d'objet, sortie d'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.
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
runSignature(Map<String, Object> entrées, Map<String, Object> sorties, String signatureKey)
Exécute l'inférence de modèle basée sur SignatureDef fournie via signatureKey.
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 Long getLastNativeInferenceDurationNanoseconds ()

Renvoie le temps d'inférence natif.

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.
Notez que les types booléens ne sont acceptés qu'en tant que tableaux (et non en tant que 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.
Notez que les types booléens ne sont acceptés qu'en tant que tableaux (et non en tant que 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.
Voir également