Interpreter

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

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

הערה: אם אינך זקוק לגישה לאף אחת מתכונות ה-API ה"ניסיוניות" למטה, העדיפו להשתמש ב-InterpreterApi וב-InterpreterFactory במקום להשתמש ב-Interpreter ישירות.

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

אם דגם לוקח או מייצר טנסור מיתר: 

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

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

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

ספריית TFLite בנויה כנגד NDK API 19. היא עשויה לעבוד עבור רמות API של Android מתחת ל-19, אך לא מובטחת.

כיתות מקוננות

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

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

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

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

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

שיטות בירושה

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

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

מאתחל Interpreter .

פרמטרים
modelFile קובץ של דגם TF Lite מאומן מראש.
זורק
חריג טיעון לא חוקי אם modelFile אינו מקודד מודל TensorFlow Lite חוקי.

מתורגמן ציבורי (מודל קובץ File , Interpreter. אפשרויות אפשרויות)

מאתחל Interpreter ומציין אפשרויות להתאמה אישית של התנהגות המתורגמן.

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

מתורגמן ציבורי ( ByteBuffer byteBuffer)

מאתחל Interpreter עם ByteBuffer של קובץ דגם.

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

פרמטרים
byteBuffer
זורק
חריג טיעון לא חוקי אם byteBuffer אינו MappedByteBuffer וגם לא ByteBuffer ישיר של nativeOrder.

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

מאתחל Interpreter עם ByteBuffer של קובץ דגם ומערכת של Interpreter.Options מותאמות אישית.

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

פרמטרים
byteBuffer
אפשרויות
זורק
חריג טיעון לא חוקי אם byteBuffer אינו MappedByteBuffer וגם לא ByteBuffer ישיר של nativeOrder.

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

להקצות ריקנות ציבורית טנסורים ()

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

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

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

 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 .

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

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

פרמטרים
opName

Public Tensor getInputTensor (int inputIndex)

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

פרמטרים
inputIndex

public int getInputTensorCount ()

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

public Tensor getInputTensorFromSignature ( String inputName, String signatureKey)

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

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

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

public Long getLastNativeInferenceDurationNanoseconds ()

מחזיר תזמון מסקנות מקומיות.

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

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

פרמטרים
opName

Public Tensor getOutputTensor (int outputIndex)

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

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

פרמטרים
outputIndex

public int getOutputTensorCount ()

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

Public Tensor getOutputTensorFromSignature ( String outputName, String signatureKey)

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

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

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

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

public String[] getSignatureInputs (מחרוזת חתימת מפתח)

מקבל את רשימת כניסות SignatureDefs עבור מתודה signatureKey .

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

פרמטרים
מפתח חתימה

מחרוזת ציבורית[] getSignatureKeys ()

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

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

public String[] getSignatureOutputs (מחרוזת חתימת מפתח)

מקבל את רשימת הפלטים של SignatureDefs עבור מתודה signatureKey .

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

פרמטרים
מפתח חתימה

public void resetVariableTensors ()

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

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

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

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

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

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

פרמטרים
idx
מתעמעם
קַפְּדָנִי

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

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

פרמטרים
idx
מתעמעם

ריצת ריק ציבורי ( קלט אובייקט, פלט אובייקט )

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

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

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

פרמטרים
קֶלֶט מערך או מערך רב מימדי, או Buffer מסוגים פרימיטיביים כולל int, float, long ובייט. Buffer הוא הדרך המועדפת להעביר נתוני קלט גדולים עבור טיפוסים פרימיטיביים, בעוד שסוגי מחרוזות דורשים שימוש בנתיב הקלט של המערך (רב-ממדי). כאשר נעשה שימוש Buffer , התוכן שלו צריך להישאר ללא שינוי עד להסקת הדגם, ועל המתקשר לוודא Buffer נמצא במיקום הקריאה המתאים. ערך null מותר רק אם המתקשר משתמש ב- Delegate המאפשר אינטררופ של נקודת אחיזה, ומאגר כזה נקשר לקלט Tensor .
תְפוּקָה מערך רב ממדי של נתוני פלט, או Buffer מסוגים פרימיטיביים כולל int, float, long ובייט. כאשר נעשה שימוש Buffer , על המתקשר לוודא שהוא מוגדר במיקום הכתיבה המתאים. ערך null מותר, והוא שימושי במקרים מסוימים, למשל, אם המתקשר משתמש ב- Delegate המאפשר אינטראפ של טיפול במאגר, ומאגר כזה נקשר ל- Tensor הפלט (ראה גם Interpreter.Options#setAllowBufferHandleOutput(בולאני) ), או אם לגרף יש פלטים בעלי צורה דינמית ועל המתקשר לשאול את צורת Tensor לאחר הפעלת ההסקה, להביא את הנתונים ישירות מטנסור הפלט (דרך Tensor.asReadOnlyBuffer() ).

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

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

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

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

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

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

public void runSignature ( מפה < מחרוזת , אובייקט > כניסות, מפה < מחרוזת , אובייקט > פלטים)

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

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

פרמטרים
תשומות
תפוקות

public void runSignature ( Map < String , Object > inputs, Map < String , Object > outputs, String signatureKey)

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

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

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

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

סט ריק ציבורי בוטל (בוליאני בוטל)

מתקדם: קוטע מסקנות באמצע קריאה run(Object, Object) .

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

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

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