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

אם המודל לוקח או מפיק רכיבי tensor של מחרוזות: 

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, ומופיעות בו צורות ברירת המחדל של הקלט.

כשמתקבלים מקורות קלט כמערכי (רב-ממדיים), אזי ה-tensor המתאימים של הקלט ישתנה באופן מרומז בהתאם לצורה של המערך. כשמזינים מקורות קלט כסוגי Buffer, לא מתבצע שינוי משתמע של הגודל; מבצע הקריאה החוזרת צריך לוודא שגודל הבייטים של Buffer תואם לזה של ה-tensor התואם, או שהוא צריך לשנות תחילה את גודל ה-tensor באמצעות resizeInput(int, int[]). ניתן לקבל מידע על הצורה והסוג של Tensor דרך המחלקה Tensor. המידע זמין דרך getInputTensor(int) ו-getOutputTensor(int).

אזהרה:InterpreterApi מופעים לא בטוחים לשרשורים.

אזהרה:המכונה InterpreterApi היא הבעלים של משאבים שחייבים לפנות באופן מפורש על ידי קריאה ל-close().

ספריית TFLite מבוססת על NDK API 19. זה עשוי לפעול ב-Android API ברמות מתחת ל-19, אבל זה לא מובטח.

מחלקות מקננות

מחלקה InterpreterApi.Options סיווג אפשרויות לשליטה בהתנהגות המתורגמנית בזמן ריצה. 

שיטות ציבוריות

מופשט בטל
allocateTensors()
מעדכנים באופן מפורש את ההקצאות לכל ה-tensors, אם יש צורך.
מופשט בטל
close()
שחרור משאבים שמשויכים למכונה InterpreterApi.
סטטי InterpreterApi
create(File modelFile, InterpreterApi.Options אפשרויות)
יוצרת מכונה של InterpreterApi באמצעות המודל והאפשרויות שצוינו.
סטטי InterpreterApi
create(ByteBuffer byteBuffer, InterpreterApi.Options אפשרויות)
יוצרת מכונה של InterpreterApi באמצעות המודל והאפשרויות שצוינו.
מופשט int
getInputIndex(מחרוזת opName)
הפונקציה מקבלת את האינדקס של הקלט בהינתן שם הפעולה של הקלט.
מופשט Tensor
getInputTensor(אינדקס קלט)
מקבלת את ה-Tensor שמשויך לאינדקס הקלט הנתון.
מופשט int
getInputTensorCount()
מקבלת את מספר רכיבי ה-tensor של הקלט.
מופשט ארוך
getLastNativeInferenceDurationNanoseconds()
מחזירה את התזמון של הסקת מסקנות מקומית.
מופשט int
getOutputIndex(מחרוזת opName)
מקבלת אינדקס של פלט בהתאם לשם הפעולה של הפלט.
מופשט Tensor
getOutputTensor(int outputIndex)
מקבלת את Tensor שמשויך לאינדקס הפלט שסופק.
מופשט int
getOutputTensorCount()
מקבלת את מספר הפלט של Tensor.
מופשט בטל
resizeInput(int idx, int[] dims, boolean strict)
שינוי הגודל של קלט idx-th של המודל המקומי לעמעום הנתונים.
מופשט בטל
resizeInput(int idx, int[] עמעום)
שינוי הגודל של קלט idx-th של המודל המקומי לעמעום הנתונים.
מופשט בטל
run(קלט אובייקט, פלט אובייקט)
מריצה הסקת מודל אם המודל מקבל רק קלט אחד ומספק פלט אחד בלבד.
מופשט בטל
runForMultipleInputsOutputs(אובייקט[], פלטי מפה<Integer, Object>)
מריצה מסקנה מהמודל אם המודל מקבל מספר מקורות קלט, או מחזיר מספר פלטים.

שיטות שעברו בירושה

שיטות ציבוריות

Public מופשט void allocateTensors ()

מעדכנים באופן מפורש את ההקצאות לכל ה-tensors, אם יש צורך.

