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(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 | |
void |
runForMultipleInputsOutputs(Object[], salidas Map<Integer, Object>)
Ejecuta la inferencia del modelo si este toma varias entradas o muestra varias salidas.
|
void |
runSignature(Map<String, Object> entradas, Map<String, Object> salidas)
Igual que
runSignature(Map, Map, String) , pero no requiere pasar una signatureKey,
suponiendo que el modelo tiene un SignatureDef. |
void | |
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 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.
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<Integer, Object> 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 Buffer
s (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.
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<String, Object> input, Map<String, Object> 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<String, Object> input, Map<String, Object> 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. |
---|