Interpreter

public final class Interpreter

Treiberklasse zur Förderung von Modellinferenzen mit TensorFlow Lite.

Hinweis: Wenn Sie keinen Zugriff auf die unten aufgeführten „experimentellen“ API-Funktionen benötigen, sollten Sie InterpreterApi und InterpreterFactory statt direkt verwenden.

Ein Interpreter kapselt ein vortrainiertes TensorFlow Lite-Modell ein, in dem Vorgänge zur Modellinferenz ausgeführt werden.

Wenn ein Modell beispielsweise nur eine Eingabe annimmt und nur eine Ausgabe zurückgibt: 

try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
   interpreter.run(input, output);
 }

Wenn ein Modell mehrere Ein- oder Ausgaben annimmt: 

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

Wenn ein Modell Stringtensoren annimmt oder erzeugt: 

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

Beachten Sie, dass es einen Unterschied zwischen Form [] und Form [1] gibt. Für skalare String-Tensor-Ausgaben: 

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

Die Reihenfolge der Eingaben und Ausgaben wird bestimmt, wenn das TensorFlow-Modell mit Toco in ein TensorFlowLite-Modell konvertiert wird, ebenso wie die Standardformen der Eingaben.

Wenn Eingaben als (mehrdimensionale) Arrays bereitgestellt werden, wird die Größe der entsprechenden Eingabetensor(en) implizit entsprechend der Form dieses Arrays angepasst. Wenn Eingaben als Buffer-Typen bereitgestellt werden, erfolgt keine implizite Größenanpassung. Der Aufrufer muss dafür sorgen, dass die Bytegröße Buffer entweder mit der Größe des entsprechenden Tensors übereinstimmt oder dass die Größe des Tensors zuerst über resizeInput(int, int[]) skaliert wird. Informationen zu Tensorform und -typ können über die Klasse Tensor abgerufen werden, die über getInputTensor(int) und getOutputTensor(int) verfügbar ist.

WARNUNG:Interpreter-Instanzen sind nicht Thread-sicher. Ein Interpreter besitzt Ressourcen, die durch Aufrufen von close() explizit freigegeben werden müssen

Die TFLite-Bibliothek basiert auf NDK API 19. Sie kann auch bei Android-API-Levels unter 19 funktionieren, ist jedoch nicht garantiert.

Verschachtelte Klassen

Klasse Interpreter.Options Eine Optionsklasse zur Steuerung des Verhaltens des Laufzeitinterpreters. 

Public Constructors

Interpreter(Datei, Modelldatei)
Initialisiert ein Interpreter.
Interpreter(Datei modelFile, Interpreter.Options-Optionen)
Initialisiert ein Interpreter und gibt Optionen zum Anpassen des Verhaltens des Interpreters an.
Interpreter(ByteBuffer byteBuffer)
Initialisiert ein Interpreter mit einer ByteBuffer einer Modelldatei.
Interpreter(Optionen für ByteBuffer mit byteBuffer, Interpreter.Options)
Initialisiert ein Interpreter mit einem ByteBuffer einer Modelldatei und einem Satz benutzerdefinierter Interpreter.Options.

Public Methods

