Interpreter

公開最終類別 翻譯模式

驅動程式類別，運用 TensorFlow Lite 進行模型推論。

注意：如果您不需要存取下列任何「實驗性」API 功能，建議使用 UnderstandingerApi 和 UnderstandingerFactory，不要直接使用翻譯器。

Interpreter 會封裝預先訓練的 TensorFlow Lite 模型，模型推論會執行作業。

舉例來說，假設模型只接受一項輸入內容，且只傳回一項輸出內容： 

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 模型時，系統會使用 Toco 做為輸入的預設形狀，決定輸入和輸出的順序。

以 (多維度) 陣列提供輸入內容時，相應的輸入張量會根據該陣列的形狀間接調整大小。以 Buffer 類型提供輸入內容時，系統不會自動調整大小；呼叫端必須確保 Buffer 位元組大小與對應的張量相符，或者必須先透過 resizeInput(int, int[]) 調整張量。您可以透過 Tensor 類別取得 Tensor 形狀和類型資訊，可透過 getInputTensor(int) 和 getOutputTensor(int) 取得。

警告：Interpreter 執行個體「不」符合執行緒安全規定。Interpreter 擁有資源，必須透過叫用 close() 明確釋出資源

TFLite 程式庫是根據 NDK API 19 建構而成。可能適用於低於 19 的 Android API 級別，但不保證一定能正常運作。

巢狀類別

類別 Interpreter.Options 控制執行階段解譯器行為的選項類別。

公用建構函式

翻譯工具(檔案 modelFile)
初始化 Interpreter。
翻譯工具(檔案 modelFile、Interpreter.Options 選項)
初始化 Interpreter，並指定自訂解譯器行為的選項。
翻譯工具(ByteBuffer byteBuffer)
使用模型檔案的 ByteBuffer 初始化 Interpreter。
翻譯工具(ByteBuffer byteBuffer、Interpreter.Options 選項)
使用模型檔案的 ByteBuffer 和一組自訂 Interpreter.Options 初始化 Interpreter。

公用方法

void
allocateTensors()
視需要明確更新所有張量的配置。
void
close()
釋出與 InterpreterApi 執行個體相關聯的資源。
int
getInputIndex(String opName)
根據輸入的運算名稱取得輸入的索引。
Tensor
getInputTensor(int inputIndex)
取得與輸入索引相關聯的 Tensor。
int
getInputTensorCount()
取得輸入張量。
Tensor
getInputTensorFromSignature(String inputName, String signatureKey)
取得與輸入名稱和簽章方法名稱相關聯的 Tensor。
長版
getLastNativeInferenceDurationNanoseconds()
傳回原生推論時間。
int
getOutputIndex(String opName)
根據輸出的運算名稱取得輸出的索引。
Tensor
getOutputTensor(int outputIndex)
取得與提供的輸出索引相關聯的 Tensor。
int
getOutputTensorCount()
取得輸出張量。
Tensor
getOutputTensorFromSignature(String outputName, String signatureKey)
取得與特定簽名方法中所提供輸出名稱相關聯的 Tensor。
String[]
getSignatureInputs(String signatureKey)
取得方法 signatureKey 的 SignatureDefs 輸入清單。
String[]
getSignatureKeys()
取得模型中可用的 SignatureDef 匯出方法名稱清單。
String[]
getSignatureOutputs(String signatureKey)
取得方法 signatureKey 的 SignatureDefs 輸出內容清單。
void
resetVariableTensors()
進階：將所有變數張量重設為預設值。
void
resizeInput(int idx, int[] 暗度，布林值)
將原生模型的 IDx 輸入值調整為指定的亮度。
void
resizeInput(int idx, int[] 調暗)
將原生模型的 IDx 輸入值調整為指定的亮度。
void
run(物件輸入、物件輸出)
如果模型只使用一項輸入內容，且只提供一項輸出內容，系統就會執行模型推論。
void
runForMultipleInputsOutputs(Object[] input, Map<Integer, Object> outputs)
如果模型接受多項輸入內容，或傳回多個輸出內容，系統就會執行模型推論。
void
runSignature(Map<String, Object> input, Map<String, Object> 輸出內容)
與 runSignature(Map, Map, String) 相同，但不需要傳送 signKey，假設模型具有一個 SignatureDef。
void
runSignature(Map<String, Object> input, Map<String, Object> 輸出, StringsignKey)
根據透過 signatureKey 提供的 SignatureDef 執行模型推論。
void
setCancelled(布林值已取消)
進階：在呼叫 run(Object, Object) 的過程中發生中斷推論。

