Interpreter

Intérprete de la clase final pública

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

Nota: Si no necesitas acceder a ninguna de las funciones "experimentales" de la API que se mencionan a continuación, usa InterpreterApi e InterpreterFactory en lugar de usar directamente Interpreter.

Un Interpreter encapsula un modelo de TensorFlow Lite previamente entrenado, en el que se ejecutan operaciones para realizar inferencias de modelos.

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

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

Si un modelo acepta varias 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 cadena:

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

Ten en cuenta que hay una distinción entre forma [] y forma[1]. Para resultados de tensores de string 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 pedidos de entrada y salida se determinan cuando se convierte un modelo de TensorFlow en un modelo de TensorFlowLite con Toco, al igual que las formas predeterminadas de las entradas.

Cuando las entradas se proporcionan como arrays (multidimensionales), se cambiará el tamaño de los tensores de entrada correspondientes de manera implícita según la forma del array. Cuando las entradas se proporcionan como tipos Buffer, no se realiza un cambio de tamaño implícito; el llamador debe asegurarse de que el tamaño en bytes de Buffer coincida con el del tensor correspondiente o que primero cambia el tamaño del tensor mediante resizeInput(int, int[]). La información de tipo y forma del tensor se puede obtener a través de la clase Tensor, que está disponible a través de getInputTensor(int) y getOutputTensor(int).

ADVERTENCIA: Las instancias Interpreter no son seguras para los subprocesos. Un Interpreter posee recursos que deben liberarse explícitamente mediante la invocación de close()

La biblioteca de TFLite se compila en función de la API 19 del NDK. Es posible que funcione para niveles de API inferiores a 19, pero no está garantizado.

Categorías anidadas

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

Constructores públicos

Intérprete(Archivo modelFile)
Inicializa un Interpreter.
Intérprete(opciones Archivo modelFile, Interpreter.Options)
Inicializa un Interpreter y especifica opciones para personalizar el comportamiento del intérprete.
Intérprete(Búfer de bytes ByteBuffer)
Inicializa un Interpreter con un ByteBuffer de un archivo de modelo.
Intérprete(Búfer de bytes ByteBuffer, opciones de Interpreter.Options)
Inicializa un Interpreter con un ByteBuffer de un archivo de modelo y un conjunto de Interpreter.Options personalizados.

Métodos públicos

void
allocateTensors()
Actualiza de manera explícita las asignaciones de todos los tensores, si es necesario.
void
close()
Libera los recursos asociados con la instancia InterpreterApi.
int
getInputIndex(nombre de operación String)
Obtiene el índice de una entrada según el nombre de la operación de la entrada.
Tensor
getInputTensor(int inputIndex)
Obtiene el tensor asociado con el índice de entrada proporcionado.
int
getInputTensorCount().
Obtiene la cantidad 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.
Versión larga
getLastNativeInferenceDurationNanoseconds()
Muestra el tiempo de inferencia nativo.
int
getOutputIndex(nombre de operación String)
Obtiene el índice de una salida según el nombre de la operación de la salida.
Tensor
getOutputTensor(int outputIndex)
Obtiene el tensor asociado con el índice de salida proporcionado.
int
getOutputTensorCount()
Obtiene la cantidad de tensores de salida.
Tensor
getOutputTensorFromSignature(String outputName, String signatureKey)
Obtiene el tensor asociado con el nombre de salida proporcionado en el método de firma específico.
Cadena[]
getSignatureInputs(String signatureKey)
Obtiene la lista de entradas de SignatureDefs para el método signatureKey.
Cadena[]
getSignatureKeys()
Obtiene la lista de nombres de métodos exportados de SignatureDef disponibles en el modelo.
Cadena[]
getSignatureOutputs(String signatureKey)
Obtiene la lista de resultados de SignatureDefs para el método signatureKey.
void
resetVariableTensors()
Avanzado: Restablece todos los tensores de variables al valor predeterminado.
void
resizeInput(int idx, int[] dims, boolean strict)
Cambia el tamaño de la entrada idx-th del modelo nativo a las atenuaciones determinadas.
void
resizeInput(int idx, int[] atenuación)
Cambia el tamaño de la entrada idx-th del modelo nativo a las atenuaciones determinadas.
void
run(entrada de objeto, salida de objeto)
Ejecuta la inferencia de modelo si el modelo admite solo una entrada y proporciona una sola salida.
void
runForMultipleInputsOutputs(Object[], salidas Map<IntegerObject>)
Ejecuta la inferencia del modelo si este toma varias entradas o muestra varias salidas.
void
runSignature(Map<StringObject> entradas, Map<StringObject> salidas)
Igual que runSignature(Map, Map, String), pero no requiere pasar una signatureKey, suponiendo que el modelo tiene un SignatureDef.
void
runSignature(Map<StringObject> entradas, Map<StringObject> salidas, String signatureKey)
Ejecuta la inferencia de modelo basada en SignatureDef proporcionado a través de signatureKey.
void
setCancelled(booleano cancelado)
Avanzado: Interrumpe la inferencia en medio de una llamada a run(Object, Object).

Métodos heredados

Constructores públicos

