מיגרציה ל-Android

עדכון ייבוא של ציונים

ל-SDK החדש נדרשת רק תלות אחת לכל ממשק API של ML Kit API. אין צורך לציין ספריות נפוצות כמו firebase-ml-vision או firebase-ml-natural-language. ערכת ML Kit משתמשת במרחב השמות com.google.android.gms של ספריות שתלויות ב-Google Play Services.

ממשקי Vision API

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

API	בחבילה	דק
זיהוי טקסט	x (בטא)	x
זיהוי פנים	x	x
סריקת ברקודים	x	x
הוספת תוויות לתמונות	x	x
זיהוי אובייקטים ומעקב אחריהם	x	-

מעדכנים את יחסי התלות של ספריות ML Kit ל-Android בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל app/build.gradle) בהתאם לטבלאות הבאות:

מודלים בחבילה

API	פריטי מידע ישנים	פריט מידע חדש שנוצר בתהליך פיתוח (Artifact)
סריקת ברקודים	com.google.firebase:firebase-ml-vision:24.0.1 com.google.firebase:firebase-ml-vision-barcode-model:16.0.1	com.google.mlkit:barcode-scanning:17.2.0
קו מתאר לפנים	com.google.firebase:firebase-ml-vision:24.0.1 com.google.firebase:firebase-ml-vision-face-model:19.0.0	com.google.mlkit:face-detection:16.1.6
הוספת תוויות לתמונות	com.google.firebase:firebase-ml-vision:24.0.1 com.google.firebase:firebase-ml-vision-image-label-model:19.0.0	com.google.mlkit:image-labeling:17.0.8
זיהוי אובייקטים	com.google.firebase:firebase-ml-vision:24.0.1 com.google.firebase:firebase-ml-vision-object-detection-model:19.0.3	com.google.mlkit:object-detection:17.0.1

דגמים דקים

API	פריטי מידע ישנים	פריט מידע חדש שנוצר בתהליך פיתוח (Artifact)
סריקת ברקודים	com.google.firebase:firebase-ml-vision:24.0.1	com.google.android.gms:play-services-mlkit-barcode-scanning:18.3.0
זיהוי פנים	com.google.firebase:firebase-ml-vision:24.0.1	com.google.android.gms:play-services-mlkit-face-detection:17.1.0
זיהוי טקסט	com.google.firebase:firebase-ml-vision:24.0.1	com.google.android.gms:play-services-mlkit-text-recognition:19.0.0

AutoMLVision Edge

API	פריט מידע ישן	פריט מידע חדש שנוצר בתהליך פיתוח (Artifact)
AutoML ללא הורדה	com.google.firebase:firebase-ml-vision:24.0.1 com.google.firebase:firebase-ml-vision-automl:18.0.3	com.google.mlkit:image-labeling-custom:17.0.2
AutoML עם הורדה	com.google.firebase:firebase-ml-vision:24.0.1 com.google.firebase:firebase-ml-vision-automl:18.0.3	com.google.mlkit:image-labeling-custom:17.0.2 com.google.mlkit:linkfirebase:17.0.0

ממשקי API של שפה טבעית (NLP)

מודלים בחבילה נשלחים כחלק מהאפליקציה. חובה להוריד מודלים דקים:

API	בחבילה	דק
מזהה שפה	x	x
תשובה מהירה	x	x (בטא)

מעדכנים את יחסי התלות של ספריות ML Kit ל-Android בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל app/build.gradle) בהתאם לטבלאות הבאות:

מודלים בחבילה

API	פריטי מידע ישנים	פריט מידע חדש שנוצר בתהליך פיתוח (Artifact)
מזהה שפה	com.google.firebase:firebase-ml-natural-language:22.0.0 com.google.firebase:firebase-ml-natural-language-language-id-model:20.0.7	com.google.mlkit:language-id:17.0.5
תשובה מהירה	com.google.firebase:firebase-ml-natural-language:22.0.0 com.google.firebase:firebase-ml-natural-language-smart-reply-model:20.0.7	com.google.mlkit:smart-reply:17.0.3

דגמים דקים

API	פריטי מידע ישנים	פריט מידע חדש שנוצר בתהליך פיתוח (Artifact)
מזהה שפה	com.google.firebase:firebase-ml-natural-language:22.0.0 com.google.firebase:firebase-ml-natural-language-language-id-model:20.0.7	com.google.android.gms:play-services-mlkit-language-id:17.0.0
תשובה מהירה	com.google.firebase:firebase-ml-natural-language:22.0.0 com.google.firebase:firebase-ml-natural-language-smart-reply-model:20.0.7	com.google.android.gms:play-services-mlkit-smart-reply:16.0.0-beta1