תתבצע הפצה של צורות והקצאות זיכרון עבור tensors תלויים באמצעות צורות הקלט של ה-tensor, כפי שניתנו.

הערה: השיחה הזו *אופציונלית לחלוטין*. ההקצאה של Tensor תתבצע באופן אוטומטי במהלך הביצוע, אם הגודל של כל גורמי הקלט השתנה. הקריאה הזו שימושית ביותר לקביעת הצורות של כל רכיבי tensor לפלט לפני הרצת התרשים, למשל, 

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

הערה: לחלק מהגרפים יש פלטים בעיצוב דינמי, ובמקרה כזה ייתכן שצורת הפלט לא תופץ באופן מלא עד שתבוצע ההסקה.

קליעות
IllegalStateException אם לא ניתן להקצות את רכיבי ה-tensor של התרשים בהצלחה.

Public מופשט void סגירה ()

שחרור משאבים שמשויכים למכונה InterpreterApi.

ציבורי סטטי InterpreterApi create (File modelFile, InterpreterApi.Options אפשרויות)

יוצרת מכונה של InterpreterApi באמצעות המודל והאפשרויות שצוינו. המודל ייטען מקובץ.

פרמטרים
modelFile קובץ שמכיל דגם TF Lite שעבר אימון.
אפשרויות קבוצת אפשרויות להתאמה אישית של התנהלות המתורגמן.
קליעות
IllegalArgumentException אם הפונקציה modelFile לא מקודדת מודל TensorFlow Lite תקין.

ציבורי סטטי InterpreterApi create (ByteBuffer byteBuffer, InterpreterApi.Options options).

יוצרת מכונה של InterpreterApi באמצעות המודל והאפשרויות שצוינו. המודל ייקרא מ-ByteBuffer.

פרמטרים
byteBuffer מודל TF Lite שעבר אימון מראש, בצורה בינארית עם סריאלית. אין לשנות את ByteBuffer אחרי היצירה של מכונה InterpreterApi. השדה ByteBuffer יכול להיות MappedByteBuffer שממפה קובץ מודל למיפוי זיכרון, או ByteBuffer ישיר של origin() שמכיל את תוכן הבייטים של המודל.
אפשרויות קבוצת אפשרויות להתאמה אישית של התנהלות המתורגמן.
קליעות
IllegalArgumentException אם byteBuffer הוא לא MappedByteBuffer או ByteBuffer ישיר שלNativeOrder.

public מופשט int getInputIndex (מחרוזת opName)

הפונקציה מקבלת את האינדקס של הקלט בהינתן שם הפעולה של הקלט.

פרמטרים
opName
קליעות
IllegalArgumentException אם opName לא תואם לקלט כלשהו במודל ששימש לאתחול המתרגם.

ציבורי מופשט Tensor getInputTensor (int insertTensor)

מקבלת את ה-Tensor שמשויך לאינדקס הקלט הנתון.

פרמטרים
inputIndex
קליעות
IllegalArgumentException אם inputIndex הוא שלילי או לא קטן ממספר הקלט של המודל.

ציבורי מופשט int getInputTensorCount ()

מקבלת את מספר רכיבי ה-tensor של הקלט.

ציבורי מופשט ארוך getLastNativeInferenceDurationNanoseconds ()

מחזירה את התזמון של הסקת מסקנות מקומית.

קליעות
IllegalArgumentException אם המודל לא מופעל על ידי המתרגם.

Public מופשט int getOutputIndex (String opName)

מקבלת אינדקס של פלט בהתאם לשם הפעולה של הפלט.

פרמטרים
opName
קליעות
IllegalArgumentException אם opName לא תואם לפלט כלשהו במודל ששימש לאתחול המתרגם.

ציבורי מופשט Tensor getOutputTensor (אינדקס פלט in)

מקבלת את Tensor שמשויך לאינדקס הפלט שסופק.

