Interpreter

Intérprete público de clase final

Clase de controlador para impulsar la inferencia de modelos con TensorFlow Lite.

Nota: Si no necesita acceso a ninguna de las funciones API "experimentales" que aparecen a continuación, prefiera utilizar InterpreterApi e InterpreterFactory en lugar de utilizar Interpreter directamente.

Un Interpreter encapsula un modelo de TensorFlow Lite previamente entrenado, en el que se ejecutan operaciones para la inferencia del modelo.

Por ejemplo, si un modelo toma solo una entrada y devuelve solo una salida:

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

Si un modelo toma múltiples entradas o salidas:

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

Si un modelo toma o produce tensores de cuerdas:

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

Tenga en cuenta que existe una distinción entre forma [] y forma [1]. Para salidas de tensor de cadena escalar:

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

Los órdenes de entradas y salidas se determinan al convertir el modelo TensorFlow al modelo TensorFlowLite con Toco, al igual que las formas predeterminadas de las entradas.

Cuando las entradas se proporcionan como matrices (multidimensionales), los tensores de entrada correspondientes cambiarán de tamaño implícitamente de acuerdo con la forma de esa matriz. Cuando las entradas se proporcionan como tipos Buffer , no se realiza ningún cambio de tamaño implícito; la persona que llama debe asegurarse de que el tamaño de bytes Buffer coincida con el del tensor correspondiente o que primero cambie el tamaño del tensor mediante resizeInput(int, int[]) . La información sobre la forma y el tipo de tensor se puede obtener a través de la clase Tensor , disponible a través de getInputTensor(int) y getOutputTensor(int) .

ADVERTENCIA: Las instancias Interpreter no son seguras para subprocesos. Un Interpreter posee recursos que deben liberarse explícitamente invocando close()

La biblioteca TFLite está construida con NDK API 19. Puede funcionar para niveles de API de Android inferiores a 19, pero no está garantizado.

Clases anidadas

clase Opciones de intérprete Una clase de opciones para controlar el comportamiento del intérprete en tiempo de ejecución.

Constructores Públicos

Intérprete (modelo de archivoArchivo )
Inicializa un Interpreter .
Intérprete (modelo de archivoArchivo , opciones Interpreter.Options )
Inicializa un Interpreter y especifica opciones para personalizar el comportamiento del intérprete.
Intérprete ( ByteBuffer byteBuffer)
Inicializa un Interpreter con un ByteBuffer de un archivo modelo.
Intérprete ( ByteBuffer byteBuffer, opciones Interpreter.Options )
Inicializa un Interpreter con un ByteBuffer de un archivo modelo y un conjunto de Interpreter.Options personalizados.

Métodos públicos

