Interpreter

Publiczny tłumacz zajęć końcowych

Klasa sterownika do sterowania wnioskowaniem modelu za pomocą TensorFlow Lite.

Uwaga: jeśli nie potrzebujesz dostępu do żadnej z poniższych „eksperymentalnych” funkcji API, wolisz używać InterpreterApi i InterpreterFactory niż bezpośrednio używać Interpretera.

Interpreter hermetyzuje wstępnie wyszkolony model TensorFlow Lite, w którym wykonywane są operacje w celu wnioskowania o modelu.

Na przykład, jeśli model przyjmuje tylko jedno wejście i zwraca tylko jedno wyjście: 

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

Jeśli model przyjmuje wiele wejść i wyjść: 

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

Jeśli model przyjmuje lub produkuje tensory strun: 

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

Zauważ, że istnieje rozróżnienie pomiędzy kształtem [] i kształtem [1]. Dla wyjść skalarnego tensora strun: 

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

Kolejność danych wejściowych i wyjściowych jest określana podczas konwersji modelu TensorFlow na model TensorFlowLite za pomocą Toco, podobnie jak domyślne kształty danych wejściowych.

Gdy dane wejściowe są dostarczane jako tablice (wielowymiarowe), rozmiar odpowiadających tensorów wejściowych zostanie domyślnie zmieniony zgodnie z kształtem tej tablicy. Gdy dane wejściowe są podawane jako typy Buffer , nie jest wykonywana żadna niejawna zmiana rozmiaru; osoba wywołująca musi upewnić się, że rozmiar bajtu Buffer albo odpowiada rozmiarowi odpowiedniego tensora, albo najpierw zmienia rozmiar tensora za pomocą resizeInput(int, int[]) . Informacje o kształcie i typie tensora można uzyskać za pośrednictwem klasy Tensor , dostępnej poprzez getInputTensor(int) i getOutputTensor(int) .

OSTRZEŻENIE: Instancje Interpreter nie są bezpieczne dla wątków. Interpreter jest właścicielem zasobów, które muszą zostać jawnie zwolnione poprzez wywołanie funkcji close()

Biblioteka TFLite jest zbudowana w oparciu o NDK API 19. Może działać w przypadku poziomów API Androida poniżej 19, ale nie jest to gwarantowane.

Klasy zagnieżdżone

klasa Opcje tłumacza Klasa opcji służąca do kontrolowania zachowania interpretera środowiska wykonawczego.

Konstruktorzy publiczni

Interpreter ( plik modelFile)
Inicjuje Interpreter .
Interpreter (opcje File modelFile, Interpreter.Options )
Inicjuje Interpreter i określa opcje dostosowywania zachowania interpretera.
Interpreter ( ByteBuffer byteBuffer)
Inicjuje Interpreter za pomocą ByteBuffer pliku modelu.
Interpreter ( ByteBuffer byteBuffer, opcje Interpreter.Options )
Inicjuje Interpreter z ByteBuffer pliku modelu i zestawem niestandardowych Interpreter.Options .

Metody publiczne

