InterpreterApi

giao diện công cộng Phiên dịch viênApi
Các lớp con gián tiếp đã biết

Giao diện cho trình thông dịch mô hình TensorFlow Lite, ngoại trừ các phương pháp thử nghiệm.

Một phiên bản InterpreterApi đóng gói một 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 tensors 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 shape [] và shape[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) tenxơ đầ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 , không có thay đổi kích thước ngầm định nào đượ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 tenxơ thông qua resizeInput(int, int[]) . Thông tin về loại và hình dạng của tenor có thể được lấy thông qua lớp Tensor , có sẵn qua getInputTensor(int) và getOutputTensor(int) .

CẢNH BÁO: Phiên bản InterpreterApi không an toàn cho chuỗi.

CẢNH BÁO: 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 hàm close()

Thư viện TFLite được xây dựng dựa trên API NDK 19. Nó có thể hoạt động với các cấp API Android dưới 19, nhưng không được bảo đảm.

Các lớp lồng nhau

lớp học Phiên dịchApi.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 thức công khai

khoảng trống trừu tượng
phân bổTensors ()
Cập nhật rõ ràng các phân bổ cho tất cả các tenxơ, 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, Phiên dịch viênApi.Options )
Xây dựng 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, Phiên dịch viênApi.Options )
Xây dựng 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
getInput Index ( Chuỗi opName)
Nhận chỉ mục của một đầu vào với tên op của đầu vào.
Tenor trừu tượng
getInputTensor (int đầu vào Index)
Nhận Tensor được liên kết với chỉ mục đầu vào được cung cấp.
int trừu tượng
getInputTensorCount ()
Nhận số lượng tenxơ đầ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
getOutput Index ( Chuỗi opName)
Nhận chỉ mục của một đầu ra với tên op của đầu ra.
Tenor trừu tượng
getOutputTensor (int đầu ra Index)
Nhận Tensor được liên kết với chỉ mục đầu ra được cung cấp.
int trừu tượng
getOutputTensorCount ()
Nhận số Tensors đầu ra.
khoảng trống trừu tượng
thay đổi kích thướcInput (int idx, int[] mờ, 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 các độ mờ nhất định.
khoảng trống trừu tượng
thay đổi kích thướcInput (int idx, int[] mờ)
Thay đổi kích thước đầu vào idx-th của mô hình gốc thành các độ mờ nhất định.
khoảng trống trừu tượng
chạy ( Đầ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 ( Object[] đầu vào, Map < Integer , Object > đầu ra)
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 thức kế thừa

Phương thức công cộng

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

Cập nhật rõ ràng các phân bổ cho tất cả các tenxơ, 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 tenxơ phụ thuộc bằng cách sử dụng (các) hình dạng tenxơ đầu vào như đã cho.

Lưu ý: Cuộc gọi này *hoàn toàn là tùy chọn*. Việc phân bổ tenxơ sẽ diễn ra tự động trong quá trình thực thi nếu bất kỳ tenxơ đầu vào nào đã được thay đổi kích thước. Cuộc gọi này hữu ích nhất trong việc xác định hình dạng cho bất kỳ tenxơ đầ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ó hình dạng độ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 tenxơ của biểu đồ không thể được phân bổ thành công.

khoảng trống trừu tượng công khai đó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 phiên dịch tĩnh công khai ( Tùy chọn tệp modelFile, Phiên dịch viênApi.Options )

Xây dựng 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 mô hình 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, Phiên dịch viênApi.Options )

Xây dựng 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ố
bộ đệm byte Một mô hình TF Lite được đào tạo trước, ở dạng tuần tự hóa nhị phân. Không nên sửa đổi ByteBuffer sau khi xây dựng một phiê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 nativeOrder() 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 getInput Index ( Chuỗi opName)

Nhận chỉ mục của một đầu vào với tên op của đầu vào.

Thông số
opName
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)

Nhận Tensor được liên kết với chỉ mục đầu vào được cung cấp.

Thông số
đầu vào Index
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 ()

Nhận số lượng tenxơ đầ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 khởi tạo bởi trình thông dịch.

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

Nhận chỉ mục của một đầu ra với tên op của đầu ra.

Thông số
opName
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 outputIndex)

Nhận Tensor được liên kết với chỉ mục đầu ra được cung cấp.

Lưu ý: Chi tiết tenxơ đầ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 của tenxơ đầu vào, điều này có thể làm mất hiệu lực hình dạng của tenxơ đầu ra), hãy sử dụng allocateTensors() để kích hoạt phân bổ và truyền 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ố
đầu ra Index
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 ()

Nhận số Tensors đầu ra.

công khai trừu tượng void resizeInput (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 các độ mờ nhất định.

Khi `strict` là True, chỉ có thể thay đổi 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ố đầ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 một tensor với kích thước cố định khi `strict` là True.

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

Thay đổi kích thước đầu vào idx-th của mô hình gốc thành các độ 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ố đầ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 Buffer (tốt nhất là trực tiếp, nhưng không bắt buộc) được sử dụng 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 nguyên thủy để có hiệu suất tốt hơn. Các loại Buffer bê tông sau đây được hỗ trợ:

  • ByteBuffer - tương thích với bất kỳ loại Tenor nguyên thủy cơ bản nào.
  • FloatBuffer - tương thích với Tenor nổi.
  • 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, không phải Buffer s 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 của các kiểu nguyên thủy 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 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 hoàn thành 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 kiểu nguyên thủy bao gồm int, float, long và byte. Khi Buffer được sử dụng, 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 Phiên dịch viên.Options#setAllowBufferHandleOutput(boolean) ) hoặc nếu biểu đồ có các đầu ra có hình dạng động và người gọi phải truy vấn hình dạng Tensor đầu ra sau khi đã gọi suy luận, 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 là null 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) .

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

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 Buffer s (tốt nhất là trực tiếp, nhưng không bắt buộc) được sử dụng làm kiểu 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 nguyên thủy để có hiệu suất tốt hơn. Các loại Buffer bê tông sau đây được hỗ trợ:

  • ByteBuffer - tương thích với bất kỳ loại Tenor nguyên thủy cơ bản nào.
  • FloatBuffer - tương thích với Tenor nổi.
  • 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, không phải Buffer s hoặc dưới dạng đầu vào vô hướng.

Lưu ý: giá trị null cho các phần tử riêng lẻ của inputs và outputs 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 (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. Đầu vào phải theo thứ tự giống như đầ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 một Buffer các kiểu nguyên thủy 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, trong khi các 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 hoàn thành 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.
đầu ra một bản đồ ánh xạ các chỉ số đầu ra tới các mảng dữ liệu đầu ra đa chiều hoặc Buffer của 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 nhập cho các kết quả đầu ra được sử dụng. Khi Buffer được sử dụng, 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 đối với các trường hợp trong đó một trong hai tay cầm bộ đệm được sử dụng cho dữ liệu tensor đầu ra hoặc các trường hợp đầu ra có hình dạng động và người gọi phải truy vấn hình dạng Tensor đầu ra sau khi đã gọi suy luận, lấy dữ liệu trực tiếp từ tensor đầu ra ( qua Tensor.asReadOnlyBuffer() ).
ném
Ngoại lệ Đối số bất hợp pháp nếu inputs là null hoặc trống, nếu outputs là null hoặc nếu xảy ra lỗi khi chạy suy luận.