InterpreterApi

Trình thông dịch giao diện công cộngApi
Các lớp con gián tiếp đã biết

Giao diện với trình thông dịch mô hình TensorFlow Lite, không bao gồm các phương pháp thử nghiệm.

Phiên bản InterpreterApi đóng gói mô hình TensorFlow Lite được đào tạo trước, trong đó các hoạt động được thực thi để suy luậ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 (InterpreterApi interpreter =
     new InterpreterApi.create(file_of_a_tensorflowlite_model)) {
   interpreter.run(input, output);
 }

Nếu một mô hình có nhiề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 (InterpreterApi interpreter =
     new InterpreterApi.create(file_of_a_tensorflowlite_model)) {
   interpreter.runForMultipleInputsOutputs(inputs, map_of_indices_to_outputs);
 }

Nếu một mô hình lấy hoặc tạo ra các 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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 đầu ra 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ư hình dạng mặc định của đầu vào.

Khi đầ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 thay đổi kích thước hoàn toàn theo hình dạng của mảng đó. Khi đầu vào được cung cấp dưới dạng loại Buffer , việc thay đổi kích thước ngầm định sẽ không được thực hiện; người 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 tenxơ tương ứng hoặc trước tiên họ thay đổi kích thước của tenxơ thông qua resizeInput(int, int[]) . Thông tin về hình dạng và loại tenxơ có thể được lấy thông qua lớp Tensor , có sẵn thông qua getInputTensor(int) và getOutputTensor(int) .

CẢNH BÁO: Phiên bản InterpreterApi không an toàn theo luồng.

CẢNH BÁO: Một phiên bản InterpreterApi sở hữu các 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 NDK API 19. Nó có thể hoạt động với các cấp API Android dưới 19 nhưng không được đảm bảo.

Các lớp lồng nhau

lớp học Thông dịch viênApi.Options Một lớp tùy chọn để kiểm soát hành vi của trình thông dịch thời gian chạy.

Phương pháp công cộng

khoảng trống trừu tượng
phân bổTensors ()
Cập nhật rõ ràng việc phân bổ cho tất cả các tensor, nếu cần.
khoảng trống trừu tượng
đóng ()
Giải phóng các tài nguyên được liên kết với phiên bản InterpreterApi .
Trình thông dịch tĩnhApi
tạo (Tùy chọn tệp modelFile, InterpreterApi.Options )
Xây dựng một phiên bản InterpreterApi , sử dụng mô hình và các tùy chọn đã chỉ định.
Trình thông dịch tĩnhApi
tạo (tùy chọn ByteBuffer byteBuffer, InterpreterApi.Options )
Xây dựng một phiên bản InterpreterApi , sử dụng mô hình và các tùy chọn đã chỉ định.
int trừu tượng
getInputIndex ( Chuỗi opName)
Lấy chỉ mục của một đầu vào dựa trên tên op của đầu vào.
Tensor trừu tượng
getInputTensor (int inputIndex)
Lấy Tensor liên kết với chỉ mục đầu vào được cung cấp.
int trừu tượng
getInputTensorCount ()
Lấy số lượng tensor đầu vào.
trừu tượng dài
getLastNativeInferenceDurationNanoseconds ()
Trả về thời gian suy luận gốc.
int trừu tượng
getOutputIndex ( Chuỗi opName)
Lấy chỉ mục của một đầu ra dựa trên tên op của đầu ra.
Tensor trừu tượng
getOutputTensor (int đầu ra Index)
Lấy Tensor liên kết với chỉ số đầu ra được cung cấp.
int trừu tượng
getOutputTensorCount ()
Lấy số lượng Tensor đầu ra.
khoảng trống trừu tượng
thay đổi kích thướcInput (int idx, int[] dims, boolean nghiêm ngặt)
Thay đổi kích thước đầu vào idx-th của mô hình gốc thành độ mờ nhất định.
khoảng trống trừu tượng
thay đổi kích thướcInput (int idx, int[] dims)
Thay đổi kích thước đầu vào idx-th của mô hình gốc thành độ mờ nhất định.
khoảng trống trừu tượng
run (Đầu vào đối tượng , Đầu ra đối tượng )
Chạy suy luận 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.
khoảng trống trừu tượng
runForMultipleInputsOutputs ( đầu vào Object[] , đầu ra Map < Integer , Object >)
Chạy suy luận mô hình nếu mô hình nhận nhiều đầu vào hoặc trả về nhiều đầu ra.