public Intérprete (Archivo modelFile)

Inicializa un Interpreter.

Parámetros
modelFile un archivo de un modelo de TF Lite previamente entrenado.
Arroja
IllegalArgumentException si modelFile no codifica un modelo de TensorFlow Lite válido.

public Intérprete (opciones de File modelFile, Interpreter.Options)

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

Parámetros
modelFile un archivo de un modelo de TF Lite previamente entrenado
Opciones un conjunto de opciones para personalizar el comportamiento del intérprete
Arroja
IllegalArgumentException si modelFile no codifica un modelo de TensorFlow Lite válido.

public Intérprete (byteBufferByteBuffer)

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

El ByteBuffer no se debe modificar después de la construcción de un Interpreter. El ByteBuffer puede ser un MappedByteBuffer que asigna memorias a un archivo de modelo o un ByteBuffer directo de nativeOrder() que incluye el contenido de bytes de un modelo.

Parámetros
byteBuffer
Arroja
IllegalArgumentException si byteBuffer no es MappedByteBuffer ni un ByteBuffer directo de nativeOrder.

public Intérprete (opciones de ByteBuffer byteBuffer, Interpreter.Options)

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

El ByteBuffer no se debe modificar después de la construcción de un Interpreter. El ByteBuffer puede ser un MappedByteBuffer que asigna la memoria a un archivo de modelo o un ByteBuffer directo de nativeOrder() que incluye el contenido de bytes de un modelo.

Parámetros
byteBuffer
Opciones
Arroja
IllegalArgumentException si byteBuffer no es MappedByteBuffer ni un ByteBuffer directo de nativeOrder.

Métodos públicos

public void allocateTensors ()

Actualiza de manera explícita las asignaciones de todos los tensores, si es necesario.

Esto propagará las formas y las asignaciones de memoria para tensores dependientes usando las formas de tensor de entrada correspondientes.

Nota: Esta llamada es *completamente opcional*. La asignación de tensores se producirá automáticamente durante la ejecución si se cambió el tamaño de los tensores de entrada. Esta llamada es más útil para determinar las formas de los tensores de salida antes de ejecutar el grafo, p.ej.,

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

public void close ()

Libera los recursos asociados con la instancia InterpreterApi.

public int getInputIndex (String opName)

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

Parámetros
opName

public Tensor getInputTensor (int inputIndex)

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

Parámetros
inputIndex

public int getInputTensorCount ()

Obtiene la cantidad de tensores de entrada.

public Tensor 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
inputName Ingresa el nombre en la firma.
signatureKey La clave de firma que identifica a SignatureDef puede ser nula si el modelo tiene una firma.
Arroja
IllegalArgumentException si inputName o signatureKey es nulo o está vacío, o se proporcionó un nombre no válido.

public Long getLastNativeInferenceDurationNanoseconds ()

Muestra el tiempo de inferencia nativo.

public int getOutputIndex (String opName)

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

Parámetros
opName

public Tensor getOutputTensor (int outputIndex)

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

Nota: Es posible que los detalles del tensor de salida (p.ej., la forma) no se propaguen por completo hasta que se ejecute la inferencia. Si necesitas 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), usa allocateTensors() para activar explícitamente la asignación y la propagación de la forma. Ten 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
outputIndex

public int getOutputTensorCount ()

Obtiene la cantidad de tensores de salida.

public Tensor getOutputTensorFromSignature (String outputName, String signatureKey)

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

Nota: Es posible que los detalles del tensor de salida (p.ej., la forma) no se propaguen por completo hasta que se ejecute la inferencia. Si necesitas 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), usa allocateTensors() para activar explícitamente la asignación y la propagación de la forma. Ten 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
outputName Nombre del resultado en la firma.
signatureKey La clave de firma que identifica a SignatureDef puede ser nula si el modelo tiene una firma.
Arroja
IllegalArgumentException si outputName o signatureKey es nulo o está vacío, o se proporcionó 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
signatureKey

public String[] 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 resultados de SignatureDefs para el método signatureKey.

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

Parámetros
signatureKey

public void resetVariableTensors ()

Avanzado: Restablece todos los tensores de 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, boolean strict)

Cambia el tamaño de la entrada idx-th del modelo nativo a las atenuaciones específicas.

Cuando `strict` se establece en True, solo se puede cambiar el tamaño de las dimensiones desconocidas. Las dimensiones desconocidas se indican como `-1` en el array que muestra `Tensor.shapeSignature()`.

Parámetros
idx
dims
Estricta

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

Cambia el tamaño de la entrada idx-th del modelo nativo a las atenuaciones específicas.

Parámetros
idx
dims

public void run (Object input, Object output)

Ejecuta la inferencia de modelo si el modelo admite solo una entrada y proporciona una sola salida.

Advertencia: La API es más eficiente si se usa un Buffer (preferentemente directo, pero no obligatorio) como tipo de datos de entrada/salida. Considera usar Buffer para enviar y recuperar datos básicos y, así, lograr un mejor rendimiento. Se admiten los siguientes tipos concretos de Buffer:

  • ByteBuffer: Es compatible con cualquier tipo de tensor primitivo subyacente.
  • FloatBuffer: compatible con tensores de número de punto flotante.
  • IntBuffer: Es compatible con tensores int32.
  • LongBuffer: Es compatible con tensores int64.