繼承的方法

公用建構函式

公開 翻譯工具 (檔案 modelFile)

初始化 Interpreter。

參數
modelFile 這個檔案是預先訓練的 TF Lite 模型檔案
擲回
IllegalArgumentException 如果 modelFile 並未編碼有效的 TensorFlow Lite 模型，就會傳回這個值。

公開 Interpreter.Options

初始化 Interpreter，並指定自訂解譯器行為的選項。

參數
modelFile 匯出為預先訓練的 TF Lite 模型檔案
選項 一組用於自訂翻譯行為的選項
擲回
IllegalArgumentException 如果 modelFile 並未編碼有效的 TensorFlow Lite 模型，就會傳回這個值。

public 翻譯工具 (ByteBuffer byteBuffer)

使用模型檔案的 ByteBuffer 初始化 Interpreter。

在建構 Interpreter 後，不得修改 ByteBuffer。ByteBuffer 可以是記憶體對應模型檔案的 MappedByteBuffer，或包含模型位元組內容的 nativeOrder() 直接 ByteBuffer。

參數
byteBuffer
擲回
IllegalArgumentException 表示 byteBuffer 不是 MappedByteBuffer 或 nativeOrder 的直接 ByteBuffer。

public 翻譯工具 (ByteBuffer byteBuffer、Interpreter.Options 選項)

使用模型檔案的 ByteBuffer 和一組自訂 Interpreter.Options 初始化 Interpreter。

ByteBuffer 不應在建構 Interpreter 後修改。ByteBuffer 可以是記憶體對應模型檔案的 MappedByteBuffer，或包含模型位元組內容的 nativeOrder() 直接 ByteBuffer。

參數
byteBuffer
選項
擲回
IllegalArgumentException 表示 byteBuffer 不是 MappedByteBuffer 或 nativeOrder 的直接 ByteBuffer。

公用方法

public void allocateTensors ()

視需要明確更新所有張量的配置。

這會使用指定的輸入張量形狀，傳播相依張量的形狀和記憶體配置。

注意：此通話 *僅限選用*。如果任何輸入張量大小經過調整，Tensor 分配作業就會在執行期間自動執行。執行圖表之前，這項呼叫最有助於判斷任何輸出張量的形狀，例如 

 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

公開 Tensor getInputTensor (int inputIndex)

取得與輸入索引相關聯的 Tensor。

參數
inputIndex

public int getInputTensorCount ()

取得輸入張量。

public Tensor getInputTensorFromSignature (String inputName, String signatureKey)

取得與輸入名稱和簽章方法名稱相關聯的 Tensor。

警告：這是實驗性 API，可能隨時會有變動。

參數
inputName 在簽名中輸入名稱。
signatureKey 用於識別 SignatureDef 的簽名金鑰。如果模型有一個簽名，則可設為空值。
擲回
IllegalArgumentException 如果 inputName 或 signatureKey 為空值、空白，或是提供的名稱無效，就會傳回這個錯誤。

public Long getLastNativeInferenceDurationNanoseconds ()

傳回原生推論時間。

public int getOutputIndex (String opName)

根據輸出的運算名稱取得輸出的索引。

參數
opName

公開 Tensor getOutputTensor (int outputIndex)

取得與提供的輸出索引相關聯的 Tensor。

