Interpreter

Intérprete de clase final pública

Clase de controlador para impulsar la inferencia del modelo con TensorFlow Lite.

Nota: Si no necesita acceder a ninguna de las características de la API "experimental" a continuación, prefiera usar InterpreterApi e InterpreterFactory en lugar de usar Interpreter directamente.

Un Interpreter encapsula un modelo TensorFlow Lite entrenado previamente, 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 cuerda:

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 hay 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 se redimensionarán 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 del byte Buffer coincida con el del tensor correspondiente o que primero cambie el tamaño del tensor a través de resizeInput(int, int[]) . La información sobre la forma y el tipo del 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 al invocar close()

La biblioteca TFLite está construida contra NDK API 19. Puede funcionar para niveles de API de Android por debajo de 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 ( Archivo modeloArchivo)
Inicializa un Interpreter .
Intérprete (Modelo de archivoArchivo , Intérprete.Opciones opciones)
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 de modelo.
Intérprete ( ByteBuffer byteBuffer, opciones de Interpreter.Options )
Inicializa un Interpreter con un ByteBuffer de un archivo de modelo y un conjunto de Interpreter.Options personalizadas.

Métodos públicos

vacío
asignar tensores ()
Actualiza explícitamente las asignaciones para todos los tensores, si es necesario.
vacío
cerrar ()
Libere los recursos asociados con la instancia InterpreterApi .
En t
getInputIndex ( String opName)
Obtiene el índice de una entrada dado el nombre de operación de la entrada.
Tensor
getInputTensor (índice de entrada int)
Obtiene el tensor asociado con el índice de entrada proporcionado.
En t
getInputTensorCount ()
Obtiene el número de tensores de entrada.
Tensor
getInputTensorFromSignature ( String inputName, String signatureKey)
Obtiene el tensor asociado con el nombre de entrada y el nombre del método de firma proporcionados.
Largo
getLastNativeInferenceDurationNanosegundos ()
Devuelve el tiempo de inferencia nativo.
En t
getOutputIndex ( Cadena opName)
Obtiene el índice de una salida dado el nombre de operación de la salida.
Tensor
getOutputTensor (índice de salida int)
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 clave de firma)
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 de SignatureDefs para el método signatureKey .
Cadena[]
obtener claves de firma ()
Obtiene la lista de nombres de métodos exportados de SignatureDef disponibles en el modelo.
Cadena[]
getSignatureOutputs (cadena clave de firma )
Obtiene la lista de salidas de SignatureDefs para el método signatureKey .
vacío
resetVariableTensors ()
Avanzado: restablece todos los tensores variables al valor predeterminado.
vacío
resizeInput (int idx, int[] dims, booleano estricto)
Cambia el tamaño de la entrada idx-ésima del modelo nativo a las dimensiones dadas.
vacío
resizeInput (int idx, int[] dims)
Cambia el tamaño de la entrada idx-ésima del modelo nativo a las dimensiones dadas.
vacío
ejecutar (entrada de objeto , salida de objeto )
Ejecuta la inferencia del modelo si el modelo solo toma 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 varias entradas o devuelve varias 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, asumiendo que el modelo tiene una SignatureDef.
vacío
runSignature ( Mapa < Cadena , Objeto > entradas, Mapa < Cadena , Objeto > salidas, Clave de firma de cadena )
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 un archivo de un modelo TF Lite preentrenado.
Lanza
Argumento de excepción ilegal si modelFile no codifica un modelo TensorFlow Lite válido.

Intérprete público (Modelo de archivoArchivo , opciones de 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 pre-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 TensorFlow Lite válido.

Intérprete público ( ByteBuffer byteBuffer)

Inicializa un Interpreter con un ByteBuffer de un archivo de modelo.

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

Parámetros
byteBuffer
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 de Interpreter.Options )

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

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

Parámetros
byteBuffer
opciones
Lanza
Argumento de excepción ilegal si byteBuffer no es un MappedByteBuffer ni un ByteBuffer directo de nativeOrder.

Métodos públicos

public void allocateTensors ()

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

Esto propagará las formas y las asignaciones de memoria para los tensores dependientes usando las formas del tensor de entrada como se indica.

