Interpreter

Interprete di classe finale pubblica

Classe driver per guidare l'inferenza del modello con TensorFlow Lite.

Nota: se non hai bisogno di accedere a nessuna delle funzionalità API "sperimentali" riportate di seguito, preferisci utilizzare InterpreterApi e InterpreterFactory anziché utilizzare direttamente Interpreter.

Un Interpreter incapsula un modello TensorFlow Lite pre-addestrato, in cui vengono eseguite le 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 richiede 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 gli 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 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 corrispondenti tensori di input verranno implicitamente ridimensionati in base alla forma di tale array. Quando gli input vengono forniti come tipi Buffer , non viene eseguito alcun ridimensionamento implicito; il chiamante deve assicurarsi che la dimensione dei 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) .

ATTENZIONE: 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 i livelli API Android inferiori a 19, ma non è garantito.

Classi nidificate

classe Opzioni.Interprete Una classe di opzioni per controllare il comportamento dell'interprete runtime.

Costruttori pubblici

Interprete ( File modelFile)
Inizializza un Interpreter .
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 ( opzioni ByteBuffer byteBuffer, Interpreter.Options )
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
vicino ()
Rilascia le risorse associate all'istanza InterpreterApi .
int
getInputIndex ( String opName)
Ottiene l'indice di un input in base al nome operativo dell'input.
Tensore
getInputTensor (int inputIndex)
Ottiene il tensore associato all'indice di input fornito.
int
getInputTensorCount ()
Ottiene il numero di tensori di input.
Tensore
getInputTensorFromSignature ( String inputName, String SignatureKey)
Ottiene il tensore associato al nome di input fornito e al nome del metodo di firma.
Lungo
getLastNativeInferenceDurationNanoseconds ()
Restituisce i tempi di inferenza nativi.
int
getOutputIndex ( String opName)
Ottiene l'indice di un output in base al nome operativo dell'output.
Tensore
getOutputTensor (int outputIndex)
Ottiene il tensore associato all'indice di output fornito.
int
getOutputTensorCount ()
Ottiene il numero di tensori di output.
Tensore
getOutputTensorFromSignature ( String outputName, String SignatureKey)
Ottiene il tensore associato al nome di output fornito nel metodo di firma specifico.
Corda[]
getSignatureInputs ( stringa chiavefirma)
Ottiene l'elenco degli input SignatureDefs per il metodo signatureKey .
Corda[]
getSignatureKeys ()
Ottiene l'elenco dei nomi dei metodi esportati SignatureDef disponibili nel modello.
Corda[]
getSignatureOutputs ( stringa chiavefirma)
Ottiene l'elenco degli output SignatureDefs per il metodo signatureKey .
vuoto
resetVariableTensors ()
Avanzato: reimposta tutti i tensori variabili sul valore predefinito.
vuoto
resizeInput (int idx, int[] dims, booleano rigoroso)
Ridimensiona l'idx-esimo input del modello nativo alle dimensioni specificate.
vuoto
resizeInput (int idx, int[] dims)
Ridimensiona l'idx-esimo input del modello nativo alle dimensioni specificate.
vuoto
esegui (input oggetto , output oggetto )
Esegue l'inferenza del modello se il modello accetta un solo input e fornisce un solo output.
vuoto
runForMultipleInputsOutputs (ingressi Object[] , output Map < Integer , Object >)
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, presupponendo che il modello abbia una SignatureDef.
vuoto
runSignature ( Map < String , Object > input, Map < String , Object > output, String SignatureKey)
Esegue l'inferenza del modello in base a SignatureDef fornita tramite signatureKey .
vuoto
setCancelled (booleano cancellato)
Avanzato: interrompe l'inferenza nel mezzo di una chiamata a run(Object, Object) .

Metodi ereditati

Costruttori pubblici

Interprete pubblico ( File modelFile)

Inizializza un Interpreter .

Parametri
modelFile un file di un modello TF Lite pre-addestrato.
Lancia
IllegalArgumentException se modelFile non codifica un modello TensorFlow Lite valido.

Interprete pubblico ( file modelFile, opzioni Interpreter.Options )

Inizializza un Interpreter e specifica le opzioni per personalizzare il comportamento dell'interprete.

