Classe driver per favorire l'inferenza del modello con TensorFlow Lite.
Nota: se non hai bisogno dell'accesso a nessuna delle funzionalità dell'API "sperimentale" riportate di seguito, preferisci utilizzare InterpreterApi e InterpreterIndustry anziché utilizzare direttamente Interpreter.
Un elemento Interpreter
incapsula un modello TensorFlow Lite preaddestrato, in cui vengono eseguite operazioni
per l'inferenza del modello.
Ad esempio, se un modello accetta un solo 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 prende 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);
}
Tieni presente che esiste una distinzione tra forma [] e forma[1]. Per output del tensore di stringa scalare:
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);
Gli ordini degli input e degli output vengono determinati quando si converte il modello TensorFlow in modello TensorFlowLite con Toco, così come le forme predefinite degli input.
Quando gli input vengono forniti come array (multidimensionali), i corrispondenti tensori di input verranno implicitamente ridimensionati in base alla forma dell'array. Quando gli input vengono forniti come tipi Buffer
, non viene eseguito il ridimensionamento implicito. Il chiamante deve assicurarsi che la dimensione in byte Buffer
corrisponda a quella del tensore corrispondente o che prima ridimensiona il tensore tramite resizeInput(int, int[])
. Le informazioni sul tipo e sulla forma del tensore possono essere ottenute tramite la classe Tensor
, disponibile tramite getInputTensor(int)
e getOutputTensor(int)
.
AVVISO: le istanze Interpreter
non sono sicure per i thread. Un Interpreter
possiede risorse che devono essere liberate esplicitamente richiamando close()
La libreria TFLite è basata sull'API NDK 19. Potrebbe funzionare per livelli API Android inferiori a 19, ma non è garantito.
Corsi nidificati
classe | Interpreter.Options | Una classe di opzioni per controllare il comportamento dell'interprete di runtime. |
Costruttori pubblici
Interprete(opzioni File modelFile, Interpreter.Options)
Inizializza un
Interpreter e specifica le opzioni per personalizzare il comportamento dell'interprete. |
|
Interprete(ByteBuffer byteBuffer)
Inizializza un oggetto
Interpreter con un ByteBuffer di un file del modello. |
|
Interpreter(opzioni ByteBuffer byteBuffer, Interpreter.Options)
Inizializza un oggetto
Interpreter con un ByteBuffer di un file del modello e un set di Interpreter.Options personalizzati. |
Metodi pubblici
void |
allocateTensors()
Aggiorna in modo esplicito le allocazioni per tutti i tensori, se necessario.
|
void |
close()
Rilascia le risorse associate all'istanza
InterpreterApi . |
int | |
Tensor |
getInputTensor(int inputIndex)
Restituisce il Tensor associato all'indice di input fornito.
|
int |
getInputTensorCount()
Restituisce il numero di tensori di input.
|
Tensor |
getInputTensorFromSignature(String inputName, String signatureKey)
Restituisce il Tensor associato al nome di input e al nome del metodo di firma forniti.
|
Lunga |
getLastNativeInferenceDurationNanoseconds()
Restituisce il tempo di inferenza nativa.
|
int |
getOutputIndex(Stringa opName)
Restituisce l'indice di un output in base al nome operativo dell'output.
|
Tensor |
getOutputTensor(int outputIndex)
Restituisce il valore Tensor associato all'indice di output fornito.
|
int |
getOutputTensorCount()
Restituisce il numero di Tensor di output.
|
Tensor |
getOutputTensorFromSignature(String outputName, String signatureKey)
Restituisce il Tensor associato al nome dell'output fornito nel metodo di firma specifico.
|
Stringa[] |
getSignatureInputs(String signatureKey)
Recupera l'elenco di input SignatureDefs per il metodo
signatureKey . |
Stringa[] |
getSignatureKeys()
Restituisce l'elenco dei nomi dei metodi esportati di SignatureDef disponibili nel modello.
|
Stringa[] |
getSignatureOutputs(String signatureKey)
Recupera l'elenco di output SignatureDefs per il metodo
signatureKey . |
void |
resetVariableTensors()
Avanzato: reimposta tutti i tensori variabili sul valore predefinito.
|
void |
resizeInput(int idx, int[] dims, boolean strict)
Ridimensiona l'input idx-esima del modello nativo nei valori specificati.
|
void |
resizeInput(int idx, int[] attenuato)
Ridimensiona l'input idx-esima del modello nativo nei valori specificati.
|
void | |
void |
runForMultipleInputsOutputs(Input di Object[], output Map<Integer, Object>)
Esegue l'inferenza del modello se il modello accetta più input o restituisce più output.
|
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 un SignatureDef. |
void | |
void |
setCancelled(booleano annullato)
Avanzata: interrompe l'inferenza nel bel mezzo di una chiamata a
run(Object, Object) . |
Metodi ereditati
Costruttori pubblici
Public Interprete (File modelFile)
Inizializza un Interpreter
.
Parametri
modelFile | un file di un modello TF Lite preaddestrato. |
---|
Lanci
IllegalArgumentException | se modelFile non codifica un modello TensorFlow Lite
valido.
|
---|
Public Interprete (opzioni File modelFile, Interpreter.Options)
Inizializza un Interpreter
e specifica le opzioni per personalizzare il comportamento dell'interprete.
Parametri
modelFile | un file di un modello TF Lite preaddestrato |
---|---|
opzioni del modello. | una serie di opzioni per personalizzare il comportamento dell'interprete |
Lanci
IllegalArgumentException | se modelFile non codifica un modello TensorFlow Lite
valido.
|
---|
pubblico Interprete (ByteBuffer byteBuffer)
Inizializza un oggetto Interpreter
con un ByteBuffer
di un file del modello.
Il ByteBuffer non deve essere modificato dopo la creazione di un Interpreter
. ByteBuffer
può essere un MappedByteBuffer
che mappa la memoria un file del modello o un ByteBuffer
diretto di nativeOrder() che include i contenuti dei byte di un modello.
Parametri
byteBuffer |
---|
Lanci
IllegalArgumentException | se byteBuffer non è un MappedByteBuffer né un
ByteBuffer diretto di nativeOrder.
|
---|
Public Interpreter (opzioni ByteBuffer byteBuffer, Interpreter.Options)
Inizializza un oggetto Interpreter
con un ByteBuffer
di un file del modello e un set di Interpreter.Options
personalizzati.
ByteBuffer
non deve essere modificato dopo la costruzione di un Interpreter
. ByteBuffer
può essere un MappedByteBuffer
che mappa in memoria un file del modello o un ByteBuffer
diretto di nativeOrder() che include i contenuti in byte di un modello.
Parametri
byteBuffer | |
---|---|
opzioni del modello. |
Lanci
IllegalArgumentException | se byteBuffer non è un MappedByteBuffer né un
ByteBuffer diretto di nativeOrder.
|
---|
Metodi pubblici
Public void allocateTensors ()
Aggiorna in modo esplicito le allocazioni per tutti i tensori, se necessario.
Questo propaga forme e allocazioni della memoria per i tensori dipendenti utilizzando le forme del tensore di input come specificato.
Nota: questa chiamata è *puramente facoltativa*. L'allocazione dei tensori avverrà automaticamente durante l'esecuzione se sono stati ridimensionati eventuali tensori di input. Questa chiamata è utile soprattutto per determinare le forme di eventuali tensori 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 con forma dinamica, nel qual caso la forma di output potrebbe non propagarsi completamente fino all'esecuzione dell'inferenza.
pubblica void chiudi ()
Rilascia le risorse associate all'istanza InterpreterApi
.
Public int getInputIndex (String opName)
Recupera l'indice di un input in base al nome operazione dell'input.
Parametri
opName |
---|
pubblico Tensor getInputTensor (int inputIndex)
Restituisce il Tensor associato all'indice di input fornito.
Parametri
inputIndex |
---|
pubblica int getInputTensorCount ()
Restituisce il numero di tensori di input.
pubblici Tensor getInputTensorFromSignature (String inputName, String signatureKey)
Restituisce il Tensor associato al nome di input e al nome del metodo di firma forniti.
AVVISO: si tratta di un'API sperimentale ed è soggetta a modifiche.
Parametri
inputName | Inserisci il nome nella firma. |
---|---|
signatureKey | La chiave di firma che identifica SignatureDef può essere nulla se il modello ha una firma. |
Lanci
IllegalArgumentException | se inputName o signatureKey è nullo o vuoto
oppure se è stato fornito un nome non valido.
|
---|
pubblici Long getLastNativeInferenceDurationNanoseconds ()
Restituisce il tempo di inferenza nativa.
Public int getOutputIndex (String opName)
Restituisce l'indice di un output in base al nome operativo dell'output.
Parametri
opName |
---|
pubblico Tensor getOutputTensor (int outputIndex)
Restituisce il valore Tensor associato all'indice di output fornito.
Nota: i dettagli del tensore di output (ad esempio la forma) potrebbero non essere compilati completamente finché non viene eseguita l'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), utilizza allocateTensors()
per attivare esplicitamente l'allocazione e la propagazione della forma. Tieni presente che, per i grafici con forme di output che dipendono da *valori* di input, la forma di output potrebbe non essere completamente determinata finché non viene eseguita l'inferenza.
Parametri
outputIndex |
---|
pubblica int getOutputTensorCount ()
Restituisce il numero di Tensor di output.
pubblici Tensor getOutputTensorFromSignature (String outputName, String signatureKey)
Restituisce il Tensor associato al nome dell'output fornito nel metodo di firma specifico.
Nota: i dettagli del tensore di output (ad esempio la forma) potrebbero non essere compilati completamente finché non viene eseguita l'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), utilizza allocateTensors()
per attivare esplicitamente l'allocazione e la propagazione della forma. Tieni presente che, per i grafici con forme di output che dipendono da *valori* di input, la forma di output potrebbe non essere completamente determinata finché non viene eseguita l'inferenza.
AVVISO: si tratta di un'API sperimentale ed è soggetta a modifiche.
Parametri
outputName | Nome dell'output nella firma. |
---|---|
signatureKey | La chiave di firma che identifica SignatureDef può essere nulla se il modello ha una firma. |
Lanci
IllegalArgumentException | se outputName o signatureKey è nullo o vuoto oppure se è stato fornito un nome non valido.
|
---|
Public String[] getSignatureInputs (String signatureKey)
Recupera l'elenco di input SignatureDefs per il metodo signatureKey
.
AVVISO: si tratta di un'API sperimentale ed è soggetta a modifiche.
Parametri
signatureKey |
---|
Public String[] getSignatureKeys ()
Restituisce l'elenco dei nomi dei metodi esportati di SignatureDef disponibili nel modello.
AVVISO: si tratta di un'API sperimentale ed è soggetta a modifiche.
Public String[] getSignatureOutputs (String signatureKey)
Recupera l'elenco di output SignatureDefs per il metodo signatureKey
.
AVVISO: si tratta di un'API sperimentale ed è soggetta a modifiche.
Parametri
signatureKey |
---|
Public void resetVariableTensors ()
Avanzato: reimposta tutti i tensori variabili sul valore predefinito.
Se a un tensore di variabile non è associato un buffer, verrà reimpostato su zero.
AVVISO: si tratta di un'API sperimentale ed è soggetta a modifiche.
Public void resizeInput (int idx, int[] dims, boolean strict)
Ridimensiona l'input idx-esima del modello nativo nei valori specificati.
Se "strict" è true, solo le dimensioni sconosciute possono essere ridimensionate. Le dimensioni sconosciute sono indicate come "-1" nell'array restituito da "Tensor.shapeSignature()".
Parametri
idx | |
---|---|
dims | |
livello massimo |
Public void resizeInput (int idx, int[] dims)
Ridimensiona l'input idx-esima del modello nativo nei valori specificati.
Parametri
idx | |
---|---|
dims |
Public void run (Input dell'oggetto, output Oggetto)
Esegue l'inferenza del modello se il modello accetta un solo input e fornisce un solo output.
Avviso: l'API è più efficiente se viene utilizzato un Buffer
(preferibilmente diretto, ma non obbligatorio) come tipo di dati di input/output. Prendi in considerazione l'utilizzo di Buffer
per fornire e recuperare i dati primitivi per migliorare le prestazioni. Sono supportati i seguenti tipi di Buffer
concreti:
ByteBuffer
: compatibile con qualsiasi tipo di Tensor primitivo sottostante.FloatBuffer
: compatibile con i float Tensor.IntBuffer
- compatibile con int32 Tensors.LongBuffer
- compatibile con Tensors int64.
Buffer
o come input scalari.Parametri
input | un array o un array multidimensionale oppure Buffer di tipi primitivi, tra cui 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 elemento Buffer , i relativi contenuti devono rimanere invariati fino al completamento dell'inferenza del modello e il chiamante deve assicurarsi che Buffer si trovi nella posizione di lettura appropriata. Un valore null è consentito solo se il chiamante utilizza un Delegate che consente l'interoperabilità dell'handle del buffer ed è stato associato all'input Tensor . |
---|---|
output | un array multidimensionale di dati di output o Buffer di tipi primitivi, tra cui 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 null ed è utile in alcuni casi, ad esempio se il chiamante utilizza un elemento Delegate che consente l'interoperabilità dell'handle del buffer e tale buffer è stato associato all'output Tensor (vedi anche Interpreter.Options#setAllowBufferHandleOutput(boolean)) oppure se il grafico ha output dal formato dinamico e il chiamante deve eseguire una query sulla forma Tensor di output dopo il recupero dei dati Tensor.asReadOnlyBuffer() o dopo il richiamo dei dati.Tensor.asReadOnlyBuffer() |
pubblici void runForMultipleInputsOutputs (Input di Object[], Map <Numero intero, output dell'oggetto>)
Esegue l'inferenza del modello se il modello accetta più input o restituisce più output.
Avviso: l'API è più efficiente se vengono utilizzati Buffer
(preferibilmente diretti, ma non obbligatori)
come tipi di dati di input/output. Prendi in considerazione l'utilizzo di Buffer
per fornire e recuperare i dati primitivi per migliorare le prestazioni. Sono supportati i seguenti tipi di Buffer
concreti:
ByteBuffer
: compatibile con qualsiasi tipo di Tensor primitivo sottostante.FloatBuffer
: compatibile con i float Tensor.IntBuffer
- compatibile con int32 Tensors.LongBuffer
- compatibile con Tensors int64.
Buffer
o come input scalari.
Nota: i valori null
per gli elementi individuali di inputs
e outputs
sono consentiti solo se il chiamante utilizza un Delegate
che consente l'interoperabilità dell'handle del buffer e questo buffer è stato associato ai Tensor
di input o di output corrispondenti.
Parametri
nascosti | un array di dati di input. Gli input devono essere nello stesso ordine degli input del modello. Ogni input può essere un array o un array multidimensionale oppure un Buffer di tipi primitivi, tra cui int, float, long e byte. Buffer è il modo preferito per trasferire dati di input di grandi dimensioni, mentre i tipi di stringa richiedono l'utilizzo del percorso di input dell'array (multidimensionale). Quando viene utilizzato Buffer , i relativi contenuti devono rimanere invariati fino al termine dell'inferenza del modello e il chiamante deve assicurarsi che Buffer si trovi nella posizione di lettura appropriata. |
---|---|
output | una mappa che mappa gli indici di output a array multidimensionali di dati di output o a Buffer di tipi primitivi tra cui int, float, long e byte. Deve solo conservare le voci per poter utilizzare gli output. Quando viene utilizzato un Buffer , il chiamante deve assicurarsi che sia impostata la posizione di scrittura appropriata. La mappa può essere vuota nei casi in cui gli handle del buffer vengono utilizzati per i dati del tensore di output o i casi in cui gli output hanno una forma dinamica e il chiamante deve eseguire una query sulla forma Tensor di output dopo che è stata richiamata 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 un SignatureDef. Se il modello ha più di un SignatureDef, genererà un'eccezione.
AVVISO: si tratta di un'API sperimentale ed è soggetta a modifiche.
Parametri
nascosti | |
---|---|
output |
Public void runSignature (Map<String, Object> input, Map<String, Object> outputs, String signatureKey)
Esegue l'inferenza del modello basata su SignatureDef fornito tramite signatureKey
.
Consulta run(Object, Object)
per ulteriori dettagli sui tipi di dati di input e di output consentiti.
AVVISO: si tratta di un'API sperimentale ed è soggetta a modifiche.
Parametri
nascosti | Una mappa dal nome di input in SignatureDef a un oggetto di input. |
---|---|
output | Una mappa dal nome dell'output in SignatureDef ai dati di output. Questo campo può essere vuoto se il chiamante vuole eseguire una query sui dati Tensor direttamente dopo l'inferenza (ad esempio se la forma di output è dinamica o se vengono utilizzati handle del buffer di output). |
signatureKey | Chiave della firma che identifica SignatureDef. |
Lanci
IllegalArgumentException | se inputs è nullo o vuoto, se outputs o signatureKey è nullo oppure se si verifica un errore durante l'esecuzione dell'inferenza.
|
---|
Public void setCancelled (boolean cancelled)
Avanzata: interrompe l'inferenza nel bel mezzo di una chiamata a run(Object, Object)
.
Quando questa funzione viene chiamata, un flag di annullamento verrà impostato su true. L'interprete controllerà il flag tra le chiamate operative e, se è true
, interromperà l'esecuzione. Lo stato dell'interprete rimarrà annullato fino a quando non verrà esplicitamente annullato entro il giorno setCancelled(false)
.
AVVISO: si tratta di un'API sperimentale ed è soggetta a modifiche.
Parametri
annullata | true per annullare l'inferenza nel modo migliore; false per riprendere. |
---|
Lanci
IllegalStateException | se l'interprete non è inizializzato con l'opzione annullabile, che è disattivata per impostazione predefinita. |
---|