Classe driver per guidare l'inferenza del modello con TensorFlow Lite.
Nota: se non hai bisogno di accedere a nessuna delle funzionalità API "sperimentali" di seguito, preferisci utilizzare InterpreterApi e InterpreterFactory piuttosto che utilizzare Interpreter direttamente.
Un Interpreter
incapsula un modello TensorFlow Lite pre-addestrato, in cui le operazioni vengono eseguite per l'inferenza del modello.
Ad esempio, se un modello accetta solo un input e restituisce un solo output:
try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
interpreter.run(input, output);
}
Se un modello accetta più input o output:
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);
}
Se un modello accetta o produce tensori di stringa:
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);
}
Gli ordini di input e output vengono determinati durante la conversione del modello TensorFlow nel modello TensorFlowLite con Toco, così come le forme predefinite degli input.
Quando gli input vengono forniti come array (multidimensionali), i tensori di input corrispondenti verranno ridimensionati in modo implicito in base alla forma dell'array. Quando gli input vengono forniti come tipi di Buffer
, non viene eseguito alcun ridimensionamento implicito; il chiamante deve assicurarsi che la dimensione del byte Buffer
corrisponda a quella del tensore corrispondente o che prima ridimensioni il tensore tramite resizeInput(int, int[])
. Le informazioni sulla forma e sul tipo del tensore possono essere ottenute tramite la classe Tensor
, disponibile tramite getInputTensor(int)
e getOutputTensor(int)
.
AVVISO: le istanze Interpreter
non sono thread-safe. Un Interpreter
possiede risorse che devono essere liberate esplicitamente invocando close()
La libreria TFLite è basata sull'API NDK 19. Potrebbe funzionare per livelli API Android inferiori a 19, ma non è garantita.
Classi nidificate
classe | Interprete.Opzioni | Una classe di opzioni per controllare il comportamento dell'interprete di runtime. |
Costruttori pubblici
Interprete ( file modelloFile, opzioni Interprete.Opzioni ) Inizializza un Interpreter e specifica le opzioni per personalizzare il comportamento dell'interprete. | |
Interprete ( ByteBuffer byteBuffer) Inizializza un Interpreter con un ByteBuffer di un file modello. | |
Interprete ( ByteBuffer byteBuffer, Opzioni Interprete.Opzioni ) Inizializza un Interpreter con un ByteBuffer di un file modello e un set di Interpreter.Options personalizzati. |
Metodi pubblici
vuoto | allocateTensors () Aggiorna esplicitamente le allocazioni per tutti i tensori, se necessario. |
vuoto | chiudi () Rilascia le risorse associate all'istanza di InterpreterApi . |
int | |
Tensore | getInputTensor (int inputIndex) Ottiene il Tensor associato all'indice di input fornito. |
int | getInputTensorCount () Ottiene il numero di tensori di input. |
Tensore | getInputTensorFromSignature ( String inputName, String signatureKey) Ottiene il Tensor associato al nome di input fornito e al nome del metodo di firma. |
Lungo | getLastNativeInferenceDurationNanoseconds () Restituisce la temporizzazione dell'inferenza nativa. |
int | |
Tensore | getOutputTensor (int outputIndex) Ottiene il Tensor associato all'indice di output fornito. |
int | getOutputTensorCount () Ottiene il numero di tensori di output. |
Tensore | getOutputTensorFromSignature ( String outputName, String signatureKey) Ottiene il Tensor associato al nome di output fornito nel metodo di firma specifico. |
Corda[] | getSignatureInputs ( String signatureKey) Ottiene l'elenco degli input di SignatureDefs per il metodo signatureKey . |
Corda[] | getSignatureKeys () Ottiene l'elenco dei nomi dei metodi esportati SignatureDef disponibili nel modello. |
Corda[] | getSignatureOutputs ( stringa signatureKey) Ottiene l'elenco degli output SignatureDefs per il metodo signatureKey . |
vuoto | resetVariableTensors () Avanzate: ripristina tutti i tensori variabili al valore predefinito. |
vuoto | resizeInput (int idx, int[] dims, boolean strict) Ridimensiona l'input idx-esimo del modello nativo alle dim date. |
vuoto | resizeInput (int idx, int[] dim) Ridimensiona l'input idx-esimo del modello nativo alle dim date. |
vuoto | |
vuoto | runForMultipleInputsOutputs ( Object[] input, Map < Integer , Object > output) Esegue l'inferenza del modello se il modello accetta più input o restituisce più output. |
vuoto | runSignature ( Map < String , Object > input, Map < String , Object > output) Uguale a runSignature(Map, Map, String) ma non richiede il passaggio di una signatureKey, supponendo che il modello abbia una SignatureDef. |
vuoto | |
vuoto | setCancelled (booleano annullato) Avanzate: interrompe l'inferenza nel mezzo di una chiamata a run(Object, Object) . |
Metodi ereditati
Costruttori pubblici
Interprete pubblico ( File modelFile)
Inizializza un Interpreter
.
Parametri
modelloFile | a File di un modello TF Lite pre-addestrato. |
---|
Tiri
IllegalArgumentException | se modelFile non codifica un modello TensorFlow Lite valido. |
---|
public Interpreter ( file modelFile, opzioni Interpreter.Options )
Inizializza un Interpreter
e specifica le opzioni per personalizzare il comportamento dell'interprete.
Parametri
modelloFile | un file di un modello TF Lite pre-addestrato |
---|---|
opzioni | una serie di opzioni per personalizzare il comportamento dell'interprete |
Tiri
IllegalArgumentException | se modelFile non codifica un modello TensorFlow Lite valido. |
---|
Interprete pubblico ( ByteBuffer byteBuffer)
Inizializza un Interpreter
con un ByteBuffer
di un file modello.
Il ByteBuffer non deve essere modificato dopo la costruzione di un Interpreter
. Il ByteBuffer
può essere un MappedByteBuffer
che mappa in memoria un file di modello o un ByteBuffer
diretto di nativeOrder() che contiene il contenuto di byte di un modello.
Parametri
byteBuffer |
---|
Tiri
IllegalArgumentException | se byteBuffer non è un MappedByteBuffer né un ByteBuffer diretto di nativeOrder. |
---|
public Interpreter ( ByteBuffer byteBuffer, opzioni Interpreter.Options )
Inizializza un Interpreter
con un ByteBuffer
di un file modello e un set di Interpreter.Options
personalizzati.
Il ByteBuffer
non deve essere modificato dopo la costruzione di un Interpreter
. Il ByteBuffer
può essere un MappedByteBuffer
che mappa in memoria un file di modello o un ByteBuffer
diretto di nativeOrder() che contiene il contenuto di byte di un modello.
Parametri
byteBuffer | |
---|---|
opzioni |
Tiri
IllegalArgumentException | se byteBuffer non è un MappedByteBuffer né un ByteBuffer diretto di nativeOrder. |
---|
Metodi pubblici
public void allocateTensors ()
Aggiorna esplicitamente le allocazioni per tutti i tensori, se necessario.
Ciò propagherà le forme e le allocazioni di memoria per i tensori dipendenti utilizzando le forme del tensore di input come indicato.
Nota: questa chiamata è *puramente facoltativa*. L'allocazione del tensore avverrà automaticamente durante l'esecuzione se i tensori di input sono stati ridimensionati. Questa chiamata è molto utile per determinare le forme di qualsiasi tensore di output prima di eseguire il grafico, ad esempio
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...
Nota: alcuni grafici hanno output di forma dinamica, nel qual caso la forma di output potrebbe non propagarsi completamente finché non viene eseguita l'inferenza.
pubblico vuoto chiudere ()
Rilascia le risorse associate all'istanza di InterpreterApi
.
public int getInputIndex ( String opName)
Ottiene l'indice di un input dato il nome operativo dell'input.
Parametri
opName |
---|
public Tensor getInputTensor (int inputIndex)
Ottiene il Tensor associato all'indice di input fornito.
Parametri
inputIndex |
---|
public int getInputTensorCount ()
Ottiene il numero di tensori di input.
public Tensor getInputTensorFromSignature ( String inputName, String signatureKey)
Ottiene il Tensor associato al nome di input fornito e al nome del metodo di firma.
ATTENZIONE: questa è un'API sperimentale ed è soggetta a modifiche.
Parametri
inputName | Inserisci il nome nella firma. |
---|---|
signatureKey | La chiave della firma che identifica la SignatureDef, può essere nulla se il modello ha una firma. |
Tiri
IllegalArgumentException | se inputName o signatureKey è nullo o vuoto o è stato fornito un nome non valido. |
---|
public Long getLastNativeInferenceDurationNanoseconds ()
Restituisce la temporizzazione dell'inferenza nativa.
public int getOutputIndex ( String opName)
Ottiene l'indice di un output dato il nome operativo dell'output.
Parametri
opName |
---|
public Tensor getOutputTensor (int outputIndex)
Ottiene il Tensor associato all'indice di output fornito.
Nota: i dettagli del tensore di output (ad esempio, la forma) potrebbero non essere completamente popolati fino a dopo l'esecuzione dell'inferenza. Se hai bisogno di dettagli aggiornati *prima* di eseguire l'inferenza (ad esempio, dopo aver ridimensionato un tensore di input, che potrebbe invalidare le forme del tensore di output), usa allocateTensors()
per attivare esplicitamente l'allocazione e la propagazione della forma. Si noti che, per i grafici con forme di output che dipendono dai *valori* di input, la forma di output potrebbe non essere completamente determinata fino all'esecuzione dell'inferenza.
Parametri
outputIndex |
---|
public int getOutputTensorCount ()
Ottiene il numero di tensori di output.
public Tensor getOutputTensorFromSignature ( String outputName, String signatureKey)
Ottiene il Tensor associato al nome di output fornito nel metodo di firma specifico.
Nota: i dettagli del tensore di output (ad esempio, la forma) potrebbero non essere completamente popolati fino a dopo l'esecuzione dell'inferenza. Se hai bisogno di dettagli aggiornati *prima* di eseguire l'inferenza (ad esempio, dopo aver ridimensionato un tensore di input, che potrebbe invalidare le forme del tensore di output), usa allocateTensors()
per attivare esplicitamente l'allocazione e la propagazione della forma. Si noti che, per i grafici con forme di output che dipendono dai *valori* di input, la forma di output potrebbe non essere completamente determinata fino all'esecuzione dell'inferenza.
ATTENZIONE: questa è un'API sperimentale ed è soggetta a modifiche.
Parametri
outputName | Nome di output nella firma. |
---|---|
signatureKey | La chiave della firma che identifica la SignatureDef, può essere nulla se il modello ha una firma. |
Tiri
IllegalArgumentException | se outputName o signatureKey è nullo o vuoto o viene fornito un nome non valido. |
---|
public String[] getSignatureInputs ( String signatureKey)
Ottiene l'elenco degli input di SignatureDefs per il metodo signatureKey
.
ATTENZIONE: questa è un'API sperimentale ed è soggetta a modifiche.
Parametri
signatureKey |
---|
public String[] getSignatureKeys ()
Ottiene l'elenco dei nomi dei metodi esportati SignatureDef disponibili nel modello.
ATTENZIONE: questa è un'API sperimentale ed è soggetta a modifiche.
public String[] getSignatureOutputs ( String signatureKey)
Ottiene l'elenco degli output SignatureDefs per il metodo signatureKey
.
ATTENZIONE: questa è un'API sperimentale ed è soggetta a modifiche.
Parametri
signatureKey |
---|
public void resetVariableTensors ()
Avanzate: ripristina tutti i tensori variabili al valore predefinito.
Se un tensore variabile non ha un buffer associato, verrà ripristinato a zero.
ATTENZIONE: questa è un'API sperimentale ed è soggetta a modifiche.
public void resizeInput (int idx, int[] dims, boolean strict)
Ridimensiona l'input idx-esimo del modello nativo alle dim date.
Quando `strict` è True, solo le dimensioni sconosciute possono essere ridimensionate. Le dimensioni sconosciute sono indicate come `-1` nell'array restituito da `Tensor.shapeSignature()`.
Parametri
idx | |
---|---|
si attenua | |
severa |
public void resizeInput (int idx, int[] dims)
Ridimensiona l'input idx-esimo del modello nativo alle dim date.
Parametri
idx | |
---|---|
si attenua |
public void run (input oggetto , output oggetto )
Esegue l'inferenza del modello se il modello accetta solo un input e fornisce un solo output.
Avviso: l'API è più efficiente se viene utilizzato un Buffer
(preferibilmente diretto, ma non necessario) come tipo di dati di input/output. Si prega di considerare l'utilizzo del Buffer
per alimentare e recuperare dati primitivi per prestazioni migliori. Sono supportati i seguenti tipi di Buffer
concreti:
-
ByteBuffer
- compatibile con qualsiasi tipo di Tensor primitivo sottostante. -
FloatBuffer
- compatibile con i tensori float. -
IntBuffer
- compatibile con i tensori int32. -
LongBuffer
- compatibile con i tensori int64.
Buffer
o come input scalari. Parametri
ingresso | un array o un array multidimensionale o un Buffer di tipi primitivi inclusi int, float, long e byte. Buffer è il modo preferito per passare dati di input di grandi dimensioni per i tipi primitivi, mentre i tipi di stringa richiedono l'utilizzo del percorso di input dell'array (multidimensionale). Quando viene utilizzato un Buffer , il suo contenuto dovrebbe rimanere invariato fino a quando non viene eseguita l'inferenza del modello e il chiamante deve assicurarsi che il Buffer si trovi nella posizione di lettura appropriata. Un valore null è consentito solo se il chiamante utilizza un Delegate che consente l'interoperabilità della gestione del buffer e tale buffer è stato associato all'input Tensor . |
---|---|
produzione | una matrice multidimensionale di dati di output o un Buffer di tipi primitivi inclusi int, float, long e byte. Quando viene utilizzato un Buffer , il chiamante deve assicurarsi che sia impostata la posizione di scrittura appropriata. È consentito un valore nullo, utile in alcuni casi, ad esempio se il chiamante utilizza un Delegate che consente l'interoperabilità dell'handle del buffer e tale buffer è stato associato all'output Tensor (vedere anche Interpreter.Options#setAllowBufferHandleOutput(boolean) ), o se il grafico ha output di forma dinamica e il chiamante deve interrogare la forma del Tensor di output dopo che è stata richiamata l'inferenza, recuperando i dati direttamente dal tensore di output (tramite Tensor.asReadOnlyBuffer() ). |
public void runForMultipleInputsOutputs (Ingressi Object[] , Map < Integer , Object > output)
Esegue l'inferenza del modello se il modello accetta più input o restituisce più output.
Avvertenza: l'API è più efficiente se i Buffer
(preferibilmente diretti, ma non obbligatori) vengono utilizzati come tipi di dati di input/output. Si prega di considerare l'utilizzo del Buffer
per alimentare e recuperare dati primitivi per prestazioni migliori. Sono supportati i seguenti tipi di Buffer
concreti:
-
ByteBuffer
- compatibile con qualsiasi tipo di Tensor primitivo sottostante. -
FloatBuffer
- compatibile con i tensori float. -
IntBuffer
- compatibile con i tensori int32. -
LongBuffer
- compatibile con i tensori int64.
Buffer
o come input scalari. Nota: i valori null
per singoli elementi di inputs
e outputs
sono consentiti solo se il chiamante utilizza un Delegate
che consente l'interoperabilità della gestione del buffer e tale buffer è stato associato al Tensor
(i) di input o output corrispondente.
Parametri
ingressi | una matrice di dati di input. Gli input devono essere nello stesso ordine degli input del modello. Ogni input può essere una matrice o una matrice multidimensionale o un Buffer di tipi primitivi inclusi int, float, long e byte. Buffer è il modo preferito per passare dati di input di grandi dimensioni, mentre i tipi di stringa richiedono l'utilizzo del percorso di input dell'array (multidimensionale). Quando viene utilizzato il Buffer , il suo contenuto deve rimanere invariato fino al completamento dell'inferenza del modello e il chiamante deve assicurarsi che il Buffer si trovi nella posizione di lettura appropriata. |
---|---|
uscite | una mappa che mappa gli indici di output su array multidimensionali di dati di output o Buffer di tipi primitivi inclusi int, float, long e byte. Ha solo bisogno di conservare le voci per gli output da utilizzare. Quando viene utilizzato un Buffer , il chiamante deve assicurarsi che sia impostata la posizione di scrittura appropriata. La mappa può essere vuota per i casi in cui vengono utilizzati gli handle del buffer per i dati del tensore di output o nei casi in cui gli output hanno una forma dinamica e il chiamante deve interrogare la forma del Tensor di output dopo che è stata invocata l'inferenza, recuperando i dati direttamente dal tensore di output ( tramite Tensor.asReadOnlyBuffer() ). |
public void runSignature ( Map < String , Object > input, Map < String , Object > output)
Uguale a runSignature(Map, Map, String)
ma non richiede il passaggio di una signatureKey, supponendo che il modello abbia una SignatureDef. Se il modello ha più di un SignatureDef genererà un'eccezione.
ATTENZIONE: questa è un'API sperimentale ed è soggetta a modifiche.
Parametri
ingressi | |
---|---|
uscite |
public void runSignature ( Map < String , Object > input, Map < String , Object > output, String signatureKey)
Esegue l'inferenza del modello basata su SignatureDef fornito tramite signatureKey
.
Vedere run(Object, Object)
per maggiori dettagli sui tipi di dati di input e output consentiti.
ATTENZIONE: questa è un'API sperimentale ed è soggetta a modifiche.
Parametri
ingressi | Una mappa dal nome di input in SignatureDef a un oggetto di input. |
---|---|
uscite | Una mappa dal nome di output in SignatureDef ai dati di output. Questo può essere vuoto se il chiamante desidera interrogare i dati del Tensor direttamente dopo l'inferenza (ad esempio, se la forma dell'output è dinamica o vengono utilizzate le maniglie del buffer di output). |
signatureKey | Chiave di firma che identifica la SignatureDef. |
Tiri
IllegalArgumentException | se inputs è nullo o vuoto, se outputs o signatureKey è nullo o se si verifica un errore durante l'esecuzione dell'inferenza. |
---|
public void setCancelled (booleano annullato)
Avanzate: interrompe l'inferenza nel mezzo di una chiamata a run(Object, Object)
.
Un flag di annullamento verrà impostato su true quando questa funzione viene chiamata. L'interprete controllerà il flag tra le invocazioni Op e, se è true
, l'interprete interromperà l'esecuzione. L'interprete rimarrà uno stato annullato fino a quando non verrà esplicitamente "uncancellato" da setCancelled(false)
.
ATTENZIONE: questa è un'API sperimentale ed è soggetta a modifiche.
Parametri
annullato | true per annullare l'inferenza nel miglior modo possibile; false per riprendere. |
---|
Tiri
IllegalStateException | se l'interprete non è inizializzato con l'opzione cancellabile, che per impostazione predefinita è disattivata. |
---|