Lớp trình điều khiển để thúc đẩy suy luận về mô hình bằng TensorFlow Lite.
Lưu ý: Nếu bạn không cần quyền truy cập vào bất kỳ tính năng API "thử nghiệm" nào dưới đây, hãy ưu tiên sử dụng phiên dịch API và phiên dịch nhà máy hơn là sử dụng tính năng Thông dịch trực tiếp.
Interpreter
đóng gói một mô hình TensorFlow Lite được huấn luyện sẵn, trong đó các toán tử được thực thi để dự đoán mô hình.
Ví dụ: nếu một mô hình chỉ nhận một đầu vào và chỉ trả về một đầu ra:
try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
interpreter.run(input, output);
}
Nếu một mô hình nhận nhiều dữ liệu đầu vào hoặc đầu ra:
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);
}
Nếu một mô hình nhận hoặc tạo ra tensor chuỗi:
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);
}
Lưu ý rằng có sự khác biệt giữa hình dạng [] và hình dạng [1]. Đối với kết quả đầu ra của tensor chuỗi vô hướng:
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);
Thứ tự của đầu vào và đầu ra được xác định khi chuyển đổi mô hình TensorFlow sang mô hình TensorFlowLite bằng Toco, cũng như các hình dạng mặc định của đầu vào.
Khi dữ liệu đầu vào được cung cấp dưới dạng mảng (đa chiều), (các) tensor đầu vào tương ứng sẽ được ngầm đổi kích thước theo hình dạng của mảng đó. Khi dữ liệu đầu vào được cung cấp dưới dạng loại Buffer
, sẽ không có thao tác đổi kích thước ngầm định nào được thực hiện; phương thức gọi phải đảm bảo rằng kích thước byte Buffer
khớp với kích thước của tensor tương ứng hoặc trước tiên chúng sẽ đổi kích thước tensor tương ứng thông qua resizeInput(int, int[])
. Bạn có thể lấy thông tin về hình dạng và loại Tensor thông qua lớp Tensor
, có sẵn qua getInputTensor(int)
và getOutputTensor(int)
.
CẢNH BÁO: Thực thể Interpreter
không an toàn cho chuỗi. Interpreter
sở hữu tài nguyên phải được giải phóng rõ ràng bằng cách gọi close()
Thư viện TFLite được xây dựng dựa trên API NDK 19. Cách này có thể hoạt động với API Android cấp dưới 19, nhưng không đảm bảo.
Lớp lồng ghép
lớp | Interpreter.Options | Một lớp tuỳ chọn để kiểm soát hành vi của trình thông dịch trong thời gian chạy. |
Công trình công cộng
Phiên dịch(Tệp mô hìnhTệp, tuỳ chọn Interpreter.Options)
Khởi động
Interpreter và chỉ định các tuỳ chọn để tuỳ chỉnh hành vi của trình phiên dịch. |
|
Phương thức công khai
void |
Hàm allocateTensors()
Cập nhật rõ ràng mức phân bổ cho tất cả tensor, nếu cần.
|
void |
Hàm close()
Phát hành các tài nguyên liên kết với thực thể
InterpreterApi . |
int | |
Tensor |
getInputTensor(int inputIndex)
Lấy Tensor liên kết với chỉ mục đầu vào được cung cấp.
|
int |
Hàm getInputTensorCount()
Lấy số lượng tensor đầu vào.
|
Tensor |
getInputTensorFromSignature(String inputName, String signatureKey)
Lấy Tensor liên kết với tên nhập và tên phương thức chữ ký đã cung cấp.
|
Long |
Hàm getLastNativeInferenceDurationNanoseconds()
Trả về thời gian suy luận gốc.
|
int | |
Tensor |
getOutputTensor(int outputIndex)
Lấy Tensor liên kết với chỉ mục đầu ra được cung cấp.
|
int |
Hàm getOutputTensorCount()
Lấy số lượng Tensor đầu ra.
|
Tensor |
getOutputTensorFromSignature(String outputName, String signatureKey)
Lấy Tensor liên kết với tên đầu ra đã cung cấp trong phương thức chữ ký cụ thể.
|
Chuỗi[] |
getSignatureInputs(String signatureKey)
Lấy danh sách dữ liệu đầu vào SignatureDefs cho phương thức
signatureKey . |
Chuỗi[] |
Hàm getSignatureKeys()
Lấy danh sách tên phương thức xuất SignatureDef có trong mô hình.
|
Chuỗi[] |
getSignatureOutputs(String signatureKey)
Lấy danh sách đầu ra SignatureDefs cho phương thức
signatureKey . |
void |
resetVariableTensors()
Nâng cao: Đặt lại tất cả tensor biến về giá trị mặc định.
|
void |
resizeInput(int idx, int[] dims, boolean strict)
Đổi kích thước đầu vào thứ idx của mô hình gốc thành độ mờ đã cho.
|
void |
resizeInput(int idx, int[] dims)
Đổi kích thước đầu vào thứ idx của mô hình gốc thành độ mờ đã cho.
|
void | |
void |
runForMultipleInputsOutputs(đầu vào Object[], đầu ra Map<Integer, Object>)
Chạy suy luận của mô hình nếu mô hình nhận nhiều đầu vào hoặc trả về nhiều đầu ra.
|
void |
runSignature(đầu vào Bản đồ<Chuỗi, Đối tượng>, kết quả đầu ra Bản đồ<Chuỗi, Đối tượng>)
Giống như
runSignature(Map, Map, String) nhưng không yêu cầu truyền một signatureKey, giả sử mô hình có một SignatureDef. |
void | |
void |
setCancelled(boolean đã bị huỷ)
Nâng cao: Gián đoạn suy luận khi đang thực hiện lệnh gọi đến
run(Object, Object) . |
Các phương thức kế thừa
Công trình công cộng
công khai Thông dịch viên (Tệp mô hìnhFile)
Khởi động Interpreter
.
Thông số
modelFile | Tệp của một mô hình TF Lite luyện sẵn. |
---|
Gửi
IllegalArgumentException | nếu modelFile không mã hoá mô hình TensorFlow Lite hợp lệ.
|
---|
công khai Thông dịch (File modelFile, Interpreter.Options tuỳ chọn)
Khởi động Interpreter
và chỉ định các tuỳ chọn để tuỳ chỉnh hành vi của trình phiên dịch.
Thông số
modelFile | tệp mô hình TF Lite huấn luyện sẵn |
---|---|
tùy chọn | một nhóm tuỳ chọn để tuỳ chỉnh hành vi của phiên dịch |
Gửi
IllegalArgumentException | nếu modelFile không mã hoá mô hình TensorFlow Lite hợp lệ.
|
---|
công khai Thông dịch viên (ByteBuffer byteBuffer)
Khởi động Interpreter
với ByteBuffer
của tệp mô hình.
Bạn không được sửa đổi ByteBuffer sau khi tạo Interpreter
. ByteBuffer
có thể là một MappedByteBuffer
liên kết bộ nhớ với một tệp mô hình, hoặc là ByteBuffer
trực tiếp của nativeOrder() chứa nội dung các byte của một mô hình.
Thông số
byteBuffer |
---|
Gửi
IllegalArgumentException | nếu byteBuffer không phải là MappedByteBuffer cũng không phải là ByteBuffer trực tiếp của nativeOrder.
|
---|
công khai Diễn giải (ByteBuffer byteBuffer, Interpreter.Options tuỳ chọn)
Khởi động Interpreter
với ByteBuffer
của tệp mô hình và một nhóm Interpreter.Options
tuỳ chỉnh.
Bạn không được sửa đổi ByteBuffer
sau khi tạo Interpreter
. ByteBuffer
có thể là một MappedByteBuffer
liên kết bộ nhớ với một tệp mô hình, hoặc là ByteBuffer
trực tiếp của nativeOrder() chứa nội dung các byte của một mô hình.
Thông số
byteBuffer | |
---|---|
tùy chọn |
Gửi
IllegalArgumentException | nếu byteBuffer không phải là MappedByteBuffer cũng không phải là ByteBuffer trực tiếp của nativeOrder.
|
---|
Phương thức công khai
công khai void allocateTensors ()
Cập nhật rõ ràng mức phân bổ cho tất cả tensor, nếu cần.
Thao tác này sẽ truyền các hình dạng và mức phân bổ bộ nhớ cho tensor phụ thuộc bằng cách sử dụng(các) hình dạng tensor đầu vào như đã cho.
Lưu ý: Cuộc gọi này *hoàn toàn không bắt buộc*. Quá trình phân bổ tensor đầu vào sẽ tự động diễn ra trong quá trình thực thi nếu có bất kỳ tensor đầu vào nào đã được đổi kích thước. Lệnh gọi này hữu ích nhất trong việc xác định hình dạng cho mọi tensor đầu ra trước khi thực thi biểu đồ, ví dụ:
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...
Lưu ý: Một số biểu đồ có đầu ra được định dạng động, trong trường hợp đó, hình dạng đầu ra có thể không truyền hoàn toàn cho đến khi suy luận được thực thi.
công khai void close ()
Phát hành các tài nguyên liên kết với thực thể InterpreterApi
.
công khai int getInputIndex (String opName)
Lấy chỉ mục của đầu vào dựa trên tên hoạt động của đầu vào.
Thông số
opName |
---|
công khai Tensor getInputTensor (int inputIndex)
Lấy Tensor liên kết với chỉ mục đầu vào được cung cấp.
Thông số
inputIndex |
---|
công khai int getInputTensorCount ()
Lấy số lượng tensor đầu vào.
công khai Tensor getInputTensorFromSignature (String inputName, String signatureKey)
Lấy Tensor liên kết với tên nhập và tên phương thức chữ ký đã cung cấp.
CẢNH BÁO: Đây là API thử nghiệm và có thể thay đổi.
Thông số
inputName | Nhập tên vào chữ ký. |
---|---|
signatureKey | Khoá chữ ký xác định SignatureDef có thể có giá trị rỗng nếu mô hình có một chữ ký. |
Gửi
IllegalArgumentException | nếu inputName hoặc signatureKey có giá trị rỗng hoặc trống,
hoặc tên không hợp lệ đã cung cấp.
|
---|
công khai int getOutputIndex (String opName)
Lấy chỉ mục của một đầu ra dựa trên tên hoạt động của đầu ra.
Thông số
opName |
---|
công khai Tensor getOutputTensor (int outputIndex)
Lấy Tensor liên kết với chỉ mục đầu ra được cung cấp.
Lưu ý: Thông tin chi tiết về tensor đầu ra (ví dụ: hình dạng) có thể chưa được điền đầy đủ cho đến khi thực thi suy luận. Nếu bạn cần cập nhật thông tin chi tiết *trước khi* chạy suy luận (ví dụ: sau khi đổi kích thước một tensor đầu vào, việc này có thể vô hiệu hoá các hình dạng tensor đầu ra), hãy sử dụng allocateTensors()
để kích hoạt tính năng phân bổ và truyền hình dạng một cách rõ ràng. Xin lưu ý rằng đối với các biểu đồ có hình dạng đầu ra phụ thuộc vào *giá trị* đầu vào, hình dạng đầu ra có thể chưa được xác định đầy đủ cho đến khi chạy suy luận.
Thông số
outputIndex |
---|
công khai int getOutputTensorCount ()
Lấy số lượng Tensor đầu ra.
công khai Tensor getOutputTensorFromSignature (String outputName, String signatureKey)
Lấy Tensor liên kết với tên đầu ra đã cung cấp trong phương thức chữ ký cụ thể.
Lưu ý: Thông tin chi tiết về tensor đầu ra (ví dụ: hình dạng) có thể chưa được điền đầy đủ cho đến khi thực thi suy luận. Nếu bạn cần cập nhật thông tin chi tiết *trước khi* chạy suy luận (ví dụ: sau khi đổi kích thước một tensor đầu vào, việc này có thể vô hiệu hoá các hình dạng tensor đầu ra), hãy sử dụng allocateTensors()
để kích hoạt tính năng phân bổ và truyền hình dạng một cách rõ ràng. Xin lưu ý rằng đối với các biểu đồ có hình dạng đầu ra phụ thuộc vào *giá trị* đầu vào, hình dạng đầu ra có thể chưa được xác định đầy đủ cho đến khi chạy suy luận.
CẢNH BÁO: Đây là API thử nghiệm và có thể thay đổi.
Thông số
outputName | Tên đầu ra trong chữ ký. |
---|---|
signatureKey | Khoá chữ ký xác định SignatureDef có thể có giá trị rỗng nếu mô hình có một chữ ký. |
Gửi
IllegalArgumentException | nếu outputName hoặc signatureKey có giá trị rỗng hoặc
trống, hoặc tên không hợp lệ đã cung cấp.
|
---|
công khai Chuỗi[] getSignatureInputs (String signatureKey)
Lấy danh sách dữ liệu đầu vào SignatureDefs cho phương thức signatureKey
.
CẢNH BÁO: Đây là API thử nghiệm và có thể thay đổi.
Thông số
signatureKey |
---|
công khai Chuỗi[] getSignatureKeys ()
Lấy danh sách tên phương thức xuất SignatureDef có trong mô hình.
CẢNH BÁO: Đây là API thử nghiệm và có thể thay đổi.
công khai Chuỗi[] getSignatureOutputs (Chuỗi signatureKey)
Lấy danh sách đầu ra SignatureDefs cho phương thức signatureKey
.
CẢNH BÁO: Đây là API thử nghiệm và có thể thay đổi.
Thông số
signatureKey |
---|
công khai vô hiệu resetVariableTensors ()
Nâng cao: Đặt lại tất cả tensor biến về giá trị mặc định.
Nếu một tensor biến không có vùng đệm liên kết, nó sẽ được đặt lại về 0.
CẢNH BÁO: Đây là API thử nghiệm và có thể thay đổi.
công khai void resizeInput (int idx, int[] dims, boolean strict)
Đổi kích thước đầu vào thứ idx của mô hình gốc thành độ mờ đã cho.
Khi "strict" được đặt là True, bạn chỉ có thể đổi kích thước của những kích thước không xác định. Các phương diện không xác định được biểu thị là "-1" trong mảng do phương thức "Tensor.shapeSignature()" trả về.
Thông số
idx | |
---|---|
dims | |
nghiêm ngặt |
công khai void resizeInput (int idx, int[] dis)
Đổi kích thước đầu vào thứ idx của mô hình gốc thành độ mờ đã cho.
Thông số
idx | |
---|---|
dims |
công khai khoảng trống run (Đối tượng đầu vào, Đối tượng đầu ra)
Chạy suy luận của mô hình nếu mô hình chỉ nhận một đầu vào và chỉ cung cấp một đầu ra.
Cảnh báo: API sẽ hiệu quả hơn nếu bạn sử dụng Buffer
(tốt nhất là trực tiếp nhưng không bắt buộc) làm loại dữ liệu đầu vào/đầu ra. Vui lòng cân nhắc sử dụng Buffer
để cấp dữ liệu và tìm nạp
dữ liệu gốc nhằm nâng cao hiệu suất. Các loại Buffer
cụ thể sau đây được hỗ trợ:
ByteBuffer
– tương thích với mọi loại Tensor gốc cơ bản.FloatBuffer
– tương thích với Tensor nổi.IntBuffer
– tương thích với Int32 Tensor.LongBuffer
– tương thích với Int64 Tensor.
Buffer
hoặc giá trị đầu vào vô hướng.Thông số
input | một mảng hoặc mảng đa chiều hoặc Buffer gồm các loại nguyên gốc bao gồm int, float, long và byte. Buffer là cách ưu tiên để truyền dữ liệu đầu vào lớn cho các loại nguyên gốc, trong khi các loại chuỗi yêu cầu sử dụng đường dẫn đầu vào của mảng (nhiều chiều). Khi Buffer được sử dụng, nội dung của nó sẽ không thay đổi cho đến khi suy luận về mô hình và phương thức gọi phải đảm bảo rằng Buffer ở vị trí đọc thích hợp. Giá trị null chỉ được phép nếu phương thức gọi đang sử dụng một Delegate cho phép khả năng tương tác xử lý vùng đệm và một vùng đệm như vậy đã được liên kết với đầu vào Tensor . |
---|---|
output | một mảng đa chiều của dữ liệu đầu ra hoặc Buffer gồm các loại nguyên gốc bao gồm int, float, long và byte. Khi sử dụng Buffer , phương thức gọi phải đảm bảo rằng nó được đặt vị trí ghi thích hợp. Cho phép sử dụng giá trị rỗng và hữu ích trong một số trường hợp nhất định, chẳng hạn như nếu phương thức gọi đang sử dụng Delegate cho phép tương tác vùng đệm và vùng đệm đó đã được liên kết với đầu ra Tensor (xem thêm Interpreter.Options#setAllowBufferHandleOutput(boolean)) hoặc nếu biểu đồ có đầu ra được định hình linh động và phương thức gọi phải truy vấn hình dạng đầu ra Tensor sau khi suy luận được gọi ra, tìm nạp dữ liệu trực tiếp từ đầu ra.Tensor.asReadOnlyBuffer() |
công khai void runForMultipleInputsOutputs (Object[] đầu vào, Bản đồ<Số nguyên, Kết quả đầu ra đối tượng>)
Chạy suy luận của mô hình nếu mô hình nhận nhiều đầu vào hoặc trả về nhiều đầu ra.
Cảnh báo: API sẽ hiệu quả hơn nếu bạn dùng Buffer
(tốt nhất là trực tiếp nhưng không bắt buộc) làm các loại dữ liệu đầu vào/đầu ra. Vui lòng cân nhắc sử dụng Buffer
để cấp dữ liệu và tìm nạp
dữ liệu gốc nhằm nâng cao hiệu suất. Các loại Buffer
cụ thể sau đây được hỗ trợ:
ByteBuffer
– tương thích với mọi loại Tensor gốc cơ bản.FloatBuffer
– tương thích với Tensor nổi.IntBuffer
– tương thích với Int32 Tensor.LongBuffer
– tương thích với Int64 Tensor.
Buffer
hoặc giá trị đầu vào vô hướng.
Lưu ý: Bạn chỉ được phép sử dụng giá trị null
cho các phần tử riêng biệt của inputs
và outputs
nếu phương thức gọi đang sử dụng một Delegate
cho phép khả năng tương tác của bộ đệm xử lý và vùng đệm như vậy đã được liên kết với(các) Tensor
đầu vào hoặc đầu ra tương ứng.
Thông số
giá trị đầu vào | một mảng dữ liệu đầu vào. Các dữ liệu đầu vào phải có cùng thứ tự với dữ liệu đầu vào của mô hình. Mỗi dữ liệu đầu vào có thể là một mảng hoặc mảng đa chiều hoặc Buffer của các loại nguyên gốc bao gồm int, float, long và byte. Buffer là cách ưu tiên để truyền dữ liệu đầu vào có kích thước lớn, trong khi các loại chuỗi yêu cầu sử dụng đường dẫn đầu vào của mảng (đa chiều). Khi Buffer được sử dụng, nội dung của lớp đó sẽ không thay đổi cho đến khi suy luận về mô hình và phương thức gọi phải đảm bảo rằng Buffer ở vị trí đọc thích hợp. |
---|---|
kết quả đầu ra | ánh xạ các chỉ mục đầu ra ánh xạ đến các mảng đa chiều của dữ liệu đầu ra hoặc Buffer thuộc các loại nguyên gốc bao gồm int, float, long và byte. Hàm này chỉ cần giữ lại các mục nhập để sử dụng kết quả. Khi sử dụng Buffer , phương thức gọi phải đảm bảo rằng nó được đặt vị trí ghi thích hợp. Bản đồ có thể trống trong các trường hợp tay cầm vùng đệm được sử dụng cho dữ liệu tensor đầu ra hoặc các trường hợp đầu ra được định dạng động và phương thức gọi phải truy vấn hình dạng Tensor đầu ra sau khi suy luận được gọi, tìm nạp dữ liệu trực tiếp từ tensor đầu ra (thông qua Tensor.asReadOnlyBuffer() ). |
công khai void runSignature (Bản đồ<Chuỗi, Đối tượng> dữ liệu đầu vào, Bản đồ<Chuỗi, Đối tượng> kết quả)
Giống như runSignature(Map, Map, String)
nhưng không yêu cầu truyền một signatureKey, giả sử mô hình có một SignatureDef. Nếu mô hình có nhiều SignatureDef, thì mô hình đó sẽ gửi một ngoại lệ.
CẢNH BÁO: Đây là API thử nghiệm và có thể thay đổi.
Thông số
giá trị đầu vào | |
---|---|
kết quả đầu ra |
công khai vô hiệu runSignature (Bản đồ<Chuỗi, Đối tượng> dữ liệu đầu vào, Bản đồ<Chuỗi, Đối tượng> kết quả đầu ra, Chuỗi signatureKey)
Chạy suy luận về mô hình dựa trên SignatureDef được cung cấp thông qua signatureKey
.
Hãy xem run(Object, Object)
để biết thêm thông tin chi tiết về các loại dữ liệu đầu vào và đầu ra được phép.
CẢNH BÁO: Đây là API thử nghiệm và có thể thay đổi.
Thông số
giá trị đầu vào | Ánh xạ từ tên đầu vào trong SignatureDef đến đối tượng đầu vào. |
---|---|
kết quả đầu ra | Một bản đồ từ tên đầu ra trong SignatureDef đến dữ liệu đầu ra. Giá trị này có thể trống nếu phương thức gọi muốn truy vấn dữ liệu Tensor trực tiếp sau khi suy luận (ví dụ: nếu hình dạng đầu ra là động hoặc tay cầm vùng đệm đầu ra được sử dụng). |
signatureKey | Khoá chữ ký xác định SignatureDef. |
Gửi
IllegalArgumentException | nếu inputs rỗng hoặc trống, nếu outputs hoặc signatureKey rỗng, hoặc nếu có lỗi xảy ra khi chạy suy luận.
|
---|
công khai void setCancelled (boolean cancelled)
Nâng cao: Gián đoạn suy luận khi đang thực hiện lệnh gọi đến run(Object, Object)
.
Cờ huỷ sẽ được đặt thành true khi hàm này được gọi. Trình thông dịch sẽ kiểm tra cờ giữa các lệnh gọi Op và nếu đó là true
, trình thông dịch sẽ ngừng thực thi. Trình thông dịch sẽ vẫn ở trạng thái đã huỷ cho đến khi setCancelled(false)
huỷ bỏ một cách rõ ràng.
CẢNH BÁO: Đây là API thử nghiệm và có thể thay đổi.
Thông số
đã hủy | true để huỷ suy luận một cách hiệu quả nhất; hãy false để tiếp tục. |
---|
Gửi
IllegalStateException | nếu trình phiên dịch không được khởi chạy bằng tuỳ chọn có thể huỷ được (theo mặc định), tuỳ chọn này ở trạng thái tắt. |
---|