InterpreterApi

InterpreterApi อินเทอร์เฟซสาธารณะ
รู้จักคลาสย่อยทางอ้อม

ส่วนต่อประสานกับล่ามโมเดล TensorFlow Lite ไม่รวมวิธีการทดลอง

อินสแตนซ์ InterpreterApi สรุปโมเดล TensorFlow Lite ที่ฝึกไว้ล่วงหน้า ซึ่งมีการดำเนินการสำหรับการอนุมานโมเดล

ตัวอย่างเช่น หากโมเดลรับอินพุตเพียงตัวเดียวและส่งคืนเอาต์พุตเพียงตัวเดียว: 

try (InterpreterApi interpreter =
     new InterpreterApi.create(file_of_a_tensorflowlite_model)) {
   interpreter.run(input, 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 (InterpreterApi interpreter =
     new InterpreterApi.create(file_of_a_tensorflowlite_model)) {
   interpreter.runForMultipleInputsOutputs(inputs, map_of_indices_to_outputs);
 }

หากโมเดลใช้หรือสร้างเทนเซอร์สตริง: 

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

โปรดทราบว่ามีความแตกต่างระหว่างรูปร่าง [] และรูปร่าง[1] สำหรับเอาต์พุตเทนเซอร์สตริงสเกลาร์: 

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

ลำดับของอินพุตและเอาต์พุตถูกกำหนดเมื่อแปลงโมเดล TensorFlow เป็นโมเดล TensorFlowLite ด้วย Toco เช่นเดียวกับรูปร่างเริ่มต้นของอินพุต

เมื่ออินพุตถูกจัดเตรียมเป็นอาร์เรย์ (หลายมิติ) เทนเซอร์อินพุตที่เกี่ยวข้องจะถูกปรับขนาดโดยปริยายตามรูปร่างของอาร์เรย์นั้น เมื่อมีการระบุอินพุตเป็นประเภท Buffer จะไม่มีการปรับขนาดโดยนัย ผู้โทรต้องแน่ใจว่าขนาด Buffer ไบต์ตรงกับขนาดเทนเซอร์ที่เกี่ยวข้อง หรือปรับขนาดเทนเซอร์ก่อนผ่าน resizeInput(int, int[]) สามารถรับข้อมูลรูปร่างและประเภทของ Tensor ได้ผ่านคลาส Tensor ซึ่งมีให้ผ่าน getInputTensor(int) และ getOutputTensor(int)

คำเตือน: อินสแตนซ์ InterpreterApi ไม่ ปลอดภัยสำหรับเธรด

คำเตือน: อินสแตนซ์ InterpreterApi เป็นเจ้าของทรัพยากรที่ ต้อง ปล่อยให้เป็นอิสระโดยชัดแจ้งโดยการเรียกใช้ close()

ไลบรารี TFLite สร้างขึ้นจาก NDK API 19 อาจใช้ได้กับ Android API ระดับต่ำกว่า 19 แต่ไม่รับประกัน

คลาสที่ซ้อนกัน

ระดับ InterpreterApi.Options คลาสตัวเลือกสำหรับการควบคุมการทำงานของล่ามรันไทม์

วิธีการสาธารณะ

ความว่างเปล่าที่เป็นนามธรรม
จัดสรรเทนเซอร์ ()
อัปเดตการจัดสรรอย่างชัดเจนสำหรับเทนเซอร์ทั้งหมด หากจำเป็น
ความว่างเปล่าที่เป็นนามธรรม
ปิด ()
เผยแพร่ทรัพยากรที่เกี่ยวข้องกับอินสแตนซ์ InterpreterApi
InterpreterApi แบบคงที่
สร้าง (ตัวเลือก ไฟล์ modelFile, InterpreterApi.Options )
สร้างอินสแตนซ์ InterpreterApi โดยใช้โมเดลและตัวเลือกที่ระบุ
InterpreterApi แบบคงที่
สร้าง ( ByteBuffer byteBuffer ตัวเลือก InterpreterApi.Options )
สร้างอินสแตนซ์ InterpreterApi โดยใช้โมเดลและตัวเลือกที่ระบุ
int นามธรรม
getInputIndex ( สตริง opName)
รับดัชนีของอินพุตที่กำหนดชื่อ op ของอินพุต
เทนเซอร์ นามธรรม
getInputTensor (ดัชนีอินพุท int)
รับ Tensor ที่เชื่อมโยงกับดัชนีอินพุตที่ให้มา
int นามธรรม
getInputTensorCount ()
รับจำนวนเทนเซอร์อินพุต
นามธรรม ยาว
getLastNativeInferenceDurationNanoseconds ()
ส่งกลับเวลาการอนุมานแบบเนทีฟ
int นามธรรม
getOutputIndex ( สตริง opName)
รับดัชนีของเอาต์พุตตามชื่อ op ของเอาต์พุต
เทนเซอร์ นามธรรม
getOutputTensor (ดัชนีเอาท์พุท int)
รับ Tensor ที่เชื่อมโยงกับดัชนีผลลัพธ์ที่ให้มา
int นามธรรม
getOutputTensorCount ()
รับจำนวน Tensors เอาต์พุต
ความว่างเปล่าที่เป็นนามธรรม
resizeInput (int idx, int[] dims, บูลีนเข้มงวด)
ปรับขนาดอินพุต idx-th ของโมเดลเนทีฟเป็นค่าสลัวที่กำหนด
ความว่างเปล่าที่เป็นนามธรรม
ปรับขนาดอินพุต (int idx, int[] dims)
ปรับขนาดอินพุต idx-th ของโมเดลเนทีฟเป็นค่าสลัวที่กำหนด
ความว่างเปล่าที่เป็นนามธรรม
เรียกใช้ (อินพุต วัตถุ , เอาต์พุต วัตถุ )
รันการอนุมานโมเดลหากโมเดลใช้เพียงอินพุตเดียว และให้เอาต์พุตเพียงตัวเดียว
ความว่างเปล่าที่เป็นนามธรรม
runForMultipleInputsOutputs ( อินพุต Object[] , Map < Integer , Object > เอาต์พุต)
รันการอนุมานโมเดลหากโมเดลใช้อินพุตหลายตัว หรือส่งคืนเอาต์พุตหลายตัว

วิธีการที่สืบทอดมา

วิธีการสาธารณะ

นามธรรมสาธารณะ โมฆะ allocationTensors ()

อัปเดตการจัดสรรอย่างชัดเจนสำหรับเทนเซอร์ทั้งหมด หากจำเป็น

สิ่งนี้จะเผยแพร่รูปร่างและการจัดสรรหน่วยความจำสำหรับเทนเซอร์ที่ขึ้นต่อกันโดยใช้รูปร่างเทนเซอร์อินพุตตามที่กำหนด

หมายเหตุ: การโทรนี้ *เป็นทางเลือกเท่านั้น* การจัดสรรเทนเซอร์จะเกิดขึ้นโดยอัตโนมัติระหว่างการดำเนินการหากมีการปรับขนาดเทนเซอร์อินพุต การเรียกนี้มีประโยชน์มากที่สุดในการกำหนดรูปร่างสำหรับเอาต์พุตเทนเซอร์ใดๆ ก่อนดำเนินการกราฟ เช่น 

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

หมายเหตุ: กราฟบางกราฟมีเอาต์พุตที่มีรูปร่างแบบไดนามิก ซึ่งในกรณีนี้รูปร่างเอาต์พุตอาจไม่เผยแพร่อย่างเต็มที่จนกว่าจะดำเนินการอนุมาน

พ่น
ข้อยกเว้นของรัฐที่ผิดกฎหมาย หากไม่สามารถจัดสรรเทนเซอร์ของกราฟได้สำเร็จ

โมฆะสาธารณะ ปิด ()

เผยแพร่ทรัพยากรที่เกี่ยวข้องกับอินสแตนซ์ InterpreterApi

สร้าง InterpreterApi แบบคงที่สาธารณะ (ตัวเลือก ไฟล์ modelFile, InterpreterApi.Options )

สร้างอินสแตนซ์ InterpreterApi โดยใช้โมเดลและตัวเลือกที่ระบุ โมเดลจะถูกโหลดจากไฟล์

พารามิเตอร์
ไฟล์โมเดล ไฟล์ที่มีโมเดล TF Lite ที่ฝึกไว้ล่วงหน้า
ตัวเลือก ชุดตัวเลือกสำหรับปรับแต่งพฤติกรรมของล่าม
พ่น
IllegalArgumentException หาก modelFile ไม่เข้ารหัสโมเดล TensorFlow Lite ที่ถูกต้อง

สร้าง InterpreterApi แบบคงที่สาธารณะ (ตัวเลือก ByteBuffer byteBuffer, InterpreterApi.Options )

สร้างอินสแตนซ์ InterpreterApi โดยใช้โมเดลและตัวเลือกที่ระบุ โมเดลจะถูกอ่านจาก ByteBuffer

พารามิเตอร์
ไบต์บัฟเฟอร์ โมเดล TF Lite ที่ผ่านการฝึกอบรมล่วงหน้าในรูปแบบไบนารีซีเรียลไลซ์ ไม่ควรแก้ไข ByteBuffer หลังจากสร้างอินสแตนซ์ InterpreterApi ByteBuffer สามารถเป็นได้ทั้ง MappedByteBuffer ที่หน่วยความจำแมปไฟล์โมเดล หรือ ByteBuffer โดยตรงของ nativeOrder() ที่มีเนื้อหาไบต์ของโมเดล
ตัวเลือก ชุดตัวเลือกสำหรับปรับแต่งพฤติกรรมของล่าม
พ่น
IllegalArgumentException ถ้า byteBuffer ไม่ใช่ MappedByteBuffer หรือ ByteBuffer โดยตรงของ nativeOrder

นามธรรมสาธารณะ int getInputIndex ( สตริง opName)

รับดัชนีของอินพุตที่กำหนดชื่อ op ของอินพุต

พารามิเตอร์
opName
พ่น
IllegalArgumentException ถ้า opName ไม่ตรงกับอินพุตใดๆ ในโมเดลที่ใช้ในการเริ่มต้นล่าม

Tensor นามธรรมสาธารณะ getInputTensor (int inputIndex)

รับ Tensor ที่เชื่อมโยงกับดัชนีอินพุตที่ให้มา

พารามิเตอร์
ดัชนีอินพุต
พ่น
IllegalArgumentException หาก inputIndex เป็นค่าลบหรือไม่น้อยกว่าจำนวนอินพุตของโมเดล

นามธรรมสาธารณะ int getInputTensorCount ()

รับจำนวนเทนเซอร์อินพุต

นามธรรมสาธารณะ Long getLastNativeInferenceDurationNanoseconds ()

ส่งกลับเวลาการอนุมานแบบเนทีฟ

พ่น
IllegalArgumentException หากโมเดลไม่ได้เริ่มต้นโดยล่าม

นามธรรมสาธารณะ int getOutputIndex ( สตริง opName)

รับดัชนีของเอาต์พุตตามชื่อ op ของเอาต์พุต

พารามิเตอร์
opName
พ่น
IllegalArgumentException ถ้า opName ไม่ตรงกับเอาต์พุตใดๆ ในโมเดลที่ใช้ในการเริ่มต้นล่าม

Tensor นามธรรมสาธารณะ getOutputTensor (int outputIndex)

รับ Tensor ที่เชื่อมโยงกับดัชนีผลลัพธ์ที่ให้มา

หมายเหตุ: รายละเอียดเทนเซอร์เอาต์พุต (เช่น รูปร่าง) อาจไม่ได้รับการเติมจนเต็มจนกว่าจะมีการอนุมาน หากคุณต้องการรายละเอียดที่อัปเดต *ก่อน* เรียกใช้การอนุมาน (เช่น หลังจากปรับขนาดเทนเซอร์อินพุต ซึ่งอาจทำให้รูปร่างเทนเซอร์เอาต์พุตไม่ถูกต้อง) ให้ใช้ allocateTensors() เพื่อทริกเกอร์การจัดสรรและเผยแพร่รูปร่างอย่างชัดเจน โปรดทราบว่าสำหรับกราฟที่มีรูปร่างเอาต์พุตที่ขึ้นอยู่กับอินพุต *ค่า* รูปร่างเอาต์พุตอาจไม่ถูกกำหนดอย่างสมบูรณ์จนกว่าจะใช้การอนุมาน

พารามิเตอร์
ดัชนีเอาต์พุต
พ่น
IllegalArgumentException หาก outputIndex เป็นค่าลบหรือไม่น้อยกว่าจำนวนเอาต์พุตของโมเดล

นามธรรมสาธารณะ int getOutputTensorCount ()

รับจำนวน Tensors เอาต์พุต

นามธรรมสาธารณะเป็นโมฆะ resizeInput (int idx, int[] dims, บูลีนเข้มงวด)

ปรับขนาดอินพุต idx-th ของโมเดลเนทีฟเป็นค่าสลัวที่กำหนด

เมื่อ "เข้มงวด" เป็น True จะปรับขนาดได้เฉพาะมิติที่ไม่รู้จักเท่านั้น ขนาดที่ไม่รู้จักจะแสดงเป็น "-1" ในอาร์เรย์ที่ส่งคืนโดย "Tensor.shapeSignature()"

พารามิเตอร์
idx
สลัว
เข้มงวด
พ่น
IllegalArgumentException ถ้า idx เป็นค่าลบหรือไม่น้อยกว่าจำนวนอินพุตของโมเดล หรือหากเกิดข้อผิดพลาดเมื่อปรับขนาดอินพุต idx-th นอกจากนี้ ข้อผิดพลาดเกิดขึ้นเมื่อพยายามปรับขนาดเทนเซอร์ที่มีขนาดคงที่เมื่อ "เข้มงวด" เป็น True

โมฆะสาธารณะนามธรรม resizeInput (int idx, int[] สลัว)

ปรับขนาดอินพุต idx-th ของโมเดลเนทีฟเป็นค่าสลัวที่กำหนด

พารามิเตอร์
idx
สลัว
พ่น
IllegalArgumentException ถ้า idx เป็นค่าลบหรือไม่น้อยกว่าจำนวนอินพุตของโมเดล หรือหากเกิดข้อผิดพลาดเมื่อปรับขนาดอินพุต idx-th

การรัน โมฆะนามธรรมสาธารณะ (อินพุต วัตถุ , เอาต์พุตวัตถุ )

รันการอนุมานโมเดลหากโมเดลใช้เพียงอินพุตเดียว และให้เอาต์พุตเพียงตัวเดียว

คำเตือน: API จะมีประสิทธิภาพมากขึ้นหากใช้ Buffer (โดยตรงแต่ไม่จำเป็น) เป็นประเภทข้อมูลอินพุต/เอาต์พุต โปรดพิจารณาใช้ Buffer เพื่อป้อนและดึงข้อมูลดั้งเดิมเพื่อประสิทธิภาพที่ดีขึ้น รองรับประเภท Buffer คอนกรีตต่อไปนี้:

  • ByteBuffer - เข้ากันได้กับประเภท Tensor ดั้งเดิมพื้นฐาน
  • FloatBuffer - เข้ากันได้กับโฟลตเทนเซอร์
  • IntBuffer - เข้ากันได้กับ int32 Tensors
  • LongBuffer - เข้ากันได้กับ int64 Tensors
โปรดทราบว่าประเภทบูลีนรองรับเป็นอาร์เรย์เท่านั้น ไม่รองรับ Buffer s หรือเป็นอินพุตแบบสเกลาร์

พารามิเตอร์
ป้อนข้อมูล อาร์เรย์หรืออาร์เรย์หลายมิติ หรือ Buffer ของประเภทดั้งเดิม ได้แก่ int, float, long และ byte Buffer เป็นวิธีที่ต้องการส่งผ่านข้อมูลอินพุตขนาดใหญ่สำหรับประเภทดั้งเดิม ในขณะที่ประเภทสตริงต้องใช้เส้นทางอินพุตอาร์เรย์ (หลายมิติ) เมื่อใช้ Buffer เนื้อหาควรไม่เปลี่ยนแปลงจนกว่าการอนุมานแบบจำลองจะเสร็จสิ้น และผู้เรียกต้องแน่ใจว่า Buffer อยู่ในตำแหน่งการอ่านที่เหมาะสม อนุญาตให้ใช้ค่า null ก็ต่อเมื่อผู้โทรใช้ Delegate ที่อนุญาตให้จัดการบัฟเฟอร์ทำงานร่วมกัน และบัฟเฟอร์ดังกล่าวถูกผูกไว้กับอินพุต Tensor
เอาต์พุต อาร์เรย์หลายมิติของข้อมูลเอาต์พุต หรือ Buffer ประเภทดั้งเดิม ได้แก่ int, float, long และ byte เมื่อใช้ Buffer ผู้เรียกใช้ต้องแน่ใจว่าได้ตั้งค่าตำแหน่งการเขียนที่เหมาะสม อนุญาตให้ใช้ค่า Null และมีประโยชน์ในบางกรณี เช่น หากผู้โทรใช้ Delegate ที่อนุญาตให้จัดการบัฟเฟอร์ระหว่างกัน และบัฟเฟอร์ดังกล่าวถูกผูกไว้กับเอาต์พุต Tensor (ดูเพิ่มเติมที่ Interpreter.Options#setAllowBufferHandleOutput(boolean) ) หรือหากกราฟมีเอาต์พุตที่มีรูปร่างแบบไดนามิกและผู้เรียกใช้ต้องค้นหารูปร่าง Tensor เอาต์พุตหลังจากเรียกใช้การอนุมานแล้ว โดยดึงข้อมูลโดยตรงจากเอาต์พุตเทนเซอร์ (ผ่าน Tensor.asReadOnlyBuffer() )
พ่น
IllegalArgumentException หาก input เป็น null หรือว่างเปล่า หรือหากเกิดข้อผิดพลาดขณะเรียกใช้การอนุมาน
IllegalArgumentException (จากการทดลอง อาจมีการเปลี่ยนแปลง) หากการอนุมานถูกขัดจังหวะโดย setCancelled(true)

โมฆะนามธรรมสาธารณะ runForMultipleInputsOutputs ( Object[] inputs, Map < Integer , Object > outputs)

รันการอนุมานโมเดลหากโมเดลใช้อินพุตหลายตัว หรือส่งคืนเอาต์พุตหลายตัว

คำเตือน: API จะมีประสิทธิภาพมากขึ้นหากใช้ Buffer s (ควรเป็นแบบตรง แต่ไม่จำเป็น) เป็นประเภทข้อมูลอินพุต/เอาต์พุต โปรดพิจารณาใช้ Buffer เพื่อป้อนและดึงข้อมูลดั้งเดิมเพื่อประสิทธิภาพที่ดีขึ้น รองรับประเภท Buffer คอนกรีตต่อไปนี้:

  • ByteBuffer - เข้ากันได้กับประเภท Tensor ดั้งเดิมพื้นฐาน
  • FloatBuffer - เข้ากันได้กับโฟลตเทนเซอร์
  • IntBuffer - เข้ากันได้กับ int32 Tensors
  • LongBuffer - เข้ากันได้กับ int64 Tensors
โปรดทราบว่าประเภทบูลีนรองรับเป็นอาร์เรย์เท่านั้น ไม่รองรับ Buffer s หรือเป็นอินพุตแบบสเกลาร์

หมายเหตุ: ค่า null สำหรับอิลิเมนต์ invididual ของ inputs และ outputs จะได้รับอนุญาตก็ต่อเมื่อผู้เรียกใช้ Delegate ที่อนุญาตให้จัดการบัฟเฟอร์การทำงานร่วมกัน และบัฟเฟอร์ดังกล่าวถูกผูกไว้กับอินพุตหรือเอาต์พุต Tensor ที่สอดคล้องกัน

พารามิเตอร์
อินพุต อาร์เรย์ของข้อมูลเข้า อินพุตควรอยู่ในลำดับเดียวกับอินพุตของโมเดล แต่ละอินพุตสามารถเป็นอาร์เรย์หรืออาร์เรย์หลายมิติ หรือ Buffer ของประเภทดั้งเดิม รวมถึง int, float, long และ byte Buffer เป็นวิธีที่ต้องการส่งผ่านข้อมูลอินพุตขนาดใหญ่ ในขณะที่ประเภทสตริงต้องใช้เส้นทางอินพุตอาร์เรย์ (หลายมิติ) เมื่อใช้ Buffer เนื้อหาควรไม่เปลี่ยนแปลงจนกว่าการอนุมานแบบจำลองจะเสร็จสิ้น และผู้เรียกต้องแน่ใจว่า Buffer อยู่ในตำแหน่งการอ่านที่เหมาะสม
เอาต์พุต ดัชนีผลลัพธ์การแมปแผนที่ไปยังอาร์เรย์หลายมิติของข้อมูลเอาต์พุตหรือ Buffer ประเภทดั้งเดิม ได้แก่ int, float, long และ byte จำเป็นต้องเก็บรายการสำหรับเอาต์พุตที่จะใช้เท่านั้น เมื่อใช้ Buffer ผู้เรียกใช้ต้องแน่ใจว่าได้ตั้งค่าตำแหน่งการเขียนที่เหมาะสม แผนที่อาจว่างเปล่าสำหรับกรณีที่มีการใช้ที่จับบัฟเฟอร์สำหรับข้อมูลเอาต์พุตเทนเซอร์ หรือกรณีที่เอาต์พุตมีรูปร่างแบบไดนามิกและผู้เรียกใช้ต้องสอบถามรูปร่างเทนเซอร์ Tensor หลังจากเรียกใช้การอนุมาน โดยดึงข้อมูลโดยตรงจากเทนเซอร์เอาต์พุต ( ผ่าน Tensor.asReadOnlyBuffer() )
พ่น
IllegalArgumentException ถ้า inputs เป็น null หรือว่างเปล่า ถ้า outputs เป็น null หรือหากมีข้อผิดพลาดเกิดขึ้นเมื่อเรียกใช้การอนุมาน