Interpreter

Penerjemah kelas akhir publik

Kelas driver untuk mendorong inferensi model dengan TensorFlow Lite.

Catatan: Jika Anda tidak memerlukan akses ke fitur API "eksperimental" apa pun di bawah, lebih baik gunakan InterpreterApi dan InterpreterFactory daripada menggunakan Interpreter secara langsung.

Interpreter merangkum model TensorFlow Lite yang telah dilatih sebelumnya, tempat operasi dijalankan untuk inferensi model.

Misalnya, jika suatu model hanya mengambil satu masukan dan hanya mengembalikan satu keluaran: 

try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
   interpreter.run(input, output);
 }

Jika suatu model mengambil beberapa input atau output: 

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);
 }

Jika suatu model mengambil atau menghasilkan tensor string: 

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);
 }

Perhatikan bahwa ada perbedaan antara bentuk [] dan bentuk[1]. Untuk keluaran tensor string skalar: 

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);

Urutan input dan output ditentukan saat mengonversi model TensorFlow ke model TensorFlowLite dengan Toco, begitu pula bentuk default inputnya.

Jika masukan disediakan sebagai larik (multidimensi), tensor masukan yang terkait akan diubah ukurannya secara implisit sesuai dengan bentuk larik tersebut. Ketika input diberikan sebagai tipe Buffer , tidak ada pengubahan ukuran implisit yang dilakukan; pemanggil harus memastikan bahwa ukuran byte Buffer cocok dengan tensor yang sesuai, atau mereka terlebih dahulu mengubah ukuran tensor melalui resizeInput(int, int[]) . Informasi bentuk dan jenis tensor dapat diperoleh melalui kelas Tensor , tersedia melalui getInputTensor(int) dan getOutputTensor(int) .

PERINGATAN: Instance Interpreter tidak aman untuk thread. Seorang Interpreter memiliki sumber daya yang harus dibebaskan secara eksplisit dengan memanggil close()

Library TFLite dibuat berdasarkan NDK API 19. Library ini mungkin berfungsi untuk Android API level di bawah 19, namun tidak dijamin.

Kelas Bersarang

kelas Penerjemah.Pilihan Kelas opsi untuk mengendalikan perilaku juru bahasa runtime.

Konstruktor Publik

Penerjemah ( File modelFile)
Menginisialisasi Interpreter .
Penerjemah ( File modelFile, Interpreter. Opsi opsi)
Menginisialisasi Interpreter dan menentukan opsi untuk menyesuaikan perilaku Interpreter.
Penerjemah ( ByteBuffer byteBuffer)
Menginisialisasi Interpreter dengan ByteBuffer dari file model.
Penerjemah ( ByteBuffer byteBuffer, Interpreter. Opsi opsi)
Menginisialisasi Interpreter dengan ByteBuffer dari file model dan sekumpulan Interpreter.Options khusus.

Metode Publik

