Interpreter

public final class インタープリタ

TensorFlow Lite でモデル推論を促進するためのドライバクラス。

注: 以下の「試験運用版」の API 機能にアクセスする必要がない場合は、Interpreter を直接使用するのではなく、InterpreterApi と InterpreterFactory を使用してください。

Interpreter は、事前トレーニング済みの TensorFlow Lite モデルをカプセル化します。ここでは、モデルの推論のためのオペレーションが実行されます。

たとえば、モデルが 1 つの入力のみを受け取り、1 つの出力のみを返す場合: 

try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
   interpreter.run(input, output);
 }

モデルが複数の入力または出力を受け取る場合: 

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);
 }

モデルが文字列テンソルを取得または生成する場合: 

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);
 }

形状 [] と形状 [1] には違いがあります。スカラー文字列テンソル出力の場合: 

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);

入力と出力の順序は、入力のデフォルトの形状と同様に、Toco を使用して TensorFlow モデルを TensorFlowLite モデルに変換するときに決定されます。

入力が（多次元）配列として提供される場合、対応する入力テンソルは、その配列の形状に応じて暗黙的にサイズ変更されます。入力が Buffer 型として提供される場合、暗黙的なサイズ変更は行われません。呼び出し元は、Buffer のバイトサイズが対応するテンソルのバイトサイズと一致するか、最初に resizeInput(int, int[]) を使用してテンソルのサイズを変更する必要があります。テンソルの形状と型の情報は、getInputTensor(int) と getOutputTensor(int) を介して利用可能な Tensor クラスを介して取得できます。

警告:Interpreter インスタンスはスレッドセーフではありません。Interpreter は、close() を呼び出して明示的に解放する必要があるリソースを所有します。

TFLite ライブラリは NDK API 19 用にビルドされています。Android API レベル 19 未満で動作する可能性がありますが、動作が保証されるわけではありません。

ネストされたクラス

クラス Interpreter.Options ランタイム インタープリタの動作を制御するオプション クラス。

パブリック コンストラクタ

Interpreter（File modelFile）
Interpreter を初期化します。
Interpreter（File modelFile、Interpreter.Options オプション）
Interpreter を初期化し、インタープリタの動作をカスタマイズするためのオプションを指定します。
Interpreter（ByteBuffer byteBuffer）
モデルファイルの ByteBuffer で Interpreter を初期化します。
Interpreter（ByteBuffer byteBuffer、Interpreter.Options オプション）
モデルファイルの ByteBuffer とカスタム Interpreter.Options のセットで Interpreter を初期化します。

パブリック メソッド

void
allocateTensors()
必要に応じて、すべてのテンソルの割り当てを明示的に更新します。
void
close()
InterpreterApi インスタンスに関連付けられているリソースを解放します。
整数
getInputIndex(String opName)
入力の演算名で指定された入力のインデックスを取得します。
Tensor
getInputTensor（int inputIndex）
指定された入力インデックスに関連付けられたテンソルを取得します。
整数
getInputTensorCount()
入力テンソルの数を取得します。
Tensor
getInputTensorFromSignature(String inputName, String signatureKey)
指定された入力名と署名メソッド名に関連付けられたテンソルを取得します。
Long
getLastNativeInferenceDurationNanoseconds()
ネイティブの推論タイミングを返します。
整数
getOutputIndex(String opName)
出力のオペレーション名を指定して、出力のインデックスを取得します。
Tensor
getOutputTensor（int outputIndex）
指定された出力インデックスに関連付けられたテンソルを取得します。
整数
getOutputTensorCount()
出力テンソルの数を取得します。
Tensor
getOutputTensorFromSignature(String outputName, String signatureKey)
特定の署名メソッドで指定された出力名に関連付けられたテンソルを取得します。
String[]
getSignatureInputs(String signatureKey)
メソッド signatureKey の SignatureDefs 入力のリストを取得します。
String[]
getSignatureKeys()
モデルで使用可能な SignatureDef によってエクスポートされたメソッド名のリストを取得します。
String[]
getSignatureOutputs(String signatureKey)
メソッド signatureKey の SignatureDefs 出力のリストを取得します。
void
resetVariableTensors()
Advanced: すべての変数テンソルをデフォルト値にリセットします。
void
resizeInput（int idx, int[] dims, boolean strict）
ネイティブ モデルの idx 番目の入力サイズを指定されたディメンションに変更します。
void
resizeInput（int idx, int[] dims）
ネイティブ モデルの idx 番目の入力サイズを指定されたディメンションに変更します。
void
run（オブジェクト入力、オブジェクト出力）
モデルが 1 つの入力のみを受け取り、1 つの出力のみを提供する場合、モデルの推論を実行します。
void
runForMultipleInputsOutputs（Object[] 入力、Map<Integer、Object> 出力）
モデルが複数の入力を取るか、複数の出力を返す場合に、モデルの推論を実行します。
void
runSignature（Map<String, Object> 入力、Map<String、Object> 出力）
runSignature(Map, Map, String) と同じですが、モデルに SignatureDef が 1 つある場合、signatureKey を渡す必要はありません。
void
runSignature（Map<String, Object> 入力、Map<String、Object> 出力、StringsignatureKey）
signatureKey を介して提供される SignatureDef に基づいてモデルの推論を実行します。
void
setCancelled（ブール値のキャンセル）
高度: run(Object, Object) 呼び出しの途中で推論を中断します。

