驅動程式類別,運用 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 | 控制執行階段解譯器行為的選項類別。 |
公用建構函式
公用方法
void |
allocateTensors()
視需要明確更新所有張量的配置。
|
void |
close()
釋出與
InterpreterApi 執行個體相關聯的資源。 |
int | |
Tensor |
getInputTensor(int inputIndex)
取得與輸入索引相關聯的 Tensor。
|
int |
getInputTensorCount()
取得輸入張量。
|
Tensor | |
長版 |
getLastNativeInferenceDurationNanoseconds()
傳回原生推論時間。
|
int | |
Tensor |
getOutputTensor(int outputIndex)
取得與提供的輸出索引相關聯的 Tensor。
|
int |
getOutputTensorCount()
取得輸出張量。
|
Tensor | |
String[] | |
String[] |
getSignatureKeys()
取得模型中可用的 SignatureDef 匯出方法名稱清單。
|
String[] | |
void |
resetVariableTensors()
進階:將所有變數張量重設為預設值。
|
void |
resizeInput(int idx, int[] 暗度,布林值)
將原生模型的 IDx 輸入值調整為指定的亮度。
|
void |
resizeInput(int idx, int[] 調暗)
將原生模型的 IDx 輸入值調整為指定的亮度。
|
void | |
void |
runForMultipleInputsOutputs(Object[] input, Map<Integer, Object> outputs)
如果模型接受多項輸入內容,或傳回多個輸出內容,系統就會執行模型推論。
|
void |
runSignature(Map<String, Object> input, Map<String, Object> 輸出內容)
與
runSignature(Map, Map, String) 相同,但不需要傳送 signKey,假設模型具有一個 SignatureDef。 |
void | |
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 getInputTensorCount ()
取得輸入張量。
public Tensor getInputTensorFromSignature (String inputName, String signatureKey)
取得與輸入名稱和簽章方法名稱相關聯的 Tensor。
警告:這是實驗性 API,可能隨時會有變動。
參數
inputName | 在簽名中輸入名稱。 |
---|---|
signatureKey | 用於識別 SignatureDef 的簽名金鑰。如果模型有一個簽名,則可設為空值。 |
擲回
IllegalArgumentException | 如果 inputName 或 signatureKey 為空值、空白,或是提供的名稱無效,就會傳回這個錯誤。 |
---|
公開 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[] 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 | 如果翻譯器未透過可取消的設定選項初始化 (該選項預設為關閉),表示支援函式。 |
---|