Classe de driver para gerar inferência de modelos com o TensorFlow Lite.
Observação: se você não precisar de acesso a nenhum dos recursos "experimentais" da API abaixo, prefira usar InterpreterApi e InterpreterFactory em vez de Interpreter diretamente.
Um Interpreter
encapsula um modelo pré-treinado do TensorFlow Lite, em que as operações
são executadas para inferência do modelo.
Por exemplo, quando um modelo usa apenas uma entrada e retorna apenas uma saída:
try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
interpreter.run(input, output);
}
Se um modelo usa várias entradas ou saídas:
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);
}
Se um modelo usa ou produz tensores de string:
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);
}
Observe que há uma distinção entre forma [] e shape[1]. Para saídas de tensor 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);
As ordens de entradas e saídas são determinadas ao converter o modelo do TensorFlow para o modelo do TensorFlowLite com o Toco, assim como as formas padrão das entradas.
Quando as entradas são fornecidas como matrizes (multidimensionais), os tensores de entrada correspondentes são implicitamente redimensionados de acordo com a forma da matriz. Quando as entradas são fornecidas como tipos Buffer
, nenhum redimensionamento implícito é feito. O autor da chamada precisa garantir que o tamanho de byte Buffer
corresponda ao do tensor correspondente ou primeiro redimensione o tensor via resizeInput(int, int[])
. As informações sobre a forma e o tipo do tensor podem ser recebidas pela classe Tensor
, disponível via getInputTensor(int)
e getOutputTensor(int)
.
AVISO: as instâncias do Interpreter
não são thread-safe. Um Interpreter
possui recursos que precisam ser explicitamente liberados ao invocar close()
A biblioteca TFLite é compilada com base na API 19 do NDK. Isso pode funcionar para níveis de API do Android anteriores ao 19, mas isso não é garantido.
Classes aninhadas
classe | Interpreter.Options | Uma classe de opções para controlar o comportamento do intérprete no momento da execução. |
Construtores públicos
Interpreter(modelo de File, Interpreter.Options)
Inicializa um
Interpreter e especifica opções para personalizar o comportamento do intérprete. |
|
Interpreter(byteBuffer ByteBuffer)
Inicializa um
Interpreter com um ByteBuffer de um arquivo de modelo. |
|
Interpreter(opções ByteBuffer byteBuffer, Interpreter.Options)
Inicializa um
Interpreter com um ByteBuffer de um arquivo de modelo e um conjunto de
Interpreter.Options personalizados. |
Métodos públicos
void |
allocateTensors()
Atualiza explicitamente as alocações para todos os tensores, se necessário.
|
void |
close()
Libere recursos associados à instância
InterpreterApi . |
int | |
Tensor (link em inglês) |
getInputTensor(int inputIndex)
Recebe o tensor associado ao índice de entrada fornecido.
|
int |
getInputTensorCount()
Recebe o número de tensores de entrada.
|
Tensor (link em inglês) |
getInputTensorFromSignature(String inputName, String signatureKey)
Recebe o Tensor associado ao nome de entrada e do método de assinatura fornecidos.
|
Longa |
getLastNativeInferenceDurationNanoseconds()
Retorna o tempo de inferência nativo.
|
int | |
Tensor (link em inglês) |
getOutputTensor(int outputIndex)
Recebe o tensor associado ao índice de saída fornecido.
|
int |
getOutputTensorCount()
Recebe o número de tensores de saída.
|
Tensor (link em inglês) |
getOutputTensorFromSignature(String outputName, String signatureKey)
Recebe o tensor associado ao nome de saída fornecido no método de assinatura específico.
|
String[] |
getSignatureInputs(String signatureKey)
Recebe a lista de entradas SignatureDefs para o método
signatureKey . |
String[] |
getSignatureKeys()
Recebe a lista de nomes de métodos exportados do SignatureDef disponíveis no modelo.
|
String[] |
getSignatureOutputs(String signatureKey)
Recebe a lista de saídas de SignatureDefs para o método
signatureKey . |
void |
resetVariableTensors()
Avançado: redefine todos os tensores de variáveis para o valor padrão.
|
void |
resizeInput(int idx, int[] dims, boolean strict)
Redimensiona a entrada idx-th do modelo nativo para as cores esmaecidas fornecidas.
|
void |
resizeInput(int idx, int[] dims)
Redimensiona a entrada idx-th do modelo nativo para as cores esmaecidas fornecidas.
|
void | |
void |
runForMultipleInputsOutputs(entradas Object[], Map<Integer, Object> saídas)
Executa a inferência de modelo se o modelo receber várias entradas ou retornar várias saídas.
|
void |
runSignature(entradas Map<String, Object>, Map<String, Object> saídas)
Igual a
runSignature(Map, Map, String) , mas não exige a transmissão de uma signatureKey, supondo que o modelo tenha um SignatureDef. |
void | |
void |
setCancelled(booleano cancelado)
Avançado: interrompe a inferência no meio de uma chamada para
run(Object, Object) . |
Métodos herdados
Construtores públicos
público Interpretador (Arquivo modelFile)
Inicializa um Interpreter
.
Parâmetros
modelFile | um arquivo de um modelo TF Lite pré-treinado. |
---|
Gera
IllegalArgumentException | se modelFile não codificar um modelo válido do TensorFlow Lite.
|
---|
public Interpretador (Arquivo modelFile, Interpreter.Options opções)
Inicializa um Interpreter
e especifica opções para personalizar o comportamento do intérprete.
Parâmetros
modelFile | um arquivo de um modelo pré-treinado do TF Lite |
---|---|
do modelo. | um conjunto de opções para personalizar o comportamento do intérprete |
Gera
IllegalArgumentException | se modelFile não codificar um modelo válido do TensorFlow Lite.
|
---|
public Interpretador (ByteBuffer byteBuffer)
Inicializa um Interpreter
com um ByteBuffer
de um arquivo de modelo.
O ByteBuffer não pode ser modificado após a construção de um Interpreter
. O ByteBuffer
pode ser um MappedByteBuffer
, que mapeia a memória de um arquivo de modelo, ou um ByteBuffer
direto de nativeOrder() que contém o conteúdo de bytes de um modelo.
Parâmetros
byteBuffer |
---|
Gera
IllegalArgumentException | se byteBuffer não for um MappedByteBuffer nem um ByteBuffer direto de nativeOrder.
|
---|
public Interpreter (ByteBuffer byteBuffer, Interpreter.Options opções)
Inicializa um Interpreter
com um ByteBuffer
de um arquivo de modelo e um conjunto de
Interpreter.Options
personalizados.
O ByteBuffer
não pode ser modificado após a construção de uma Interpreter
. O ByteBuffer
pode ser um MappedByteBuffer
, que mapeia a memória de um arquivo de modelo, ou um ByteBuffer
direto de nativeOrder() que contém o conteúdo de bytes de um modelo.
Parâmetros
byteBuffer | |
---|---|
do modelo. |
Gera
IllegalArgumentException | se byteBuffer não for um MappedByteBuffer nem um ByteBuffer direto de nativeOrder.
|
---|
Métodos públicos
public void allocateTensors ()
Atualiza explicitamente as alocações para todos os tensores, se necessário.
Isso propagará formas e alocações de memória para tensores dependentes usando as formas de tensor de entrada, conforme indicado.
Observação: esta chamada é *totalmente opcional*. A alocação de tensor vai ocorrer automaticamente durante a execução se algum tensor de entrada tiver sido redimensionado. Essa chamada é mais útil para determinar as formas de qualquer tensor de saída antes de executar o gráfico, por exemplo,
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...
Observação: alguns gráficos têm saídas com formato dinâmico. Nesse caso, a forma de saída pode não se propagar totalmente até que a inferência seja executada.
public void close ()
Libere recursos associados à instância InterpreterApi
.
public int getInputIndex (String opName)
Recebe o índice de uma entrada de acordo com o nome da operação dela.
Parâmetros
opName |
---|
público Tensor getInputTensor (int inputIndex)
Recebe o tensor associado ao índice de entrada fornecido.
Parâmetros
inputIndex |
---|
public int getInputTensorCount ()
Recebe o número de tensores de entrada.
public Tensor getInputTensorFromSignature (String inputName, String signatureKey)
Recebe o Tensor associado ao nome de entrada e do método de assinatura fornecidos.
AVISO: esta API é experimental e está sujeita a alterações.
Parâmetros
inputName | Nome de entrada na assinatura. |
---|---|
signatureKey | A chave de assinatura que identifica o SignatureDef pode ser nula se o modelo tiver uma assinatura. |
Gera
IllegalArgumentException | se inputName ou signatureKey for nulo ou vazio,
ou nome inválido fornecido.
|
---|
public int getOutputIndex (String opName)
Recebe o índice de uma saída conforme o nome da operação da saída.
Parâmetros
opName |
---|
público Tensor getOutputTensor (int outputIndex)
Recebe o tensor associado ao índice de saída fornecido.
Observação: os detalhes do tensor de saída (por exemplo, forma) podem não ser totalmente preenchidos até que a inferência
seja executada. Se você precisar de detalhes atualizados *antes* de executar a inferência (por exemplo, depois de redimensionar um tensor de entrada, o que pode invalidar as formas do tensor de saída), use allocateTensors()
para acionar explicitamente a alocação e a propagação da forma. Em gráficos com formas de saída que dependem de *valores* de entrada, a forma de saída pode não ser totalmente determinada até a execução da inferência.
Parâmetros
outputIndex |
---|
public int getOutputTensorCount ()
Recebe o número de tensores de saída.
public Tensor getOutputTensorFromSignature (String outputName, String signatureKey)
Recebe o tensor associado ao nome de saída fornecido no método de assinatura específico.
Observação: os detalhes do tensor de saída (por exemplo, forma) podem não ser totalmente preenchidos até que a inferência
seja executada. Se você precisar de detalhes atualizados *antes* de executar a inferência (por exemplo, depois de redimensionar um tensor de entrada, o que pode invalidar as formas do tensor de saída), use allocateTensors()
para acionar explicitamente a alocação e a propagação da forma. Em gráficos com formas de saída que dependem de *valores* de entrada, a forma de saída pode não ser totalmente determinada até a execução da inferência.
AVISO: esta API é experimental e está sujeita a alterações.
Parâmetros
outputName | Nome de saída na assinatura. |
---|---|
signatureKey | A chave de assinatura que identifica o SignatureDef pode ser nula se o modelo tiver uma assinatura. |
Gera
IllegalArgumentException | se outputName ou signatureKey for nulo ou vazio, ou nome inválido fornecido.
|
---|
public String[] getSignatureInputs (String signatureKey)
Recebe a lista de entradas SignatureDefs para o método signatureKey
.
AVISO: esta API é experimental e está sujeita a alterações.
Parâmetros
signatureKey |
---|
public String[] getSignatureKeys ()
Recebe a lista de nomes de métodos exportados do SignatureDef disponíveis no modelo.
AVISO: esta API é experimental e está sujeita a alterações.
public String[] getSignatureOutputs (String signatureKey)
Recebe a lista de saídas de SignatureDefs para o método signatureKey
.
AVISO: esta API é experimental e está sujeita a alterações.
Parâmetros
signatureKey |
---|
public void resetVariableTensors ()
Avançado: redefine todos os tensores de variáveis para o valor padrão.
Se um tensor de variável não tiver um buffer associado, ele será redefinido como zero.
AVISO: esta API é experimental e está sujeita a alterações.
public void resizeInput (int idx, int[] dims, boolean strict)
Redimensiona a entrada idx-th do modelo nativo para as cores esmaecidas fornecidas.
Quando "strict" for "True", somente dimensões desconhecidas poderão ser redimensionadas. Dimensões desconhecidas são indicadas como "-1" na matriz retornada por "Tensor.shapeSignature()".
Parâmetros
idx | |
---|---|
dims | |
restrito |
public void resizeInput (int idx, int[] dims)
Redimensiona a entrada idx-th do modelo nativo para as cores esmaecidas fornecidas.
Parâmetros
idx | |
---|---|
dims |
public void run (entrada de Object, saída de Objeto)
Executa a inferência de modelo se o modelo usa apenas uma entrada e fornece apenas uma saída.
Aviso: a API será mais eficiente se um Buffer
(de preferência direto, mas não obrigatório)
for usado como o tipo de dados de entrada/saída. Considere usar Buffer
para alimentar e buscar
dados primitivos para melhor desempenho. Há suporte para os seguintes tipos concretos de Buffer
:
ByteBuffer
: compatível com qualquer tipo de Tensor primitivo.FloatBuffer
: compatível com tensores flutuantes.IntBuffer
: compatível com tensores int32.LongBuffer
: compatível com tensores int64.
Buffer
s ou como entradas escalares.Parâmetros
entrada | uma matriz ou matriz multidimensional ou uma Buffer de tipos primitivos, incluindo int, flutuante, long e byte. Buffer é a maneira preferencial de transmitir grandes dados de entrada para tipos primitivos, enquanto os tipos de string exigem o uso do caminho de entrada da matriz (multidimensional). Quando um Buffer é usado, o conteúdo dele precisa permanecer inalterado até que a inferência do modelo seja feita. O autor da chamada precisa garantir que o Buffer esteja na posição de leitura apropriada. Um valor null só será permitido se o autor da chamada estiver usando um
Delegate que permita a interoperabilidade de processamento do buffer e esse buffer tiver sido vinculado ao
Tensor de entrada. |
---|---|
saída | uma matriz multidimensional de dados de saída ou uma Buffer de tipos primitivos, incluindo int, float, long e byte. Quando um Buffer é usado, o autor da chamada precisa garantir
que a posição de gravação adequada esteja definida. Um valor nulo é permitido e é útil para
certos casos, por exemplo, se o autor da chamada estiver usando um Delegate que permite a interoperabilidade de
processamento do buffer e esse buffer tiver sido vinculado à saída Tensor (consulte também Interpreter.Options#setAllowBufferHandleOutput(boolean)),
ou se o gráfico tiver formas dinâmicas e o autor da chamada precisar consultar a forma Tensor de saída após a inferência ter sido invocada (por meio da invocação
da saída).Tensor.asReadOnlyBuffer() |
public void runForMultipleInputsOutputs (Object[] entradas, Map<Integer, Object> saídas)
Executa a inferência de modelo se o modelo receber várias entradas ou retornar várias saídas.
Aviso: a API é mais eficiente quando Buffer
s (de preferência direto, mas não obrigatório)
são usados como tipos de dados de entrada/saída. Considere usar Buffer
para alimentar e buscar
dados primitivos para melhor desempenho. Há suporte para os seguintes tipos concretos de Buffer
:
ByteBuffer
: compatível com qualquer tipo de Tensor primitivo.FloatBuffer
: compatível com tensores flutuantes.IntBuffer
: compatível com tensores int32.LongBuffer
: compatível com tensores int64.
Buffer
s ou como entradas escalares.
Observação: valores null
para elementos individuais de inputs
e outputs
são permitidos somente se o autor da chamada estiver usando um Delegate
que permita a interoperabilidade de processamento do buffer e esse buffer tiver sido vinculado aos Tensor
(s) de entrada ou saída correspondentes.
Parâmetros
escondidas | uma matriz de dados de entrada. As entradas precisam estar na mesma ordem que as entradas do modelo. Cada entrada pode ser uma matriz, uma matriz multidimensional ou uma Buffer de tipos primitivos, incluindo int, float, long e byte. Buffer é a maneira preferencial para transmitir grandes dados de entrada, enquanto os tipos de string exigem o uso do caminho de entrada da matriz (multidimensional). Quando Buffer é usado, o conteúdo precisa permanecer inalterado até que a inferência do modelo seja feita. O autor da chamada precisa garantir que o Buffer esteja na posição de leitura apropriada. |
---|---|
saídas | Um mapa que mapeia índices de saída para matrizes multidimensionais de dados de saída ou Buffer s de tipos primitivos, incluindo int, float, long e byte. Ele só precisa manter entradas para que as saídas sejam usadas. Quando um Buffer é usado, o autor da chamada precisa garantir
que a posição de gravação adequada esteja definida. O mapa pode estar vazio nos casos em que identificadores de buffer são usados para dados do tensor de saída ou casos em que as saídas são dinamicamente moldadas e o autor da chamada precisa consultar a forma Tensor de saída após a inferência ter sido invocada, buscando os dados diretamente do tensor de saída (via Tensor.asReadOnlyBuffer() ). |
public void runSignature (Map<String, Object> entradas, Map<String, Object> saídas)
Igual a runSignature(Map, Map, String)
, mas não exige a transmissão de uma signatureKey, supondo que o modelo tenha um SignatureDef. Se o modelo tiver mais de um SignatureDef, ele vai gerar uma exceção.
AVISO: esta API é experimental e está sujeita a alterações.
Parâmetros
escondidas | |
---|---|
saídas |
public void runSignature (Map<String, Object> entradas, Map<String, Object> saídas, String signatureKey)
Executa a inferência de modelo com base no SignatureDef fornecido pelo signatureKey
.
Consulte run(Object, Object)
para mais detalhes sobre os tipos de dados de entrada e saída
permitidos.
AVISO: esta API é experimental e está sujeita a alterações.
Parâmetros
escondidas | Um mapa do nome de entrada no SignatureDef para um objeto de entrada. |
---|---|
saídas | Um mapa do nome de saída em SignatureDef para dados de saída. Pode estar vazio se o autor da chamada quiser consultar os dados de Tensor diretamente após a inferência (por exemplo, se o formato de saída for dinâmico ou se forem usados identificadores de buffer de saída). |
signatureKey | Chave de assinatura que identifica o SignatureDef. |
Gera
IllegalArgumentException | se inputs for nulo ou vazio, se outputs ou signatureKey for nulo ou se ocorrer um erro ao executar a inferência.
|
---|
public void setCancelled (boolean cancelled)
Avançado: interrompe a inferência no meio de uma chamada para run(Object, Object)
.
Uma sinalização de cancelamento será definida como verdadeira quando essa função for chamada. O intérprete vai verificar a flag entre as invocações da operação e, se for true
, interromper a
execução. O intérprete permanecerá um estado cancelado até ser explicitamente "cancelado" por
setCancelled(false)
.
AVISO: esta API é experimental e está sujeita a alterações.
Parâmetros
cancelou | true para cancelar a inferência da melhor maneira possível, false para retomar. |
---|
Gera
IllegalStateException | se o intérprete não for inicializado com a opção cancelável, que é desativada por padrão. |
---|