ruang kosong
mengalokasikanTensor ()
Perbarui alokasi untuk semua tensor secara eksplisit, jika perlu.
ruang kosong
menutup ()
Rilis sumber daya yang terkait dengan instans InterpreterApi .
ke dalam
getInputIndex ( String nama operasi)
Mendapatkan indeks masukan berdasarkan nama operasi masukan tersebut.
Tensor
getInputTensor (int inputIndex)
Mengasosiasikan Tensor dengan indeks masukan yang disediakan.
ke dalam
dapatkanInputTensorCount ()
Mendapatkan jumlah tensor masukan.
Tensor
getInputTensorFromSignature ( String masukanNama, String tanda tanganKey)
Mengasosiasikan Tensor dengan nama masukan dan nama metode tanda tangan yang diberikan.
Panjang
dapatkanLastNativeInferenceDurationNanodetik ()
Mengembalikan waktu inferensi asli.
ke dalam
getOutputIndex ( String nama operasi)
Mendapat indeks keluaran dengan nama operasi keluaran.
Tensor
getOutputTensor (int keluaranIndeks)
Mengasosiasikan Tensor dengan indeks keluaran yang disediakan.
ke dalam
dapatkanOutputTensorCount ()
Mendapatkan jumlah Tensor keluaran.
Tensor
getOutputTensorFromSignature ( String keluaranNama, String tanda tanganKey)
Mengasosiasikan Tensor dengan nama keluaran yang diberikan dalam metode tanda tangan tertentu.
Rangkaian[]
getSignatureInputs ( String tanda tanganKey)
Mendapatkan daftar input SignatureDefs untuk metode signatureKey .
Rangkaian[]
dapatkanSignatureKeys ()
Mendapatkan daftar nama metode SignatureDef yang diekspor dan tersedia dalam model.
Rangkaian[]
getSignatureOutputs ( String tanda tanganKey)
Mendapatkan daftar keluaran SignatureDefs untuk metode signatureKey .
ruang kosong
resetVariableTensor ()
Lanjutan: Menyetel ulang semua tensor variabel ke nilai default.
ruang kosong
resizeInput (int idx, int[] meredup, boolean ketat)
Mengubah ukuran masukan ke-idx dari model asli ke peredupan tertentu.
ruang kosong
resizeInput (int idx, int[] meredup)
Mengubah ukuran masukan ke-idx dari model asli ke peredupan tertentu.
ruang kosong
jalankan (Masukan objek , Keluaran objek )
Menjalankan inferensi model jika model hanya mengambil satu masukan, dan hanya menyediakan satu keluaran.
ruang kosong
runForMultipleInputsOutputs ( masukan Objek[] , keluaran Peta < Integer , Objek >)
Menjalankan inferensi model jika model mengambil banyak masukan, atau mengembalikan beberapa keluaran.
ruang kosong
runSignature ( masukan Peta < String , Objek >, keluaran Peta < String , Objek >)
Sama seperti runSignature(Map, Map, String) tetapi tidak perlu meneruskan SignatureKey, dengan asumsi model memiliki satu SignatureDef.
ruang kosong
runSignature ( masukan Map < String , Object > , keluaran Map < String , Object > , String SignatureKey)
Menjalankan inferensi model berdasarkan SignatureDef yang disediakan melalui signatureKey .
ruang kosong
setCancelled (boolean dibatalkan)
Lanjutan: Menginterupsi inferensi di tengah panggilan ke run(Object, Object) .

Metode Warisan

Konstruktor Publik

Penerjemah publik ( File modelFile)

Menginisialisasi Interpreter .

Parameter
file model File model TF Lite terlatih.
Melempar
Pengecualian Argumen Ilegal jika modelFile tidak mengkodekan model TensorFlow Lite yang valid.

Penerjemah publik ( File modelFile, opsi Interpreter.Options )

Menginisialisasi Interpreter dan menentukan opsi untuk menyesuaikan perilaku Interpreter.

Parameter
file model file model TF Lite terlatih
pilihan serangkaian opsi untuk menyesuaikan perilaku juru bahasa
Melempar
Pengecualian Argumen Ilegal jika modelFile tidak mengkodekan model TensorFlow Lite yang valid.

Penerjemah publik ( ByteBuffer byteBuffer)

Menginisialisasi Interpreter dengan ByteBuffer dari file model.

ByteBuffer tidak boleh diubah setelah pembuatan Interpreter . ByteBuffer dapat berupa MappedByteBuffer yang memetakan memori file model, atau ByteBuffer langsung dari nativeOrder() yang berisi konten byte model.

Parameter
byteBuffer
Melempar
Pengecualian Argumen Ilegal jika byteBuffer bukan MappedByteBuffer atau ByteBuffer langsung dari nativeOrder.

Penerjemah publik ( ByteBuffer byteBuffer, Interpreter. Opsi opsi)

Menginisialisasi Interpreter dengan ByteBuffer dari file model dan sekumpulan Interpreter.Options khusus.

ByteBuffer tidak boleh diubah setelah pembuatan Interpreter . ByteBuffer dapat berupa MappedByteBuffer yang memetakan memori file model, atau ByteBuffer langsung dari nativeOrder() yang berisi konten byte model.

Parameter
byteBuffer
pilihan
Melempar
Pengecualian Argumen Ilegal jika byteBuffer bukan MappedByteBuffer atau ByteBuffer langsung dari nativeOrder.

Metode Publik

alokasi kekosongan publikTensor ()

Perbarui alokasi untuk semua tensor secara eksplisit, jika perlu.

Ini akan menyebarkan bentuk dan alokasi memori untuk tensor dependen menggunakan bentuk tensor masukan seperti yang diberikan.