próżnia
przydzielTensory ()
W razie potrzeby jawnie aktualizuje alokacje dla wszystkich tensorów.
próżnia
zamknąć ()
Zwolnij zasoby powiązane z instancją InterpreterApi .
wew
getInputIndex ( łańcuch opName)
Pobiera indeks wejścia, biorąc pod uwagę nazwę operacji wejścia.
Napinacz
getInputTensor (int inputIndex)
Pobiera Tensor skojarzony z podanym indeksem wejściowym.
wew
getInputTensorCount ()
Pobiera liczbę tensorów wejściowych.
Napinacz
getInputTensorFromSignature ( String inputName, String podpisKey)
Pobiera Tensor skojarzony z podaną nazwą wejściową i nazwą metody podpisu.
Długi
getLastNativeInferenceDurationNanosekundy ()
Zwraca natywny czas wnioskowania.
wew
getOutputIndex ( Ciąg opName)
Pobiera indeks wyjścia, biorąc pod uwagę nazwę operacji wyjścia.
Napinacz
getOutputTensor (int wynikIndex)
Pobiera Tensor skojarzony z podanym indeksem wyjściowym.
wew
getOutputTensorCount ()
Pobiera liczbę tensorów wyjściowych.
Napinacz
getOutputTensorFromSignature ( String OutputName, String SignatureKey)
Pobiera Tensor skojarzony z podaną nazwą wyjściową w określonej metodzie podpisu.
Strunowy[]
getSignatureInputs ( łańcuch podpisKey)
Pobiera listę danych wejściowych SignatureDefs dla metody signatureKey .
Strunowy[]
pobierz klucze podpisu ()
Pobiera listę wyeksportowanych nazw metod SignatureDef dostępnych w modelu.
Strunowy[]
getSignatureOutputs ( łańcuch podpisKey)
Pobiera listę danych wyjściowych SignatureDefs dla metody signatureKey .
próżnia
resetZmienneTensory ()
Zaawansowane: Resetuje wszystkie tensory zmiennych do wartości domyślnych.
próżnia
resizeInput (int idx, int[] przyciemnia, boolean strict)
Zmienia rozmiar wejścia idx-tego modelu natywnego do podanych przyciemnień.
próżnia
resizeInput (int idx, int[] przyciemnia)
Zmienia rozmiar wejścia idx-tego modelu natywnego do podanych przyciemnień.
próżnia
run (Wejście obiektu , Wyjście obiektu )
Uruchamia wnioskowanie o modelu, jeśli model przyjmuje tylko jedno wejście i udostępnia tylko jedno wyjście.
próżnia
runForMultipleInputsOutputs ( Obiekt [] wejścia, Mapa < Liczba całkowita , Obiekt > wyjścia)
Uruchamia wnioskowanie o modelu, jeśli model przyjmuje wiele danych wejściowych lub zwraca wiele wyników.
próżnia
runSignature ( Mapa < String , Obiekt > wejścia, Mapa < String , Obiekt > wyjścia)
To samo co runSignature(Map, Map, String) , ale nie wymaga przekazywania podpisuKey, zakładając, że model ma jeden SignatureDef.
próżnia
runSignature ( Mapa < String , Obiekt > wejścia, Mapa < String , Obiekt > wyjścia, String podpisKey)
Uruchamia wnioskowanie o modelu na podstawie SignatureDef dostarczonej przez signatureKey .
próżnia
setCancelled (boolean anulowane)
Zaawansowane: Przerywa wnioskowanie w trakcie wywołania run(Object, Object) .

Metody dziedziczone

Konstruktorzy publiczni

publiczny interpreter ( plik modelFile)

Inicjuje Interpreter .

Parametry
plik modelu a Plik wstępnie wytrenowanego modelu TF Lite.
Rzuca
Wyjątek IllegalArgument jeśli modelFile nie koduje prawidłowego modelu TensorFlow Lite.

public Interpreter ( File modelFile, Interpreter.Options opcje)

Inicjuje Interpreter i określa opcje dostosowywania zachowania interpretera.

Parametry
plik modelu plik wstępnie wytrenowanego modelu TF Lite
opcje zestaw opcji dostosowywania zachowania interpretera
Rzuca
Wyjątek IllegalArgument jeśli modelFile nie koduje prawidłowego modelu TensorFlow Lite.

publiczny interpreter ( ByteBuffer byteBuffer)

Inicjuje Interpreter za pomocą ByteBuffer pliku modelu.

ByteBuffer nie powinien być modyfikowany po skonstruowaniu Interpreter . ByteBuffer może być MappedByteBuffer , który odwzorowuje plik modelu w pamięci, lub bezpośrednim ByteBuffer funkcji nativeOrder(), który zawiera zawartość bajtów modelu.

Parametry
bufor bajtowy
Rzuca
Wyjątek IllegalArgument jeśli byteBuffer nie jest MappedByteBuffer ani bezpośrednim ByteBuffer z nativeOrder.

publiczny interpreter ( ByteBuffer byteBuffer, opcje Interpreter.Options )

Inicjuje Interpreter z ByteBuffer pliku modelu i zestawem niestandardowych Interpreter.Options .

ByteBuffer nie powinien być modyfikowany po skonstruowaniu Interpreter . ByteBuffer może być MappedByteBuffer , który odwzorowuje plik modelu w pamięci, lub bezpośrednim ByteBuffer funkcji nativeOrder(), który zawiera zawartość bajtów modelu.

Parametry
bufor bajtowy
opcje
Rzuca
Wyjątek IllegalArgument jeśli byteBuffer nie jest MappedByteBuffer ani bezpośrednim ByteBuffer z nativeOrder.

Metody publiczne

public void allocateTensors ()

W razie potrzeby jawnie aktualizuje alokacje dla wszystkich tensorów.

Spowoduje to propagację kształtów i alokacji pamięci dla tensorów zależnych przy użyciu podanych kształtów tensora wejściowego.

Uwaga: to wywołanie jest *wyłącznie opcjonalne*. Alokacja tensora nastąpi automatycznie podczas wykonywania, jeśli zmieniono rozmiar któregokolwiek tensora wejściowego. To wywołanie jest najbardziej przydatne przy określaniu kształtów dowolnych tensorów wyjściowych przed wykonaniem wykresu, np. 

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