void
allocateTensors() zu
Aktualisiert bei Bedarf explizit Zuweisungen für alle Tensoren.
void
close()
Geben Sie Ressourcen frei, die mit der Instanz InterpreterApi verknüpft sind.
int
getInputIndex(String opName)
Ruft den Index einer Eingabe anhand des Vorgangsnamens der Eingabe ab.
Tensor
getInputTensor(int inputIndex)
Ruft den Tensor ab, der dem bereitgestellten Eingabeindex zugeordnet ist.
int
getInputTensorCount()
Ruft die Anzahl der Eingabetensoren ab.
Tensor
getInputTensorFromSignature(String inputName, String signatureKey)
Ruft den Tensor ab, der dem angegebenen Eingabenamen und Namen der Signaturmethode zugeordnet ist.
Lang
getLastNativeInferenceDurationNanoseconds()
Gibt das Timing der nativen Inferenz zurück.
int
getOutputIndex(String opName)
Ruft den Index einer Ausgabe anhand des Vorgangsnamens der Ausgabe ab.
Tensor
getOutputTensor(int outputIndex)
Ruft den Tensor ab, der dem bereitgestellten Ausgabeindex zugeordnet ist.
int
getOutputTensorCount()
Ruft die Anzahl der Ausgabe-Tensoren ab.
Tensor
getOutputTensorFromSignature(String outputName, String signatureKey)
Ruft den Tensor ab, der dem angegebenen Ausgabenamen in einer bestimmten Signaturmethode zugeordnet ist.
String[]
getSignatureInputs(String signatureKey)
Ruft die Liste der SignatureDefs-Eingaben für die Methode signatureKey ab.
String[]
getSignatureKeys()
Ruft die Liste der nach SignatureDef exportierten Methodennamen ab, die im Modell verfügbar sind.
String[]
getSignatureOutputs(String signatureKey)
Ruft die Liste der SignatureDefs-Ausgaben für die Methode signatureKey ab.
void
resetVariableTensors()
Erweitert: Setzt alle Variablentensoren auf den Standardwert zurück.
void
resizeInput(int idx, int[] dims, boolean strict)
Passt die Größe der idx-ten Eingabe des nativen Modells an die angegebenen Dimmungen an.
void
resizeInput(int idx, int[] dimm)
Passt die Größe der idx-ten Eingabe des nativen Modells an die angegebenen Dimmungen an.
void
run(Objekt-Eingabe, Objekt-Ausgabe)
Führt eine Modellinferenz aus, wenn das Modell nur eine Eingabe annimmt und nur eine Ausgabe liefert.
void
runForMultipleInputsOutputs(Object[]-Eingaben, Map<Integer, Object>-Ausgaben)
Führt eine Modellinferenz aus, wenn das Modell mehrere Eingaben annimmt oder mehrere Ausgaben zurückgibt.
void
runSignature(Map<String, Object>-Eingaben, Map<String, Objekt>-Ausgaben)
Wie runSignature(Map, Map, String), erfordert jedoch keine Übergabe eines signatureKey, vorausgesetzt, das Modell hat eine SignatureDef-Funktion.
void
runSignature(Map<String, Object>-Eingaben, Map<String, Objekt>-Ausgaben, String signatureKey)
Führt Modellinferenz auf Basis von SignatureDef aus, die über signatureKey bereitgestellt werden.
void
setCancelled(Boolescher Wert abgebrochen)
Fortgeschritten: Unterbricht Inferenz in der Mitte eines Aufrufs an run(Object, Object).

Übernommene Methoden

Public Constructors

public Interpreter (Datei modelFile)

Initialisiert ein Interpreter.

Parameter
modelFile Datei eines vortrainierten TF Lite-Modells.
Löst aus
IllegalArgumentException modelFile codiert kein gültiges TensorFlow Lite-Modell.

public Interpreter (File modelFile, Interpreter.Options-Optionen)

Initialisiert ein Interpreter und gibt Optionen zum Anpassen des Verhaltens des Interpreters an.

Parameter
modelFile Eine Datei eines vortrainierten TF Lite-Modells
Optionen eine Reihe von Optionen zum Anpassen des Verhaltens des Interpreters
Löst aus
IllegalArgumentException modelFile codiert kein gültiges TensorFlow Lite-Modell.

public Interpreter (ByteBuffer byteBuffer)

Initialisiert ein Interpreter mit einer ByteBuffer einer Modelldatei.

ByteBuffer sollte nach der Konstruktion eines Interpreter nicht mehr geändert werden. Die ByteBuffer kann entweder eine MappedByteBuffer sein, die eine Modelldatei zuordnet, oder ein direkter ByteBuffer von nativeOrder(), der den Byteinhalt eines Modells enthält.