Catatan: Panggilan ini *murni opsional*. Alokasi tensor akan terjadi secara otomatis selama eksekusi jika ada tensor masukan yang diubah ukurannya. Panggilan ini paling berguna dalam menentukan bentuk tensor keluaran apa pun sebelum mengeksekusi grafik, misalnya 

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

Catatan: Beberapa grafik memiliki keluaran berbentuk dinamis, dalam hal ini bentuk keluaran mungkin tidak sepenuhnya menyebar hingga inferensi dijalankan.

penutupan kekosongan publik ()

Rilis sumber daya yang terkait dengan instans InterpreterApi .

int publik getInputIndex ( String opName)

Mendapatkan indeks masukan berdasarkan nama operasi masukan tersebut.

Parameter
nama op

Tensor publik getInputTensor (int inputIndex)

Mengasosiasikan Tensor dengan indeks masukan yang disediakan.

Parameter
masukanIndeks

int publik getInputTensorCount ()

Mendapatkan jumlah tensor masukan.

Tensor publik getInputTensorFromSignature ( String inputName, String SignatureKey)

Mengasosiasikan Tensor dengan nama masukan dan nama metode tanda tangan yang diberikan.

PERINGATAN: Ini adalah API eksperimental dan dapat berubah.

Parameter
nama masukan Masukkan nama pada tanda tangan.
tanda tanganKey Kunci tanda tangan yang mengidentifikasi SignatureDef, bisa bernilai null jika model memiliki satu tanda tangan.
Melempar
Pengecualian Argumen Ilegal jika inputName atau signatureKey adalah null atau kosong, atau nama yang diberikan tidak valid.

public Long getLastNativeInferenceDurationNanodetik ()

Mengembalikan waktu inferensi asli.

int publik getOutputIndex ( String opName)

Mendapat indeks keluaran dengan nama operasi keluaran.

Parameter
nama op

Tensor publik getOutputTensor (int outputIndex)

Mengasosiasikan Tensor dengan indeks keluaran yang disediakan.

Catatan: Detail tensor keluaran (misalnya bentuk) mungkin tidak terisi penuh hingga inferensi dijalankan. Jika Anda memerlukan detail yang diperbarui *sebelum* menjalankan inferensi (misalnya, setelah mengubah ukuran tensor masukan, yang mungkin membuat bentuk tensor keluaran tidak valid), gunakan allocateTensors() untuk secara eksplisit memicu alokasi dan propagasi bentuk. Perhatikan bahwa, untuk grafik dengan bentuk keluaran yang bergantung pada *nilai* masukan, bentuk keluaran mungkin tidak sepenuhnya ditentukan hingga inferensi dijalankan.

Parameter
Indeks keluaran

int publik getOutputTensorCount ()

Mendapatkan jumlah Tensor keluaran.

Tensor publik getOutputTensorFromSignature ( String keluaranNama, String tanda tanganKey)

Mengasosiasikan Tensor dengan nama keluaran yang diberikan dalam metode tanda tangan tertentu.

Catatan: Detail tensor keluaran (misalnya bentuk) mungkin tidak terisi penuh hingga inferensi dijalankan. Jika Anda memerlukan detail yang diperbarui *sebelum* menjalankan inferensi (misalnya, setelah mengubah ukuran tensor masukan, yang mungkin membuat bentuk tensor keluaran tidak valid), gunakan allocateTensors() untuk secara eksplisit memicu alokasi dan propagasi bentuk. Perhatikan bahwa, untuk grafik dengan bentuk keluaran yang bergantung pada *nilai* masukan, bentuk keluaran mungkin tidak sepenuhnya ditentukan hingga inferensi dijalankan.

PERINGATAN: Ini adalah API eksperimental dan dapat berubah.

Parameter
Nama keluaran Nama keluaran di tanda tangan.
tanda tanganKey Kunci tanda tangan yang mengidentifikasi SignatureDef, bisa bernilai null jika model memiliki satu tanda tangan.
Melempar
Pengecualian Argumen Ilegal jika outputName atau signatureKey adalah nol atau kosong, atau nama yang diberikan tidak valid.

String publik[] getSignatureInputs ( String tanda tanganKey)

Mendapatkan daftar input SignatureDefs untuk metode signatureKey .

PERINGATAN: Ini adalah API eksperimental dan dapat berubah.

Parameter
tanda tanganKey

String publik[] getSignatureKeys ()