注意：在執行推論後，輸出張量詳細資料 (例如形狀) 可能無法完全填入。如果在執行推論「之前」需要更新詳細資料 (例如調整輸入張量大小，這可能會導致輸出張量形狀失效)，請使用 allocateTensors() 明確觸發配置和形狀傳播。請注意，如果圖表的輸出形狀是依賴輸入「值」*，在推論前可能無法完全決定輸出形狀。

參數
outputIndex

public int getOutputTensorCount ()

取得輸出張量。

public Tensor getOutputTensorFromSignature (String outputName、String signatureKey)

取得與特定簽名方法中所提供輸出名稱相關聯的 Tensor。

注意：在執行推論後，輸出張量詳細資料 (例如形狀) 可能無法完全填入。如果在執行推論「之前」需要更新詳細資料 (例如調整輸入張量大小，這可能會導致輸出張量形狀失效)，請使用 allocateTensors() 明確觸發配置和形狀傳播。請注意，如果圖表中的輸出形狀是依賴輸入「值」*，在推論前可能無法完全確定輸出內容形狀。

警告：這是實驗性 API，可能隨時會有變動。

參數
outputName 簽章中的輸出名稱。
signatureKey 用於識別 SignatureDef 的簽名金鑰。如果模型有一個簽名，則可設為空值。
擲回
IllegalArgumentException 如果 outputName 或 signatureKey 為空值或空白，或是提供的名稱無效。

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

進階：將所有變數張量重設為預設值。

如果變數張量沒有相關聯的緩衝區，該緩衝區會重設為零。

警告：這是實驗性 API，可能隨時會有變動。

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

將原生模型的 IDx 輸入值調整為指定的亮度。

「Strict」(嚴格) 設為 True 時，只能調整未知的尺寸。在 Tensor.shapeSignature() 傳回的陣列中，不明維度會以「-1」表示。

參數
idx
dims
嚴格篩選

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

將原生模型的 IDx 輸入值調整為指定的亮度。

參數
idx
dims

public void run (Object 輸入、Object 輸出)

如果模型只使用一項輸入內容，且只提供一項輸出內容，系統就會執行模型推論。

警告：如果使用 Buffer (最好是直接，但並非必要) 做為輸入/輸出資料類型，API 會更有效率。建議您使用 Buffer 來動態饋給及擷取原始資料，以提升效能。系統支援下列具體 Buffer 類型：

  • ByteBuffer - 與任何基礎原始 Tensor 類型相容。
  • FloatBuffer - 與浮點 Tensor 相容。
  • IntBuffer - 與 int32 Tensor 相容。
  • LongBuffer：與 int64 Tensor 相容。
請注意，布林值類型僅支援陣列，不支援 Buffer 或純量輸入。

