מיגרציה ל-Android

במדריך הזה מוסבר איך לעבור מ-ML Kit for Firebase ל-Android.

עדכון הייבוא של Gradle

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

ממשקי API של Vision

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

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

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

מודלים דקים

AutoMLVision Edge

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

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

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

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

מודלים דקים

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

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

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

• מסירים את הקידומת 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.
• כל ה-handles (גלאי/סורק/מתייג/מתרגם...) ניתנים לסגירה. חשוב לוודא שהשיטה close() נקראת כשהאובייקטים האלה לא בשימוש יותר. אם משתמשים בהם ב-Fragment או ב-AppCompatActivity, אחת מהדרכים לעשות זאת היא להפעיל את LifecycleOwner.getLifecycle() ב-Fragment או ב-AppCompatActivity, ואז להפעיל את Lifecycle.addObserver.
• כדי לשמור על עקביות, השמות processImage() ו-detectInImage() ב-Vision API שונו ל-process().
• ממשקי ה-API של שפה טבעית משתמשים עכשיו במונח "תג שפה" (כפי שמוגדר בתקן BCP 47) במקום במונח "קוד שפה".
• הוסרו ה-methods מסוג getter במחלקות xxxOptions.
• השיטה getBitmap() במחלקה InputImage (שמחליפה את FirebaseVisionImage) לא נתמכת יותר כחלק מהממשק הציבורי. כדי להמיר מפת סיביות (bitmap) מסוגי קלט שונים, עיינו ב-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 {
  // …
}

• מחליפים את ה-classpath של הפלאגין של Google Services Gradle בקובץ Gradle של הפרויקט (ברמת הבסיס) (build.gradle.kts) ב-classpath של הפלאגין 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.

קבלת עזרה

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