Phương pháp kế thừa

Phương pháp công cộng

trừu tượng công khai void phân bổTensors ()

Cập nhật rõ ràng việc phân bổ cho tất cả các tensor, nếu cần.

Điều này sẽ truyền các hình dạng và phân bổ bộ nhớ cho các 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 ý: Lệnh gọi này *hoàn toàn là tùy chọn*. Việc phân bổ tensor sẽ tự động diễn ra trong quá trình thực thi nếu bất kỳ tensor đầu vào nào đã được thay đổ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 bất kỳ tensor đầu ra nào trước khi thực hiện 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 hình động, trong trường hợp đó, hình dạng đầu ra có thể không lan truyền hoàn toàn cho đến khi thực hiện suy luận.

Ném
Ngoại lệ nhà nước bất hợp pháp nếu các tensor của đồ thị không thể được phân bổ thành công.

trừu tượng công khai void đóng ()

Giải phóng các tài nguyên được liên kết với phiên bản InterpreterApi .

Tạo thông dịch viên tĩnh công khai (Tùy chọn tệp modelFile, InterpreterApi.Options )

Xây dựng một phiên bản InterpreterApi , sử dụng mô hình và các tùy chọn đã chỉ định. Mô hình sẽ được tải từ một tập tin.

Thông số
tập tin mô hình Một tệp chứa mô hình TF Lite được đào tạo trước.
tùy chọn Một tập hợp các tùy chọn để tùy chỉnh hành vi của trình thông dịch.
Ném
Ngoại lệ Đối số bất hợp pháp nếu modelFile không mã hóa mô hình TensorFlow Lite hợp lệ.

Tạo phiên dịch tĩnh công khai (tùy chọn ByteBuffer byteBuffer, InterpreterApi.Options )

Xây dựng một phiên bản InterpreterApi , sử dụng mô hình và các tùy chọn đã chỉ định. Mô hình sẽ được đọc từ ByteBuffer .

Thông số
byteBuffer Một mô hình TF Lite được đào tạo trước, ở dạng tuần tự nhị phân. Không nên sửa đổi ByteBuffer sau khi xây dựng phiên bản InterpreterApi . ByteBuffer có thể là MappedByteBuffer ánh xạ bộ nhớ tệp mô hình hoặc ByteBuffer trực tiếp của localOrder() chứa nội dung byte của mô hình.
tùy chọn Một tập hợp các tùy chọn để tùy chỉnh hành vi của trình thông dịch.
Ném
Ngoại lệ Đối số bất hợp pháp nếu byteBuffer không phải là MappedByteBuffer cũng không phải là ByteBuffer trực tiếp của NativeOrder.

tóm tắt công khai int getInputIndex ( Chuỗi opName)

Lấy chỉ mục của một đầu vào dựa trên tên op của đầu vào.

Thông số
tên op
Ném
Ngoại lệ Đối số bất hợp pháp nếu opName không khớp với bất kỳ đầu vào nào trong mô hình được sử dụng để khởi tạo trình thông dịch.

Tensor trừu tượng công khai 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ố
chỉ số đầu vào
Ném
Ngoại lệ Đối số bất hợp pháp nếu inputIndex âm hoặc không nhỏ hơn số lượng đầu vào của mô hình.

tóm tắt công khai int getInputTensorCount ()

Lấy số lượng tensor đầu vào.