עדכון שמות הכיתות

אם הכיתה מופיעה בטבלה הזו, מבצעים את השינוי שצוין:

כיתה ישנה	כיתה חדשה
com.google.firebase.ml.common.FirebaseMLException	com.google.mlkit.common.MlKitException
com.google.firebase.ml.vision.common.FirebaseVisionImage	com.google.mlkit.vision.common.InputImage
com.google.firebase.ml.vision.barcode.FirebaseVisionBarcodeDetector	com.google.mlkit.vision.barcode.BarcodeScanner
com.google.firebase.ml.vision.labeler.FirebaseVisionImageLabel	com.google.mlkit.vision.label.ImageLabeler
com.google.firebase.ml.vision.barcode.FirebaseVisionBarcodeDetector	com.google.mlkit.vision.barcode.BarcodeScanner
com.google.firebase.ml.vision.automl.FirebaseAutoMLLocalModel	com.google.mlkit.common.model.LocalModel
com.google.firebase.ml.vision.automl.FirebaseAutoMLRemoteModel	com.google.mlkit.common.model.CustomRemoteModel
com.google.firebase.ml.vision.label.FirebaseVisionOnDeviceImageLabelerOptions	com.google.mlkit.vision.label.defaults.ImageLabelerOptions
com.google.firebase.ml.vision.label.FirebaseVisionImageLabel	com.google.mlkit.vision.label.ImageLabel
com.google.firebase.ml.vision.label.FirebaseVisionOnDeviceAutoMLImageLabelerOptions	com.google.mlkit.vision.label.custom.CustomImageLabelerOptions
com.google.firebase.ml.vision.objects.FirebaseVisionObjectDetectorOptions	com.google.mlkit.vision.objects.defaults.ObjectDetectorOptions

לכיתות אחרות, צריך לפעול לפי הכללים הבאים:

• צריך להסיר את הקידומת FirebaseVision משם הכיתה.
• צריך להסיר משם המחלקה קידומות אחרות שמתחילות בקידומת Firebase.

כמו כן, בשמות החבילות מחליפים את הקידומת com.google.firebase.ml ב-com.google.mlkit.

עדכון שמות השיטות

יש שינויים קלים בקוד:

• מזהה/סורק/מתייג/מתרגם... מופע השתנה. לכל תכונה יש עכשיו נקודת כניסה משלה. לדוגמה: BarcodeScanning, TextRecognition, ImageLabeling, Translation... קריאות לשירות Firebase getInstance() מוחלפות בקריאות ל-method getClient() של נקודת הכניסה לתכונה.
• יצירת ברירת המחדל עבור TextRecognizer הוסרה כי השקנו ספריות נוספות לזיהוי סקריפטים אחרים, כמו סינית וקוריאנית. כדי להשתמש באפשרויות ברירת המחדל עם מודל זיהוי הטקסט של סקריפט לטיני, יש להצהיר תלות ב-com.google.android.gms:play-services-mlkit-text-recognition ולהשתמש ב-TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS).
• יצירת ברירת המחדל ל-ImageLabeler ול-ObjectDetector הוסרה, מכיוון שהוספנו תמיכה במודלים מותאמים אישית בשתי התכונות האלה. לדוגמה, כדי להשתמש באפשרויות ברירת מחדל עם מודל בסיס ב-ImageLabeling, יש להצהיר על תלות ב-com.google.mlkit:image-labeling ולהשתמש ב-ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS) ב-Java.
• כל נקודות האחיזה (גלאי/סורק/מתייג/מתרגם...) ניתנות לסגירה. צריך לוודא שתתבצע קריאה לשיטה close() כשלא יהיה יותר שימוש באובייקטים האלה. אם אתם משתמשים בהם ב-Fragment או ב-AppCompatActivity, אחת הדרכים הפשוטות לעשות זאת היא לקרוא לפונקציה LifecycleOwner.getLifecycle() ב-Fragment או AppCompatActivity ולאחר מכן קוראים לפונקציה Lifecycle.addObserver
• השמות של processImage() ו-detectInImage() ב-Vision API שונו ל-process() כדי לשמור על עקביות.
• בממשקי ה-API של שפה טבעית (NLP) נעשה שימוש במונח 'תג שפה' (כפי שמוגדר בתקן BCP 47) במקום במונח language code.
• שיטות Getter ממחלקות xxxOptions הוסרו.
• כבר אין תמיכה בשיטת getBitmap() במחלקה של InsertImage(החלפה של FirebaseVisionImage) כחלק מהממשק הציבורי. ניתן לעיין ב-BitmapUtils.java בדוגמה למתחילים של ערכת ML כדי להמיר מפת סיביות למקורות קלט שונים.
• FirebaseVisionImageMetadata הוסר. אפשר פשוט להעביר מטא-נתונים של תמונה, כגון רוחב, גובה, rotationDegrees או פורמט, אל שיטות הבנייה של קלטImages.