Mendapatkan daftar nama metode SignatureDef yang diekspor dan tersedia dalam model.

PERINGATAN: Ini adalah API eksperimental dan dapat berubah.

String publik[] getSignatureOutputs ( String tanda tanganKey)

Mendapatkan daftar keluaran SignatureDefs untuk metode signatureKey .

PERINGATAN: Ini adalah API eksperimental dan dapat berubah.

Parameter
tanda tanganKey

kekosongan publik resetVariableTensors ()

Lanjutan: Menyetel ulang semua tensor variabel ke nilai default.

Jika tensor variabel tidak memiliki buffer terkait, tensor tersebut akan disetel ulang ke nol.

PERINGATAN: Ini adalah API eksperimental dan dapat berubah.

public void resizeInput (int idx, int[] meredup, boolean ketat)

Mengubah ukuran masukan ke-idx dari model asli ke peredupan tertentu.

Jika `strict` bernilai True, hanya dimensi yang tidak diketahui yang dapat diubah ukurannya. Dimensi yang tidak diketahui ditunjukkan sebagai `-1` dalam array yang dikembalikan oleh `Tensor.shapeSignature()`.

Parameter
idx
meredup
ketat

public void resizeInput (int idx, int[] meredup)

Mengubah ukuran masukan ke-idx dari model asli ke peredupan tertentu.

Parameter
idx
meredup

public void run (masukan objek , keluaran objek )

Menjalankan inferensi model jika model hanya mengambil satu masukan, dan hanya menyediakan satu keluaran.

Peringatan: API lebih efisien jika Buffer (sebaiknya langsung, tetapi tidak wajib) digunakan sebagai tipe data masukan/keluaran. Harap pertimbangkan untuk menggunakan Buffer untuk memberi makan dan mengambil data primitif untuk kinerja yang lebih baik. Jenis Buffer beton berikut ini didukung:

  • ByteBuffer - kompatibel dengan semua tipe Tensor primitif yang mendasarinya.
  • FloatBuffer - kompatibel dengan Tensor float.
  • IntBuffer - kompatibel dengan Tensor int32.
  • LongBuffer - kompatibel dengan Tensor int64.
Perhatikan bahwa tipe boolean hanya didukung sebagai array, bukan Buffer , atau sebagai input skalar.