tóm tắt công khai Long getLastNativeInferenceDurationNanoseconds ()

Trả về thời gian suy luận gốc.

Ném
Ngoại lệ Đối số bất hợp pháp nếu mô hình không được trình thông dịch khởi tạo.

tóm tắt công khai int getOutputIndex ( Chuỗi opName)

Lấy chỉ mục của một đầu ra dựa trên tên op của đầu ra.

Thông số
tên op
Ném
Ngoại lệ Đối số bất hợp pháp nếu opName không khớp với bất kỳ đầu ra nào trong mô hình được sử dụng để khởi tạo trình thông dịch.

Tensor trừu tượng công khai getOutputTensor (int inputIndex)

Lấy Tensor liên kết với chỉ số đầu ra được cung cấp.

Lưu ý: Các chi tiết tensor đầu ra (ví dụ: hình dạng) có thể không được điền đầy đủ cho đến khi thực hiện 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 thay đổi kích thước một tenxơ đầu vào, điều này có thể làm mất hiệu lực hình dạng tenxơ đầu ra), hãy sử dụng allocateTensors() để kích hoạt phân bổ và truyền bá hình dạng một cách rõ ràng. 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ể không được xác định đầy đủ cho đến khi chạy suy luận.

Thông số
chỉ số đầu ra
Ném
Ngoại lệ Đối số bất hợp pháp nếu outputIndex âm hoặc không nhỏ hơn số lượng đầu ra của mô hình.

tóm tắt công khai int getOutputTensorCount ()

Lấy số lượng Tensor đầu ra.

trừu tượng công khai void sizeInput (int idx, int[] dims, boolean strict)

Thay đổi kích thước đầu vào idx-th của mô hình gốc thành độ mờ nhất định.

Khi `nghiêm ngặt` là Đúng, chỉ có thể thay đổi kích thước các kích thước không xác định. Các kích thước không xác định được biểu thị là `-1` trong mảng được trả về bởi `Tensor.shapeSignature()`.

Thông số
idx
mờ đi
nghiêm ngặt
Ném
Ngoại lệ Đối số bất hợp pháp nếu idx âm hoặc không nhỏ hơn số lượng đầu vào mô hình; hoặc nếu xảy ra lỗi khi thay đổi kích thước đầu vào idx-th. Ngoài ra, lỗi xảy ra khi cố gắng thay đổi kích thước của một tenxơ có kích thước cố định khi `nghiêm ngặt` là Đúng.

trừu tượng công khai void sizeInput (int idx, int[] dims)

Thay đổi kích thước đầu vào idx-th của mô hình gốc thành độ mờ nhất định.

Thông số
idx
mờ đi
Ném
Ngoại lệ Đối số bất hợp pháp nếu idx âm hoặc không nhỏ hơn số lượng đầu vào mô hình; hoặc nếu xảy ra lỗi khi thay đổi kích thước đầu vào idx-th.

chạy void trừu tượng công khai (Đầu vào đối tượng , Đầu ra đối tượng )

Chạy suy luận 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 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 để cung cấp và tìm nạp dữ liệu gốc để có hiệu suất tốt hơn. Các loại Buffer đệm cụ thể sau đây được hỗ trợ:

  • ByteBuffer - tương thích với mọi loại Tensor nguyên thủy cơ bản.
  • FloatBuffer - tương thích với Tensor float.
  • IntBuffer - tương thích với Tensor int32.
  • LongBuffer - tương thích với Tensor int64.
Lưu ý rằng các kiểu boolean chỉ được hỗ trợ dưới dạng mảng chứ không phải Buffer hoặc dưới dạng đầu vào vô hướng.

