InterpreterApi

giao diện công khai InterpreterApi
Lớp con gián tiếp đã biết

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

Một thực thể InterpreterApi đóng gói mô hình TensorFlow Lite được huấn luyện trước, trong đó các phép toán sẽ được thực thi để suy luận mô hình.

Ví dụ: nếu một mô hình chỉ nhận một dữ liệu đầu vào và chỉ trả về một dữ liệu đầ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 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 sử dụng 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]. Cho tensor chuỗi vô hướng kết quả: 

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ự đầu vào và đầu ra được xác định khi chuyển đổi mô hình TensorFlow sang TensorFlowLite với 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 các 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 dữ liệu đầu vào được cung cấp dưới dạng loại Buffer, việc đổi kích thước ngầm ẩn sẽ không đượ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 đáp ứng trước đổi kích thước tensor thông qua resizeInput(int, int[]). Thông tin về hình dạng và loại Tensor có thể được lấy qua lớp Tensor, được cung cấp qua getInputTensor(int) và getOutputTensor(int).

CẢNH BÁO: Các thực thể InterpreterApi không an toàn cho luồng.

CẢNH BÁO:Một thực thể InterpreterApi sở hữu các tài nguyên phải là được giải phóng một cách 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. Ứng dụng này có thể hoạt động với API Android cấp 19 trở xuống, nhưng không được đả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 phiên dịch trong thời gian chạy.

Phương thức công khai

trừu tượng trống
allocateTensors()
Cập nhật rõ ràng các lượt phân bổ cho tất cả tensor, nếu cần.
trừu tượng trống
close()
Phát hành các tài nguyên liên kết với thực thể InterpreterApi.
tĩnh InterpreterApi
tạo(các tuỳ chọn File modelFile, InterpreterApi.Options)
Tạo một thực thể InterpreterApi bằng mô hình và các tuỳ chọn đã chỉ định.
tĩnh InterpreterApi
tạo(các lựa chọn ByteBuffer byteBuffer, InterpreterApi.Options)
Tạo một thực thể InterpreterApi bằng mô hình và các tuỳ chọn đã chỉ định.
trừu tượng đánh chặn
getInputIndex(String opName)
Lấy chỉ mục của một đầu vào dựa vào tên vận hành của đầu vào đó.
trừu tượng Tensor
getInputTensor(int inputIndex)
Lấy Tensor liên kết với chỉ mục đầu vào đã cung cấp.
trừu tượng đánh chặn
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.
trừu tượng đánh chặn
getOutputIndex(String opName)
Lấy chỉ mục của một đầu ra dựa vào tên hoạt động của đầu ra.
trừu tượng 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 đánh chặn
getOutputTensorCount()
Lấy số Tensor đầu ra.
trừu tượng trống
resizeInput(int idx, int[] dims, boolean strict)
Đổi kích thước dữ liệu đầu vào thứ idx của mô hình gốc thành các độ tối đã cho.
trừu tượng trống
resizeInput(int idx, int[] dims)
Đổi kích thước dữ liệu đầu vào thứ idx của mô hình gốc thành các độ tối đã cho.
trừu tượng trống
run(Đầu vào Đối tượng, Đầu ra Đối tượng)
Chạy dự đoá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.
trừu tượng trống
runForMultipleInputsOutputs(đầu vào Object[], đầu ra Map<Integer, Object>)
Chạy dự đoán cho mô hình nếu mô hình lấy 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 khai

công khai trừu tượng trống allocateTensors ()

Cập nhật rõ ràng các lượt 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à cơ cấu phân bổ bộ nhớ cho các tensor phụ thuộc bằng cách sử dụng dữ liệu đầu vào hình dạng tensor như đã cho.

Lưu ý: Lệnh gọi này *hoàn toàn không bắt buộc*. Quá trình phân bổ Tensor sẽ tự động diễn ra trong 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 cho các tensor đầu ra bất kỳ 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 toàn bộ cho đến khi thực thi suy luận.

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

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

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 modelFile, InterpreterApi.Options tuỳ chọn)

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

Tham số
modelFile Tệp có chứa mô hình TF Lite đã 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ột TensorFlow Lite hợp lệ mô hình.

công khai tĩnh InterpreterApi tạo (các tuỳ chọnByteBuffer byteBuffer, InterpreterApi.Options)

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

