InterpreterApi

giao diện công khai InterpreterApi
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 thức thử nghiệm.

Thực thể InterpreterApi đóng gói một mô hình TensorFlow Lite được huấn luyện trước, 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 (InterpreterApi interpreter =
     new InterpreterApi.create(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 (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 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 (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 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 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ể InterpreterApi không an toàn cho chuỗi.

CẢNH BÁO: Thực thể 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 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 InterpreterApi.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. 

Phương thức công khai

trừu tượng trống
Hàm allocateTensors()
Cập nhật rõ ràng mức phân bổ cho tất cả tensor, nếu cần.
trừu tượng trống
Hàm close()
Phát hành các tài nguyên liên kết với thực thể InterpreterApi.
Tĩnh InterpreterApi
create(File mô hìnhFile, các tuỳ chọn InterpreterApi.Options)
Tạo một thực thể InterpreterApi bằng mô hình và các tuỳ chọn được chỉ định.
Tĩnh InterpreterApi
create(ByteBuffer byteBuffer, tuỳ chọn InterpreterApi.Options)
Tạo một thực thể InterpreterApi bằng mô hình và các tuỳ chọn được chỉ định.
trừu tượng 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.
bản tóm tắt Tensor
getInputTensor(int inputIndex)
Lấy Tensor liên kết với chỉ mục đầu vào được cung cấp.
trừu tượng int
Hàm getInputTensorCount()
Lấy số lượng tensor đầu vào.
trừu tượng Dài
Hàm getLastNativeInferenceDurationNanoseconds()
Trả về thời gian suy luận gốc.
trừu tượng 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.
bản tóm tắt Tensor
getOutputTensor(int outputIndex)
Lấy Tensor liên kết với chỉ mục đầu ra được cung cấp.
trừu tượng int
Hàm getOutputTensorCount()
Lấy số lượng Tensor đầu ra.
trừu tượng trống
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.
trừu tượng trống
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.
trừu tượng trống
run(Đầu vào đối tượng, đầu ra Đối tượng)
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.
trừu tượng trống
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.

Các phương thức kế thừa

Phương thức công khai

công khai trừu tượng 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.

Gửi
IllegalStateException nếu không thể phân bổ thành công tensor của biểu đồ.

công khai trừu tượng 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 tĩnh InterpreterApi tạo (Tệp mô hìnhFile, tuỳ chọn InterpreterApi.Options)

Tạo một thực thể InterpreterApi bằng mô hình và các tuỳ chọn được chỉ định. Mô hình sẽ được tải qua một tệp.

Tham số
modelFile Tệp chứa mô hình TF Lite được huấn luyện trước.
tùy chọn Một tập hợp các tuỳ chọn để tuỳ chỉnh hoạt động 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 tĩnh InterpreterApi tạo (ByteBuffer tùy chọn byteBuffer, InterpreterApi.Options)

Tạo một thực thể InterpreterApi bằng mô hình và các tuỳ chọn được chỉ định. Mô hình sẽ được đọc từ ByteBuffer.

Tham số
byteBuffer Một mô hình TF Lite huấn luyện trước, ở dạng nối tiếp nhị phân. Bạn không nên sửa đổi ByteBuffer sau khi tạo thực thể InterpreterApi. 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.
tùy chọn Một tập hợp các tuỳ chọn để tuỳ chỉnh hoạt động của phiên dịch.
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.

Public abstract 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.

Tham số
opName
Gửi
IllegalArgumentException nếu opName không khớp với bất kỳ dữ liệu đầu vào nào trong mô hình được dùng để khởi chạy trình thông dịch.

công khai bản tóm tắt Tensor getInputTensor (int inputIndex)

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

Tham số
inputIndex
Gửi
IllegalArgumentException nếu inputIndex là số âm hoặc không nhỏ hơn số đầu vào của mô hình.

Public abstract int getInputTensorCount ()

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

công khai trừu tượng Dài getLastNativeInferenceDurationNanoseconds ()

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

Gửi
IllegalArgumentException nếu mô hình không được trình thông dịch khởi tạo.

public abstract 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.

Tham số
opName
Gửi
IllegalArgumentException nếu opName không khớp với bất kỳ kết quả nào trong mô hình được dùng để khởi chạy trình thông dịch.

công khai bản tóm tắt 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.

Tham số
outputIndex
Gửi
IllegalArgumentException nếu outputIndex là số âm hoặc không nhỏ hơn số đầu ra của mô hình.

public abstract int getOutputTensorCount ()

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

công khai trừu tượng 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ề.

Tham số
idx
dims
nghiêm ngặt
Gửi
IllegalArgumentException nếu idx mang giá trị âm hoặc không nhỏ hơn số lượng đầu vào của mô hình; hoặc nếu xảy ra lỗi khi đổi kích thước đầu vào thứ idx. Ngoài ra, lỗi xảy ra khi cố gắng đổi kích thước tensor với kích thước cố định khi giá trị "strict" là True.

công khai trừu tượng 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.

Tham số
idx
dims
Gửi
IllegalArgumentException nếu idx mang giá trị âm hoặc không nhỏ hơn số lượng đầu vào của mô hình; hoặc nếu xảy ra lỗi khi đổi kích thước đầu vào thứ idx.

công khai trừu tượng 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.
Xin lưu ý rằng các loại boolean chỉ được hỗ trợ dưới dạng mảng, không phải Buffer hoặc giá trị đầu vào vô hướng.

Tham 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()
Gửi
IllegalArgumentException nếu input rỗng hoặc trống, hoặc nếu xảy ra lỗi khi chạy suy luận.
IllegalArgumentException (THỬ NGHIỆM, có thể thay đổi) nếu suy luận bị gián đoạn bởi setCancelled(true).

công khai trừu tượng void runForMultipleInputsOutputs (Object[] đầu vào, Map<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.
Xin lưu ý rằng các loại boolean chỉ được hỗ trợ dưới dạng mảng, không phải 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.

Tham 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()).
Gửi
IllegalArgumentException nếu inputs rỗng hoặc trống, nếu outputs rỗng, hoặc nếu có lỗi xảy ra khi chạy dự đoán.