InterpreterApi

interface publiqueInterpreterApi
Sous-classes indirectes connues

Interface vers l'interpréteur de modèle TensorFlow Lite, hors méthodes expérimentales.

Une instance InterpreterApi encapsule un modèle TensorFlow Lite pré-entraîné, dans lequel les opérations sont exécutées pour l'inférence de modèle.

Par exemple, si un modèle prend une seule entrée et renvoie une seule sortie :

try (InterpreterApi interpreter =
     new InterpreterApi.create(file_of_a_tensorflowlite_model)) {
   interpreter.run(input, output);
 }
 

Si un modèle prend 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 prend ou produit des tenseurs de chaînes :

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 shape [] et shape[1]. Pour les sorties du tenseur 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);
 

Les ordres des entrées et des sorties sont déterminés lors de la conversion du modèle TensorFlow en modèle TensorFlowLite avec Toco, tout comme les formes par défaut des entrées.

Lorsque les entrées sont fournies sous forme de tableaux (multidimensionnels), le ou les tenseurs d'entrée correspondants seront implicitement redimensionnés en fonction de la forme de ce tableau. Lorsque les entrées sont fournies sous forme de types Buffer , aucun redimensionnement implicite n’est effectué ; l'appelant doit s'assurer que la taille de l'octet Buffer correspond à celle du tenseur correspondant, ou qu'il redimensionne d'abord le tenseur via resizeInput(int, int[]) . Les informations sur la forme et le type du tenseur 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 construite sur l'API NDK 19. Elle peut fonctionner pour les niveaux d'API Android inférieurs à 19, mais n'est pas garantie.

Classes imbriquées

classe InterprèteApi.Options Une classe d'options pour contrôler le comportement de l'interpréteur d'exécution.

Méthodes publiques

