Interpreter

Интерпретатор публичного финального класса

Класс драйвера для управления выводом модели с помощью TensorFlow Lite.

Примечание. Если вам не нужен доступ ни к одной из «экспериментальных» функций API, указанных ниже, предпочитайте использовать InterpreterApi и InterpreterFactory, а не использовать Interpreter напрямую.

Interpreter инкапсулирует предварительно обученную модель TensorFlow Lite, в которой выполняются операции для вывода модели.

Например, если модель принимает только один вход и возвращает только один результат:

try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
   interpreter.run(input, 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);
 }
 

Если модель принимает или создает тензоры строк:

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

Обратите внимание, что существует различие между shape[] и shape[1]. Для выходных данных тензора скалярной строки:

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

Порядок входных и выходных данных определяется при преобразовании модели TensorFlow в модель TensorFlowLite с помощью Toco, как и формы входных данных по умолчанию.

Когда входные данные предоставляются в виде (многомерных) массивов, соответствующие входные тензоры будут неявно изменены в соответствии с формой этого массива. Когда входные данные предоставляются как типы Buffer , неявное изменение размера не выполняется; вызывающая сторона должна убедиться, что размер байта Buffer соответствует размеру соответствующего тензора, или сначала изменить размер тензора с помощью resizeInput(int, int[]) . Информацию о форме и типе тензора можно получить через класс Tensor , доступный через getInputTensor(int) и getOutputTensor(int) .

ВНИМАНИЕ: Экземпляры Interpreter не являются потокобезопасными. Interpreter принадлежат ресурсы, которые необходимо явно освободить, вызвав функцию close()

Библиотека TFLite создана на основе NDK API 19. Она может работать для уровней Android API ниже 19, но это не гарантируется.

Вложенные классы

сорт Интерпретатор.Опции Класс опций для управления поведением интерпретатора во время выполнения.

Публичные конструкторы

Интерпретатор ( файл modelFile)
Инициализирует Interpreter .
Интерпретатор (опции File modelFile, Interpreter.Options )
Инициализирует Interpreter и определяет параметры настройки поведения интерпретатора.
Интерпретатор ( ByteBuffer byteBuffer)
Инициализирует Interpreter с помощью ByteBuffer файла модели.
Интерпретатор (опции ByteBuffer byteBuffer, Interpreter.Options )
Инициализирует Interpreter с помощью ByteBuffer файла модели и набора пользовательских Interpreter.Options .

Публичные методы

пустота
выделитьТензоры ()
При необходимости явно обновляет распределения для всех тензоров.
пустота
закрывать ()
Освободите ресурсы, связанные с экземпляром InterpreterApi .
интервал
getInputIndex ( строка opName)
Получает индекс входа по имени операции входа.
Тензор
getInputTensor (int inputIndex)
Получает тензор, связанный с предоставленным входным индексом.
интервал
getInputTensorCount ()
Получает количество входных тензоров.
Тензор
getInputTensorFromSignature ( строковое имя_входа, строковый ключ подписи)
Получает тензор, связанный с указанным входным именем и именем метода подписи.
Длинный
getLastNativeInferenceDurationNano Seconds ()
Возвращает собственное время вывода.
интервал
getOutputIndex ( строка opName)
Получает индекс вывода по имени операции вывода.
Тензор
getOutputTensor (int выходной индекс)
Получает тензор, связанный с предоставленным выходным индексом.
интервал
getOutputTensorCount ()
Получает количество выходных тензоров.
Тензор
getOutputTensorFromSignature ( строковое имя вывода, строковый ключ подписи)
Получает тензор, связанный с указанным выходным именем в определенном методе подписи.
Нить[]
getSignatureInputs ( строковый ключ подписи)
Получает список входных данных SignatureDefs для метода signatureKey .
Нить[]
getSignatureKeys ()
Получает список имен экспортированных методов SignatureDef, доступных в модели.
Нить[]
getSignatureOutputs ( строковый ключ подписи)
Получает список выходных данных SignatureDefs для метода signatureKey .
пустота
сбросVariableTensors ()
Дополнительно: сбрасывает все переменные тензоры к значению по умолчанию.
пустота
resizeInput (int idx, int[] dims, логическое строгое)
Изменяет размер idx-го ввода собственной модели до заданных размеров.
пустота
resizeInput (int idx, int[] тускнеет)
Изменяет размер idx-го ввода собственной модели до заданных размеров.
пустота
запустить (ввод объекта , вывод объекта )
Выполняет вывод модели, если модель принимает только один вход и предоставляет только один выход.
пустота
runForMultipleInputsOutputs (входные данные Object[] , Map < Integer , Object > выходные)
Выполняет вывод модели, если модель принимает несколько входных данных или возвращает несколько выходных данных.
пустота
runSignature ( Map < String , Object > входные данные, Map < String , Object > выходные данные)
То же, что и runSignature(Map, Map, String) , но не требует передачи SignatureKey, при условии, что модель имеет один SignatureDef.
пустота
runSignature ( Map < String , Object > входные данные, Map < String , Object > выходные данные, String SignatureKey)
Выполняет вывод модели на основе SignatureDef, предоставленного через signatureKey .
пустота
setCancelled (логическое значение отменено)
Дополнительно: прерывает вывод в середине вызова run(Object, Object) .