Parametri
modelFile un file di un modello TF Lite pre-addestrato
opzioni una serie di opzioni per personalizzare il comportamento dell'interprete
Lancia
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 dovrebbe 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 in byte di un modello.

Parametri
byteBuffer
Lancia
IllegalArgumentException se byteBuffer non è un MappedByteBuffer né un ByteBuffer diretto di nativeOrder.

Interprete pubblico (opzioni ByteBuffer byteBuffer, Interpreter.Options )

Inizializza un Interpreter con un ByteBuffer di un file modello e un set di Interpreter.Options personalizzati.

Il ByteBuffer non dovrebbe 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 in byte di un modello.

Parametri
byteBuffer
opzioni
Lancia
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 fornite.

Nota: questa chiamata è *puramente facoltativa*. L'allocazione del tensore avverrà automaticamente durante l'esecuzione se eventuali 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 con forma dinamica, nel qual caso la forma dell'output potrebbe non propagarsi completamente finché non viene eseguita l'inferenza.

pubblico vuoto chiudi ()

Rilascia le risorse associate all'istanza InterpreterApi .

public int getInputIndex ( String opName)

Ottiene l'indice di un input in base al nome operativo dell'input.

Parametri
opNome

Tensore pubblico getInputTensor (int inputIndex)

Ottiene il tensore associato all'indice di input fornito.

Parametri
inputIndex

public int getInputTensorCount ()

Ottiene il numero di tensori di input.

Tensore pubblico getInputTensorFromSignature ( String inputName, String SignatureKey)

Ottiene il tensore associato al nome di input fornito e al nome del metodo di firma.

ATTENZIONE: questa è un'API sperimentale e soggetta a modifiche.

Parametri
inputNome Inserisci il nome nella firma.
firmaKey La chiave della firma che identifica la SignatureDef, può essere nulla se il modello ha una firma.
Lancia
IllegalArgumentException se inputName o signatureKey è nullo o vuoto oppure è stato fornito un nome non valido.

public Long getLastNativeInferenceDurationNanoseconds ()

Restituisce i tempi di inferenza nativi.

public int getOutputIndex ( String opName)

Ottiene l'indice di un output in base al nome operativo dell'output.

Parametri
opNome

Tensore pubblico getOutputTensor (int outputIndex)

Ottiene il tensore associato all'indice di output fornito.

Nota: i dettagli del tensore di output (ad esempio, la forma) potrebbero non essere completamente popolati finché non viene eseguita l'inferenza. Se sono necessari 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), utilizzare 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
outputIndice

public int getOutputTensorCount ()

Ottiene il numero di tensori di output.

Tensore pubblico getOutputTensorFromSignature ( String outputName, String SignatureKey)

Ottiene il tensore 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 finché non viene eseguita l'inferenza. Se sono necessari 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), utilizzare 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 e soggetta a modifiche.

Parametri
nomeuscita Nome di output nella firma.
firmaKey La chiave della firma che identifica la SignatureDef, può essere nulla se il modello ha una firma.
Lancia
IllegalArgumentException se outputName o signatureKey è nullo o vuoto oppure è stato fornito un nome non valido.

public String[] getSignatureInputs ( String SignatureKey)

Ottiene l'elenco degli input SignatureDefs per il metodo signatureKey .

ATTENZIONE: questa è un'API sperimentale e soggetta a modifiche.

Parametri
firmaKey

public String[] getSignatureKeys ()

Ottiene l'elenco dei nomi dei metodi esportati SignatureDef disponibili nel modello.

ATTENZIONE: questa è un'API sperimentale e soggetta a modifiche.

public String[] getSignatureOutputs ( String SignatureKey)

Ottiene l'elenco degli output SignatureDefs per il metodo signatureKey .

ATTENZIONE: questa è un'API sperimentale e soggetta a modifiche.

Parametri
firmaKey

public void resetVariableTensors ()

Avanzato: reimposta tutti i tensori variabili sul valore predefinito.

Se un tensore variabile non ha un buffer associato, verrà ripristinato a zero.

ATTENZIONE: questa è un'API sperimentale e soggetta a modifiche.

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

Ridimensiona l'idx-esimo input del modello nativo alle dimensioni specificate.