Uwaga: Niektóre wykresy mają dynamicznie kształtowane wyniki, w takim przypadku kształt wyjściowy może nie zostać w pełni rozprzestrzeniony, dopóki nie zostanie wykonane wnioskowanie.

publiczna pustka zamknij ()

Zwolnij zasoby powiązane z instancją InterpreterApi .

public int getInputIndex ( String opName)

Pobiera indeks wejścia, biorąc pod uwagę nazwę operacji wejścia.

Parametry
nazwa op

publiczny Tensor getInputTensor (int inputIndex)

Pobiera Tensor skojarzony z podanym indeksem wejściowym.

Parametry
Indeks wejściowy

publiczny int getInputTensorCount ()

Pobiera liczbę tensorów wejściowych.

public Tensor getInputTensorFromSignature ( String inputName, String podpisKey)

Pobiera Tensor skojarzony z podaną nazwą wejściową i nazwą metody podpisu.

OSTRZEŻENIE: To jest eksperymentalny interfejs API i może ulec zmianom.

Parametry
nazwa wejściowa Wpisz imię i nazwisko w podpisie.
podpisKlucz Klucz podpisu identyfikujący SignatureDef może mieć wartość null, jeśli model ma jeden podpis.
Rzuca
Wyjątek IllegalArgument jeśli inputName lub signatureKey ma wartość null lub jest pusty albo podano nieprawidłową nazwę.

public Long getLastNativeInferenceDurationNanosekundy ()

Zwraca natywny czas wnioskowania.

public int getOutputIndex ( String opName)

Pobiera indeks wyjścia, biorąc pod uwagę nazwę operacji wyjścia.

Parametry
nazwa op

publiczny Tensor getOutputTensor (int OutputIndex)

Pobiera Tensor skojarzony z podanym indeksem wyjściowym.

Uwaga: Szczegóły tensora wyjściowego (np. kształt) mogą nie zostać w pełni wypełnione do czasu wykonania wnioskowania. Jeśli potrzebujesz zaktualizowanych szczegółów *przed* uruchomieniem wnioskowania (np. po zmianie rozmiaru tensora wejściowego, co może unieważnić kształty tensora wyjściowego), użyj allocateTensors() w celu jawnego wyzwolenia alokacji i propagacji kształtu. Należy zauważyć, że w przypadku wykresów, których kształty wyjściowe zależą od *wartości* wejściowych, kształt wyjściowy może nie zostać w pełni określony do czasu uruchomienia wnioskowania.

Parametry
indeks wyjściowy

publiczny int getOutputTensorCount ()

Pobiera liczbę tensorów wyjściowych.

public Tensor getOutputTensorFromSignature ( String OutputName, String SignatureKey)

Pobiera Tensor skojarzony z podaną nazwą wyjściową w określonej metodzie podpisu.

Uwaga: Szczegóły tensora wyjściowego (np. kształt) mogą nie zostać w pełni wypełnione do czasu wykonania wnioskowania. Jeśli potrzebujesz zaktualizowanych szczegółów *przed* uruchomieniem wnioskowania (np. po zmianie rozmiaru tensora wejściowego, co może unieważnić kształty tensora wyjściowego), użyj allocateTensors() w celu jawnego wyzwolenia alokacji i propagacji kształtu. Należy zauważyć, że w przypadku wykresów, których kształty wyjściowe zależą od *wartości* wejściowych, kształt wyjściowy może nie zostać w pełni określony do czasu uruchomienia wnioskowania.

OSTRZEŻENIE: To jest eksperymentalny interfejs API i może ulec zmianom.

Parametry
nazwawyjściowa Nazwa wyjściowa w podpisie.
podpisKlucz Klucz podpisu identyfikujący SignatureDef może mieć wartość null, jeśli model ma jeden podpis.
Rzuca
Wyjątek IllegalArgument jeśli outputName lub signatureKey ma wartość null lub jest pusta albo podano nieprawidłową nazwę.

public String[] getSignatureInputs ( String podpisKey)

Pobiera listę danych wejściowych SignatureDefs dla metody signatureKey .

OSTRZEŻENIE: To jest eksperymentalny interfejs API i może ulec zmianom.

Parametry
podpisKlucz

public String[] getSignatureKeys ()

Pobiera listę wyeksportowanych nazw metod SignatureDef dostępnych w modelu.

OSTRZEŻENIE: To jest eksperymentalny interfejs API i może ulec zmianom.

public String[] getSignatureOutputs ( String podpisKey)