Parameter
byteBuffer
Löst aus
IllegalArgumentException wenn byteBuffer weder ein MappedByteBuffer noch ein direktes ByteBuffer von nativeOrder ist.

public Interpreter (ByteBuffer byteBuffer, Interpreter.Options-Optionen)

Initialisiert ein Interpreter mit einem ByteBuffer einer Modelldatei und einem Satz benutzerdefinierter Interpreter.Options.

Das ByteBuffer sollte nach der Erstellung eines Interpreter nicht mehr geändert werden. Die ByteBuffer kann entweder eine MappedByteBuffer sein, die eine Modelldatei zuordnet, oder ein direkter ByteBuffer von nativeOrder(), der den Byteinhalt eines Modells enthält.

Parameter
byteBuffer
Optionen
Löst aus
IllegalArgumentException wenn byteBuffer weder ein MappedByteBuffer noch ein direktes ByteBuffer von nativeOrder ist.

Public Methods

public void allocateTensors ()

Aktualisiert bei Bedarf explizit Zuweisungen für alle Tensoren.

Dadurch werden Formen und Speicherzuweisungen für abhängige Tensoren mithilfe der angegebenen Eingabetensor-Formen weitergegeben.

Hinweis: Dieser Aufruf ist *rein optional*. Die Tensorzuordnung erfolgt automatisch während der Ausführung, wenn die Größe von Eingabetensoren geändert wurde. Dieser Aufruf ist am nützlichsten, um die Formen für alle Ausgabetensoren zu bestimmen, bevor der Graph ausgeführt wird. Beispiel: 

 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...

Hinweis: Einige Diagramme haben dynamisch geformte Ausgaben. In diesem Fall wird die Ausgabeform erst vollständig übernommen, wenn die Inferenz ausgeführt wurde.

public void close ()

Geben Sie Ressourcen frei, die mit der Instanz InterpreterApi verknüpft sind.

public int getInputIndex (String opName)

Ruft den Index einer Eingabe anhand des Vorgangsnamens der Eingabe ab.

Parameter
opName

public Tensor getInputTensor (int inputIndex)

Ruft den Tensor ab, der dem bereitgestellten Eingabeindex zugeordnet ist.

Parameter
inputIndex

public int getInputTensorCount ()

Ruft die Anzahl der Eingabetensoren ab.

public Tensor getInputTensorFromSignature (String inputName, String signatureKey)

Ruft den Tensor ab, der dem angegebenen Eingabenamen und Namen der Signaturmethode zugeordnet ist.

WARNUNG: Dies ist eine experimentelle API, die sich noch ändern kann.

Parameter
inputName Geben Sie den Namen in die Signatur ein.
signatureKey Signaturschlüssel zur Identifizierung von SignatureDef. Der Schlüssel kann null sein, wenn das Modell eine Signatur hat.
Löst aus
IllegalArgumentException wenn inputName oder signatureKey null oder leer ist oder ein ungültiger Name angegeben wurde.

public Lang getLastNativeInferenceDurationNanoseconds ()

Gibt das Timing der nativen Inferenz zurück.

public int getOutputIndex (String opName)

Ruft den Index einer Ausgabe anhand des Vorgangsnamens der Ausgabe ab.

Parameter
opName

public Tensor getOutputTensor (int outputIndex)

Ruft den Tensor ab, der dem bereitgestellten Ausgabeindex zugeordnet ist.

Hinweis: Die Ausgabetensordetails (z.B. die Form) werden möglicherweise erst nach der Ausführung der Inferenz vollständig ausgefüllt. Wenn Sie die Details aktualisieren müssen, *bevor* Sie die Inferenz ausführen (z.B. nach der Größenänderung eines Eingabetensors, der die Form des Ausgabetensors ungültig machen kann), verwenden Sie allocateTensors(), um die Zuweisung und Formweitergabe explizit auszulösen. Bei Grafiken mit Ausgabeformen, die von *Eingabewerten* abhängig sind, kann die Ausgabeform erst nach der Ausführung der Inferenz vollständig bestimmt werden.

