InterpreterApi

interfaccia pubblica InterpreterApi
Sottoclassi indirette note

Interfaccia per l'interprete del modello TensorFlow Lite, esclusi i metodi sperimentali.

Un'istanza InterpreterApi 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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 (InterpreterApi interpreter =
     new InterpreterApi.create(file_of_a_tensorflowlite_model)) {
   interpreter.runForMultipleInputsOutputs(inputs, map_of_indices_to_outputs);
 }

Se un modello accetta o produce tensori stringa: 

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);
 }

Si noti che esiste una distinzione tra forma [] e forma[1]. Per gli output del tensore 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 tensori di input corrispondenti verranno ridimensionati implicitamente in base alla forma dell'array. Quando gli input vengono forniti come tipi 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 ridimensioni prima 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 InterpreterApi non sono thread-safe.

ATTENZIONE: un'istanza InterpreterApi possiede risorse che devono essere esplicitamente liberate richiamando close()

La libreria TFLite è basata su API NDK 19. Potrebbe funzionare per livelli API Android inferiori a 19, ma non è garantito.

Classi nidificate

classe InterpreterApi.Options Una classe di opzioni per controllare il comportamento dell'interprete di runtime.

Metodi pubblici

vuoto astratto
allocateTensors ()
Aggiorna in modo esplicito le allocazioni per tutti i tensori, se necessario.
vuoto astratto
chiudere ()
Rilascia le risorse associate all'istanza InterpreterApi .
InterpreterApi statico
create ( opzioni File modelFile, InterpreterApi.Options )
Costruisce un'istanza InterpreterApi , utilizzando il modello e le opzioni specificati.
InterpreterApi statico
create ( opzioni ByteBuffer byteBuffer, InterpreterApi.Options )
Costruisce un'istanza InterpreterApi , utilizzando il modello e le opzioni specificati.
astratto int
getInputIndex ( String opName)
Ottiene l'indice di un input dato il nome op dell'input.
Tensore astratto
getInputTensor (int inputIndex)
Ottiene il tensore associato all'indice di input fornito.
astratto int
getInputTensorCount ()
Ottiene il numero di tensori di input.
astratto Lungo
getLastNativeInferenceDurationNanoseconds ()
Restituisce il tempo di inferenza nativo.
astratto int
getOutputIndex ( String opName)
Ottiene l'indice di un output dato il nome op dell'output.
Tensore astratto
getOutputTensor (int outputIndex)
Ottiene il tensore associato all'indice di output fornito.
astratto int
getOutputTensorCount ()
Ottiene il numero di tensori di output.
vuoto astratto
resizeInput (int idx, int[] dims, boolean strict)
Ridimensiona l'idx-esimo input del modello nativo alle dims fornite.
vuoto astratto
resizeInput (int idx, int[] dims)
Ridimensiona l'idx-esimo input del modello nativo alle dims fornite.
vuoto astratto
run (Input oggetto , Output oggetto )
Esegue l'inferenza del modello se il modello accetta un solo input e fornisce un solo output.
vuoto astratto
runForMultipleInputsOutputs ( Object[] input, Map < Integer , Object > output)
Esegue l'inferenza del modello se il modello accetta più input o restituisce più output.

Metodi ereditati

Metodi pubblici

public abstract void allocateTensors ()

Aggiorna in modo esplicito 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 è particolarmente 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.

Getta
IllegalStateException se non è stato possibile allocare correttamente i tensori del grafo.

public abstract void close ()

Rilascia le risorse associate all'istanza InterpreterApi .

public static InterpreterApi create ( opzioni File modelFile, InterpreterApi.Options )

Costruisce un'istanza InterpreterApi , utilizzando il modello e le opzioni specificati. Il modello verrà caricato da un file.

Parametri
modelFile Un file contenente un modello TF Lite pre-addestrato.
opzioni Una serie di opzioni per personalizzare il comportamento dell'interprete.
Getta
IllegalArgumentException se modelFile non codifica un modello TensorFlow Lite valido.

public static InterpreterApi create ( opzioni ByteBuffer byteBuffer, InterpreterApi.Options )

Costruisce un'istanza InterpreterApi , utilizzando il modello e le opzioni specificati. Il modello verrà letto da un ByteBuffer .

Parametri
byteBuffer Un modello TF Lite pre-addestrato, in formato serializzato binario. Il ByteBuffer non deve essere modificato dopo la costruzione di un'istanza InterpreterApi . Il ByteBuffer può essere un MappedByteBuffer che mappa in memoria un file modello o un ByteBuffer diretto di nativeOrder() che contiene il contenuto in byte di un modello.
opzioni Una serie di opzioni per personalizzare il comportamento dell'interprete.
Getta
IllegalArgumentException se byteBuffer non è un MappedByteBuffer né un ByteBuffer diretto di nativeOrder.

