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. יכול להיות שהתכונה תפעל גם ברמות API של Android מתחת ל-19, אבל הדבר לא מובטח.

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

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

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

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

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

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

ציבורי מופשט ריק allocateTensors ()

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

הפעולה הזו תפיץ צורות והקצאות זיכרון של מעבדים תלויים (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 אם לא ניתן להקצות בהצלחה את הקצוות של הגרף.

ציבורי מופשט ריק סגירה ()

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

ציבורי סטטי InterpreterApi יצירה (קובץ modelFile, אפשרויות InterpreterApi.Options)

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

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

ציבורי סטטי InterpreterApi יצירה (ByteBuffer byteBuffer, InterpreterApi.Options אפשרויות)

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

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

ציבורי מופשט INT getInputIndex (מחרוזת opName)

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

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

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

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

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

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

הפונקציה מקבלת את מספר Tensors הקלט.

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

הפונקציה מחזירה את תזמון ההסקה המקורי.

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

ציבורי מופשט INT getOutputIndex (מחרוזת opName)

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

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

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

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

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

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

ציבורי מופשט INT getOutputTensorCount ()

הפונקציה מקבלת את מספר Tensors הפלט.

ציבורי מופשט ריק resizeInput (int idx, int[] מעומעם, בוליאני קפדני)

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

אם הערך של 'strict' הוא 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 – תואם למכשירי Tensor מצופים.
  • IntBuffer – תואם למכשירי int32 Tensor.
  • LongBuffer – תואם למכשירי int64 של Tensor.
לתשומת ליבכם: סוגים בוליאניים נתמכים רק כמערכים, לא כ-Buffer או כקלט סקלרי.

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

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

מפעילה את ההֶקֵּשׁ של המודל אם המודל מקבל כמה קלטים, או מחזיר כמה פלטים.

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

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

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

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