vide abstrait
allouer des Tenseurs ()
Met à jour explicitement les allocations pour tous les tenseurs, si nécessaire.
vide abstrait
fermer ()
Libérez les ressources associées à l’instance InterpreterApi .
InterpreterApi statique
créer ( fichier modelFile, options InterpreterApi.Options )
Construit une instance InterpreterApi , à l'aide du modèle et des options spécifiés.
InterpreterApi statique
créer ( ByteBuffer byteBuffer, options InterpreterApi.Options )
Construit une instance InterpreterApi , à l'aide du modèle et des options spécifiés.
abstrait entier
getInputIndex ( String opName)
Obtient l'index d'une entrée en fonction du nom d'opération de l'entrée.
Tenseur abstrait
getInputTensor (int inputIndex)
Obtient le Tensor associé à l'index d'entrée fourni.
abstrait entier
getInputTensorCount ()
Obtient le nombre de tenseurs d'entrée.
abstrait long
getLastNativeInferenceDurationNanosecondes ()
Renvoie le timing d’inférence natif.
abstrait entier
getOutputIndex ( String opName)
Obtient l'index d'une sortie en fonction du nom d'opération de la sortie.
Tenseur abstrait
getOutputTensor (int outputIndex)
Obtient le Tensor associé à l'index de sortie fourni.
abstrait entier
getOutputTensorCount ()
Obtient le nombre de Tensors de sortie.
vide abstrait
resizeInput (int idx, int[] dims, booléen strict)
Redimensionne l'entrée idx-ème du modèle natif aux dimensions données.
vide abstrait
resizeInput (int idx, int[] dims)
Redimensionne l'entrée idx-ème du modèle natif aux dimensions données.
vide abstrait
exécuter (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.
vide abstrait
runForMultipleInputsOutputs ( entrées Object[] , Map < Integer , Object > sorties)
Exécute l'inférence de modèle si le modèle prend plusieurs entrées ou renvoie plusieurs sorties.

Méthodes héritées

Méthodes publiques

public abstrait void allocateTensors ()

Met à jour explicitement les allocations pour tous les tenseurs, si nécessaire.

Cela propagera les formes et les allocations de mémoire pour les tenseurs dépendants en utilisant la ou les formes du tenseur d'entrée comme indiqué.

Remarque : Cet appel est *purement facultatif*. L'allocation du tenseur se produira automatiquement pendant l'exécution si des tenseurs d'entrée ont été redimensionnés. Cet appel est très utile pour déterminer les formes de tous les tenseurs de sortie avant d'exécuter le graphique, 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 graphiques ont des sorties de forme dynamique, auquel cas la forme de sortie peut ne pas se propager complètement tant que l'inférence n'est pas exécutée.

Jetés
IllegalStateException si les tenseurs du graphe ne pouvaient pas être alloués avec succès.

public abstrait vide fermer ()

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

public static InterpreterApi create ( Fichier modelFile, options InterpreterApi.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
fichier modèle Un fichier contenant un modèle TF Lite pré-entraîné.
choix Un ensemble d'options pour personnaliser le comportement de l'interprète.
Jetés
Exception d'argument illégal si modelFile n'encode pas un modèle TensorFlow Lite valide.

création d'InterpreterApi statique publique (options 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
octetBuffer Un 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.
choix Un ensemble d'options pour personnaliser le comportement de l'interprète.
Jetés
Exception d'argument illégal si byteBuffer n'est pas un MappedByteBuffer ni un ByteBuffer direct de nativeOrder.

public abstract int getInputIndex ( String opName)

Obtient l'index d'une entrée en fonction du nom d'opération de l'entrée.

Paramètres
NomOp
Jetés
Exception d'argument illégal si opName ne correspond à aucune entrée du modèle utilisé pour initialiser l'interpréteur.

Tensor abstrait public getInputTensor (int inputIndex)

Obtient le Tensor associé à l'index d'entrée fourni.

Paramètres
Indice d'entrée
Jetés
Exception d'argument illégal si inputIndex est négatif ou n’est pas inférieur au nombre d’entrées du modèle.

public abstrait int getInputTensorCount ()

Obtient le nombre de tenseurs d'entrée.

public abstrait Long getLastNativeInferenceDurationNanoseconds ()

Renvoie le timing d’inférence natif.

Jetés
Exception d'argument illégal si le modèle n'est pas initialisé par l'interpréteur.

public abstract int getOutputIndex ( String opName)

Obtient l'index d'une sortie en fonction du nom d'opération de la sortie.

Paramètres
NomOp
Jetés
Exception d'argument illégal si opName ne correspond à aucune sortie du modèle utilisé pour initialiser l'interpréteur.

Tensor abstrait public getOutputTensor (int outputIndex)

Obtient le Tensor associé à l'index de sortie fourni.

Remarque : Les détails du tenseur de sortie (par exemple, la forme) peuvent ne pas être entièrement renseignés avant l'exécution de l'inférence. Si vous avez besoin de détails mis à jour *avant* d'exécuter l'inférence (par exemple, après avoir redimensionné un tenseur d'entrée, ce qui peut invalider les formes du tenseur de sortie), utilisez allocateTensors() pour déclencher explicitement l'allocation et la propagation de forme. Notez que, pour les graphiques dont les formes de sortie dépendent des *valeurs* d'entrée, la forme de sortie peut ne pas être entièrement déterminée avant l'exécution de l'inférence.

Paramètres
Indice de sortie
Jetés
Exception d'argument illégal si outputIndex est négatif ou n’est pas inférieur au nombre de sorties du modèle.

public abstrait int getOutputTensorCount ()

Obtient le nombre de Tensors de sortie.

public abstract void resizeInput (int idx, int[] dims, boolean strict)

Redimensionne l'entrée idx-ème du modèle natif aux dimensions données.

Lorsque « strict » est True, seules les dimensions inconnues peuvent être redimensionnées. Les dimensions inconnues sont indiquées par « -1 » dans le tableau renvoyé par « Tensor.shapeSignature() ».

Paramètres
idx
s'assombrit
strict
Jetés
Exception d'argument illégal 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. De plus, l'erreur se produit lors de la tentative de redimensionnement d'un tenseur avec des dimensions fixes lorsque « strict » est vrai.

public abstract void resizeInput (int idx, int[] dims)

Redimensionne l'entrée idx-ème du modèle natif aux dimensions données.

Paramètres
idx
s'assombrit
Jetés
Exception d'argument illégal 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 abstract 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.

Attention : 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. Veuillez envisager d'utiliser Buffer pour alimenter et récupérer des données primitives afin de meilleures performances. Les types Buffer concrets suivants sont pris en charge :

  • ByteBuffer - compatible avec tout type Tensor primitif sous-jacent.
  • FloatBuffer - compatible avec les tenseurs float.
  • IntBuffer - compatible avec les tenseurs int32.
  • LongBuffer - compatible avec les tenseurs int64.
Notez que les types booléens ne sont pris en charge que sous forme de tableaux, pas Buffer ou d'entrées scalaires.

Paramètres
saisir un tableau ou un tableau multidimensionnel, ou un Buffer de types primitifs, notamment int, float, long et byte. Buffer est le moyen préféré pour transmettre des données d'entrée volumineuses pour les types primitifs, tandis que les types de chaîne nécessitent l'utilisation du chemin d'entrée du tableau (multidimensionnel). Lorsqu'un Buffer est utilisé, son contenu doit rester inchangé jusqu'à ce que l'inférence du modèle soit effectuée, et l'appelant doit s'assurer que le Buffer est à la position de lecture appropriée. Une valeur null autorisée que si l'appelant utilise un Delegate qui autorise l'interopérabilité des gestionnaires de tampon et qu'un tel tampon a été lié à l'entrée Tensor .
sortir un tableau multidimensionnel de données de sortie ou un Buffer de types primitifs comprenant 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 et est utile dans certains cas, par exemple si l'appelant utilise un Delegate qui autorise l'interopérabilité des gestionnaires de tampon et qu'un tel tampon a été lié au Tensor de sortie (voir aussi Interpreter.Options#setAllowBufferHandleOutput(boolean) ), ou si le graphique a des sorties de forme dynamique et que l'appelant doit interroger la forme Tensor de sortie après que l'inférence a été invoquée, en récupérant les données directement à partir du tenseur de sortie (via Tensor.asReadOnlyBuffer() ).
Jetés
Exception d'argument illégal si input est nulle ou vide, ou si une erreur se produit lors de l'exécution de l'inférence.
Exception d'argument illégal (EXPERIMENTAL, sujet à changement) si l'inférence est interrompue par setCancelled(true) .

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

Exécute l'inférence de modèle si le modèle prend plusieurs entrées ou renvoie plusieurs sorties.

Attention : L'API est plus efficace si des Buffer (de préférence directs, mais pas obligatoires) sont utilisés comme types de données d'entrée/sortie. Veuillez envisager d'utiliser Buffer pour alimenter et récupérer des données primitives afin de meilleures performances. Les types Buffer concrets suivants sont pris en charge :

  • ByteBuffer - compatible avec tout type Tensor primitif sous-jacent.
  • FloatBuffer - compatible avec les tenseurs float.
  • IntBuffer - compatible avec les tenseurs int32.
  • LongBuffer - compatible avec les tenseurs int64.
Notez que les types booléens ne sont pris en charge que sous forme de tableaux, pas de Buffer ou d'entrées scalaires.

Remarque : les valeurs null pour les éléments individuels des inputs et outputs ne sont autorisées que si l'appelant utilise un Delegate qui autorise l'interopérabilité des gestionnaires de tampon et qu'un tel tampon a été lié au(x) Tensor (s) d'entrée ou de sortie correspondant(s).

Paramètres
contributions 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 ou un tableau multidimensionnel, ou un Buffer de types primitifs, notamment int, float, long et byte. Buffer est le moyen préféré pour transmettre des données d'entrée volumineuses, tandis que les types de chaîne nécessitent l'utilisation du chemin d'entrée du tableau (multidimensionnel). Lorsque Buffer est utilisé, son contenu doit rester inchangé jusqu'à ce que l'inférence du modèle soit effectuée, et l'appelant doit s'assurer que le Buffer est à la position de lecture appropriée.
les sorties une carte mappant les indices de sortie à des tableaux multidimensionnels de données de sortie ou Buffer de types primitifs, notamment 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ù des descripteurs de tampon sont utilisés pour les données du tenseur de sortie, ou dans les cas où les sorties sont façonnées dynamiquement et 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 tenseur de sortie ( via Tensor.asReadOnlyBuffer() ).
Jetés
Exception d'argument illégal si inputs sont nulles ou vides, si outputs sont nulles ou si une erreur se produit lors de l'exécution de l'inférence.