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.Options オプション)
Interpreter を初期化し、インタープリタの動作をカスタマイズするためのオプションを指定します。 |
|
パブリック メソッド
void |
allocateTensors()
必要に応じて、すべてのテンソルの割り当てを明示的に更新します。
|
void |
close()
InterpreterApi インスタンスに関連付けられているリソースを解放します。 |
整数 | |
Tensor |
getInputTensor(int inputIndex)
指定された入力インデックスに関連付けられたテンソルを取得します。
|
整数 |
getInputTensorCount()
入力テンソルの数を取得します。
|
Tensor |
getInputTensorFromSignature(String inputName, String signatureKey)
指定された入力名と署名メソッド名に関連付けられたテンソルを取得します。
|
Long |
getLastNativeInferenceDurationNanoseconds()
ネイティブの推論タイミングを返します。
|
整数 | |
Tensor |
getOutputTensor(int outputIndex)
指定された出力インデックスに関連付けられたテンソルを取得します。
|
整数 |
getOutputTensorCount()
出力テンソルの数を取得します。
|
Tensor |
getOutputTensorFromSignature(String outputName, String signatureKey)
特定の署名メソッドで指定された出力名に関連付けられたテンソルを取得します。
|
String[] | |
String[] |
getSignatureKeys()
モデルで使用可能な SignatureDef によってエクスポートされたメソッド名のリストを取得します。
|
String[] | |
void |
resetVariableTensors()
Advanced: すべての変数テンソルをデフォルト値にリセットします。
|
void |
resizeInput(int idx, int[] dims, boolean strict)
ネイティブ モデルの idx 番目の入力サイズを指定されたディメンションに変更します。
|
void |
resizeInput(int idx, int[] dims)
ネイティブ モデルの idx 番目の入力サイズを指定されたディメンションに変更します。
|
void | |
void |
runForMultipleInputsOutputs(Object[] 入力、Map<Integer、Object> 出力)
モデルが複数の入力を取るか、複数の出力を返す場合に、モデルの推論を実行します。
|
void |
runSignature(Map<String, Object> 入力、Map<String、Object> 出力)
runSignature(Map, Map, String) と同じですが、モデルに SignatureDef が 1 つある場合、signatureKey を渡す必要はありません。 |
void | |
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 getInputTensorCount ()
入力テンソルの数を取得します。
public Tensor getInputTensorFromSignature (String inputName, String signatureKey)
指定された入力名と署名メソッド名に関連付けられたテンソルを取得します。
警告: これは試験運用版の API であり、変更される可能性があります。
パラメータ
inputName | 署名に名前を入力します。 |
---|---|
signatureKey | SignatureDef を識別する署名鍵。モデルに 1 つの署名がある場合、null にできます。 |
例外
IllegalArgumentException | inputName または signatureKey が null または空の場合、あるいは無効な名前が指定された場合。 |
---|
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 オプション(デフォルトでオフ)で初期化されていない場合。 |
---|