InterpreterApi

interface publique InterpreterApi
Sous-classes indirectes connues

Interface de l'interpréteur de modèles TensorFlow Lite, à l'exclusion des méthodes expérimentales.

Une instance InterpreterApi 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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 InterpreterApi ne sont pas thread-safe.

AVERTISSEMENT:Une instance InterpreterApi 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 InterpreterApi.Options Classe d'options permettant de contrôler le comportement de l'interpréteur au moment de l'exécution. 

Méthodes publiques

abstrait vide
allocateTensors()
Met à jour explicitement les allocations pour tous les Tensors, si nécessaire.
abstrait vide
close()
Libérez les ressources associées à l'instance InterpreterApi.
statique InterpreterApi
create(File modelFile, InterpreterApi.Options)
Construit une instance InterpreterApi à l'aide du modèle et des options spécifiés.
statique InterpreterApi
create(options ByteBuffer byteBuffer, InterpreterApi.Options)
Construit une instance InterpreterApi à l'aide du modèle et des options spécifiés.
abstrait entier
getInputIndex(String opName)
Récupère l'index d'une entrée en fonction du nom d'opération de l'entrée.
abstrait Tensor
getInputTensor(int inputIndex)
Récupère le Tensor associé à l'index d'entrée fourni.
abstrait entier
getInputTensorCount()
Récupère le nombre de Tensors d'entrée.
abstrait Long
getLastNativeInferenceDurationNanoseconds()
Renvoie le temps d'inférence natif.
abstrait entier
getOutputIndex(String opName)
Récupère l'index d'une sortie en fonction du nom d'opération de la sortie.
abstrait Tensor
getOutputTensor(int outputIndex)
Récupère le Tensor associé à l'index de sortie fourni.
abstrait entier
getOutputTensorCount()
Récupère le nombre de Tensors de sortie.
abstrait vide
resizeInput(int idx, int[] dims, boolean strict)
Redimensionne idx-ième entrée du modèle natif en fonction des dimensions données.
abstrait vide
resizeInput(int idx, int[] diminue)
Redimensionne idx-ième entrée du modèle natif en fonction des dimensions données.
abstrait vide
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.
abstrait vide
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.

Méthodes héritées

Méthodes publiques

public abstrait 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.

Génère
IllegalStateException si les Tensors du graphe n'ont pas pu être alloués.

public abstrait vide close ()

Libérez les ressources associées à l'instance InterpreterApi.

public statique InterpreterApi create (File modelFile, InterpreterApi.Options options)

Construit une instance InterpreterApi à l'aide du modèle et des options spécifiés. Le modèle sera chargé à partir d'un fichier.

Paramètres
modelFile Fichier contenant un modèle TF Lite pré-entraîné.
options Ensemble d'options permettant de personnaliser le comportement de l'interpréteur.
Génère
IllegalArgumentException Si modelFile n'encode pas de modèle TensorFlow Lite valide.

public statique InterpreterApi create (ByteBuffer byteBuffer, InterpreterApi.Options)

Construit une instance InterpreterApi à l'aide du modèle et des options spécifiés. Le modèle sera lu à partir d'un ByteBuffer.

Paramètres
byteBuffer Modèle TF Lite pré-entraîné, sous forme sérialisée binaire. Le ByteBuffer ne doit pas être modifié après la construction d'une instance InterpreterApi. 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.
options Ensemble d'options permettant de personnaliser le comportement de l'interpréteur.
Génère
IllegalArgumentException si byteBuffer n'est pas une MappedByteBuffer ni une ByteBuffer directe de nativeOrder.

public abstract 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
Génère
IllegalArgumentException Si opName ne correspond à aucune entrée du modèle utilisé pour initialiser l'interpréteur.

public abstrait Tensor getInputTensor (int inputIndex)

Récupère le Tensor associé à l'index d'entrée fourni.

Paramètres
inputIndex
Génère
IllegalArgumentException Si la valeur de inputIndex est négative ou n'est pas inférieure au nombre d'entrées du modèle.

public abstrait int getInputTensorCount ()

Récupère le nombre de Tensors d'entrée.

public abstrait Long getLastNativeInferenceDurationNanoseconds ()

Renvoie le temps d'inférence natif.

Génère
IllegalArgumentException si le modèle n'est pas initialisé par l'interpréteur.

public abstract 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
Génère
IllegalArgumentException Si opName ne correspond à aucune sortie du modèle utilisé pour initialiser l'interpréteur.

public abstrait 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
Génère
IllegalArgumentException Si outputIndex est négatif ou n'est pas inférieur au nombre de sorties du modèle.

public abstrait int getOutputTensorCount ()

Récupère le nombre de Tensors de sortie.

public abstrait 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
Génère
IllegalArgumentException si idx est négatif ou n'est pas inférieur au nombre d'entrées du modèle, ou si une erreur se produit lors du redimensionnement de l'entrée "idx-th". En outre, cette erreur se produit lorsque vous tentez de redimensionner un Tensor avec des dimensions fixes lorsque "strict" est défini sur "True".

public abstrait vide 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
Génère
IllegalArgumentException si idx est négatif ou n'est pas inférieur au nombre d'entrées du modèle, ou si une erreur se produit lors du redimensionnement de l'entrée "idx-th".

public abstrait vide 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()
Génère
IllegalArgumentException si input est nul ou vide, ou si une erreur se produit lors de l'exécution de l'inférence.
IllegalArgumentException (EXPÉRIMENTAL, susceptible d'être modifié) si l'inférence est interrompue par setCancelled(true).

public abstract void runForMultipleInputsOutputs (entrées Object[], Map<Entier, Objet>)

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()).
Génère
IllegalArgumentException si inputs est nul ou vide, si outputs est nul, ou si une erreur se produit lors de l'exécution de l'inférence.