InterpreterApi

Interface pública InterpreterApi
Subclasses indiretas conhecidas

Interface para o intérprete de modelo do TensorFlow Lite, exceto métodos experimentais.

Uma instância InterpreterApi 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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 redimensione o tensor usando resizeInput(int, int[]). As informações sobre a forma e o tipo do tensor podem ser recebidas por meio da classe Tensor, disponível via getInputTensor(int) e getOutputTensor(int).

AVISO: as instâncias do InterpreterApi não são thread-safe.

AVISO: uma instância InterpreterApi possui recursos que precisam ser explicitamente liberados com a invocação de 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 InterpreterApi.Options Uma classe de opções para controlar o comportamento do intérprete no momento da execução. 

Métodos públicos

abstrato nulo
allocateTensors()
Atualiza explicitamente as alocações para todos os tensores, se necessário.
abstrato nulo
close()
Libere recursos associados à instância InterpreterApi.
estático InterpreterApi
create(modelFile de Arquivo, opções de InterpreterApi.Options)
Constrói uma instância de InterpreterApi, usando o modelo e as opções especificados.
estático InterpreterApi
create(byteBuffer ByteBuffer, opções InterpreterApi.Options)
Constrói uma instância de InterpreterApi, usando o modelo e as opções especificados.
abstrato int
getInputIndex(String opName)
Recebe o índice de uma entrada de acordo com o nome da operação dela.
abstrato Tensor
getInputTensor(int inputIndex)
Recebe o tensor associado ao índice de entrada fornecido.
abstrato int
getInputTensorCount()
Recebe o número de tensores de entrada.
abstrato Longo
getLastNativeInferenceDurationNanoseconds()
Retorna o tempo de inferência nativo.
abstrato int
getOutputIndex(String opName)
Recebe o índice de uma saída conforme o nome da operação da saída.
abstrato Tensor
getOutputTensor(int outputIndex)
Recebe o tensor associado ao índice de saída fornecido.
abstrato int
getOutputTensorCount()
Recebe o número de tensores de saída.
abstrato nulo
resizeInput(int idx, int[] dims, boolean strict)
Redimensiona a entrada idx-th do modelo nativo para as cores esmaecidas fornecidas.
abstrato nulo
resizeInput(int idx, int[] dims)
Redimensiona a entrada idx-th do modelo nativo para as cores esmaecidas fornecidas.
abstrato nulo
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.
abstrato nulo
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.

Métodos herdados

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.

Gera
IllegalStateException caso os tensores do gráfico não possam ser alocados.

public void fechar ()

Libere recursos associados à instância InterpreterApi.

public Static InterpreterApi create (File modelFile, InterpreterApi.Options opções)

Constrói uma instância de InterpreterApi, usando o modelo e as opções especificados. O modelo será carregado usando um arquivo.

Parâmetros
modelFile Um arquivo contendo 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 estático InterpreterApi create (ByteBuffer byteBuffer, InterpreterApi.Options)

Constrói uma instância de InterpreterApi, usando o modelo e as opções especificados. O modelo será lido a partir de um ByteBuffer.

Parâmetros
byteBuffer Um modelo TF Lite pré-treinado, em formato binário serializado. O ByteBuffer não pode ser modificado após a construção de uma instância do InterpreterApi. 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.
do modelo. Um conjunto de opções para personalizar o comportamento do intérprete.
Gera
IllegalArgumentException se byteBuffer não for um MappedByteBuffer nem um ByteBuffer direto de nativeOrder.

public abstrata int getInputIndex (String opName)

Recebe o índice de uma entrada de acordo com o nome da operação dela.

Parâmetros
opName
Gera
IllegalArgumentException se opName não corresponde a nenhuma entrada no modelo usado para inicializar o intérprete.

público abstrato Tensor getInputTensor (int inputIndex)

Recebe o tensor associado ao índice de entrada fornecido.

Parâmetros
inputIndex
Gera
IllegalArgumentException se inputIndex for negativo ou não for menor que o número de entradas do modelo.

public abstrato int getInputTensorCount ()

Recebe o número de tensores de entrada.

public abstrato Long getLastNativeInferenceDurationNanoseconds ()

Retorna o tempo de inferência nativo.

Gera
IllegalArgumentException se o modelo não for inicializado pelo intérprete.

public abstrata int getOutputIndex (String opName)

Recebe o índice de uma saída conforme o nome da operação da saída.

Parâmetros
opName
Gera
IllegalArgumentException se opName não corresponder a nenhuma saída no modelo usado para inicializar o intérprete.

público abstrato 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
Gera
IllegalArgumentException se outputIndex for negativo ou não for menor que o número de saídas do modelo.

public abstrata int getOutputTensorCount ()

Recebe o número de tensores de saída.

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
Gera
IllegalArgumentException se idx for negativo ou não for menor que o número de entradas do modelo ou se ocorrer um erro ao redimensionar a entrada idx-th. Além disso, o erro ocorre ao tentar redimensionar um tensor com dimensões fixas quando "strict" é True.

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

Redimensiona a entrada idx-th do modelo nativo para as cores esmaecidas fornecidas.

Parâmetros
idx
dims
Gera
IllegalArgumentException se idx for negativo ou não for menor que o número de entradas do modelo ou se ocorrer um erro ao redimensionar a entrada idx-th.

public digdes de segurança 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.

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()
Gera
IllegalArgumentException se input for nulo ou vazio ou se ocorrer um erro ao executar a inferência.
IllegalArgumentException (EXPERIMENTAL, sujeito a mudanças) se a inferência for interrompida por setCancelled(true).

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()).
Gera
IllegalArgumentException se inputs for nulo ou vazio, se outputs for nulo ou se ocorrer um erro ao executar a inferência.