參數
輸入 陣列或多維度陣列，或原始類型的 Buffer，包括 int、浮點值、長整數和位元組。如要傳遞原始類型的大型輸入資料，建議使用 Buffer，而字串類型則需使用 (多維度) 陣列輸入路徑。使用 Buffer 時，在模型推論完成前，其內容應保持不變，且呼叫端必須確保 Buffer 位於適當的讀取位置。只有在呼叫端使用的 Delegate 允許緩衝區處理互通性，且這類緩衝區已繫結至輸入 Tensor 時，才允許 null 值。
output 輸出資料的多維陣列，或原始類型的 Buffer，包括 int、浮點值、Long 和 byte。使用 Buffer 時，呼叫端必須確保其設定的是適當的寫入位置。可以使用空值，且在某些情況下相當實用，例如呼叫端使用的 Delegate 允許緩衝區處理互通性，而此類緩衝區已繫結至輸出 Tensor (另請參閱「Interpreter.Options#setAllowBufferHandleOutput(boolean)」)，或者如果圖表已動態形塑輸出，且呼叫端必須在推論後透過 Tensor.asReadOnlyBuffer() 動態擷取輸出內容，才能從 Tensor.asReadOnlyBuffer() 擷取輸出形狀 (以 Tensor.asReadOnlyBuffer() 進行推斷)。Tensor

public void runForMultipleInputsOutputs (Object[] input, Map<Integer, Object> 輸出)

如果模型接受多項輸入內容，或傳回多個輸出內容，系統就會執行模型推論。

警告：如果使用 Buffer (最好是直接，但並非必要) 做為輸入/輸出資料類型，API 會更有效率。建議您使用 Buffer 來動態饋給及擷取原始資料，以提升效能。系統支援下列具體 Buffer 類型：

  • ByteBuffer - 與任何基礎原始 Tensor 類型相容。
  • FloatBuffer - 與浮點 Tensor 相容。
  • IntBuffer - 與 int32 Tensor 相容。
  • LongBuffer：與 int64 Tensor 相容。
請注意，布林值類型僅支援陣列，不支援 Buffer 或純量輸入。

注意：只有在呼叫端使用的 Delegate 允許緩衝區處理互通性，且這類緩衝區已繫結至對應的輸入或輸出 Tensor 時，才允許 inputs 和 outputs 的個別元素的 null 值。

參數
輸入來源 輸入資料的陣列。輸入內容的順序應與模型的輸入順序相同。每個輸入都可以是陣列或多維度陣列，或原始類型的 Buffer (包括 int、浮點數、長和位元組)。Buffer 是傳遞大型輸入資料的最佳方式，而字串類型則必須使用 (多維度) 陣列輸入路徑。使用 Buffer 時，在模型推論完成前，其內容應保持不變，且呼叫端必須確保 Buffer 位於適當的讀取位置。
輸出 將地圖輸出索引對應至輸出資料的多維陣列，或是原始類型的 Buffer (包括 int、float、Long 和 byte)。此類型只需要保留項目，才能使用輸出。使用 Buffer 時，呼叫端必須確保其設定的是適當的寫入位置。如果任一緩衝區控點用於輸出張量資料，或者輸出會動態形狀，且呼叫端必須在叫用推論後查詢輸出內容Tensor形狀，直接從輸出張量擷取資料 (透過 Tensor.asReadOnlyBuffer())，地圖就可能是空白的。

public void runSignature (Map<String, Object> input, Map<String, Object> 輸出內容)

與 runSignature(Map, Map, String) 相同，但不需要傳送 signKey，假設模型具有一個 SignatureDef。如果模型有多個 SignatureDef，就會擲回例外狀況。

警告：這是實驗性 API，可能隨時會有變動。

參數
輸入來源
輸出

public void runSignature (Map<String, Object> input, Map<String、Object> 輸出、String 簽章金鑰)

根據透過 signatureKey 提供的 SignatureDef 執行模型推論。

如要進一步瞭解允許的輸入和輸出資料類型，請參閱 run(Object, Object)。

警告：這是實驗性 API，可能隨時會有變動。

參數
輸入來源 從 SignatureDef 輸入名稱到輸入物件的對應。
輸出 SignatureDef 中輸出名稱以輸出資料的對應。如果呼叫端想在推論後直接查詢 Tensor 資料 (例如輸出形狀是動態，或使用輸出緩衝區控點)，則該呼叫資料可能空白。
signatureKey 用於識別 SignatureDef 的簽名金鑰。
擲回
IllegalArgumentException 如果 inputs 為空值或空白，如果 outputs 或 signatureKey 為空值，或執行推論時發生錯誤。

public void setCancelled (boolean cancelled)

進階：在呼叫 run(Object, Object) 的過程中發生中斷推論。

呼叫這個函式時，取消旗標會設為 true。解譯器會檢查運算元件叫用之間的標記，如果是 true，翻譯器就會停止執行。解譯器會維持取消狀態，直到 setCancelled(false) 明確「未取消」。

警告：這是實驗性 API，可能隨時會有變動。

參數
已取消 true：以最佳方式取消推論；設為 false 即可繼續。
擲回
IllegalStateException 如果翻譯器未透過可取消的設定選項初始化 (該選項預設為關閉)，表示支援函式。
另請參閱