vacío
asignarTensores ()
Actualiza explícitamente las asignaciones para todos los tensores, si es necesario.
vacío
cerca ()
Libere los recursos asociados con la instancia InterpreterApi .
En t
getInputIndex ( cadena nombre de operación)
Obtiene el índice de una entrada dado el nombre de operación de la entrada.
Tensor
getInputTensor (int índice de entrada)
Obtiene el tensor asociado con el índice de entrada proporcionado.
En t
getInputTensorCount ()
Obtiene el número de tensores de entrada.
Tensor
getInputTensorFromSignature ( String nombre de entrada, String firmaClave)
Obtiene el tensor asociado con el nombre de entrada proporcionado y el nombre del método de firma.
Largo
getLastNativeInferenceDurationNanosegundos ()
Devuelve el tiempo de inferencia nativo.
En t
getOutputIndex ( cadena nombre de operación)
Obtiene el índice de una salida dado el nombre de operación de la salida.
Tensor
getOutputTensor (int índice de salida)
Obtiene el tensor asociado con el índice de salida proporcionado.
En t
getOutputTensorCount ()
Obtiene el número de tensores de salida.
Tensor
getOutputTensorFromSignature ( String nombre de salida, String firmaClave)
Obtiene el tensor asociado con el nombre de salida proporcionado en un método de firma específico.
Cadena[]
getSignatureInputs (cadena clave de firma )
Obtiene la lista de entradas SignatureDefs para el método signatureKey .
Cadena[]
obtener claves de firma ()
Obtiene la lista de nombres de métodos exportados SignatureDef disponibles en el modelo.
Cadena[]
getSignatureOutputs (cadena clave de firma )
Obtiene la lista de resultados de SignatureDefs para el método signatureKey .
vacío
restablecerVariableTensores ()
Avanzado: restablece todos los tensores variables al valor predeterminado.
vacío
resizeInput (int idx, int[] atenua, booleano estricto)
Cambia el tamaño de la entrada idx-ésima del modelo nativo a las atenuaciones dadas.
vacío
resizeInput (int idx, int[] se atenúa)
Cambia el tamaño de la entrada idx-ésima del modelo nativo a las atenuaciones dadas.
vacío
ejecutar (entrada de objeto , salida de objeto )
Ejecuta la inferencia del modelo si el modelo toma solo una entrada y proporciona solo una salida.
vacío
runForMultipleInputsOutputs ( Objeto[] entradas, Mapa < Entero , Objeto > salidas)
Ejecuta la inferencia del modelo si el modelo toma múltiples entradas o devuelve múltiples salidas.
vacío
runSignature ( Mapa < Cadena , Objeto > entradas, Mapa < Cadena , Objeto > salidas)
Igual que runSignature(Map, Map, String) pero no requiere pasar una clave de firma, suponiendo que el modelo tenga una SignatureDef.
vacío
runSignature ( Mapa < Cadena , Objeto > entradas, Mapa < Cadena , Objeto > salidas, Cadena firmaClave)
Ejecuta la inferencia del modelo basada en SignatureDef proporcionada a través de signatureKey .
vacío
setCancelled (booleano cancelado)
Avanzado: interrumpe la inferencia en medio de una llamada a run(Object, Object) .

Métodos heredados

Constructores Públicos

Intérprete público ( Archivo modeloArchivo)

Inicializa un Interpreter .

Parámetros
modeloArchivo a Archivo de un modelo TF Lite previamente entrenado.
Lanza
Argumento de excepción ilegal si modelFile no codifica un modelo válido de TensorFlow Lite.

Intérprete público (modelo de archivo , archivo, intérprete. Opciones)

Inicializa un Interpreter y especifica opciones para personalizar el comportamiento del intérprete.

Parámetros
modeloArchivo un archivo de un modelo TF Lite previamente entrenado
opciones un conjunto de opciones para personalizar el comportamiento del intérprete
Lanza
Argumento de excepción ilegal si modelFile no codifica un modelo válido de TensorFlow Lite.

Intérprete público ( ByteBuffer byteBuffer)

Inicializa un Interpreter con un ByteBuffer de un archivo modelo.

El ByteBuffer no debe modificarse después de la construcción de un Interpreter . ByteBuffer puede ser un MappedByteBuffer que asigna en memoria un archivo de modelo o un ByteBuffer directo de NativeOrder() que contiene el contenido de bytes de un modelo.

Parámetros
búfer de bytes
Lanza
Argumento de excepción ilegal si byteBuffer no es un MappedByteBuffer ni un ByteBuffer directo de NativeOrder.

Intérprete público ( ByteBuffer byteBuffer, opciones Interpreter.Options )

Inicializa un Interpreter con un ByteBuffer de un archivo modelo y un conjunto de Interpreter.Options personalizados.

El ByteBuffer no debe modificarse después de la construcción de un Interpreter . ByteBuffer puede ser un MappedByteBuffer que asigna en memoria un archivo de modelo o un ByteBuffer directo de NativeOrder() que contiene el contenido de bytes de un modelo.

Parámetros
búfer de bytes
opciones
Lanza
Argumento de excepción ilegal si byteBuffer no es un MappedByteBuffer ni un ByteBuffer directo de NativeOrder.

Métodos públicos

asignación nula públicaTensores ()

Actualiza explícitamente las asignaciones para todos los tensores, si es necesario.

Esto propagará formas y asignaciones de memoria para tensores dependientes utilizando las formas del tensor de entrada tal como se proporcionan.