継承されるメソッド

パブリック コンストラクタ

public インタープリタ （ファイル modelFile）

Interpreter を初期化します。

パラメータ
modelFile 事前トレーニング済みの TF Lite モデルのファイル。
例外
IllegalArgumentException modelFile が有効な TensorFlow Lite モデルをエンコードしていない場合。

public Interpreter （File modelFile、Interpreter.Options オプション）

Interpreter を初期化し、インタープリタの動作をカスタマイズするためのオプションを指定します。

パラメータ
modelFile 事前トレーニング済みの TF Lite モデルのファイル
オプション インタープリタの動作をカスタマイズするための一連のオプション
例外
IllegalArgumentException modelFile が有効な TensorFlow Lite モデルをエンコードしていない場合。

public Interpreter （ByteBuffer byteBuffer）

モデルファイルの ByteBuffer で Interpreter を初期化します。

Interpreter の構築後は ByteBuffer を変更しないでください。ByteBuffer は、モデルファイルをメモリマップする MappedByteBuffer か、モデルのバイト コンテンツを含む nativeOrder() の直接 ByteBuffer のいずれかです。

パラメータ
byteBuffer
例外
IllegalArgumentException byteBuffer が MappedByteBuffer でも、nativeOrder の直接 ByteBuffer でもない場合。

public Interpreter （ByteBuffer byteBuffer、Interpreter.Options オプション）

モデルファイルの ByteBuffer とカスタム Interpreter.Options のセットで Interpreter を初期化します。

Interpreter の構築後は ByteBuffer を変更しないでください。ByteBuffer は、モデルファイルをメモリマップする MappedByteBuffer か、モデルのバイト コンテンツを含む nativeOrder() の直接 ByteBuffer のいずれかです。

パラメータ
byteBuffer
オプション
例外
IllegalArgumentException byteBuffer が MappedByteBuffer でも、nativeOrder の直接 ByteBuffer でもない場合。

パブリック メソッド

public void allocateTensors ()

必要に応じて、すべてのテンソルの割り当てを明示的に更新します。

これにより、与えられた入力テンソル形状を使用して、従属テンソルの形状とメモリ割り当てが伝播されます。

注: この通話は *完全に任意*です。入力テンソルのサイズが変更された場合、実行時にテンソルの割り当てが自動的に行われます。この呼び出しは、グラフを実行する前に出力テンソルの形状を確認する場合に最も役立ちます。たとえば、 

 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...

注: 一部のグラフでは出力が動的に変化します。その場合、出力形状は推論が実行されるまで完全に伝播しないことがあります。

public void close ()

InterpreterApi インスタンスに関連付けられているリソースを解放します。

public int getInputIndex (String opName)

入力の演算名で指定された入力のインデックスを取得します。

パラメータ
opName

public Tensor getInputTensor (int inputIndex)

指定された入力インデックスに関連付けられたテンソルを取得します。

パラメータ
inputIndex

public int getInputTensorCount ()

入力テンソルの数を取得します。

public Tensor getInputTensorFromSignature (String inputName, String signatureKey)

指定された入力名と署名メソッド名に関連付けられたテンソルを取得します。

警告: これは試験運用版の API であり、変更される可能性があります。

パラメータ
inputName 署名に名前を入力します。
signatureKey SignatureDef を識別する署名鍵。モデルに 1 つの署名がある場合、null にできます。
例外
IllegalArgumentException inputName または signatureKey が null または空の場合、あるいは無効な名前が指定された場合。

public Long getLastNativeInferenceDurationNanoseconds ()

ネイティブの推論タイミングを返します。

public int getOutputIndex (String opName)

出力のオペレーション名を指定して、出力のインデックスを取得します。

パラメータ
opName

public Tensor getOutputTensor (int outputIndex)

指定された出力インデックスに関連付けられたテンソルを取得します。

