InterpreterApi

interfejs publiczny InterpreterApi
Znane podklasy pośrednie

Interfejs do interpretera modelu TensorFlow Lite, z wyłączeniem metod eksperymentalnych.

Instancja InterpreterApi hermetyzuje wstępnie wytrenowany 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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 InterpreterApi nie są bezpieczne dla wątków.

OSTRZEŻENIE: Instancja InterpreterApi posiada zasoby, 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 InterpreterApi.Opcje Klasa opcji służąca do kontrolowania zachowania interpretera środowiska wykonawczego.

Metody publiczne

abstrakcyjna pustka
przydzielTensory ()
W razie potrzeby jawnie aktualizuje alokacje dla wszystkich tensorów.
abstrakcyjna pustka
zamknąć ()
Zwolnij zasoby powiązane z instancją InterpreterApi .
statyczny interpreterApi
utwórz ( plik modelFile, opcje InterpreterApi.Options )
Konstruuje instancję InterpreterApi przy użyciu określonego modelu i opcji.
statyczny interpreterApi
utwórz ( ByteBuffer byteBuffer, opcje InterpreterApi.Options )
Konstruuje instancję InterpreterApi przy użyciu określonego modelu i opcji.
streszczenie wew
getInputIndex ( łańcuch opName)
Pobiera indeks wejścia, biorąc pod uwagę nazwę operacji wejścia.
abstrakcyjny tensor
getInputTensor (int inputIndex)
Pobiera Tensor skojarzony z podanym indeksem wejściowym.
streszczenie wew
getInputTensorCount ()
Pobiera liczbę tensorów wejściowych.
streszczenie Długie
getLastNativeInferenceDurationNanosekundy ()
Zwraca natywny czas wnioskowania.
streszczenie wew
getOutputIndex ( Ciąg opName)
Pobiera indeks wyjścia, biorąc pod uwagę nazwę operacji wyjścia.
abstrakcyjny tensor
getOutputTensor (int wynikIndex)
Pobiera Tensor skojarzony z podanym indeksem wyjściowym.
streszczenie wew
getOutputTensorCount ()
Pobiera liczbę tensorów wyjściowych.
abstrakcyjna pustka
resizeInput (int idx, int[] przyciemnia, boolean strict)
Zmienia rozmiar wejścia idx-tego modelu natywnego do podanych przyciemnień.
abstrakcyjna pustka
resizeInput (int idx, int[] przyciemnia)
Zmienia rozmiar wejścia idx-tego modelu natywnego do podanych przyciemnień.
abstrakcyjna pustka
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.
abstrakcyjna pustka
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.

Metody dziedziczone

Metody publiczne

publiczna abstrakcja nieważna przydzielTensory ()

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.

Rzuca
Wyjątek IllegalStateException jeśli nie udało się pomyślnie przydzielić tensorów grafu.

publiczne streszczenie nieważne zamknij ()

Zwolnij zasoby powiązane z instancją InterpreterApi .

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

Konstruuje instancję InterpreterApi przy użyciu określonego modelu i opcji. Model zostanie wczytany z pliku.

Parametry
plik modelu Plik zawierający wstępnie wytrenowany model TF Lite.
opcje Zestaw opcji dostosowywania zachowania interpretera.
Rzuca
Wyjątek IllegalArgument jeśli modelFile nie koduje prawidłowego modelu TensorFlow Lite.

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

Konstruuje instancję InterpreterApi przy użyciu określonego modelu i opcji. Model zostanie odczytany z ByteBuffer .

Parametry
bufor bajtowy Wstępnie wytrenowany model TF Lite w binarnej postaci serializowanej. ByteBuffer nie powinien być modyfikowany po skonstruowaniu instancji InterpreterApi . 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.
opcje Zestaw opcji dostosowywania zachowania interpretera.
Rzuca
Wyjątek IllegalArgument jeśli byteBuffer nie jest MappedByteBuffer ani bezpośrednim ByteBuffer z nativeOrder.

public streszczenie int getInputIndex ( String opName)

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

Parametry
nazwa op
Rzuca
Wyjątek IllegalArgument jeśli opName nie pasuje do żadnego wejścia w modelu użytym do inicjalizacji interpretera.

publiczny streszczenie Tensor getInputTensor (int inputIndex)

Pobiera Tensor skojarzony z podanym indeksem wejściowym.

Parametry
Indeks wejściowy
Rzuca
Wyjątek IllegalArgument jeśli inputIndex jest ujemny lub nie mniejszy niż liczba wejść modelu.

publiczne streszczenie int getInputTensorCount ()

Pobiera liczbę tensorów wejściowych.

publiczne streszczenie Długie pobieranieLastNativeInferenceDurationNanosekundy ()

Zwraca natywny czas wnioskowania.

Rzuca
Wyjątek IllegalArgument jeśli model nie został zainicjowany przez interpreter.

publiczne streszczenie int getOutputIndex ( String opName)

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

Parametry
nazwa op
Rzuca
Wyjątek IllegalArgument jeśli opName nie pasuje do żadnego wyjścia w modelu użytym do inicjalizacji interpretera.

publiczny streszczenie 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
Rzuca
Wyjątek IllegalArgument jeśli outputIndex jest ujemny lub nie mniejszy niż liczba wyników modelu.

publiczne streszczenie int getOutputTensorCount ()

Pobiera liczbę tensorów wyjściowych.

public streszczenie 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
Rzuca
Wyjątek IllegalArgument jeśli idx jest ujemne lub nie mniejsze niż liczba wejść modelu; lub jeśli wystąpi błąd podczas zmiany rozmiaru wejścia idx. Ponadto błąd występuje podczas próby zmiany rozmiaru tensora o stałych wymiarach, gdy „ścisły” ma wartość True.

publiczne streszczenie void resizeInput (int idx, int[] dims)

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

Parametry
idx
przyciemnia się
Rzuca
Wyjątek IllegalArgument jeśli idx jest ujemne lub nie mniejsze niż liczba wejść modelu; lub jeśli wystąpi błąd podczas zmiany rozmiaru wejścia idx.

publiczne streszczenie 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() ).
Rzuca
Wyjątek IllegalArgument jeśli input mają wartość null lub są puste, lub jeśli podczas uruchamiania wnioskowania wystąpi błąd.
Wyjątek IllegalArgument (EKSPERYMENTALNE, może ulec zmianie), jeśli wnioskowanie zostanie przerwane przez setCancelled(true) .

publiczne streszczenie void 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.

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() ).
Rzuca
Wyjątek IllegalArgument jeśli inputs mają wartość null lub są puste, jeśli outputs mają wartość null lub jeśli podczas uruchamiania wnioskowania wystąpi błąd.