Унаследованные методы

Публичные конструкторы

общедоступный интерпретатор ( файл modelFile)

Инициализирует Interpreter .

Параметры
МодельФайл Файл предварительно обученной модели TF Lite.
Броски
IllegalArgumentException если modelFile не кодирует действительную модель TensorFlow Lite.

общедоступный интерпретатор (опции File modelFile, Interpreter.Options )

Инициализирует Interpreter и определяет параметры настройки поведения интерпретатора.

Параметры
МодельФайл файл предварительно обученной модели TF Lite
параметры набор опций для настройки поведения интерпретатора
Броски
IllegalArgumentException если modelFile не кодирует действительную модель TensorFlow Lite.

общедоступный интерпретатор ( ByteBuffer byteBuffer)

Инициализирует Interpreter с помощью ByteBuffer файла модели.

ByteBuffer не следует изменять после создания Interpreter . ByteBuffer может быть либо MappedByteBuffer , который отображает в памяти файл модели, либо прямым ByteBuffer метода ownOrder(), который содержит байтовое содержимое модели.

Параметры
байтбуфер
Броски
IllegalArgumentException если byteBuffer не является MappedByteBuffer и не является прямым ByteBuffer для ownOrder.

общедоступный интерпретатор (опции ByteBuffer byteBuffer, Interpreter.Options )

Инициализирует Interpreter с помощью ByteBuffer файла модели и набора пользовательских Interpreter.Options .

ByteBuffer не следует изменять после создания Interpreter . ByteBuffer может быть либо MappedByteBuffer , который отображает в памяти файл модели, либо прямым ByteBuffer метода ownOrder(), который содержит байтовое содержимое модели.

Параметры
байтбуфер
параметры
Броски
IllegalArgumentException если byteBuffer не является MappedByteBuffer и не является прямым ByteBuffer для ownOrder.

Публичные методы

общественная пустота allocateTensors ()

При необходимости явно обновляет распределения для всех тензоров.

Это будет распространять формы и распределение памяти для зависимых тензоров, используя заданные формы входных тензоров.

Примечание. Этот вызов *совершенно необязателен*. Распределение тензоров произойдет автоматически во время выполнения, если размер входных тензоров был изменен. Этот вызов наиболее полезен при определении формы любых выходных тензоров перед выполнением графа, например

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

Примечание. Некоторые графики имеют выходные данные с динамической формой, и в этом случае выходная форма может не распространяться полностью, пока не будет выполнен вывод.

public void закрыть ()

Освободите ресурсы, связанные с экземпляром InterpreterApi .

public int getInputIndex ( String opName)

Получает индекс входа по имени операции входа.

Параметры
имя_оператора

общедоступный тензор getInputTensor (int inputIndex)

Получает тензор, связанный с предоставленным входным индексом.

Параметры
инпутиндекс

public int getInputTensorCount ()

Получает количество входных тензоров.

public Tensor getInputTensorFromSignature ( строка inputName, строка подписьKey)

Получает тензор, связанный с указанным входным именем и именем метода подписи.

ВНИМАНИЕ: это экспериментальный API, в который могут быть внесены изменения.

Параметры
входное имя Введите имя в подпись.
ключ подписи Ключ подписи, идентифицирующий SignatureDef, может иметь значение null, если модель имеет одну подпись.
Броски
IllegalArgumentException если inputName или signatureKey имеют значение NULL или пустое, либо указано неверное имя.

public Long getLastNativeInferenceDurationNanoсекунды ()

Возвращает собственное время вывода.

public int getOutputIndex ( String opName)

Получает индекс вывода по имени операции вывода.

Параметры
имя_оператора

общедоступный тензор getOutputTensor (int outputIndex)

Получает тензор, связанный с предоставленным выходным индексом.

Примечание. Детали выходного тензора (например, форма) могут не быть полностью заполнены до тех пор, пока не будет выполнен вывод. Если вам нужны обновленные данные *перед* выполнением вывода (например, после изменения размера входного тензора, которое может сделать недействительными формы выходного тензора), используйте allocateTensors() , чтобы явно инициировать выделение и распространение формы. Обратите внимание, что для графиков с выходными формами, которые зависят от входных *значений*, выходная форма не может быть полностью определена до выполнения вывода.