注: 出力テンソルの詳細（シェイプなど）は、推論が実行されるまで完全に入力されない場合があります。推論を実行する前（入力テンソルのサイズ変更後に出力テンソルの形状が無効になる可能性がある）で詳細を更新する必要がある場合は、allocateTensors() を使用して割り当てと形状の伝播を明示的にトリガーします。入力 *値*に依存する出力形状のグラフの場合、推論を実行するまで出力形状が完全には確定されない場合があります。

パラメータ
outputIndex

public int getOutputTensorCount ()

出力テンソルの数を取得します。

public Tensor getOutputTensorFromSignature (String outputName, String signatureKey)

特定の署名メソッドで指定された出力名に関連付けられた Tensor を取得します。

注: 出力テンソルの詳細（シェイプなど）は、推論が実行されるまで完全に入力されない場合があります。推論を実行する前（入力テンソルのサイズ変更後に出力テンソルの形状が無効になる可能性がある）で詳細を更新する必要がある場合は、allocateTensors() を使用して割り当てと形状の伝播を明示的にトリガーします。入力 *値*に依存する出力形状のグラフの場合、推論を実行するまで出力形状が完全には確定されない場合があります。

警告: これは試験運用版の API であり、変更される可能性があります。

パラメータ
outputName シグネチャの出力名。
signatureKey SignatureDef を識別する署名鍵。モデルに 1 つの署名がある場合、null にできます。
例外
IllegalArgumentException outputName または signatureKey が null または空の場合、あるいは無効な名前が指定された場合。

public String[] getSignatureInputs (String signatureKey)

メソッド signatureKey の SignatureDefs 入力のリストを取得します。

警告: これは試験運用版の API であり、変更される可能性があります。

パラメータ
signatureKey

public String[] getSignatureKeys ()

モデルで使用可能な、SignatureDef によってエクスポートされたメソッド名のリストを取得します。

警告: これは試験運用版の API であり、変更される可能性があります。

public String[] getSignatureOutputs (String signatureKey)

メソッド signatureKey の SignatureDefs 出力のリストを取得します。

警告: これは試験運用版の API であり、変更される可能性があります。

パラメータ
signatureKey

public void resetVariableTensors ()

Advanced: すべての変数テンソルをデフォルト値にリセットします。

変数テンソルに関連付けられたバッファがない場合、0 にリセットされます。

警告: これは試験運用版の API であり、変更される可能性があります。

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

ネイティブ モデルの idx 番目の入力サイズを指定されたディメンションに変更します。

「strict」が True の場合、サイズ変更できるのは不明なディメンションのみです。「Tensor.shapeSignature()」によって返される配列では、不明なディメンションは「-1」として示されます。

パラメータ
idx
dims
strict

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

ネイティブ モデルの idx 番目の入力サイズを指定されたディメンションに変更します。

パラメータ
idx
dims

public void run （オブジェクト 入力、オブジェクト出力）

モデルが 1 つの入力のみを受け取り、1 つの出力のみを提供する場合、モデルの推論を実行します。

警告: 入出力データ型として Buffer（できれば直接型ですが、必須ではありません）を使用すると、API の効率が向上します。パフォーマンスを向上させるには、Buffer を使用してプリミティブ データのフィードと取得を行うことを検討してください。次の具体的な Buffer 型がサポートされています。

  • ByteBuffer - 基になるすべてのプリミティブ Tensor 型と互換性があります。
  • FloatBuffer - 浮動小数点テンソルと互換性があります。
  • IntBuffer - int32 Tensors と互換性があります。
  • LongBuffer - int64 Tensors と互換性があります。
ブール値型は配列としてのみサポートされています。Buffer やスカラー入力としてはサポートされていません。

パラメータ
入力 配列または多次元配列、あるいは int、float、long、byte などのプリミティブ型の Buffer。プリミティブ型の大規模な入力データを渡すには、Buffer の使用をおすすめしますが、文字列型では（多次元の）配列入力パスを使用する必要があります。Buffer を使用する場合、モデルの推論が完了するまで、その内容は変更されません。また、呼び出し元は、Buffer が適切な読み取り位置にあることを確認する必要があります。null 値は、呼び出し元がバッファ ハンドルの相互運用を許可する Delegate を使用していて、そのようなバッファが入力 Tensor にバインドされている場合にのみ許可されます。
出力 出力データの多次元配列、または int、float、long、byte などのプリミティブ型の Buffer。Buffer を使用する場合、呼び出し元は、適切な書き込み位置が設定されていることを確認する必要があります。null 値は許容され、たとえば、呼び出し元がバッファ ハンドルの相互運用を許可する Delegate を使用していて、そのようなバッファが出力 Tensor にバインドされている場合（Interpreter.Options#setAllowBufferHandleOutput(boolean) も参照）、またはグラフで動的に整形された出力があり、推論が出力された後に出力 Tensor のシェイプをクエリする必要がある場合（Tensor.asReadOnlyBuffer() から直接データをフェッチする）場合などに、null 値が許容されます。

