Interpreter

כיתת ביניים ציבורית מתורגמן

מחלקת נהגים להסקת מסקנות מהמודל באמצעות TensorFlow Lite.

הערה: אם אין לך צורך בגישה לאף אחת מתכונות ה-API ה"ניסיוניות" שלמטה, מומלץ להשתמש ב- intererApi וב-שפה Translationer במפעל במקום בתרגום ישיר.

Interpreter כולל מודל TensorFlow Lite שעבר אימון, שבו הפעולות מתבצעות לצורך הסקת מודל.

לדוגמה, אם המודל מקבל רק קלט אחד ומחזיר רק פלט אחד: 

try (Interpreter interpreter = new Interpreter(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 (Interpreter interpreter = new Interpreter(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 (Interpreter interpreter = new Interpreter(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).

אזהרה:Interpreter מופעים לא בטוחים לשרשורים. יש בבעלות Interpreter משאבים שחובה לשחרר אותם באופן מפורש על ידי הפעלת close()

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

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

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

בנאים ציבוריים

תרגום שיחה פעילה(File modelFile)
הפעולה של Interpreter מופעלת.
תרגום שיחה פעילה(קובץ modelFile, Interpreter.Options)
הפעלה של Interpreter ופירוט של אפשרויות להתאמה אישית של התנהגות המתורגמן.
תרגום שיחה פעילה(ByteBuffer byteBuffer)
המערכת מפעילה Interpreter עם ByteBuffer של קובץ מודל.
תרגום שיחה פעילה(ByteBuffer byteBuffer, Interpreter.Options)
הפונקציה מפעילה Interpreter עם ByteBuffer של קובץ מודל וקבוצה של Interpreter.Options בהתאמה אישית.

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

void
allocateTensors()
מעדכנים באופן מפורש את ההקצאות לכל ה-tensors, אם יש צורך.
void
close()
שחרור משאבים שמשויכים למכונה InterpreterApi.
int
getInputIndex(מחרוזת opName)
הפונקציה מקבלת את האינדקס של הקלט בהינתן שם הפעולה של הקלט.
טנסור
getInputTensor(אינדקס קלט)
מקבלת את ה-Tensor שמשויך לאינדקס הקלט הנתון.
int
getInputTensorCount()
מקבלת את מספר רכיבי ה-tensor של הקלט.
טנסור
getInputTensorFromSignature(StringinputName, String signatureKey)
הפונקציה מקבלת את Tensor שמשויך לשם הקלט ולשם שיטת החתימה שצוינו.
ארוכה
getLastNativeInferenceDurationNanoseconds()
מחזירה את התזמון של הסקת מסקנות מקומית.
int
getOutputIndex(מחרוזת opName)
מקבלת אינדקס של פלט בהתאם לשם הפעולה של הפלט.
טנסור
getOutputTensor(int outputIndex)
מקבלת את Tensor שמשויך לאינדקס הפלט שסופק.
int
getOutputTensorCount()
מקבלת את מספר הפלט של Tensor.
טנסור
getOutputTensorFromSignature(String outputName, String signatureKey)
הפונקציה מקבלת את Tensor שמשויך לשם הפלט שצוין בשיטת חתימה ספציפית.
מחרוזת[]
getSignatureInputs(String signatureKey)
מקבלת את רשימת ערכי הקלט של SignatureDefs ל-method signatureKey.
מחרוזת[]
getSignatureKeys()
מקבל את רשימת שמות השיטות המיוצאים של SignatureDef שזמינים במודל.
מחרוזת[]
getSignatureOutputs(String signatureKey)
מקבלת את רשימת הפלט של SignatureDefs לשיטה signatureKey.
void
resetVariableTensors()
מתקדם: איפוס כל רכיבי ה-tensor של המשתנים לערך ברירת המחדל.
void
resizeInput(int idx, int[] dims, boolean strict)
שינוי הגודל של קלט idx-th של המודל המקומי לעמעום הנתונים.
void
resizeInput(int idx, int[] עמעום)
שינוי הגודל של קלט idx-th של המודל המקומי לעמעום הנתונים.
void
run(קלט אובייקט, פלט אובייקט)
מריצה הסקת מודל אם המודל מקבל רק קלט אחד ומספק פלט אחד בלבד.
void
runForMultipleInputsOutputs(אובייקט[], פלטי מפה<Integer, Object>)
מריצה מסקנה מהמודל אם המודל מקבל מספר מקורות קלט, או מחזיר מספר פלטים.
void
runSignature(פלט<מחרוזת, אובייקט>, פלטי מפה<מחרוזת, אובייקט>)
זהה ל-runSignature(Map, Map, String) אבל לא מחייב העברה של signatureKey, בהנחה שלמודל יש SignatureDef אחד.
void
runSignature(פלט<מחרוזת, Object>, מפה<מחרוזת, אובייקט> פלטים, מחרוזת signatureKey)
מריצה את ההסקה של המודל על סמך SignatureDef שסופק דרך signatureKey.
void
setCancelled(בוטל) בוליאני
מתקדם: הסקת מסקנות במהלך השיחה אל run(Object, Object).

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

בנאים ציבוריים

ציבורי מתרגם (קובץ modelFile)

הפעולה של Interpreter מופעלת.

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

ציבורי מתרגם (קובץ modelFile, Interpreter.Options אפשרויות)

הפעלה של Interpreter ופירוט של אפשרויות להתאמה אישית של התנהגות המתורגמן.

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

ציבורי תרגום שיחה פעילה (ByteBuffer byteBuffer)

המערכת מפעילה Interpreter עם ByteBuffer של קובץ מודל.

אין לשנות את ByteBuffer לאחר היצירה של Interpreter. השדה ByteBuffer יכול להיות MappedByteBuffer שמשמש למיפוי זיכרון של קובץ מודל, או רכיב ByteBuffer ישיר של השדהNativeOrder() שמכיל את תוכן הבייטים של המודל.

פרמטרים
byteBuffer
קליעות
IllegalArgumentException אם byteBuffer הוא לא MappedByteBuffer או ByteBuffer ישיר שלNativeOrder.

ציבורי מתרגם (ByteBuffer byteBuffer, Interpreter.Options אפשרויות)

הפונקציה מפעילה Interpreter עם ByteBuffer של קובץ מודל וקבוצה של Interpreter.Options בהתאמה אישית.

אין לשנות את ByteBuffer לאחר היצירה של Interpreter. השדה ByteBuffer יכול להיות MappedByteBuffer שמשמש למיפוי זיכרון של קובץ מודל, או רכיב ByteBuffer ישיר של origin() שמכיל את תוכן הבייטים של המודל.

פרמטרים
byteBuffer
אפשרויות
קליעות
IllegalArgumentException אם byteBuffer הוא לא MappedByteBuffer או ByteBuffer ישיר שלNativeOrder.

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

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

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

public void סגירה ()

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

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

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

פרמטרים
opName

Public Tensor getInputTensor (אינדקס קלט פנימי)

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

פרמטרים
inputIndex

Public int getInputTensorCount ()

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

Public Tensor getInputTensorFromSignature (StringinputName, String signatureKey)

הפונקציה מקבלת את Tensor שמשויך לשם הקלט ולשם שיטת החתימה שצוינו.

אזהרה: זהו API ניסיוני ועשוי להשתנות.

פרמטרים
inputName יש להזין שם בחתימה.
signatureKey מפתח חתימה שמזהה את ה-SignatureDef יכול להיות null אם למודל יש חתימה אחת.
קליעות
IllegalArgumentException אם inputName או signatureKey ריקים, או אם צוין שם לא חוקי.

Public ארוך getLastNativeInferenceDurationNanoseconds ()

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

public int getOutputIndex (String opName)

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

פרמטרים
opName

Public Tensor getOutputTensor (אינדקס פלט פנימי)

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

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

פרמטרים
outputIndex

Public int getOutputTensorCount ()

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

Public Tensor getOutputTensorFromSignature (StringoutputName, String signatureKey)

הפונקציה מקבלת את Tensor שמשויך לשם הפלט שצוין בשיטת חתימה ספציפית.

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

אזהרה: זהו API ניסיוני ועשוי להשתנות.

פרמטרים
outputName שם הפלט בחתימה.
signatureKey מפתח חתימה שמזהה את ה-SignatureDef יכול להיות null אם למודל יש חתימה אחת.
קליעות
IllegalArgumentException אם outputName או signatureKey ריקים, או אם צוין שם לא חוקי.

Public String[] getSignatureInputs (String signatureKey)

מקבלת את רשימת ערכי הקלט של SignatureDefs ל-method signatureKey.

אזהרה: זהו API ניסיוני ועשוי להשתנות.

פרמטרים
signatureKey

Public String[] getSignatureKeys ()

מקבל את רשימת שמות השיטות המיוצאים של SignatureDef שזמינים במודל.

אזהרה: זהו API ניסיוני ועשוי להשתנות.

Public String[] getSignatureOutputs (String signatureKey)

מקבלת את רשימת הפלט של SignatureDefs לשיטה signatureKey.

אזהרה: זהו API ניסיוני ועשוי להשתנות.

פרמטרים
signatureKey

public void resetVariableTensors ()

מתקדם: איפוס כל רכיבי ה-tensor של המשתנים לערך ברירת המחדל.

אם למשתנה tensor לא משויך מאגר נתונים זמני, הוא יתאפס.

אזהרה: זהו API ניסיוני ועשוי להשתנות.

Public void resizeInput (int idx, int[] dims, boolean strict)

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

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

פרמטרים
idx
dims
מחמיר

Public void resizeInput (int idx, int[] עמעום)

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

פרמטרים
idx
dims

Public void 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()

Public void 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()).

Public בטל runSignature (מפה<מחרוזת, אובייקט> קלט, מפה<מחרוזת, אובייקט> פלטים

זהה ל-runSignature(Map, Map, String) אבל לא מחייב העברה של signatureKey, בהנחה שלמודל יש SignatureDef אחד. אם למודל יש יותר מ-SignatureDef אחד, החריגה תופיע.

אזהרה: זהו API ניסיוני ועשוי להשתנות.

פרמטרים
קלט
פלטים

Public בטל runSignature (מפה<מחרוזת, קלט אובייקט>, מפה<מחרוזת, פלט> פלט, חתימת מחרוזות

מריצה את ההסקה של המודל על סמך SignatureDef שסופק דרך signatureKey.

בכתובת run(Object, Object) אפשר לקרוא פרטים נוספים על הסוגים המותרים של נתוני קלט ופלט.

אזהרה: זהו API ניסיוני ועשוי להשתנות.

פרמטרים
קלט מפה משם הקלט ב-SignatureDef לאובייקט קלט.
פלטים מפה משם הפלט ב-SignatureDef לנתוני פלט. השדה הזה יכול להיות ריק אם מבצע הקריאה החוזרת רוצה להריץ שאילתה על הנתונים של Tensor ישירות לאחר ההסקה (למשל, אם צורת הפלט היא דינמית או אם נעשה שימוש בנקודות אחיזה של מאגר הנתונים הזמני).
signatureKey מפתח חתימה המזהה את SignatureDef.
קליעות
IllegalArgumentException אם inputs ריק או ריק, אם outputs או signatureKey הם null, או אם מתרחשת שגיאה בהרצת ההסקה.

public void setCancelled (boolean cancelled)

מתקדם: הסקת מסקנות במהלך השיחה אל run(Object, Object).

סימון הביטול יוגדר כ-True כשמתבצעת קריאה לפונקציה הזו. המתורגמן יבדוק את הדגל בין הפעלות של פעולות הפעלה. אם הערך הוא true, התרגום יפסיק את הביצוע. המתורגמן יישאר במצב 'מבוטל' עד ש'לא יבוטל' באופן מפורש על ידי setCancelled(false).

אזהרה: זהו API ניסיוני ועשוי להשתנות.

פרמטרים
בוטלה true כדי לבטל את ההסקה בדרך הטובה ביותר; false כדי להמשיך.
קליעות
IllegalStateException אם המתרגם או התרגום לא מאותחלים באמצעות האפשרות ניתנת לביטול, שהיא מושבתת כברירת מחדל.
ראו בנוסף