Параметры
выходной индекс

public int getOutputTensorCount ()

Получает количество выходных тензоров.

public Tensor getOutputTensorFromSignature ( String выходное имя, строковый ключ подписи)

Получает тензор, связанный с указанным выходным именем в определенном методе подписи.

Примечание. Детали выходного тензора (например, форма) могут не быть полностью заполнены до тех пор, пока не будет выполнен вывод. Если вам нужны обновленные данные *перед* выполнением вывода (например, после изменения размера входного тензора, которое может сделать недействительными формы выходного тензора), используйте allocateTensors() , чтобы явно инициировать выделение и распространение формы. Обратите внимание, что для графиков с выходными формами, которые зависят от входных *значений*, выходная форма не может быть полностью определена до выполнения вывода.

ВНИМАНИЕ: это экспериментальный API, в который могут быть внесены изменения.

Параметры
выходное имя Вывести имя в подписи.
ключ подписи Ключ подписи, идентифицирующий SignatureDef, может иметь значение null, если модель имеет одну подпись.
Броски
IllegalArgumentException если outputName или signatureKey имеет значение NULL или пустое, либо указано неверное имя.

public String[] getSignatureInputs ( String SignatureKey)

Получает список входных данных SignatureDefs для метода signatureKey .

ВНИМАНИЕ: это экспериментальный API, в который могут быть внесены изменения.

Параметры
ключ подписи

общественная строка [] getSignatureKeys ()

Получает список имен экспортированных методов SignatureDef, доступных в модели.

ВНИМАНИЕ: это экспериментальный API, в который могут быть внесены изменения.

public String[] getSignatureOutputs ( String SignatureKey)

Получает список выходных данных SignatureDefs для метода signatureKey .

ВНИМАНИЕ: это экспериментальный API, в который могут быть внесены изменения.

Параметры
ключ подписи

общественный недействительный сбросVariableTensors ()

Дополнительно: сбрасывает все переменные тензоры к значению по умолчанию.

Если переменный тензор не имеет связанного с ним буфера, он будет сброшен в ноль.

ВНИМАНИЕ: это экспериментальный API, в который могут быть внесены изменения.

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

Изменяет размер idx-го ввода собственной модели до заданных размеров.

Когда `strict` имеет значение True, можно изменить размер только неизвестных размеров. Неизвестные размеры обозначаются как «-1» в массиве, возвращаемом функцией «Tensor.shapeSignature()».

Параметры
идентификатор
тускнеет
строгий

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

Изменяет размер idx-го ввода собственной модели до заданных размеров.

Параметры
идентификатор
тускнеет

public void run (ввод объекта , вывод объекта )

Выполняет вывод модели, если модель принимает только один вход и предоставляет только один выход.

Предупреждение. API более эффективен, если в качестве типа входных/выходных данных используется Buffer (желательно прямой, но не обязательный). Пожалуйста, рассмотрите возможность использования Buffer для подачи и извлечения примитивных данных для повышения производительности. Поддерживаются следующие конкретные типы Buffer :

  • ByteBuffer — совместим с любым базовым примитивным типом Tensor.
  • FloatBuffer — совместим с тензорами с плавающей запятой.
  • IntBuffer — совместим с тензорами int32.
  • LongBuffer — совместим с тензорами int64.
Обратите внимание, что логические типы поддерживаются только как массивы, а не как Buffer или как скалярные входные данные.