Nota: Esta llamada es *puramente opcional*. La asignación de tensores se producirá automáticamente durante la ejecución si se ha cambiado el tamaño de algún tensor de entrada. Esta llamada es más útil para determinar las formas de cualquier tensor de salida antes de ejecutar el gráfico, por ejemplo,

 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: Algunos gráficos tienen resultados con forma dinámica, en cuyo caso es posible que la forma de salida no se propague por completo hasta que se ejecute la inferencia.

cierre público vacío ()

Libere los recursos asociados con la instancia InterpreterApi .

public int getInputIndex ( String opName)

Obtiene el índice de una entrada dado el nombre de operación de la entrada.

Parámetros
nombre de operación

Tensor público getInputTensor (int inputIndex)

Obtiene el tensor asociado con el índice de entrada proporcionado.

Parámetros
índice de entrada

público int getInputTensorCount ()

Obtiene el número de tensores de entrada.

Tensor público getInputTensorFromSignature ( String inputName, String SignatureKey)

Obtiene el tensor asociado con el nombre de entrada proporcionado y el nombre del método de firma.

ADVERTENCIA: Esta es una API experimental y está sujeta a cambios.

Parámetros
nombre de entrada Introduzca el nombre en la firma.
firmaClave La clave de firma que identifica SignatureDef puede ser nula si el modelo tiene una firma.
Lanza
Argumento de excepción ilegal si inputName o signatureKey son nulos o están vacíos, o se proporciona un nombre no válido.

public Long getLastNativeInferenceDurationNanosegundos ()

Devuelve el tiempo de inferencia nativo.

public int getOutputIndex ( String opName)

Obtiene el índice de una salida dado el nombre de operación de la salida.

Parámetros
nombre de operación

tensor público getOutputTensor (int índice de salida)

Obtiene el tensor asociado con el índice de salida proporcionado.

Nota: Es posible que los detalles del tensor de salida (p. ej., forma) no se rellenen por completo hasta que se ejecute la inferencia. Si necesita detalles actualizados *antes* de ejecutar la inferencia (por ejemplo, después de cambiar el tamaño de un tensor de entrada, lo que puede invalidar las formas del tensor de salida), use allocateTensors() para activar explícitamente la asignación y la propagación de formas. Tenga en cuenta que, para gráficos con formas de salida que dependen de *valores* de entrada, es posible que la forma de salida no se determine completamente hasta que se ejecute la inferencia.

Parámetros
índice de salida

público int getOutputTensorCount ()

Obtiene el número de tensores de salida.

Tensor público getOutputTensorFromSignature ( String nombre de salida, String firmaClave)

Obtiene el tensor asociado con el nombre de salida proporcionado en un método de firma específico.

Nota: Es posible que los detalles del tensor de salida (p. ej., forma) no se rellenen por completo hasta que se ejecute la inferencia. Si necesita detalles actualizados *antes* de ejecutar la inferencia (por ejemplo, después de cambiar el tamaño de un tensor de entrada, lo que puede invalidar las formas del tensor de salida), use allocateTensors() para activar explícitamente la asignación y la propagación de formas. Tenga en cuenta que, para gráficos con formas de salida que dependen de *valores* de entrada, es posible que la forma de salida no se determine completamente hasta que se ejecute la inferencia.

ADVERTENCIA: Esta es una API experimental y está sujeta a cambios.

Parámetros
nombre de salida Nombre de salida en la firma.
firmaClave La clave de firma que identifica SignatureDef puede ser nula si el modelo tiene una firma.
Lanza
Argumento de excepción ilegal si outputName o signatureKey son nulos o están vacíos, o se proporciona un nombre no válido.

Cadena pública [] getSignatureInputs (Cadena clave de firma )

Obtiene la lista de entradas SignatureDefs para el método signatureKey .

ADVERTENCIA: Esta es una API experimental y está sujeta a cambios.

Parámetros
firmaClave

cadena pública [] getSignatureKeys ()

Obtiene la lista de nombres de métodos exportados SignatureDef disponibles en el modelo.