public void runForMultipleInputsOutputs （Object[] 入力、Map<Integer、Object> 出力）

モデルが複数の入力を取るか、複数の出力を返す場合に、モデルの推論を実行します。

警告: 入出力データ型として Buffer（直接型が望ましいが、必須ではありません）を使用すると、API の効率が向上します。パフォーマンスを向上させるには、Buffer を使用してプリミティブ データのフィードと取得を行うことを検討してください。次の具体的な Buffer 型がサポートされています。

  • ByteBuffer - 基になるすべてのプリミティブ Tensor 型と互換性があります。
  • FloatBuffer - 浮動小数点テンソルと互換性があります。
  • IntBuffer - int32 Tensors と互換性があります。
  • LongBuffer - int64 Tensors と互換性があります。
ブール値型は、配列としてのみサポートされています。Buffer やスカラー入力としてはサポートされていません。

注: inputs と outputs の個別の要素の null 値は、呼び出し元がバッファ ハンドルの相互運用を許可する Delegate を使用していて、そのようなバッファが対応する入力または出力 Tensor にバインドされている場合にのみ許可されます。

パラメータ
入力 入力データの配列。入力はモデルの入力と同じ順序にする必要があります。各入力は、配列または多次元配列、または int、float、long、byte などのプリミティブ型の Buffer です。サイズの大きい入力データを渡すには Buffer の使用をおすすめしますが、文字列型では（多次元の）配列入力パスを使用する必要があります。Buffer を使用する場合、モデルの推論が完了するまで、その内容は変更されません。また、呼び出し元は、Buffer が適切な読み取り位置にあることを確認する必要があります。
結果 出力インデックスを、出力データの多次元配列、または int、float、long、byte などのプリミティブ型の Buffer にマッピングするマップ。使用する出力のエントリを保持するだけで済みます。Buffer を使用する場合、呼び出し元は、適切な書き込み位置が設定されていることを確認する必要があります。出力テンソルデータにバッファ ハンドルを使用する場合や、出力が動的にシェーピングされ、呼び出し元が出力テンソルから（Tensor.asReadOnlyBuffer() を介して）直接データをフェッチして推論が呼び出された後に、出力 Tensor シェイプを照会する必要がある場合、マップは空になることがあります。

public void runSignature （Map<String、Object> 入力、Map<String、Object> 出力）

runSignature(Map, Map, String) と同じですが、モデルに SignatureDef が 1 つある場合、signatureKey を渡す必要はありません。モデルに複数の SignatureDef がある場合、例外がスローされます。

警告: これは試験運用版の API であり、変更される可能性があります。

パラメータ
入力
結果

public void runSignature （Map<String、Object> 入力、Map<String、Object> 出力、StringsignatureKey）

signatureKey を介して提供された SignatureDef に基づいてモデルの推論を実行します。

使用可能な入力データ型と出力データ型の詳細については、run(Object, Object) をご覧ください。

警告: これは試験運用版の API であり、変更される可能性があります。

パラメータ
入力 SignatureDef 内の入力名から入力オブジェクトへのマップ。
結果 SignatureDef の出力名から出力データへのマップ。呼び出し元が推論後に直接 Tensor データをクエリする場合（出力シェイプが動的である場合や、出力バッファ ハンドルが使用されている場合など）は、空になることがあります。
signatureKey SignatureDef を識別する署名キー。
例外
IllegalArgumentException inputs が null または空の場合、outputs または signatureKey が null の場合、推論の実行時にエラーが発生した場合。

public void setCancelled (boolean cancelled)

高度: run(Object, Object) 呼び出しの途中で推論を中断します。

この関数が呼び出されると、キャンセル フラグが true に設定されます。インタープリタは Op の呼び出し間でフラグをチェックし、true の場合は実行を停止します。インタープリタは、setCancelled(false) によって明示的に「キャンセル解除」されるまで、キャンセル状態になります。

警告: これは試験運用版の API であり、変更される可能性があります。

パラメータ
キャンセル true の場合はベスト エフォート方式で推論をキャンセルし、再開する場合は false です。
例外
IllegalStateException インタープリタが cancellable オプション（デフォルトでオフ）で初期化されていない場合。
関連情報