Pobiera listę danych wyjściowych SignatureDefs dla metody signatureKey .

OSTRZEŻENIE: To jest eksperymentalny interfejs API i może ulec zmianom.

Parametry
podpisKlucz

public void resetVariableTensors ()

Zaawansowane: Resetuje wszystkie tensory zmiennych do wartości domyślnych.

Jeśli ze zmiennym tensorem nie jest powiązany bufor, zostanie on zresetowany do zera.

OSTRZEŻENIE: To jest eksperymentalny interfejs API i może ulec zmianom.

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

Zmienia rozmiar wejścia idx-tego modelu natywnego do podanych przyciemnień.

Gdy „ścisły” ma wartość True, można zmieniać rozmiar tylko nieznanych wymiarów. Nieznane wymiary są oznaczane jako „-1” w tablicy zwracanej przez funkcję „Tensor.shapeSignature()”.

Parametry
idx
przyciemnia się
ścisły

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

Zmienia rozmiar wejścia idx-tego modelu natywnego do podanych przyciemnień.

Parametry
idx
przyciemnia się

publiczne puste uruchomienie (wejście obiektu , wyjście obiektu )

Uruchamia wnioskowanie o modelu, jeśli model przyjmuje tylko jedno wejście i udostępnia tylko jedno wyjście.

Ostrzeżenie: interfejs API jest bardziej wydajny, jeśli jako typ danych wejściowych/wyjściowych używany jest Buffer (najlepiej bezpośredni, ale nie wymagany). Rozważ użycie Buffer do podawania i pobierania prymitywnych danych w celu uzyskania lepszej wydajności. Obsługiwane są następujące typy Buffer betonowych:

  • ByteBuffer — kompatybilny z dowolnym podstawowym typem prymitywnego tensora.
  • FloatBuffer - kompatybilny z tensorami float.
  • IntBuffer - kompatybilny z tensorami int32.
  • LongBuffer - kompatybilny z tensorami int64.
Należy pamiętać, że typy logiczne są obsługiwane tylko jako tablice, nie Buffer , ani jako wejścia skalarne.