הערה: ייתכן שפרטי tensor של פלט (למשל, shape) לא יאוכלסו במלואם עד לאחר ביצוע ההסקה. אם צריך לעדכן את הפרטים *לפני* הרצת ההסקה (לדוגמה, אחרי שינוי גודל של tensor של קלט, שעשוי לבטל את התוקף של צורות tensor של פלט), אפשר להשתמש ב-allocateTensors() כדי להפעיל באופן מפורש את ההקצאה ואת הפצת הצורות. שימו לב: בגרפים עם צורות פלט שתלויים ב *ערכים* של קלט, ייתכן שצורת הפלט לא תיקבע במלואה עד להפעלת הסקת הפלט.

פרמטרים
outputIndex
קליעות
IllegalArgumentException אם outputIndex הוא שלילי או לא קטן ממספר הפלטים של המודל.

Public מופשט int getOutputTensorCount ()

מקבלת את מספר הפלט של Tensor.

Public מופשט void resizeInput (int idx, int[] dims, boolean strict)

שינוי הגודל של קלט idx-th של המודל המקומי לעמעום הנתונים.

אם המדיניות 'strict' מוגדרת כ-True, אפשר לשנות את הגודל רק של מימדים לא ידועים. מאפיינים לא ידועים מסומנים כ-'1-' במערך שמוחזר על ידי 'Tensor.shapeSignature() '.

פרמטרים
idx
dims
מחמיר
קליעות
IllegalArgumentException אם idx הוא שלילי או לא קטן יותר ממספר הקלט של המודל; או אם מתרחשת שגיאה כשמשנים את הגודל של קלט ה-idx. בנוסף, השגיאה מתקבלת כשמנסים לשנות את הגודל של t e n s o עם מידות קבועות, אם 'strict' מוגדר כ-True.