public abstract int getInputIndex ( String opName)

Ottiene l'indice di un input dato il nome op dell'input.

Parametri
opNome
Getta
IllegalArgumentException se opName non corrisponde ad alcun input nel modello utilizzato per inizializzare l'interprete.

public abstract Tensor getInputTensor (int inputIndex)

Ottiene il tensore associato all'indice di input fornito.

Parametri
inputIndex
Getta
IllegalArgumentException se inputIndex è negativo o non è inferiore al numero di input del modello.

public abstract int getInputTensorCount ()

Ottiene il numero di tensori di input.

public abstract Long getLastNativeInferenceDurationNanoseconds ()

Restituisce il tempo di inferenza nativo.

Getta
IllegalArgumentException se il modello non è inizializzato dall'interprete.

public abstract int getOutputIndex ( String opName)

Ottiene l'indice di un output dato il nome op dell'output.

Parametri
opNome
Getta
IllegalArgumentException se opName non corrisponde ad alcun output nel modello utilizzato per inizializzare l'interprete.

public abstract Tensor 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 completati fino a quando 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), 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
Getta
IllegalArgumentException se outputIndex è negativo o non è inferiore al numero di output del modello.

public abstract int getOutputTensorCount ()

Ottiene il numero di tensori di output.

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

Ridimensiona l'idx-esimo input del modello nativo alle dims fornite.

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
attenua
rigoroso
Getta
IllegalArgumentException se idx è negativo o non è inferiore al numero di input del modello; o se si verifica un errore durante il ridimensionamento dell'idx-esimo input. Inoltre, l'errore si verifica quando si tenta di ridimensionare un tensore con dimensioni fisse quando `strict` è True.

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

Ridimensiona l'idx-esimo input del modello nativo alle dims fornite.

Parametri
idx
attenua
Getta
IllegalArgumentException se idx è negativo o non è inferiore al numero di input del modello; o se si verifica un errore durante il ridimensionamento dell'idx-esimo input.

public abstract void run (Input 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. Si prega di prendere in considerazione l'utilizzo Buffer per alimentare e recuperare dati primitivi per prestazioni migliori. Sono supportati i seguenti tipi Buffer concreti:

  • ByteBuffer - compatibile con qualsiasi tipo Tensor primitivo sottostante.
  • FloatBuffer - compatibile con tensori float.
  • IntBuffer - compatibile con tensori int32.
  • LongBuffer - compatibile con tensori int64.
Si noti che i tipi booleani sono supportati solo come array, non 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 usa un Delegate che consente l'interoperabilità dell'handle del buffer e tale buffer è stato associato all'input Tensor .
produzione un array 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. Un valore nullo è consentito ed è 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 al Tensor di output (vedere anche Interpreter.Options#setAllowBufferHandleOutput(boolean) ) o se il grafico ha output di 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() ).
Getta
IllegalArgumentException se input è nullo o vuoto o se si verifica un errore durante l'esecuzione dell'inferenza.
IllegalArgumentException (SPERIMENTALE, soggetto a modifiche) se l'inferenza viene interrotta da setCancelled(true) .

public abstract void runForMultipleInputsOutputs ( Object[] input, Map < Integer , Object > output)

Esegue l'inferenza del modello se il modello accetta più input o restituisce più output.

Avviso: l'API è più efficiente se Buffer s (preferibilmente diretti, ma non obbligatori) vengono utilizzati come tipi di dati di input/output. Si prega di prendere in considerazione l'utilizzo Buffer per alimentare e recuperare dati primitivi per prestazioni migliori. Sono supportati i seguenti tipi Buffer concreti:

  • ByteBuffer - compatibile con qualsiasi tipo Tensor primitivo sottostante.
  • FloatBuffer - compatibile con tensori float.
  • IntBuffer - compatibile con tensori int32.
  • LongBuffer - compatibile con tensori int64.
Si noti che i tipi booleani sono supportati solo come array, non Buffer o come input scalari.

Nota: i valori null per i singoli elementi di inputs e outputs sono consentiti solo se il chiamante utilizza un Delegate che consente l'interoperabilità dell'handle del buffer e tale buffer è stato associato al corrispondente Tensor di input o output.

Parametri
ingressi una matrice 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 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 Buffer , il suo contenuto dovrebbe rimanere invariato fino a quando non viene eseguita l'inferenza del modello e il chiamante deve assicurarsi che 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 mantenere le voci per le uscite 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 i casi in cui gli output sono modellati dinamicamente 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() ).
Getta
IllegalArgumentException se inputs è nullo o vuoto, se outputs è nullo o se si verifica un errore durante l'esecuzione dell'inferenza.