Parameter
outputIndex

public int getOutputTensorCount ()

Ruft die Anzahl der Ausgabe-Tensoren ab.

public Tensor getOutputTensorFromSignature (String outputName, String signatureKey)

Ruft den Tensor ab, der dem angegebenen Ausgabenamen in einer bestimmten Signaturmethode zugeordnet ist.

Hinweis: Die Ausgabetensordetails (z.B. die Form) werden möglicherweise erst nach der Ausführung der Inferenz vollständig ausgefüllt. Wenn Sie die Details aktualisieren müssen, *bevor* Sie die Inferenz ausführen (z.B. nach der Größenänderung eines Eingabetensors, der die Form des Ausgabetensors ungültig machen kann), verwenden Sie allocateTensors(), um die Zuweisung und Formweitergabe explizit auszulösen. Bei Grafiken mit Ausgabeformen, die von *Eingabewerten* abhängig sind, kann die Ausgabeform erst nach der Ausführung der Inferenz vollständig bestimmt werden.

WARNUNG: Dies ist eine experimentelle API, die sich noch ändern kann.

Parameter
outputName Ausgabename in der Signatur.
signatureKey Signaturschlüssel zur Identifizierung von SignatureDef. Der Schlüssel kann null sein, wenn das Modell eine Signatur hat.
Löst aus
IllegalArgumentException wenn outputName oder signatureKey null oder leer ist oder ein ungültiger Name angegeben wurde.

public String[] getSignatureInputs (String signatureKey)

Ruft die Liste der SignatureDefs-Eingaben für die Methode signatureKey ab.

WARNUNG: Dies ist eine experimentelle API, die sich noch ändern kann.

Parameter
signatureKey

public String[] getSignatureKeys ()

Ruft die Liste der nach SignatureDef exportierten Methodennamen ab, die im Modell verfügbar sind.

WARNUNG: Dies ist eine experimentelle API, die sich noch ändern kann.

public String[] getSignatureOutputs (String signatureKey)

Ruft die Liste der SignatureDefs-Ausgaben für die Methode signatureKey ab.

WARNUNG: Dies ist eine experimentelle API, die sich noch ändern kann.

Parameter
signatureKey

public void resetVariableTensors ()

Erweitert: Setzt alle Variablentensoren auf den Standardwert zurück.

Wenn einem Variablentensor kein Zwischenspeicher zugeordnet ist, wird er auf null zurückgesetzt.

WARNUNG: Dies ist eine experimentelle API, die sich noch ändern kann.

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

Passt die Größe der idx-ten Eingabe des nativen Modells an die angegebenen Dimmungen an.

Wenn „strict“ auf „True“ gesetzt ist, kann die Größe nur unbekannter Abmessungen geändert werden. Unbekannte Dimensionen werden im von „Tensor.shapeSignature()“ zurückgegebenen Array mit „-1“ angegeben.

Parameter
idx
dims
Strikt

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

Passt die Größe der idx-ten Eingabe des nativen Modells an die angegebenen Dimmungen an.

Parameter
idx
dims

public void run (Objekt-Eingabe, Objekt--Ausgabe)

Führt eine Modellinferenz aus, wenn das Modell nur eine Eingabe annimmt und nur eine Ausgabe liefert.

Warnung: Die API ist effizienter, wenn als Eingabe-/Ausgabedatentyp Buffer verwendet wird (am besten direkt, aber nicht erforderlich). Sie sollten Buffer verwenden, um primitive Daten zu erfassen und abzurufen und so eine bessere Leistung zu erzielen. Die folgenden konkreten Buffer-Typen werden unterstützt:

  • ByteBuffer – kompatibel mit allen zugrunde liegenden primitiven Tensortypen
  • FloatBuffer – kompatibel mit Float-Tensoren.
  • IntBuffer – kompatibel mit int32-Tensoren
  • LongBuffer – kompatibel mit int64-Tensoren.
