מיגרציה ל-Android

במדריך הזה מוסבר איך להפסיק להשתמש ב-ML Kit for Firebase ל-Android.

עדכון של ייבוא gradle

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

Vision APIs

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

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

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

מודלים רזים

‫AutoMLVision Edge

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

מודלים בחבילה מועברים כחלק מהאפליקציה. צריך להוריד מודלים רזים:

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

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

מודלים רזים

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

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

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

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

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

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

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

• השתנה אופן יצירת המופע של הכלי לזיהוי/סריקה/הוספת תוויות/תרגום... לכל תכונה יש עכשיו נקודת כניסה משלה. לדוגמה: BarcodeScanning, TextRecognition, ImageLabeling, Translation... קריאות לשירות Firebase‏ getInstance() מוחלפות בקריאות לשיטה 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.
• אפשר לסגור את כל ה-handle (גלאי, סורק, מתייג, מתרגם וכו'). חשוב לוודא שהמערכת קוראת לשיטה close() כשכבר לא יהיה שימוש באובייקטים האלה. אם אתם משתמשים בהם ב-Fragment או ב-AppCompatActivity, אחת הדרכים לעשות זאת היא להתקשר אל LifecycleOwner.getLifecycle() ב-Fragment או ב-AppCompatActivity, ואז להתקשר אל Lifecycle.addObserver.
• השמות של processImage() ושל detectInImage() ב-Vision APIs שונו ל-process() כדי לשמור על עקביות.
• במקום 'קוד שפה', ממשקי Natural Language API משתמשים עכשיו במונח 'תג שפה' (כפי שמוגדר בתקן BCP 47).
• הוסרו getter methods במחלקות xxxOptions.
• השיטה getBitmap() במחלקה InputImage (שמחליפה את FirebaseVisionImage) לא נתמכת יותר כחלק מהממשק הציבורי. אפשר לעיין ב-BitmapUtils.java בדוגמה למדריך למתחילים ב-ML Kit כדי לראות איך ממירים מגוון קלטים למפת סיביות.
• הוסר FirebaseVisionImageMetadata, אפשר להעביר רק מטא-נתונים של תמונה כמו width, height, rotationDegrees, format לשיטות הבנייה של InputImage.

ריכזנו כאן כמה דוגמאות לשיטות ישנות וחדשות של 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 lifecycle 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 lifecycle 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

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

ב-Barcode Scanning API, יש עכשיו שתי דרכים להעברת המודלים:

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

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

זיהוי פנים

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

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

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

תרגום

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

‫AutoML Image Labeling (יצא משימוש)

הוצאנו משימוש את האפשרות להוריד מודלים בהתאמה אישית לתוויות של תמונות באמצעות AutoML, והיא תושבת ב-15 ביוני 2027. כדאי להשתמש ב-Cloud Storage כדי לארח מודלים ולהוסיף לאפליקציה לוגיקה להורדת המודלים. פרטים נוספים זמינים במדריך להעברת נתונים מ-Firebase ML ל-Cloud Storage.

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

אם האפליקציה משתמשת בזיהוי אובייקטים עם סיווג גס, חשוב לדעת שב-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

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

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

plugins {
  id("com.android.application")
  id("com.google.gms.google-services")
}

android {
  // …
}

plugins {
  id("com.android.application")
  id("com.google.android.gms.strict-version-matcher-plugin")
}

android {
  // …
}

• מחליפים את נתיב המחלקה של הפלאגין Google Services Gradle בקובץ Gradle של הפרויקט (ברמת הבסיס) (build.gradle.kts) בנתיב של הפלאגין Strict Version Matcher:

buildscript {
  dependencies {
    // ...

    classpath("com.google.gms:google-services:4.3.3")
  }
}

buildscript {
  dependencies {
    // ...
    classpath("com.google.android.gms:strict-version-matcher-plugin:1.2.1")
  }
}

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

קבלת עזרה

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