Interpreter

classe final pública Interpretador

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(Arquivo modelFile)
Inicializa um Interpreter.
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
getInputIndex(String opName)
Recebe o índice de uma entrada de acordo com o nome da operação dela.
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
getOutputIndex(String opName)
Recebe o índice de uma saída conforme o nome da operação da saída.
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
run(entrada de objeto, saída de objeto)
Executa a inferência de modelo se o modelo usa apenas uma entrada e fornece apenas uma saída.
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
runSignature(Entradas de Map<String, Object>, Map<String, Object>, String signatureKey)
Executa a inferência de modelo com base no SignatureDef fornecido pelo signatureKey.
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 Long getLastNativeInferenceDurationNanoseconds ()

Retorna o tempo de inferência nativo.

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.
Os tipos booleanos são compatíveis apenas como matrizes, não Buffers 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 Buffers (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.
Os tipos booleanos são compatíveis apenas como matrizes, não Buffers 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 Buffers 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.
Ver também