Interpreter

Intérprete de aula final pública

Classe de driver para conduzir inferência de modelo com 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 usar Interpreter diretamente.

Um Interpreter encapsula um modelo pré-treinado do TensorFlow Lite, no qual as operações são executadas para inferência do modelo.

Por exemplo, se um modelo recebe 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 aceita múltiplas 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 forma[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 TensorFlow em modelo TensorFlowLite com Toco, assim como as formas padrão das entradas.

Quando as entradas são fornecidas como matrizes (multidimensionais), os tensores de entrada correspondentes serão redimensionados implicitamente de acordo com o formato dessa matriz. Quando as entradas são fornecidas como tipos Buffer , nenhum redimensionamento implícito é feito; o chamador deve garantir que o tamanho do byte Buffer corresponda ao do tensor correspondente ou que primeiro redimensione o tensor por meio resizeInput(int, int[]) . As informações de forma e tipo do tensor podem ser obtidas por meio da classe Tensor , disponível via getInputTensor(int) e getOutputTensor(int) .

AVISO: as instâncias Interpreter não são thread-safe. Um Interpreter possui recursos que devem ser explicitamente liberados invocando close()

A biblioteca TFLite foi criada com base na API NDK 19. Ela pode funcionar para níveis de API Android abaixo de 19, mas não é garantida.

Classes aninhadas

aula Interpretador.Opções Uma classe de opções para controlar o comportamento do interpretador de tempo de execução.

Construtores Públicos

Intérprete ( Arquivo modelFile)
Inicializa um Interpreter .
Interpretador ( arquivo modelFile, opções Interpreter.Options )
Inicializa um Interpreter e especifica opções para personalizar o comportamento do intérprete.
Intérprete ( ByteBuffer byteBuffer)
Inicializa um Interpreter com um ByteBuffer de um arquivo de modelo.
Interpretador (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

vazio
alocarTensores ()
Atualiza explicitamente as alocações para todos os tensores, se necessário.
vazio
fechar ()
Libere recursos associados à instância InterpreterApi .
interno
getInputIndex ( String opName)
Obtém o índice de uma entrada de acordo com o nome da operação da entrada.
Tensor
getInputTensor (int inputIndex)
Obtém o Tensor associado ao índice de entrada fornecido.
interno
getInputTensorCount ()
Obtém o número de tensores de entrada.
Tensor
getInputTensorFromSignature ( String inputName, String assinaturaKey)
Obtém o Tensor associado ao nome de entrada e ao nome do método de assinatura fornecidos.
Longo
getLastNativeInferenceDurationNanoseconds ()
Retorna o tempo de inferência nativo.
interno
getOutputIndex ( String opName)
Obtém o índice de uma saída de acordo com o nome da operação da saída.
Tensor
getOutputTensor (int outputIndex)
Obtém o Tensor associado ao índice de saída fornecido.
interno
getOutputTensorCount ()
Obtém o número de tensores de saída.
Tensor
getOutputTensorFromSignature ( String outputName, String assinaturaKey)
Obtém o Tensor associado ao nome de saída fornecido no método de assinatura específico.
Corda[]
getSignatureInputs ( String assinaturaKey)
Obtém a lista de entradas SignatureDefs para o método signatureKey .
Corda[]
getSignatureKeys ()
Obtém a lista de nomes de métodos exportados SignatureDef disponíveis no modelo.
Corda[]
getSignatureOutputs ( String assinaturaKey)
Obtém a lista de saídas SignatureDefs para o método signatureKey .
vazio
resetVariableTensores ()
Avançado: redefine todos os tensores variáveis ​​para o valor padrão.
vazio
resizeInput (int idx, int[] escurece, booleano estrito)
Redimensiona a idx-ésima entrada do modelo nativo para as dimensões fornecidas.
vazio
resizeInput (int idx, int[] escurece)
Redimensiona a idx-ésima entrada do modelo nativo para as dimensões fornecidas.
vazio
run (entrada de objeto , saída de objeto )
Executa a inferência do modelo se o modelo receber apenas uma entrada e fornecer apenas uma saída.
vazio
runForMultipleInputsOutputs (entradas Object[] , saídas Map < Integer , Object >)
Executa a inferência do modelo se o modelo receber diversas entradas ou retornar diversas saídas.
vazio
runSignature ( Map < String , Object > entradas, Map < String , Object > saídas)
O mesmo que runSignature(Map, Map, String) mas não requer a passagem de uma assinaturaKey, assumindo que o modelo tenha um SignatureDef.
vazio
runSignature ( Map < String , Object > entradas, Map < String , Object > saídas, String subscriptionKey)
Executa inferência de modelo com base em SignatureDef fornecido por meio de signatureKey .
vazio
setCancelled (booleano cancelado)
Avançado: interrompe a inferência no meio de uma chamada para run(Object, Object) .

Métodos herdados

Construtores Públicos

intérprete público ( arquivo modelFile)

Inicializa um Interpreter .

Parâmetros
arquivomodelo um arquivo de um modelo TF Lite pré-treinado.
Lança
Exceção de argumento ilegal se modelFile não codificar um modelo válido do TensorFlow Lite.

intérprete público ( arquivo modelFile, opções Interpreter.Options )

Inicializa um Interpreter e especifica opções para personalizar o comportamento do intérprete.

Parâmetros
arquivomodelo um arquivo de um modelo TF Lite pré-treinado
opções um conjunto de opções para personalizar o comportamento do intérprete
Lança
Exceção de argumento ilegal se modelFile não codificar um modelo válido do TensorFlow Lite.

intérprete público ( ByteBuffer byteBuffer)

Inicializa um Interpreter com um ByteBuffer de um arquivo de modelo.

O ByteBuffer não deve 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
Lança
Exceção de argumento ilegal se byteBuffer não for um MappedByteBuffer nem um ByteBuffer direto de nativeOrder.

intérprete público (opções ByteBuffer byteBuffer, Interpreter.Options )

Inicializa um Interpreter com um ByteBuffer de um arquivo de modelo e um conjunto de Interpreter.Options personalizados.

O ByteBuffer não deve 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
opções
Lança
Exceção de argumento ilegal se byteBuffer não for um MappedByteBuffer nem um ByteBuffer direto de nativeOrder.

Métodos Públicos

public void allocateTensores ()

Atualiza explicitamente as alocações para todos os tensores, se necessário.

Isso irá propagar formas e alocações de memória para tensores dependentes usando as formas do tensor de entrada conforme fornecidas.

Nota: Esta chamada é *puramente opcional*. A alocação de tensores ocorrerá automaticamente durante a execução se algum tensor de entrada tiver sido redimensionado. Esta chamada é mais útil para determinar as formas de quaisquer tensores 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...

Nota: Alguns gráficos têm saídas com formato dinâmico; nesse caso, o formato da saída pode não ser totalmente propagado até que a inferência seja executada.

fechamento de vazio público ()

Libere recursos associados à instância InterpreterApi .

public int getInputIndex ( String opName)

Obtém o índice de uma entrada de acordo com o nome da operação da entrada.

Parâmetros
opName

Tensor público getInputTensor (int inputIndex)

Obtém o Tensor associado ao índice de entrada fornecido.

Parâmetros
índice de entrada

público int getInputTensorCount ()

Obtém o número de tensores de entrada.

Tensor público getInputTensorFromSignature ( String inputName, String assinaturaKey)

Obtém o Tensor associado ao nome de entrada e ao nome do método de assinatura fornecidos.

AVISO: Esta é uma API experimental e sujeita a alterações.

Parâmetros
entradaNome Insira o nome na assinatura.
assinaturaKey A chave de assinatura que identifica SignatureDef pode ser nula se o modelo tiver uma assinatura.
Lança
Exceção de argumento ilegal se inputName ou signatureKey for nulo ou vazio ou se o nome for inválido.

public Long getLastNativeInferenceDurationNanoseconds ()

Retorna o tempo de inferência nativo.

public int getOutputIndex ( String opName)

Obtém o índice de uma saída de acordo com o nome da operação da saída.

Parâmetros
opName

Tensor público getOutputTensor (int outputIndex)

Obtém o Tensor associado ao índice de saída fornecido.

Nota: 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, após 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. Observe que, para 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
índice de saída

público int getOutputTensorCount ()

Obtém o número de tensores de saída.

Tensor público getOutputTensorFromSignature ( String outputName, String assinaturaKey)

Obtém o Tensor associado ao nome de saída fornecido no método de assinatura específico.

Nota: 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, após 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. Observe que, para 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 é uma API experimental e sujeita a alterações.

Parâmetros
nome de saída Nome de saída na assinatura.
assinaturaKey A chave de assinatura que identifica SignatureDef pode ser nula se o modelo tiver uma assinatura.
Lança
Exceção de argumento ilegal se outputName ou signatureKey for nulo ou vazio ou se o nome for inválido.

public String[] getSignatureInputs ( String assinaturaKey)

Obtém a lista de entradas SignatureDefs para o método signatureKey .

AVISO: Esta é uma API experimental e sujeita a alterações.

Parâmetros
assinaturaKey

String pública[] getSignatureKeys ()

Obtém a lista de nomes de métodos exportados SignatureDef disponíveis no modelo.

AVISO: Esta é uma API experimental e sujeita a alterações.

public String[] getSignatureOutputs ( String assinaturaKey)

Obtém a lista de saídas SignatureDefs para o método signatureKey .

AVISO: Esta é uma API experimental e sujeita a alterações.

Parâmetros
assinaturaKey

public void resetVariableTensors ()

Avançado: redefine todos os tensores variáveis ​​para o valor padrão.

Se um tensor variável não tiver um buffer associado, ele será zerado.

AVISO: Esta é uma API experimental e sujeita a alterações.

public void resizeInput (int idx, int[] escurece, boolean strict)

Redimensiona a idx-ésima entrada do modelo nativo para as dimensões fornecidas.

Quando `strict` for True, apenas dimensões desconhecidas poderão ser redimensionadas. Dimensões desconhecidas são indicadas como `-1` na matriz retornada por `Tensor.shapeSignature()`.

Parâmetros
idx
escurece
estrito

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

Redimensiona a idx-ésima entrada do modelo nativo para as dimensões fornecidas.

Parâmetros
idx
escurece

public void run (entrada de objeto , saída de objeto )

Executa a inferência do modelo se o modelo receber apenas uma entrada e fornecer apenas uma saída.

Aviso: A API é mais eficiente se um Buffer (de preferência direto, mas não obrigatório) for usado como tipo de dados de entrada/saída. Considere usar Buffer para alimentar e buscar dados primitivos para melhor desempenho. Os seguintes tipos Buffer concretos são suportados:

  • ByteBuffer - compatível com qualquer tipo de Tensor primitivo subjacente.
  • FloatBuffer - compatível com tensores flutuantes.
  • IntBuffer - compatível com tensores int32.
  • LongBuffer - compatível com tensores int64.
Observe que os tipos booleanos são suportados apenas como arrays, não Buffer s, ou como entradas escalares.

Parâmetros
entrada um array ou array multidimensional, ou um Buffer de tipos primitivos incluindo int, float, long e byte. Buffer é a maneira preferida de passar 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, seu conteúdo deve permanecer inalterado até que a inferência do modelo seja feita, e o chamador deve garantir que o Buffer esteja na posição de leitura apropriada. Um valor null será permitido somente se o chamador estiver usando um Delegate que permite a interoperabilidade do identificador de buffer e esse buffer tiver sido vinculado ao Tensor de entrada.
saída uma matriz multidimensional de dados de saída ou um Buffer de tipos primitivos, incluindo int, float, long e byte. Quando um Buffer é usado, o chamador deve garantir que ele esteja definido na posição de gravação apropriada. Um valor nulo é permitido e é útil para certos casos, por exemplo, se o chamador estiver usando um Delegate que permite interoperabilidade de manipulação de buffer, e tal buffer foi vinculado ao Tensor de saída (consulte também Interpreter.Options#setAllowBufferHandleOutput(boolean) ), ou se o gráfico tiver saídas com formato dinâmico e o chamador precisar 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 runForMultipleInputsOutputs (entradas Object[] , saídas Map < Integer , Object >)

Executa a inferência do modelo se o modelo receber diversas entradas ou retornar diversas saídas.

Aviso: a API é mais eficiente se Buffer s (de preferência diretos, mas não obrigatórios) forem usados ​​como tipos de dados de entrada/saída. Considere usar Buffer para alimentar e buscar dados primitivos para melhor desempenho. Os seguintes tipos Buffer concretos são suportados:

  • ByteBuffer - compatível com qualquer tipo de Tensor primitivo subjacente.
  • FloatBuffer - compatível com tensores flutuantes.
  • IntBuffer - compatível com tensores int32.
  • LongBuffer - compatível com tensores int64.
Observe que os tipos booleanos são suportados apenas como arrays, não Buffer s, ou como entradas escalares.

Nota: valores null para elementos individuais de inputs e outputs são permitidos somente se o chamador estiver usando um Delegate que permite interoperabilidade de manipulação de buffer, e tal buffer tiver sido vinculado ao(s) Tensor (es) de entrada ou saída correspondente(s).

Parâmetros
entradas uma matriz de dados de entrada. As entradas devem estar na mesma ordem que as entradas do modelo. Cada entrada pode ser um array ou array multidimensional, ou um Buffer de tipos primitivos incluindo int, float, long e byte. Buffer é a maneira preferida de passar grandes dados de entrada, enquanto os tipos de string exigem o uso do caminho de entrada da matriz (multidimensional). Quando Buffer é usado, seu conteúdo deve permanecer inalterado até que a inferência do modelo seja feita, e o chamador deve 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 as saídas a serem utilizadas. Quando um Buffer é usado, o chamador deve garantir que ele esteja definido na posição de gravação apropriada. O mapa pode estar vazio para casos em que os identificadores de buffer são usados ​​para dados do tensor de saída ou casos em que as saídas são moldadas dinamicamente e o chamador deve consultar a forma do Tensor de saída após a inferência ter sido invocada, buscando os dados diretamente do tensor de saída ( através de Tensor.asReadOnlyBuffer() ).

public void runSignature ( Map < String , Object > entradas, Map < String , Object > saídas)

O mesmo que runSignature(Map, Map, String) mas não requer a passagem de uma assinaturaKey, assumindo que o modelo tenha um SignatureDef. Se o modelo tiver mais de um SignatureDef, lançará uma exceção.

AVISO: Esta é uma API experimental e sujeita a alterações.

Parâmetros
entradas
saídas

public void runSignature ( Map < String , Object > entradas, Map < String , Object > saídas, String subscriptionKey)

Executa inferência de modelo com base em SignatureDef fornecido por meio de signatureKey .

Consulte run(Object, Object) para obter mais detalhes sobre os tipos de dados de entrada e saída permitidos.

AVISO: Esta é uma API experimental e sujeita a alterações.

Parâmetros
entradas 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 os dados de saída. Pode estar vazio se o chamador desejar consultar os dados 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).
assinaturaKey Chave de assinatura que identifica o SignatureDef.
Lança
Exceção de argumento ilegal se inputs forem nulas ou vazias, se outputs ou signatureKey forem nulas ou se ocorrer um erro ao executar a inferência.

public void setCancelled (booleano cancelado)

Avançado: interrompe a inferência no meio de uma chamada para run(Object, Object) .

Um sinalizador de cancelamento será definido como verdadeiro quando esta função for chamada. O intérprete verificará o sinalizador entre as invocações Op e, se for true , o intérprete interromperá a execução. O intérprete permanecerá em um estado cancelado até que seja explicitamente "não cancelado" por setCancelled(false) .

AVISO: Esta é uma API experimental e está sujeita a alterações.

Parâmetros
cancelado true para cancelar a inferência com o melhor esforço; false para continuar.
Lança
IllegalStateException se o interpretador não for inicializado com a opção cancelável, que está desativada por padrão.