Public מופשט void resizeInput (int idx, int[]

שינוי הגודל של קלט idx-th של המודל המקומי לעמעום הנתונים.

פרמטרים
idx
dims
קליעות
IllegalArgumentException אם idx הוא שלילי או לא קטן יותר ממספר הקלט של המודל; או אם מתרחשת שגיאה כשמשנים את הגודל של קלט ה-idx.

Public מופשט VAC run (קלט אובייקט, פלט אובייקט)

מריצה הסקת מודל אם המודל מקבל רק קלט אחד ומספק פלט אחד בלבד.

אזהרה: ה-API יעיל יותר אם משתמשים ב-Buffer (עדיף ישיר, אבל לא חובה) בתור סוג נתוני הקלט/פלט. כדי לשפר את הביצועים, מומלץ להשתמש ב-Buffer כדי לעדכן ולאחזר נתונים ראשוניים. ניתן להשתמש בסוגי Buffer הבטון הבאים:

  • ByteBuffer – תואם לכל סוג פרימיטיבי של Tensor.
  • FloatBuffer – תואם ל-Tensors צפים.
  • IntBuffer – תואם ל-int32 Tensors.
  • LongBuffer – תואם ל-int64 Tensors.
שימו לב שסוגים בוליאניים נתמכים רק כמערכים, ולא כערכי Buffer, או כקלט סקלרי.

פרמטרים
קלט מערך או מערך רב-ממדי, או Buffer של טיפוסים פרימיטיביים, כולל int, float, long ו-byte. Buffer היא הדרך המועדפת להעביר נתוני קלט גדולים לסוגים פרימיטיביים, ואילו סוגי מחרוזות מחייבים שימוש בנתיב הקלט של המערך (הרב-ממדי). כשמשתמשים ב-Buffer, התוכן שלו צריך להישאר ללא שינוי עד לסיום ההסקה של המודל, והמתקשר צריך לוודא שה-Buffer נמצא במיקום הקריאה המתאים. מותר להשתמש בערך null רק אם מבצע הקריאה החוזרת משתמש ב-Delegate שמאפשר יכולת פעולה הדדית של מאגר נתונים זמני, ומאגר אחסון זמני כזה קושר לקלט Tensor.
output מערך רב-ממדי של נתוני פלט, או Buffer של סוגים פרימיטיביים, כולל int, float, long ו-byte. כאשר נעשה שימוש ב-Buffer, מבצע הקריאה החוזרת חייב לוודא שהוא מוגדר למיקום הכתיבה המתאים. אפשר להשתמש בערך אפסי, והוא שימושי במקרים מסוימים, למשל, אם המתקשר משתמש ב-Delegate שמאפשר יכולת פעולה הדדית של מאגר נתונים זמני, ומאגר נתונים זמני כזה קושר לפלט Tensor (ראו גם Interpreter.Options#setAllowBufferHandleOutput(boolean)), או אם התרשים משתמש בפלט דינמי, ובפונקציית הפלט, ומבוצעת פקודת פלט שצורפה Tensor באופן ישיר לאחר ביצוע השאילתה ובוצעה שאילתות על הפלט Tensor.Tensor.asReadOnlyBuffer()
קליעות
IllegalArgumentException אם input הוא ריק או ריק, או אם מתרחשת שגיאה בהרצת ההסקה.
IllegalArgumentException (ניסיוני, עשוי להשתנות) אם ההסקה קטועה על ידי setCancelled(true).

public מופשט בטל runForMultipleInputsOutputs (קלט של אובייקט[], מפה<מספר שלם, אובייקט> פלט)

מריצה מסקנה מהמודל אם המודל מקבל מספר מקורות קלט, או מחזיר מספר פלטים.

אזהרה: ה-API יעיל יותר אם משתמשים בערכי Buffer (עדיף ישירים, אבל לא נדרשים) כסוגי נתוני הקלט/פלט. כדי לשפר את הביצועים, מומלץ להשתמש ב-Buffer כדי לעדכן ולאחזר נתונים ראשוניים. ניתן להשתמש בסוגי Buffer הבטון הבאים:

  • ByteBuffer – תואם לכל סוג פרימיטיבי של Tensor.
  • FloatBuffer – תואם ל-Tensors צפים.
  • IntBuffer – תואם ל-int32 Tensors.
  • LongBuffer – תואם ל-int64 Tensors.
שימו לב שסוגים בוליאניים נתמכים רק כמערכים, ולא כערכי Buffer, או כקלט סקלרי.

הערה: ערכי null של אלמנטים לא חלקיים של inputs ו-outputs מותרים רק אם מבצע הקריאה החוזרת משתמש ב-Delegate שמאפשר יכולת פעולה הדדית של ידית מאגר נתונים זמני, ומאגר כזה קושר לקלט או לפלט המתאימים Tensor.

פרמטרים
קלט מערך של נתוני קלט. ערכי הקלט צריכים להיות באותו סדר של ערכי הקלט במודל. כל קלט יכול להיות מערך או מערך רב ממדי, או Buffer של טיפוסים פרימיטיביים, כולל int, float, long ו-byte. Buffer היא הדרך המועדפת להעביר נתוני קלט גדולים, ואילו סוגי מחרוזות מחייבים שימוש בנתיב הקלט של המערך (הרב-ממדי). כשמשתמשים ב-Buffer, התוכן שלו צריך להישאר ללא שינוי עד המסקנות של המודל, והמתקשר צריך לוודא שה-Buffer נמצא במיקום הקריאה המתאים.
פלטים מיפוי פלט אינדקסי פלט למערכים רב ממדיים של נתוני פלט או ל-Buffer סוגים פרימיטיביים כולל int, float, long ו-byte. צריך לשמור רשומות רק כדי שניתן יהיה להשתמש בפלטים. כאשר נעשה שימוש ב-Buffer, מבצע הקריאה החוזרת חייב לוודא שהוא מוגדר למיקום הכתיבה המתאים. המפה עשויה להיות ריקה במקרים שבהם נקודות אחיזה של מאגר נתונים זמני משמשות לנתוני tensor של פלט, או מקרים שבהם הפלטים מעוצבים באופן דינמי והמתקשר צריך לשלוח שאילתה לגבי צורת הפלט Tensor לאחר הפעלת ההסקה, ומאחזרים את הנתונים ישירות מ-Tensor הפלט (באמצעות Tensor.asReadOnlyBuffer()).
קליעות
IllegalArgumentException אם inputs הוא ריק או null, אם outputs הוא null או אם מתרחשת שגיאה בזמן הרצת ההסקה.