ADVERTENCIA: Esta es una API experimental y está sujeta a cambios.

Cadena pública [] getSignatureOutputs (Cadena clave de firma )

Obtiene la lista de resultados de SignatureDefs para el método signatureKey .

ADVERTENCIA: Esta es una API experimental y está sujeta a cambios.

Parámetros
firmaClave

reinicio público vacíoVariableTensors ()

Avanzado: restablece todos los tensores variables al valor predeterminado.

Si un tensor variable no tiene un búfer asociado, se restablecerá a cero.

ADVERTENCIA: Esta es una API experimental y está sujeta a cambios.

public void resizeInput (int idx, int[] atenua, booleano estricto)

Cambia el tamaño de la entrada idx-ésima del modelo nativo a las atenuaciones dadas.

Cuando "estricto" es Verdadero, solo se pueden cambiar el tamaño de las dimensiones desconocidas. Las dimensiones desconocidas se indican como "-1" en la matriz devuelta por "Tensor.shapeSignature()".

Parámetros
identificación
se atenúa
estricto

public void resizeInput (int idx, int[] se atenúa)

Cambia el tamaño de la entrada idx-ésima del modelo nativo a las atenuaciones dadas.

Parámetros
identificación
se atenúa

ejecución pública vacía (entrada de objeto , salida de objeto )

Ejecuta la inferencia del modelo si el modelo toma solo una entrada y proporciona solo una salida.

Advertencia: La API es más eficiente si se utiliza un Buffer (preferiblemente directo, pero no obligatorio) como tipo de datos de entrada/salida. Considere utilizar Buffer para alimentar y recuperar datos primitivos para un mejor rendimiento. Se admiten los siguientes tipos Buffer concretos:

  • ByteBuffer : compatible con cualquier tipo de tensor primitivo subyacente.
  • FloatBuffer : compatible con tensores flotantes.
  • IntBuffer : compatible con tensores int32.
  • LongBuffer : compatible con tensores int64.
Tenga en cuenta que los tipos booleanos solo se admiten como matrices, no como Buffer o como entradas escalares.

