Classe de pilote pour 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 InterpreterApi et InterpreterFactory plutôt que d'utiliser directement Interpreter.
Un Interpreter
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 ne prend qu'une seule entrée et ne renvoie qu'une seule sortie :
try (Interpreter interpreter = new Interpreter(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 (Interpreter interpreter = new Interpreter(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 (Interpreter interpreter = new Interpreter(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 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 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ète.Options | Une classe d'options pour contrôler le comportement de l'interpréteur d'exécution. |
Constructeurs Publics
Interprète (options Fichier modèleFichier, Interprète.Options ) Initialise un Interpreter et spécifie les options de personnalisation du comportement de l'interpréteur. | |
Interpréteur ( ByteBuffer byteBuffer) Initialise un Interpreter avec un ByteBuffer d'un fichier modèle. | |
Interpréteur ( ByteBuffer byteBuffer, options Interpreter.Options ) Initialise un Interpreter avec un ByteBuffer d'un fichier modèle et un ensemble d' Interpreter.Options personnalisés. |
Méthodes publiques
vide | allouer des Tenseurs () Met à jour explicitement les allocations pour tous les tenseurs, si nécessaire. |
vide | fermer () Libérez les ressources associées à l’instance InterpreterApi . |
int | getInputIndex ( String opName) Obtient l'index d'une entrée en fonction du nom d'opération de l'entrée. |
Tenseur | getInputTensor (int inputIndex) Obtient le Tensor associé à l'index d'entrée fourni. |
int | getInputTensorCount () Obtient le nombre de tenseurs d'entrée. |
Tenseur | getInputTensorFromSignature ( String inputName, String signatureKey) Obtient le Tensor associé au nom d'entrée fourni et au nom de la méthode de signature. |
Long | getLastNativeInferenceDurationNanosecondes () Renvoie le timing d’inférence natif. |
int | getOutputIndex ( String opName) Obtient l'index d'une sortie en fonction du nom d'opération de la sortie. |
Tenseur | getOutputTensor (int outputIndex) Obtient le Tensor associé à l'index de sortie fourni. |
int | getOutputTensorCount () Obtient le nombre de Tensors de sortie. |
Tenseur | getOutputTensorFromSignature ( String nom de sortie, String signatureKey) Obtient le Tensor associé au nom de sortie fourni dans une méthode de signature spécifique. |
Chaîne[] | getSignatureInputs (SignatureKey de chaîne ) Obtient la liste des entrées SignatureDefs pour la méthode signatureKey . |
Chaîne[] | getSignatureKeys () Obtient la liste des noms de méthodes exportées SignatureDef disponibles dans le modèle. |
Chaîne[] | getSignatureOutputs (SignatureKey de chaîne ) Obtient la liste des sorties SignatureDefs pour la méthode signatureKey . |
vide | réinitialiserVariableTensors () Avancé : réinitialise tous les tenseurs variables à la valeur par défaut. |
vide | resizeInput (int idx, int[] dims, booléen strict) Redimensionne l'entrée idx-ème du modèle natif aux dimensions données. |
vide | resizeInput (int idx, int[] dims) Redimensionne l'entrée idx-ème du modèle natif aux dimensions données. |
vide | |
vide | 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. |
vide | runSignature ( Map < String , Object > entrées, Map < String , Object > sorties) Identique à runSignature(Map, Map, String) mais ne nécessite pas de transmettre une signatureKey, en supposant que le modèle ait une SignatureDef. |
vide | |
vide | setCancelled (booléen annulé) Avancé : interrompt l'inférence au milieu d'un appel à run(Object, Object) . |
Méthodes héritées
Constructeurs Publics
Interprète public ( Fichier modèleFichier)
Initialise un Interpreter
.
Paramètres
fichier modèle | un fichier d'un modèle TF Lite pré-entraîné. |
---|
Jetés
IllegalArgumentException | si modelFile n'encode pas un modèle TensorFlow Lite valide. |
---|
Interpréteur public ( Fichier modèleFichier, options Interpreter.Options )
Initialise un Interpreter
et spécifie les options de personnalisation du comportement de l'interpréteur.
Paramètres
fichier modèle | un fichier d'un modèle TF Lite pré-entraîné |
---|---|
choix | un ensemble d'options pour personnaliser le comportement de l'interprète |
Jetés
IllegalArgumentException | si modelFile n'encode pas un modèle TensorFlow Lite valide. |
---|
Interpréteur public ( ByteBuffer byteBuffer)
Initialise un Interpreter
avec un ByteBuffer
d'un fichier 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
octetBuffer |
---|
Jetés
IllegalArgumentException | si byteBuffer n'est pas un MappedByteBuffer ni un ByteBuffer direct de nativeOrder. |
---|
Interpréteur public ( ByteBuffer byteBuffer, options Interpreter.Options )
Initialise un Interpreter
avec un ByteBuffer
d'un fichier modèle et un ensemble d' 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
octetBuffer | |
---|---|
choix |
Jetés
IllegalArgumentException | si byteBuffer n'est pas un MappedByteBuffer ni un ByteBuffer direct de nativeOrder. |
---|
Méthodes publiques
public 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 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 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.
public vide fermer ()
Libérez les ressources associées à l’instance InterpreterApi
.
public 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 |
---|
Tensor public getInputTensor (int inputIndex)
Obtient le Tensor associé à l'index d'entrée fourni.
Paramètres
Indice d'entrée |
---|
public int getInputTensorCount ()
Obtient le nombre de tenseurs d'entrée.
public Tensor getInputTensorFromSignature ( String inputName, String signatureKey)
Obtient le Tensor associé au nom d'entrée fourni et au nom de la méthode de signature.
AVERTISSEMENT : Il s'agit d'une API expérimentale et susceptible d'être modifiée.
Paramètres
Nom d'entrée | Saisissez le nom dans la signature. |
---|---|
clé de signature | Clé de signature identifiant SignatureDef, peut être nulle si le modèle a une signature. |
Jetés
IllegalArgumentException | si inputName ou signatureKey est nul ou vide, ou si un nom non valide est fourni. |
---|
public int getOutputIndex ( String opName)
Obtient l'index d'une sortie en fonction du nom d'opération de la sortie.
Paramètres
nomOp |
---|
Tensor 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 |
---|
public int getOutputTensorCount ()
Obtient le nombre de Tensors de sortie.
public Tensor getOutputTensorFromSignature ( String outputName, String signatureKey)
Obtient le Tensor associé au nom de sortie fourni dans une méthode de signature spécifique.
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.
AVERTISSEMENT : Il s'agit d'une API expérimentale et susceptible d'être modifiée.
Paramètres
Nom de sortie | Nom de sortie dans la signature. |
---|---|
clé de signature | Clé de signature identifiant SignatureDef, peut être nulle si le modèle a une signature. |
Jetés
IllegalArgumentException | si outputName ou signatureKey est nul ou vide, ou si un nom non valide est fourni. |
---|
public String[] getSignatureInputs ( String signatureKey)
Obtient la liste des entrées SignatureDefs pour la méthode signatureKey
.
AVERTISSEMENT : Il s'agit d'une API expérimentale et susceptible d'être modifiée.
Paramètres
clé de signature |
---|
public String[] getSignatureKeys ()
Obtient la liste des noms de méthodes exportées SignatureDef disponibles dans le modèle.
AVERTISSEMENT : Il s'agit d'une API expérimentale et susceptible d'être modifiée.
public String[] getSignatureOutputs ( String signatureKey)
Obtient la liste des sorties SignatureDefs pour la méthode signatureKey
.
AVERTISSEMENT : Il s'agit d'une API expérimentale et susceptible d'être modifiée.
Paramètres
clé de signature |
---|
public void resetVariableTensors ()
Avancé : réinitialise tous les tenseurs variables à la valeur par défaut.
Si un tenseur variable n'a pas de tampon associé, il sera remis à zéro.
AVERTISSEMENT : Il s'agit d'une API expérimentale et susceptible d'être modifiée.
public 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 |
public 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 |
public 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.
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 n'est 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() ). |
public 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 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.
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
entré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 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. |
---|---|
sorties | une carte mappant les indices de sortie à des tableaux multidimensionnels de données de sortie ou à des 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() ). |
public void runSignature ( Map < String , Object > entrées, Map < String , Object > sorties)
Identique à runSignature(Map, Map, String)
mais ne nécessite pas de transmettre une signatureKey, en supposant que le modèle ait une SignatureDef. Si le modèle possède plusieurs SignatureDef, une exception sera levée.
AVERTISSEMENT : Il s'agit d'une API expérimentale et susceptible d'être modifiée.
Paramètres
entrées | |
---|---|
sorties |
public 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 fourni via signatureKey
.
Voir run(Object, Object)
pour plus de détails sur les types de données d'entrée et de sortie autorisés.
AVERTISSEMENT : Il s'agit d'une API expérimentale et susceptible d'être modifiée.
Paramètres
entrées | Une carte du nom d’entrée dans SignatureDef à un objet d’entrée. |
---|---|
sorties | Une carte du nom de sortie dans SignatureDef aux données de sortie. Cela 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 descripteurs de tampon de sortie sont utilisés). |
clé de signature | Clé de signature identifiant le SignatureDef. |
Jetés
IllegalArgumentException | si inputs sont nulles ou vides, si outputs ou signatureKey sont nulles ou si une erreur se produit lors de l'exécution de l'inférence. |
---|
public void setCancelled (booléen annulé)
Avancé : interrompt l'inférence au milieu d'un appel à run(Object, Object)
.
Un indicateur d'annulation sera défini sur true lorsque cette fonction sera appelée. L'interpréteur vérifiera l'indicateur entre les invocations d'Op, et si c'est true
, l'interpréteur arrêtera l'exécution. L'interpréteur restera dans un état annulé jusqu'à ce qu'il soit explicitement "non annulé" par setCancelled(false)
.
AVERTISSEMENT : Il s'agit d'une API expérimentale et susceptible d'être modifiée.
Paramètres
annulé | true pour annuler l'inférence au mieux ; false pour reprendre. |
---|
Jetés
IllegalStateException | si l'interpréteur n'est pas initialisé avec l'option annulable, qui est désactivée par défaut. |
---|