Ten en cuenta que los tipos booleanos solo se admiten como arrays, no como Buffer ni como entradas escalares.

Parámetros
entrada un array o un array 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 los tipos primitivos, mientras que los tipos de cadenas requieren el uso de una ruta de entrada de array (multidimensional). Cuando se usa una Buffer, su contenido no debe modificarse hasta que se complete la inferencia de modelo, y el llamador debe asegurarse de que Buffer esté en la posición de lectura adecuada. Solo se permite un valor null si el llamador usa un Delegate que permite la interoperabilidad del controlador de búfer y si ese búfer se vinculó a la Tensor de entrada.
salida un array multidimensional de datos de salida o un Buffer de tipos primitivos, incluidos int, float, long y byte. Cuando se usa un Buffer, el llamador debe asegurarse de que esté configurada en la posición de escritura adecuada. Se permite un valor nulo, que es útil en determinados casos, p.ej., si el llamador usa un Delegate que permite la interoperabilidad del controlador de búfer y ese búfer se vinculó al Tensor de salida (consulta también Interpreter.Options#setAllowBufferHandleOutput(boolean)), o si el gráfico dio forma a salidas de forma dinámica y el llamador debe consultar la forma Tensor de salida después de invocar la inferencia (recuperando los datos directamente desde el tensor de salida).Tensor.asReadOnlyBuffer()

public void runForMultipleInputsOutputs (Object[] entradas, Map<IntegerObject> output)

Ejecuta la inferencia del modelo si este toma varias entradas o muestra varias salidas.

Advertencia: La API es más eficiente si se usan Buffers (preferentemente directos, pero no obligatorios) como tipos de datos de entrada/salida. Considera usar Buffer para enviar y recuperar datos básicos y, así, lograr un mejor rendimiento. Se admiten los siguientes tipos concretos de Buffer:

  • ByteBuffer: Es compatible con cualquier tipo de tensor primitivo subyacente.
  • FloatBuffer: compatible con tensores de número de punto flotante.
  • IntBuffer: Es compatible con tensores int32.
  • LongBuffer: Es compatible con tensores int64.
Ten en cuenta que los tipos booleanos solo se admiten como arrays, no como Buffer ni como entradas escalares.

Nota: Solo se permiten valores null para elementos individuales de inputs y outputs si el llamador usa un Delegate que permite la interoperabilidad de control del búfer y este se vinculó a las Tensor de entrada o salida correspondientes.

Parámetros
ocultas un array de datos de entrada. Las entradas deben estar en el mismo orden que las entradas del modelo. Cada entrada puede ser un array o un array multidimensional, o bien una Buffer de tipos primitivos, como int, float, long y byte. Buffer es la forma preferida de pasar datos de entrada grandes, mientras que los tipos de cadenas requieren el uso de la ruta de entrada de array (multidimensional). Cuando se usa Buffer, su contenido debe permanecer sin cambios hasta que se complete la inferencia de modelo, y el llamador debe asegurarse de que Buffer esté en la posición de lectura adecuada.
salidas una asignación de índices de salida a arrays multidimensionales de datos de salida o Buffer de tipos primitivos, como int, float, long y byte. Solo necesita conservar entradas para que las salidas se usen. Cuando se usa un Buffer, el llamador debe asegurarse de que esté configurada en la posición de escritura adecuada. El mapa puede estar vacío para casos en los que los controladores de búfer se usan para datos del tensor de salida o en los que las salidas tienen una forma dinámica y el llamador debe consultar la forma Tensor de salida después de invocar la inferencia y recuperar los datos directamente desde el tensor de salida (a través de Tensor.asReadOnlyBuffer()).

public void runSignature (Map<StringObject> input, Map<StringObject> output)

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

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

Parámetros
ocultas
salidas

public void runSignature (Map<StringObject> input, Map<StringObject> output, String signatureKey)

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

Consulta 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
ocultas Una asignación del nombre de entrada en SignatureDef a un objeto de entrada.
salidas Una asignación del nombre de salida en SignatureDef a los datos de salida. Puede estar vacío si el llamador desea consultar los datos de Tensor directamente después de la inferencia (p.ej., si la forma de salida es dinámica o se usan controladores del búfer de salida).
signatureKey Clave de firma que identifica a SignatureDef.
Arroja
IllegalArgumentException si inputs es nulo o está vacío, si outputs o signatureKey es nulo, o si se produce un error cuando se ejecuta la inferencia.

public void setCancelled (boolean cancelled)

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

Una marca de cancelación se establecerá como verdadera cuando se llame a esta función. El intérprete verificará la marca entre las invocaciones de operaciones y, si es true, detendrá la ejecución. El intérprete permanecerá en un estado cancelado hasta que setCancelled(false) lo anule explícitamente.

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

Parámetros
cancelado true para cancelar la inferencia de la mejor manera posible; false para reanudar.
Arroja
IllegalStateException si el intérprete no se inicializa con la opción cancelable, que está desactivada de forma predeterminada.