Parameter
memasukkan array atau array multidimensi, atau Buffer tipe primitif termasuk int, float, long, dan byte. Buffer adalah cara yang lebih disukai untuk meneruskan data input besar untuk tipe primitif, sedangkan tipe string memerlukan penggunaan jalur input array (multi-dimensi). Ketika Buffer digunakan, kontennya harus tetap tidak berubah sampai inferensi model selesai, dan pemanggil harus memastikan bahwa Buffer berada pada posisi baca yang sesuai. Nilai null hanya diperbolehkan jika pemanggil menggunakan Delegate yang mengizinkan interop penanganan buffer, dan buffer tersebut telah terikat ke input Tensor .
keluaran array multidimensi dari data keluaran, atau Buffer tipe primitif termasuk int, float, long, dan byte. Ketika Buffer digunakan, pemanggil harus memastikan bahwa buffer tersebut diatur pada posisi tulis yang sesuai. Nilai null diperbolehkan, dan berguna untuk kasus tertentu, misalnya, jika pemanggil menggunakan Delegate yang mengizinkan interop penanganan buffer, dan buffer tersebut telah terikat ke Tensor output (lihat juga Interpreter.Options#setAllowBufferHandleOutput(boolean) ), atau jika grafik memiliki keluaran berbentuk dinamis dan pemanggil harus menanyakan bentuk Tensor keluaran setelah inferensi dipanggil, mengambil data langsung dari tensor keluaran (melalui Tensor.asReadOnlyBuffer() ).

public void runForMultipleInputsOutputs (masukan Objek[] , Peta < Integer , Objek > keluaran)

Menjalankan inferensi model jika model mengambil banyak masukan, atau mengembalikan beberapa keluaran.

Peringatan: API lebih efisien jika Buffer (sebaiknya langsung, tetapi tidak wajib) digunakan sebagai tipe data masukan/keluaran. Harap pertimbangkan untuk menggunakan Buffer untuk memberi makan dan mengambil data primitif untuk kinerja yang lebih baik. Jenis Buffer beton berikut ini didukung:

  • ByteBuffer - kompatibel dengan semua tipe Tensor primitif yang mendasarinya.
  • FloatBuffer - kompatibel dengan Tensor float.
  • IntBuffer - kompatibel dengan Tensor int32.
  • LongBuffer - kompatibel dengan Tensor int64.
Perhatikan bahwa tipe boolean hanya didukung sebagai array, bukan Buffer , atau sebagai input skalar.

Catatan: nilai null untuk masing-masing elemen inputs dan outputs hanya diperbolehkan jika pemanggil menggunakan Delegate yang mengizinkan interop penanganan buffer, dan buffer tersebut telah terikat ke Tensor input atau output yang sesuai.

Parameter
masukan serangkaian data masukan. Inputnya harus dalam urutan yang sama dengan input model. Setiap input dapat berupa array atau array multidimensi, atau Buffer tipe primitif termasuk int, float, long, dan byte. Buffer adalah cara yang lebih disukai untuk meneruskan data masukan yang besar, sedangkan tipe string memerlukan penggunaan jalur masukan array (multidimensi). Ketika Buffer digunakan, kontennya harus tetap tidak berubah sampai inferensi model selesai, dan pemanggil harus memastikan bahwa Buffer berada pada posisi baca yang sesuai.
keluaran peta yang memetakan indeks keluaran ke array multidimensi dari data keluaran atau Buffer tipe primitif termasuk int, float, long, dan byte. Ia hanya perlu menyimpan entri agar output dapat digunakan. Ketika Buffer digunakan, pemanggil harus memastikan bahwa buffer tersebut diatur pada posisi tulis yang sesuai. Peta mungkin kosong jika salah satu pegangan buffer digunakan untuk data tensor keluaran, atau jika keluaran berbentuk dinamis dan pemanggil harus menanyakan bentuk Tensor keluaran setelah inferensi dipanggil, mengambil data langsung dari tensor keluaran ( melalui Tensor.asReadOnlyBuffer() ).

public void runSignature ( masukan Map < String , Object > , keluaran Map < String , Object > )

Sama seperti runSignature(Map, Map, String) tetapi tidak perlu meneruskan SignatureKey, dengan asumsi model memiliki satu SignatureDef. Jika model memiliki lebih dari satu SignatureDef, maka akan muncul pengecualian.

PERINGATAN: Ini adalah API eksperimental dan dapat berubah.

Parameter
masukan
keluaran

public void runSignature ( masukan Peta < String , Objek >, keluaran Peta < String , Objek >, Kunci tanda tangan String )

Menjalankan inferensi model berdasarkan SignatureDef yang disediakan melalui signatureKey .

Lihat run(Object, Object) untuk detail lebih lanjut tentang tipe data input dan output yang diperbolehkan.

PERINGATAN: Ini adalah API eksperimental dan dapat berubah.

Parameter
masukan Peta dari nama masukan di SignatureDef ke objek masukan.
keluaran Peta dari nama keluaran di SignatureDef ke data keluaran. Ini mungkin kosong jika pemanggil ingin menanyakan data Tensor langsung setelah inferensi (misalnya, jika bentuk keluarannya dinamis, atau pegangan buffer keluaran digunakan).
tanda tanganKey Kunci tanda tangan yang mengidentifikasi SignatureDef.
Melempar
Pengecualian Argumen Ilegal jika inputs bernilai nol atau kosong, jika outputs atau signatureKey bernilai nol, atau jika terjadi kesalahan saat menjalankan inferensi.

public void setDibatalkan (boolean dibatalkan)

Lanjutan: Menginterupsi inferensi di tengah panggilan ke run(Object, Object) .

Bendera pembatalan akan disetel ke true saat fungsi ini dipanggil. Penerjemah akan memeriksa tanda di antara pemanggilan Op, dan jika true , penerjemah akan menghentikan eksekusi. Penerjemah akan tetap dalam keadaan dibatalkan sampai secara eksplisit "dibatalkan" oleh setCancelled(false) .

PERINGATAN: Ini adalah API eksperimental dan dapat berubah.

Parameter
dibatalkan true untuk membatalkan inferensi dengan cara yang terbaik; false untuk melanjutkan.
Melempar
IlegalStateException jika penerjemah tidak diinisialisasi dengan opsi yang dapat dibatalkan, yang secara default tidak aktif.
Lihat juga