Параметры
вход массив или многомерный массив или Buffer примитивных типов, включая int, float, long и byte. Buffer — это предпочтительный способ передачи больших входных данных для примитивных типов, тогда как строковые типы требуют использования входного пути (многомерного) массива. Когда используется Buffer , его содержимое должно оставаться неизменным до тех пор, пока не будет выполнен вывод модели, и вызывающая сторона должна убедиться, что Buffer находится в соответствующей позиции чтения. null значение допускается только в том случае, если вызывающая сторона использует Delegate , который разрешает взаимодействие дескриптора буфера, и такой буфер привязан к входному Tensor .
выход многомерный массив выходных данных или Buffer примитивных типов, включая int, float, long и byte. Когда используется Buffer , вызывающая сторона должна убедиться, что ему установлена ​​соответствующая позиция записи. Нулевое значение разрешено и полезно в определенных случаях, например, если вызывающая сторона использует Delegate , который разрешает взаимодействие дескриптора буфера, и такой буфер привязан к выходному Tensor (см. также Interpreter.Options#setAllowBufferHandleOutput(boolean) ), или если график имеет выходные данные динамической формы, и вызывающий объект должен запросить выходную форму Tensor после вызова вывода, извлекая данные непосредственно из выходного тензора (через Tensor.asReadOnlyBuffer() ).

public void runForMultipleInputsOutputs (входы Object[] , Map < Integer , Object > выходы)

Выполняет вывод модели, если модель принимает несколько входных данных или возвращает несколько выходных данных.

Предупреждение. API более эффективен, если в качестве типов входных/выходных данных используются Buffer (желательно напрямую, но не обязательно). Пожалуйста, рассмотрите возможность использования Buffer для подачи и извлечения примитивных данных для повышения производительности. Поддерживаются следующие конкретные типы Buffer :

  • ByteBuffer — совместим с любым базовым примитивным типом Tensor.
  • FloatBuffer — совместим с тензорами с плавающей запятой.
  • IntBuffer — совместим с тензорами int32.
  • LongBuffer — совместим с тензорами int64.
Обратите внимание, что логические типы поддерживаются только как массивы, а не как Buffer или как скалярные входные данные.

Примечание. Значения null для отдельных элементов inputs и outputs разрешены только в том случае, если вызывающая сторона использует Delegate , который разрешает взаимодействие дескрипторов буфера, и такой буфер был привязан к соответствующему входному или выходному Tensor (ам).

Параметры
входы массив входных данных. Входные данные должны быть в том же порядке, что и входные данные модели. Каждый вход может быть массивом или многомерным массивом или Buffer примитивных типов, включая int, float, long и byte. Buffer — предпочтительный способ передачи больших входных данных, тогда как строковые типы требуют использования входного пути (многомерного) массива. Когда используется Buffer , его содержимое должно оставаться неизменным до тех пор, пока не будет выполнен вывод модели, и вызывающая сторона должна убедиться, что Buffer находится в соответствующей позиции чтения.
результаты карта, отображающая выходные индексы в многомерные массивы выходных данных или Buffer примитивных типов, включая int, float, long и byte. Необходимо только сохранять записи для используемых выходов. Когда используется Buffer , вызывающая сторона должна убедиться, что ему установлена ​​соответствующая позиция записи. Карта может быть пустой в случаях, когда либо дескрипторы буфера используются для выходных данных тензора, либо в случаях, когда выходные данные имеют динамическую форму, и вызывающая сторона должна запросить форму выходного Tensor после вызова вывода, извлекая данные непосредственно из выходного тензора ( через Tensor.asReadOnlyBuffer() ).

public void runSignature ( Map < String , Object > входные данные, Map < String , Object > выходные данные)

То же, что и runSignature(Map, Map, String) , но не требует передачи SignatureKey, при условии, что модель имеет один SignatureDef. Если модель имеет более одного SignatureDef, будет выдано исключение.

ВНИМАНИЕ: это экспериментальный API, в который могут быть внесены изменения.

Параметры
входы
результаты

public void runSignature ( Map < String , Object > входные данные, Map < String , Object > выходные данные, String SignatureKey)

Выполняет вывод модели на основе SignatureDef, предоставленного через signatureKey .

См. run(Object, Object) для получения более подробной информации о разрешенных типах входных и выходных данных.

ВНИМАНИЕ: это экспериментальный API, в который могут быть внесены изменения.

Параметры
входы Сопоставление входного имени в SignatureDef с входным объектом.
результаты Сопоставление выходного имени в SignatureDef с выходными данными. Оно может быть пустым, если вызывающая сторона желает запросить данные Tensor непосредственно после вывода (например, если форма вывода является динамической или используются дескрипторы выходного буфера).
ключ подписи Ключ подписи, идентифицирующий SignatureDef.
Броски
IllegalArgumentException если inputs имеют значение NULL или пусты, если outputs или signatureKey имеют значение NULL или если при выполнении вывода возникает ошибка.

public void setCancelled (логическое значение отменено)

Дополнительно: прерывает вывод в середине вызова run(Object, Object) .

Флаг отмены будет установлен в значение true при вызове этой функции. Интерпретатор будет проверять флаг между вызовами Op, и если он равен true , интерпретатор остановит выполнение. Интерпретатор будет оставаться в отмененном состоянии до тех пор, пока он не будет явно «отменен» с помощью setCancelled(false) .

ВНИМАНИЕ: это экспериментальный API, в который могут быть внесены изменения.

Параметры
отменен true , чтобы отменить вывод наилучшим образом; false для возобновления.
Броски
IllegalStateException если интерпретатор не инициализирован с опцией отмены, которая по умолчанию отключена.
Смотрите также