Quando "strict" è True, è possibile ridimensionare solo le dimensioni sconosciute. Le dimensioni sconosciute sono indicate come "-1" nell'array restituito da "Tensor.shapeSignature()".

Parametri
idx
si attenua
rigoroso

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

Ridimensiona l'idx-esimo input del modello nativo alle dimensioni specificate.

Parametri
idx
si attenua

esecuzione public void (input oggetto , output oggetto )

Esegue l'inferenza del modello se il modello accetta un solo input e fornisce un solo output.

Avvertenza: l'API è più efficiente se viene utilizzato un Buffer (preferibilmente diretto, ma non obbligatorio) come tipo di dati di input/output. Considera l'utilizzo Buffer per alimentare e recuperare dati primitivi per prestazioni migliori. Sono supportati i seguenti tipi Buffer concreti:

  • ByteBuffer : compatibile con qualsiasi tipo di tensore primitivo sottostante.
  • FloatBuffer : compatibile con tensori float.
  • IntBuffer : compatibile con i tensori int32.
  • LongBuffer : compatibile con i tensori int64.
Tieni presente che i tipi booleani sono supportati solo come array, non Buffer o come input scalari.

Parametri
ingresso un array o un array multidimensionale oppure un 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 Buffer , il suo contenuto dovrebbe rimanere invariato finché 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 un array multidimensionale di dati di output o un 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 nullo, utile in alcuni casi, ad esempio se il chiamante utilizza un Delegate che consente l'interoperabilità della gestione del buffer e tale buffer è stato associato al Tensor di output (vedere anche Interpreter.Options#setAllowBufferHandleOutput(boolean) ), o se il grafico ha output con forma dinamica e il chiamante deve interrogare la forma Tensor output dopo che è stata invocata l'inferenza, recuperando i dati direttamente dal tensore di output (tramite Tensor.asReadOnlyBuffer() ).

public void runForMultipleInputsOutputs ( Object[] input, 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. Considera l'utilizzo Buffer per alimentare e recuperare dati primitivi per prestazioni migliori. Sono supportati i seguenti tipi Buffer concreti:

  • ByteBuffer : compatibile con qualsiasi tipo di tensore primitivo sottostante.
  • FloatBuffer : compatibile con tensori float.
  • IntBuffer : compatibile con i tensori int32.
  • LongBuffer : compatibile con i tensori int64.
Tieni presente che i tipi booleani sono supportati solo come array, non Buffer o come input scalari.

Nota: 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 ai corrispondenti Tensor di input o output.

Parametri
input una matrice di dati di input. Gli input dovrebbero 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 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 Buffer , il suo contenuto dovrebbe rimanere invariato finché non viene eseguita l'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 tra cui int, float, long e byte. È sufficiente conservare le voci relative agli 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 nei 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 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, presupponendo che il modello abbia una SignatureDef. Se il modello ha più di una SignatureDef genererà un'eccezione.

ATTENZIONE: questa è un'API sperimentale e soggetta a modifiche.

Parametri
input
uscite

public void runSignature ( Map < String , Object > input, Map < String , Object > output, String SignatureKey)

Esegue l'inferenza del modello in base a SignatureDef fornita tramite signatureKey .

Vedere run(Object, Object) per ulteriori dettagli sui tipi di dati di input e output consentiti.

ATTENZIONE: questa è un'API sperimentale e soggetta a modifiche.

Parametri
input 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 di output è dinamica o vengono utilizzati gli handle del buffer di output).
firmaKey Chiave di firma che identifica SignatureDef.
Lancia
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 cancellato)

Avanzato: interrompe l'inferenza nel mezzo di una chiamata a run(Object, Object) .

Un flag di annullamento verrà impostato su true quando viene chiamata questa funzione. L'interprete controllerà il flag tra le invocazioni Op e, se è true , l'interprete interromperà l'esecuzione. L'interprete rimarrà in uno stato annullato finché non verrà esplicitamente "non annullato" da setCancelled(false) .

ATTENZIONE: questa è un'API sperimentale e soggetta a modifiche.

Parametri
annullato true per annullare l'inferenza nel modo migliore possibile; false per riprendere.
Lancia
IllegalStateException se l'interprete non è inizializzato con l'opzione cancellabile, che per impostazione predefinita è disattivata.