כמה דוגמאות לשיטות ישנות וחדשות ב-Kotlin:

ישן

// Construct image labeler with base model and default options.
val imageLabeler = FirebaseVision.getInstance().onDeviceImageLabeler

// Construct object detector with base model and default options.
val objectDetector = FirebaseVision.getInstance().onDeviceObjectDetector

// Construct face detector with given options
val faceDetector = FirebaseVision.getInstance().getVisionFaceDetector(options)

// Construct image labeler with local AutoML model
val localModel =
    FirebaseAutoMLLocalModel.Builder()
      .setAssetFilePath("automl/manifest.json")
      .build()
val autoMLImageLabeler =
    FirebaseVision.getInstance()
      .getOnDeviceAutoMLImageLabeler(
          FirebaseVisionOnDeviceAutoMLImageLabelerOptions.Builder(localModel)
            .setConfidenceThreshold(0.3F)
            .build()
    )

חדש

// Construct image labeler with base model and default options.
val imageLabeler = ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS)
// Optional: add life cycle observer
lifecycle.addObserver(imageLabeler)

// Construct object detector with base model and default options.
val objectDetector = ObjectDetection.getClient(ObjectDetectorOptions.DEFAULT_OPTIONS)

// Construct face detector with given options
val faceDetector = FaceDetection.getClient(options)

// Construct image labeler with local AutoML model
val localModel =
  LocalModel.Builder()
    .setAssetManifestFilePath("automl/manifest.json")
    .build()
val autoMLImageLabeler =
  ImageLabeling.getClient(
    CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.3F).build())
  

הנה כמה דוגמאות לשיטות Java ישנות וחדשות:

ישן

// Construct image labeler with base model and default options.
FirebaseVisionImageLabeler imagelLabeler =
     FirebaseVision.getInstance().getOnDeviceImageLabeler();

// Construct object detector with base model and default options.
FirebaseVisionObjectDetector objectDetector =
     FirebaseVision.getInstance().getOnDeviceObjectDetector();

// Construct face detector with given options
FirebaseVisionFaceDetector faceDetector =
     FirebaseVision.getInstance().getVisionFaceDetector(options);

// Construct image labeler with local AutoML model
FirebaseAutoMLLocalModel localModel =
    new FirebaseAutoMLLocalModel.Builder()
      .setAssetFilePath("automl/manifest.json")
      .build();
FirebaseVisionImageLabeler autoMLImageLabeler =
    FirebaseVision.getInstance()
      .getOnDeviceAutoMLImageLabeler(
          FirebaseVisionOnDeviceAutoMLImageLabelerOptions.Builder(localModel)
            .setConfidenceThreshold(0.3F)
            .build());

חדש

// Construct image labeler with base model and default options.
ImageLabeler imageLabeler = ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS);
// Optional: add life cycle observer
getLifecycle().addObserver(imageLabeler);

// Construct object detector with base model and default options.
ObjectDetector objectDetector = ObjectDetection.getClient(ObjectDetectorOptions.DEFAULT_OPTIONS);

// Construct face detector with given options
FaceDetector faceDetector = FaceDetection.getClient(options);

// Construct image labeler with local AutoML model
LocalModel localModel =
  new LocalModel.Builder()
    .setAssetManifestFilePath("automl/manifest.json")
    .build();
ImageLabeler autoMLImageLabeler =
  ImageLabeling.getClient(
    new CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.3F).build());
  

שינויים ספציפיים ל-API

סריקת ברקודים

עבור ממשק ה-API לסריקת ברקוד, יש עכשיו שתי דרכים לספק את המודלים:

• דרך Google Play Services, שנקראת 'דק' (מומלץ) – הפעולה הזו מקטינה את גודל האפליקציה והמודל משותף בין אפליקציות. עם זאת, המפתחים יצטרכו לוודא שהמודל הורד לפני שישתמשו בו בפעם הראשונה.
• ב-APK של האפליקציה, כלומר "bundled" (חבילה), פעולה זו מגדילה את גודל האפליקציה, אבל ניתן להשתמש במודל באופן מיידי.

שתי ההטמעות שונות מעט, והגרסה ה"חבילה" כוללת מספר שיפורים לעומת הגרסה ה"דקה". פרטים על ההבדלים האלה מופיעים בהנחיות של Barcode Scanning API.