Parámetros
aporte una matriz o matriz multidimensional, o un Buffer de tipos primitivos que incluyen int, float, long y byte. Buffer es la forma preferida de pasar datos de entrada grandes para tipos primitivos, mientras que los tipos de cadena requieren el uso de la ruta de entrada de matriz (multidimensional). Cuando se utiliza un Buffer , su contenido debe permanecer sin cambios hasta que se realice la inferencia del modelo, y la persona que llama debe asegurarse de que el Buffer esté en la posición de lectura adecuada. Se permite un valor null solo si la persona que llama utiliza un Delegate que permite la interoperabilidad del controlador del búfer y dicho búfer se ha vinculado al Tensor de entrada.
producción una matriz multidimensional de datos de salida o un Buffer de tipos primitivos que incluyen int, float, long y byte. Cuando se utiliza un Buffer , la persona que llama debe asegurarse de que esté configurado en la posición de escritura adecuada. Se permite un valor nulo y es útil en determinados casos, por ejemplo, si la persona que llama utiliza un Delegate que permite la interoperabilidad del manejo del búfer y dicho búfer se ha vinculado al Tensor de salida (consulte también Interpreter.Options#setAllowBufferHandleOutput(boolean) ), o si el gráfico tiene salidas con forma dinámica y la persona que llama debe consultar la forma Tensor salida después de invocar la inferencia, obteniendo los datos directamente del tensor de salida (a través de Tensor.asReadOnlyBuffer() ).

public void runForMultipleInputsOutputs ( Objeto[] entradas, Mapa < Entero , Objeto > salidas)

Ejecuta la inferencia del modelo si el modelo toma múltiples entradas o devuelve múltiples salidas.

Advertencia: La API es más eficiente si se utilizan Buffer (preferiblemente directos, pero no obligatorios) como tipos de datos de entrada/salida. Considere utilizar Buffer para alimentar y recuperar datos primitivos para un mejor rendimiento. Se admiten los siguientes tipos Buffer concretos:

  • ByteBuffer : compatible con cualquier tipo de tensor primitivo subyacente.
  • FloatBuffer : compatible con tensores flotantes.
  • IntBuffer : compatible con tensores int32.
  • LongBuffer : compatible con tensores int64.
Tenga en cuenta que los tipos booleanos solo se admiten como matrices, no como Buffer o como entradas escalares.

Nota: los valores null para elementos individuales de inputs y outputs solo se permiten si la persona que llama utiliza un Delegate que permite la interoperabilidad del manejo del búfer, y dicho búfer se ha vinculado a los Tensor de entrada o salida correspondientes.

Parámetros
entradas una serie de datos de entrada. Las entradas deben estar en el mismo orden que las entradas del modelo. Cada entrada puede ser una matriz o una matriz multidimensional, o un Buffer de tipos primitivos que incluyen int, float, long y byte. Buffer es la forma preferida de pasar datos de entrada grandes, mientras que los tipos de cadena requieren el uso de la ruta de entrada de la matriz (multidimensional). Cuando se utiliza Buffer , su contenido debe permanecer sin cambios hasta que se realice la inferencia del modelo, y la persona que llama debe asegurarse de que el Buffer esté en la posición de lectura adecuada.
salidas un mapa que asigna índices de salida a matrices multidimensionales de datos de salida o Buffer de tipos primitivos, incluidos int, float, long y byte. Solo necesita conservar las entradas para las salidas que se utilizarán. Cuando se utiliza un Buffer , la persona que llama debe asegurarse de que esté configurado en la posición de escritura adecuada. El mapa puede estar vacío en los casos en los que se utilizan identificadores de búfer para los datos del tensor de salida, o en los casos en los que las salidas tienen forma dinámica y el autor de la llamada debe consultar la forma del Tensor de salida después de invocar la inferencia, obteniendo los datos directamente del tensor de salida ( a través de Tensor.asReadOnlyBuffer() ).

public void runSignature ( Mapa < Cadena , Objeto > entradas, Mapa < Cadena , Objeto > salidas)

Igual que runSignature(Map, Map, String) pero no requiere pasar una clave de firma, suponiendo que el modelo tenga una SignatureDef. Si el modelo tiene más de un SignatureDef, generará una excepción.

ADVERTENCIA: Esta es una API experimental y está sujeta a cambios.

Parámetros
entradas
salidas

public void runSignature ( Mapa < Cadena , Objeto > entradas, Mapa < Cadena , Objeto > salidas, Cadena firmaClave)

Ejecuta la inferencia del modelo basada en SignatureDef proporcionada a través de signatureKey .

Consulte run(Object, Object) para obtener más detalles sobre los tipos de datos de entrada y salida permitidos.

ADVERTENCIA: Esta es una API experimental y está sujeta a cambios.

Parámetros
entradas Un mapa del nombre de entrada en SignatureDef a un objeto de entrada.
salidas Un mapa desde el nombre de salida en SignatureDef hasta los datos de salida. Esto puede estar vacío si la persona que llama desea consultar los datos del Tensor directamente después de la inferencia (por ejemplo, si la forma de salida es dinámica o se utilizan identificadores del búfer de salida).
firmaClave Clave de firma que identifica SignatureDef.
Lanza
Argumento de excepción ilegal si inputs son nulas o están vacías, si outputs o signatureKey son nulas o si se produce un error al ejecutar la inferencia.

set de vacío público cancelado (booleano cancelado)

Avanzado: interrumpe la inferencia en medio de una llamada a run(Object, Object) .

Un indicador de cancelación se establecerá en verdadero cuando se llame a esta función. El intérprete verificará la bandera entre las invocaciones de Op y, si es true , detendrá la ejecución. El intérprete permanecerá en un estado cancelado hasta que setCancelled(false) lo "descancele" explícitamente.

ADVERTENCIA: Esta es una API experimental y está sujeta a cambios.

Parámetros
cancelado true para cancelar la inferencia con el mejor esfuerzo; false para reanudar.
Lanza
Excepción de estado ilegal si el intérprete no se inicializa con la opción cancelable, que está desactivada de forma predeterminada.