Tham số
byteBuffer Mô hình TF Lite được huấn luyện trước, ở dạng chuyển đổi tuần tự nhị phân. ByteBuffer sẽ không bị sửa đổi sau khi tạo bản sao InterpreterApi. ByteBuffer có thể là MappedByteBuffer liên kết bộ nhớ với một tệp mô hình, hoặc trực tiếp ByteBuffer của nativeOrder() chứa nội dung 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 hoặc không ByteBuffer trực tiếp của nativeOrder.

công khai trừu tượng đánh chặn getInputIndex (Chuỗi opName)

Lấy chỉ mục của một đầu vào dựa vào tên vận hành 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 đã dùng để khởi chạy trình phiên dịch.

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

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

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

công khai trừu tượng đánh chặn 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.

công khai trừu tượng đánh chặn getOutputIndex (Chuỗi opName)

Lấy chỉ mục của một đầu ra dựa vào 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ỳ đầu ra nào trong mô hình đã dùng để khởi chạy trình phiên dịch.

công khai trừu tượng 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 đầu ra tensor (ví dụ: hình dạng) có thể không được điền đầy đủ cho đến sau khi suy luận sẽ được thực thi. 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 tensor đầu vào có thể vô hiệu hoá hình dạng tensor đầu ra), 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 biểu đồ có hình dạng đầu ra phụ thuộc vào *giá trị* đầu vào, thì hình dạng đầu ra có thể không được xác định hoàn toàn cho đến khi đang 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ố lượng đầu ra của mô hình.

công khai trừu tượng đánh chặn getOutputTensorCount ()

Lấy số Tensor đầu ra.

công khai trừu tượng trống resizeInput (int idx, int[] dims, boolean nghiêm ngặt)

Đổi kích thước dữ liệu đầu vào thứ idx của mô hình gốc thành các độ tối đã cho.

Khi giá trị "strict" là True, thì bạn chỉ có thể đổi kích thước những phương diện chưa xác định. Phương diện không xác định là được biểu thị là "-1" trong mảng do "Tensor.shapeSignature() trả về".

Tham số
quyền kiểm soát xu hướng
giảm độ sáng
nghiêm ngặt
Gửi
IllegalArgumentException nếu idx là số âm hoặc không nhỏ hơn số này đầu vào của mô hình; hoặc nếu xảy ra lỗi khi đổi kích thước dữ liệu đầu vào 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 trống resizeInput (int idx, int[] dims)

Đổi kích thước dữ liệu đầu vào thứ idx của mô hình gốc thành các độ tối đã cho.

Tham số
quyền kiểm soát xu hướng
giảm độ sáng
Gửi
IllegalArgumentException nếu idx là số âm hoặc không nhỏ hơn số này đầu vào của mô hình; hoặc nếu xảy ra lỗi khi đổi kích thước dữ liệu đầu vào idx.

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

Chạy dự đoá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 này sẽ hiệu quả hơn nếu là Buffer (tốt nhất là trực tiếp, nhưng không bắt buộc) được dùng làm kiểu dữ liệu đầu vào/đầu ra. Hãy cân nhắc sử dụng Buffer để cấp dữ liệu và tìm nạp để có hiệu suất tốt hơn. Các loại Buffer cụ thể sau đây là được hỗ trợ:

  • ByteBuffer – tương thích với mọi kiểu Tensor nguyên thuỷ cơ bản.
  • FloatBuffer – tương thích với float Tensor.
  • 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 chứ không phải dưới dạng Buffer hoặc dưới dạng đầu vào vô hướng.

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

công khai trừu tượng trống runForMultipleInputsOutputs (Đầu vào Object[], đầu ra Bản đồ<Số nguyên, Đối tượng>)

Chạy dự đoán cho mô hình nếu mô hình lấy nhiều đầu vào hoặc trả về nhiều đầu ra.

Cảnh báo: API này 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 dùng làm kiểu dữ liệu đầu vào/đầu ra. Hãy cân nhắc sử dụng Buffer để cấp dữ liệu và tìm nạp để có hiệu suất tốt hơn. Các loại Buffer cụ thể sau đây là được hỗ trợ:

  • ByteBuffer – tương thích với mọi kiểu Tensor nguyên thuỷ cơ bản.
  • FloatBuffer – tương thích với float Tensor.
  • 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 chứ không phải dưới dạng Buffer hoặc dưới dạng đầu vào vô hướng.

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