Boolesche Typen werden nur als Arrays, nicht als Buffers oder als skalare Eingaben unterstützt.

Parameter
Eingabe Ein Array oder ein mehrdimensionales Array oder ein Buffer mit primitiven Typen wie „int“, „Gleitkommazahl“, „long“ und „byte“. Buffer ist die bevorzugte Methode zum Übergeben großer Eingabedaten für primitive Typen, während für Stringtypen der (mehrdimensionale) Array-Eingabepfad verwendet werden muss. Wenn ein Buffer verwendet wird, sollte sein Inhalt unverändert bleiben, bis die Modellinferenz abgeschlossen ist. Der Aufrufer muss dann dafür sorgen, dass sich Buffer an der entsprechenden Leseposition befindet. Ein null-Wert ist nur zulässig, wenn der Aufrufer eine Delegate verwendet, die Interoperabilität mit Zwischenspeichern zulässt und ein solcher Zwischenspeicher an die Eingabe-Tensor gebunden wurde.
output Ein mehrdimensionales Array von Ausgabedaten oder eine Buffer mit primitiven Typen wie „int“, „Gleitkommazahl“, „long“ und „byte“. Wenn ein Buffer verwendet wird, muss der Aufrufer dafür sorgen, dass die entsprechende Schreibposition festgelegt ist. Ein Nullwert ist zulässig und ist in bestimmten Fällen nützlich, z. B. wenn der Aufrufer einen Delegate verwendet, der die Zwischenspeicher-Handle-Interop zulässt, und ein solcher Zwischenspeicher an die Ausgabe-Tensor gebunden wurde (siehe auch Interpreter.Options#setAllowBufferHandleOutput(boolean)). Oder wenn der Graph über die dynamisch geformten Ausgaben dynamisch geformt ist und der Aufrufer die Ausgabe-Tensor-Form nach der Ausgabe-Inferenz aufgerufen hat und der Aufrufer die Ausgabe-Tensor-Form direkt nach der Ausgabe-Inferenz abfragen muss.Tensor.asReadOnlyBuffer()

public void runForMultipleInputsOutputs (Object[]-Eingaben, Map<Ganzzahl, Objekt->-Ausgaben)

Führt eine Modellinferenz aus, wenn das Modell mehrere Eingaben annimmt oder mehrere Ausgaben zurückgibt.

Warnung: Die API ist effizienter, wenn als Eingabe-/Ausgabedatentypen Buffers verwendet werden (am besten direkt, aber nicht erforderlich). Sie sollten Buffer verwenden, um primitive Daten zu erfassen und abzurufen und so eine bessere Leistung zu erzielen. Die folgenden konkreten Buffer-Typen werden unterstützt:

  • ByteBuffer – kompatibel mit allen zugrunde liegenden primitiven Tensortypen
  • FloatBuffer – kompatibel mit Float-Tensoren.
  • IntBuffer – kompatibel mit int32-Tensoren
  • LongBuffer – kompatibel mit int64-Tensoren.
Boolesche Typen werden nur als Arrays, nicht als Buffers oder als skalare Eingaben unterstützt.

Hinweis: null-Werte für einzelne Elemente von inputs und outputs sind nur zulässig, wenn der Aufrufer einen Delegate verwendet, der Interoperabilität mit Zwischenspeichern zulässt, und ein solcher Zwischenspeicher an die entsprechenden Eingabe- oder Ausgabe-Tensors gebunden wurde.

Parameter
Eingaben ein Array von Eingabedaten. Die Eingaben sollten in derselben Reihenfolge wie die Eingaben des Modells sein. Jede Eingabe kann ein Array oder ein mehrdimensionales Array oder ein Buffer mit primitiven Typen wie „int“, „Gleitkommazahl“, „long“ und „byte“ sein. Buffer ist die bevorzugte Methode zum Übergeben großer Eingabedaten, während für Stringtypen der (mehrdimensionale) Array-Eingabepfad verwendet werden muss. Wenn Buffer verwendet wird, sollte sein Inhalt unverändert bleiben, bis die Modellinferenz abgeschlossen ist. Der Aufrufer muss dann dafür sorgen, dass sich Buffer an der entsprechenden Leseposition befindet.
Ausgaben Eine Karte, die Ausgabeindexe mehrdimensionalen Arrays von Ausgabedaten oder Buffers primitiver Typen wie „int“, „Gleitkommazahl“, „long“ und „byte“ zuordnet. Es müssen nur Einträge gespeichert werden, damit die Ausgaben verwendet werden können. Wenn ein Buffer verwendet wird, muss der Aufrufer dafür sorgen, dass die entsprechende Schreibposition festgelegt ist. Die Karte kann leer sein, wenn entweder Puffer-Handles für Ausgabetensordaten verwendet werden oder in denen die Ausgaben dynamisch geformt werden und der Aufrufer die Ausgabeform Tensor nach dem Aufrufen der Inferenz abfragen muss, um die Daten direkt vom Ausgabetensor (über Tensor.asReadOnlyBuffer()) abzurufen.

public void runSignature (Map<String, Object>-Eingaben, Map<String, Object>-Ausgaben)

Wie runSignature(Map, Map, String), erfordert jedoch keine Übergabe eines signatureKey, vorausgesetzt, das Modell hat eine SignatureDef-Funktion. Wenn das Modell mehr als ein SignatureDef-Element hat, wird eine Ausnahme ausgelöst.

WARNUNG: Dies ist eine experimentelle API, die sich noch ändern kann.

Parameter
Eingaben
Ausgaben

public void runSignature (Map<String, Object>-Eingaben, Map<String, Objekt>-Ausgaben, String signatureKey)

Führt Modellinferenz auf Basis von SignatureDef aus, die über signatureKey bereitgestellt werden.

Weitere Informationen zu den zulässigen Eingabe- und Ausgabedatentypen finden Sie unter run(Object, Object).

WARNUNG: Dies ist eine experimentelle API, die sich noch ändern kann.

Parameter
Eingaben Eine Zuordnung des Eingabenamens in SignatureDef zu einem Eingabeobjekt.
Ausgaben Eine Zuordnung vom Ausgabenamen in SignatureDef zu den Ausgabedaten. Dieses Feld kann leer sein, wenn der Aufrufer die Tensor-Daten direkt nach der Inferenz abfragen möchte, z.B. wenn die Ausgabeform dynamisch ist oder Ausgabepuffer-Handles verwendet werden.
signatureKey Signaturschlüssel zur Identifizierung von SignatureDef.
Löst aus
IllegalArgumentException Wenn inputs null oder leer ist, wenn outputs oder signatureKey null ist oder wenn beim Ausführen einer Inferenz ein Fehler auftritt.

public void setCancelled (boolean cancelled)

Fortgeschritten: Unterbricht Inferenz in der Mitte eines Aufrufs an run(Object, Object).

Ein Abbruch-Flag wird auf „true“ gesetzt, wenn diese Funktion aufgerufen wird. Der Interpreter prüft das Flag zwischen den Vorgangsaufrufen. Wenn der Wert true lautet, beendet der Interpreter die Ausführung. Der Interpreter bleibt so lange abgebrochen, bis er von setCancelled(false) explizit „uncancelled“ erhält.

WARNUNG: Dies ist eine experimentelle API, die sich noch ändern kann.

Parameter
storniert true, um die Inferenz bestmöglich abzubrechen; false, um fortzufahren.
Löst aus
IllegalStateException Der Interpreter wurde nicht mit der Option „Kündigung“ initialisiert. Diese ist standardmäßig deaktiviert.
Weitere Informationen