זיהוי פנים

יש שתי דרכים להעביר את המודלים של Face Detection API:

• דרך Google Play Services, שנקראת 'דק' (מומלץ) – הפעולה הזו מקטינה את גודל האפליקציה והמודל משותף בין אפליקציות. עם זאת, המפתחים יצטרכו לוודא שהמודל הורד לפני שישתמשו בו בפעם הראשונה.
• ב-APK של האפליקציה, נקרא 'bundled' - הפעולה הזו מגדילה את גודל ההורדה של האפליקציה, אבל ניתן להשתמש במודל באופן מיידי.

ההתנהגות של ההטמעות זהה.

תרגום

• עכשיו TranslateLanguage משתמש בשמות קריאים עבור הקבועים (למשל ENGLISH) במקום תגי שפה (EN). הם נקראים עכשיו גם @StringDef, במקום @IntDef, והערך הקבוע הוא תג השפה BCP 47 התואם.

• אם באפליקציה שלך נעשה שימוש בתנאי ההורדה 'מכשיר לא פעיל', חשוב לדעת שהאפשרות הזו הוסרה ואי אפשר להשתמש בה יותר. עדיין אפשר להשתמש באפשרות 'טעינת מכשיר'. אם רוצים התנהגות מורכבת יותר, אפשר לדחות את הקריאה ל-RemoteModelManager.download מאחורי לוגיקה משלכם.

תיוג תמונות של AutoML

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

אם רוצים התנהגות מורכבת יותר, אפשר לעכב את הפעולה של RemoteModelManager.download מאחורי לוגיקה משלכם.

זיהוי אובייקטים ומעקב

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

קטגוריית הסיווג מוחזרת כמופע של DetectedObject.Label במקום מספר שלם. כל הקטגוריות האפשריות למסווג הגס נכללות במחלקה PredefinedCategory.

דוגמה לקוד הישן והחדש של Kotlin:

ישן

if (object.classificationCategory == FirebaseVisionObject.CATEGORY_FOOD) {
    ...
}

חדש

if (!object.labels.isEmpty() && object.labels[0].text == PredefinedCategory.FOOD) {
    ...
}
// or
if (!object.labels.isEmpty() && object.labels[0].index == PredefinedCategory.FOOD_INDEX) {
    ...
}

הנה דוגמה לקוד Java הישן והחדש:

ישן

if (object.getClassificationCategory() == FirebaseVisionObject.CATEGORY_FOOD) {
    ...
}

חדש

if (!object.getLabels().isEmpty()
    && object.getLabels().get(0).getText().equals(PredefinedCategory.FOOD)) {
    ...
}
// or
if (!object.getLabels().isEmpty()
    && object.getLabels().get(0).getIndex() == PredefinedCategory.FOOD_INDEX) {
    ...
}

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

הסרת יחסי תלות של Firebase (אופציונלי)

השלב הזה חל רק אם התנאים הבאים מתקיימים:

• ערכת ML של Firebase היא רכיב Firebase היחיד שבו אתה משתמש.
• אתם משתמשים רק בממשקי API במכשיר.
• לא נעשה שימוש בהצגת מודלים.

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

• מסירים את קובץ התצורה של Firebase על ידי מחיקת קובץ התצורה google-services.json בספריית המודול (ברמת האפליקציה) של האפליקציה.
• מחליפים את הפלאגין של Google Services Gradle בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל מדובר בקובץ app/build.gradle) בפלאגין Strict Versioner:

לפני

apply plugin: 'com.android.application'
apply plugin: 'com.google.gms.google-services'  // Google Services plugin

android {
  // …
}

אחרי

apply plugin: 'com.android.application'
apply plugin: 'com.google.android.gms.strict-version-matcher-plugin'

android {
  // …
}

• מחליפים את ה-classpath של הפלאגין Gradle של שירותי Google בקובץ Gradle של הפרויקט (ברמת השורש) בקובץ Gradle (build.gradle) בפלאגין של Strict Versioner:

לפני

buildscript {
  dependencies {
    // ...

    classpath 'com.google.gms:google-services:4.3.3'  // Google Services plugin
  }
}

אחרי

buildscript {
  dependencies {
    // ...

    classpath 'com.google.android.gms:strict-version-matcher-plugin:1.2.1'
  }
}

מוחקים את אפליקציית Firebase במסוף Firebase בהתאם instructions באתר התמיכה של Firebase.

קבלת עזרה

נתקלתם בבעיה? כדאי להיכנס לדף הקהילה, שבו מפורטים הערוצים שבהם אפשר ליצור איתנו קשר.