Nota: Esta llamada es *puramente opcional*. La asignación de tensores ocurrirá automáticamente durante la ejecución si se ha cambiado el tamaño de los tensores 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 de vacío público ()

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
opName

Tensor público getInputTensor (int inputIndex)

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

Parámetros
índice de entrada

getInputTensorCount público int ()

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 y el nombre del método de firma proporcionados.

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 a SignatureDef puede ser nula si el modelo tiene una firma.
Lanza
Argumento de excepción ilegal si inputName o signatureKey es nulo o está vacío, o si 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
opName

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

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

Nota: Es posible que los detalles del tensor de salida (por ejemplo, la forma) no se llenen por completo hasta que se ejecute la inferencia. Si necesita detalles actualizados *antes* de ejecutar la inferencia (p. ej., 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 los gráficos con formas de salida que dependen de *valores* de entrada, es posible que la forma de salida no se determine por completo hasta que se ejecute la inferencia.

Parámetros
índice de salida

getOutputTensorCount público int ()

Obtiene el número de tensores de salida.

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

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 (por ejemplo, la forma) no se llenen por completo hasta que se ejecute la inferencia. Si necesita detalles actualizados *antes* de ejecutar la inferencia (p. ej., 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 los gráficos con formas de salida que dependen de *valores* de entrada, es posible que la forma de salida no se determine por completo hasta que se ejecute la inferencia.

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

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

public String[] getSignatureInputs ( String signatureKey)

Obtiene la lista de entradas de 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 de SignatureDef disponibles en el modelo.

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

public String[] getSignatureOutputs ( String signatureKey)

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

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

Parámetros
firmaClave

public void resetVariableTensors ()

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[] dims, booleano estricto)

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

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

Parámetros
idx
atenúa
estricto

resizeInput vacío público (int idx, int[] dims)

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

Parámetros
idx
atenúa

ejecución de vacío público (entrada de objeto , salida de objeto )

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

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

  • 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, incluidos 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 usa 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 está usando un Delegate que permite la interoperabilidad de manejo de 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, incluidos 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 para ciertos casos, por ejemplo, si la persona que llama está usando un Delegate que permite la interoperabilidad del manejo del búfer, y dicho búfer se ha vinculado al Tensor de salida (ver 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 varias entradas o devuelve varias salidas.

Advertencia: la API es más eficaz si se utilizan Buffer s (preferiblemente directos, pero no obligatorios) como tipos de datos de entrada/salida. Considere usar Buffer para alimentar y obtener datos primitivos para un mejor rendimiento. Se admiten los siguientes tipos Buffer concretas:

  • 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 está utilizando un Delegate que permite la interoperabilidad de manejo de búfer, y dicho búfer se ha vinculado a los Tensor de entrada o salida correspondientes.

Parámetros
entradas una matriz 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, incluidos int, float, long y byte. Buffer es la forma preferida de pasar datos de entrada de gran tamaño, mientras que los tipos de cadena requieren el uso de la ruta de entrada de matriz (multidimensional). Cuando se usa Buffer , su contenido debe permanecer sin cambios hasta que se realice la inferencia del modelo, y la persona que llama debe asegurarse de que 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 mantener 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 para los casos en los que se utilizan controladores de búfer para los datos del tensor de salida, o en los casos en que las salidas tienen una forma dinámica y la persona que llama debe consultar la forma Tensor de salida después de invocar la inferencia, obteniendo los datos directamente del tensor de salida ( a través de Tensor.asReadOnlyBuffer() ).

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

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

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

Parámetros
entradas
salidas

runSignature public void ( mapa < cadena , objeto > entradas, mapa < cadena , objeto > salidas, cadena firma clave)

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 Tensor directamente después de la inferencia (por ejemplo, si la forma de salida es dinámica o si se utilizan controladores de búfer de salida).
firmaClave Clave de firma que identifica a 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.

public void setCancelled (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á el indicador entre las invocaciones de Op y, si es true , el intérprete 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 en la forma de mejor esfuerzo; false para reanudar.
Lanza
IllegalStateExceptionIlegalStateException si el intérprete no se inicializa con la opción cancelable, que por defecto está desactivada.