Thông số
đầu vào một mảng hoặc mảng nhiều chiều hoặc Buffer gồm các kiểu nguyên thủy bao gồm int, float, long và byte. Buffer là cách ưa thích để truyền dữ liệu đầu vào lớn cho các kiểu nguyên thủy, trong khi các kiểu chuỗi yêu cầu sử dụng đường dẫn đầu vào mảng (đa chiều). Khi Buffer được sử dụng, nội dung của nó sẽ không thay đổi cho đến khi thực hiện suy luận mô hình và người 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 người gọi đang sử dụng Delegate cho phép tương tác xử lý bộ đệm và bộ đệm như vậy đã được liên kết với Tensor đầu vào.
đầu ra một mảng dữ liệu đầu ra đa chiều hoặc Buffer gồm các kiểu nguyên thủy bao gồm int, float, long và byte. Khi sử dụng Buffer , người gọi phải đảm bảo rằng nó được đặt ở vị trí ghi thích hợp. Giá trị null được cho phép và hữu ích trong một số trường hợp nhất định, ví dụ: nếu người gọi đang sử dụng Delegate cho phép tương tác xử lý bộ đệm và bộ đệm như vậy đã được liên kết với Tensor đầu ra (xem thêm Interpreter.Options#setAllowBufferHandleOutput(boolean) ) hoặc nếu biểu đồ có đầu ra được định hình động và trình 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() ).
Ném
Ngoại lệ Đối số bất hợp pháp nếu input rỗng hoặc trống hoặc nếu xảy ra lỗi khi chạy suy luận.
Ngoại lệ Đối số bất hợp pháp (THỬ NGHIỆM, có thể thay đổi) nếu suy luận bị gián đoạn bởi setCancelled(true) .

trừu tượng công khai void runForMultipleInputsOutputs ( đầu vào Object[] , đầu ra Map < Integer , Object >)

Chạy suy luận 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 sử dụng Buffer s (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 để cung cấp và tìm nạp dữ liệu gốc để có hiệu suất tốt hơn. Các loại Buffer đệm cụ thể sau đây được hỗ trợ:

  • ByteBuffer - tương thích với mọi loại Tensor nguyên thủy cơ bản.
  • FloatBuffer - tương thích với Tensor float.
  • IntBuffer - tương thích với Tensor int32.
  • LongBuffer - tương thích với Tensor int64.
Lưu ý rằng các kiểu boolean chỉ được hỗ trợ dưới dạng mảng chứ không phải Buffer hoặc dưới dạng đầu vào vô hướng.

Lưu ý: chỉ cho phép các giá trị null cho các phần tử riêng lẻ của inputs và outputs nếu người gọi đang sử dụng Delegate cho phép tương tác xử lý bộ đệm và bộ đệ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ố
đầu vào một mảng dữ liệu đầu vào. Các đầu vào phải theo cùng thứ tự với các đầu vào của mô hình. Mỗi đầu vào có thể là một mảng hoặc mảng nhiều chiều hoặc Buffer có các kiểu nguyên thủy bao gồm int, float, long và byte. Buffer là cách ưa thích để truyền dữ liệu đầu vào lớn, trong khi loại chuỗi yêu cầu sử dụng đường dẫn đầu vào mảng (đa chiều). Khi Buffer được sử dụng, nội dung của nó sẽ không thay đổi cho đến khi thực hiện suy luận mô hình và người gọi phải đảm bảo rằng Buffer ở vị trí đọc thích hợp.
kết quả đầu ra một bản đồ ánh xạ các chỉ mục đầu ra tới các mảng đa chiều của dữ liệu đầu ra hoặc Buffer thuộc các kiểu nguyên thủy bao gồm int, float, long và byte. Nó chỉ cần giữ các mục để đầu ra được sử dụng. Khi sử dụng Buffer , người 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 sử dụng bộ điều khiển bộ đệm cho dữ liệu tensor đầu ra hoặc trường hợp đầu ra được định hình động và người 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() ).
Ném
Ngoại lệ Đối số bất hợp pháp nếu inputs rỗng hoặc trống, nếu outputs rỗng hoặc nếu xảy ra lỗi khi chạy suy luận.