Parametry
wejście tablica lub tablica wielowymiarowa lub Buffer typu pierwotnego, w tym int, float, long i byte. Buffer jest preferowanym sposobem przekazywania dużych danych wejściowych dla typów pierwotnych, podczas gdy typy łańcuchowe wymagają użycia (wielowymiarowej) ścieżki wejściowej tablicy. Gdy używany jest Buffer , jego zawartość powinna pozostać niezmieniona do czasu wykonania wnioskowania o modelu, a obiekt wywołujący musi upewnić się, że Buffer znajduje się w odpowiedniej pozycji odczytu. Wartość null jest dozwolona tylko wtedy, gdy obiekt wywołujący używa Delegate , który umożliwia współdziałanie z uchwytem bufora, a taki bufor został powiązany z wejściem Tensor .
wyjście wielowymiarową tablicę danych wyjściowych lub Buffer typu pierwotnego, w tym int, float, long i byte. Gdy używany jest Buffer , osoba wywołująca musi upewnić się, że ustawiono odpowiednią pozycję zapisu. Wartość null jest dozwolona i jest użyteczna w niektórych przypadkach, np. jeśli wywołujący używa Delegate , który umożliwia interoperację z uchwytem bufora, a taki bufor został powiązany z wyjściowym Tensor (zobacz także Interpreter.Options#setAllowBufferHandleOutput(boolean) ) lub jeśli wykres ma dynamicznie kształtowane dane wyjściowe i obiekt wywołujący musi zapytać o wyjściowy kształt Tensor po wywołaniu wnioskowania, pobierając dane bezpośrednio z tensora wyjściowego (za pośrednictwem Tensor.asReadOnlyBuffer() ).

public void runForMultipleInputsOutputs ( wejścia obiektu [] , mapa < liczba całkowita , obiekt > wyjścia)

Uruchamia wnioskowanie o modelu, jeśli model przyjmuje wiele danych wejściowych lub zwraca wiele wyników.

Ostrzeżenie: interfejs API jest bardziej wydajny, jeśli jako typy danych wejściowych/wyjściowych używane są Buffer (najlepiej bezpośrednie, ale nie wymagane). Rozważ użycie Buffer do podawania i pobierania prymitywnych danych w celu uzyskania lepszej wydajności. Obsługiwane są następujące typy Buffer betonowych:

  • ByteBuffer — kompatybilny z dowolnym podstawowym typem prymitywnego tensora.
  • FloatBuffer - kompatybilny z tensorami float.
  • IntBuffer - kompatybilny z tensorami int32.
  • LongBuffer - kompatybilny z tensorami int64.
Należy pamiętać, że typy logiczne są obsługiwane tylko jako tablice, nie Buffer , ani jako wejścia skalarne.

Uwaga: wartości null dla poszczególnych elementów inputs i outputs są dozwolone tylko wtedy, gdy osoba wywołująca korzysta z Delegate , który umożliwia interoperację z obsługą bufora, a taki bufor został powiązany z odpowiednimi Tensor wejściowymi lub wyjściowymi.

Parametry
wejścia tablica danych wejściowych. Dane wejściowe powinny być w tej samej kolejności, co dane wejściowe modelu. Każde wejście może być tablicą, tablicą wielowymiarową lub Buffer typu pierwotnego, w tym int, float, long i byte. Buffer jest preferowanym sposobem przekazywania dużych danych wejściowych, podczas gdy typy łańcuchowe wymagają użycia (wielowymiarowej) ścieżki wejściowej tablicy. Gdy używany jest Buffer , jego zawartość powinna pozostać niezmieniona do czasu wykonania wnioskowania o modelu, a obiekt wywołujący musi upewnić się, że Buffer znajduje się w odpowiedniej pozycji odczytu.
wyjścia mapa mapująca indeksy wyjściowe na wielowymiarowe tablice danych wyjściowych lub Buffer typów pierwotnych, w tym int, float, long i byte. Musi jedynie przechowywać wpisy dotyczące wyjść, które mają być użyte. Gdy używany jest Buffer , osoba wywołująca musi upewnić się, że ustawiono odpowiednią pozycję zapisu. Mapa może być pusta w przypadkach, gdy dla danych wyjściowych tensora używane są uchwyty buforów lub w przypadkach, gdy dane wyjściowe są kształtowane dynamicznie, a obiekt wywołujący musi zapytać o kształt wyjściowego Tensor po wywołaniu wnioskowania, pobierając dane bezpośrednio z tensora wyjściowego ( poprzez Tensor.asReadOnlyBuffer() ).

public void runSignature ( Mapa < String , Obiekt > wejścia, Mapa < String , Obiekt > wyjścia)

To samo co runSignature(Map, Map, String) , ale nie wymaga przekazywania podpisuKey, zakładając, że model ma jeden SignatureDef. Jeśli model ma więcej niż jeden SignatureDef, zgłosi wyjątek.

OSTRZEŻENIE: To jest eksperymentalny interfejs API i może ulec zmianom.

Parametry
wejścia
wyjścia

public void runSignature ( Mapa < String , Obiekt > wejścia, Mapa < String , Obiekt > wyjścia, String podpisKey)

Uruchamia wnioskowanie o modelu na podstawie SignatureDef dostarczonej przez signatureKey .

Zobacz run(Object, Object) aby uzyskać więcej informacji na temat dozwolonych typów danych wejściowych i wyjściowych.

OSTRZEŻENIE: To jest eksperymentalny interfejs API i może ulec zmianom.

Parametry
wejścia Mapowanie nazwy wejściowej w SignatureDef na obiekt wejściowy.
wyjścia Mapa od nazwy wyjściowej w SignatureDef do danych wyjściowych. Pole to może być puste, jeśli wywołujący chce wysłać zapytanie do danych Tensor bezpośrednio po wnioskowaniu (np. jeśli kształt wyjściowy jest dynamiczny lub używane są uchwyty bufora wyjściowego).
podpisKlucz Klucz podpisu identyfikujący SignatureDef.
Rzuca
Wyjątek IllegalArgument jeśli inputs mają wartość null lub są puste, jeśli outputs lub signatureKey mają wartość null lub jeśli podczas uruchamiania wnioskowania wystąpi błąd.

public void setAnulowano (boolean anulowano)

Zaawansowane: Przerywa wnioskowanie w trakcie wywołania run(Object, Object) .

Po wywołaniu tej funkcji flaga anulowania zostanie ustawiona na wartość true. Interpreter sprawdzi flagę pomiędzy wywołaniami Op i jeśli jest true , interpreter zatrzyma wykonanie. Interpreter pozostanie w stanie anulowanym, dopóki nie zostanie jawnie „nieanulowany” przez setCancelled(false) .

OSTRZEŻENIE: To jest eksperymentalny interfejs API i może ulec zmianom.

Parametry
odwołany true Aby anulować wnioskowanie w najlepszy sposób; false aby wznowić.
Rzuca
Wyjątek IllegalStateException jeśli interpreter nie został zainicjowany opcją z możliwością anulowania, która jest domyślnie wyłączona.
Zobacz też