מיגרציה ל-Android

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

ב-SDK החדש נדרש רק יחסי תלות אחד לכל ממשק API של ML Kit. אין צורך לציין ספריות נפוצות כמו 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	פריטי מידע ישנים שנוצרו בתהליך פיתוח (Artifacts)	ארטיפקט חדש
סריקת ברקודים	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.3.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.7
הוספת תוויות לתמונות	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.9
זיהוי אובייקטים	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.2

מודלים דקים

API	פריטי מידע ישנים שנוצרו בתהליך פיתוח (Artifacts)	ארטיפקט חדש
סריקת ברקודים	com.google.firebase:firebase-ml-vision:24.0.1	com.google.android.gms:play-services-mlkit-barcode-scanning:18.3.1
זיהוי פנים	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.1

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.3
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.3 com.google.mlkit:linkfirebase:17.0.0

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

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

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

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

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

API	פריטי מידע ישנים שנוצרו בתהליך פיתוח (Artifacts)	ארטיפקט חדש
מזהה השפה	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.6
תשובה מהירה	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.4

מודלים דקים

API	פריטי מידע ישנים שנוצרו בתהליך פיתוח (Artifacts)	ארטיפקט חדש
מזהה השפה	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… קריאות לשירות getInstance() של Firebase מוחלפות בקריאות ל-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() בממשקי ה-API של Vision שונו לשם process() לשם שמירה על עקביות.
• ב-Natural Language API נעשה עכשיו שימוש במונח 'תג שפה' (כפי שמוגדר בתקן BCP 47) במקום 'קוד שפה'.
• שיטות Getter בכיתות xxxOptions הוסרו.
• השיטה getBitmap()‏ בכיתה InputImage(החלפת FirebaseVisionImage) לא נתמכת יותר כחלק מהממשק הציבורי. כדי להמיר קובץ bitmap מקלטות שונות, אפשר לעיין ב-BitmapUtils.java בדוגמה למתחילים ב-ML Kit.
• FirebaseVisionImageMetadata הוסר, אפשר פשוט להעביר מטא-נתונים של תמונות כמו רוחב, גובה, rotationDegrees ופורמט לשיטות היצירה של InputImages.

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

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

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

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

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

זיהוי פנים

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

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

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

תרגום

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

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

AutoML Image Labeling

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

אם רוצים התנהגות מורכבת יותר, אפשר לדחות את הקריאה ל-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 (אופציונלי)

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

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

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

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

לפני

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 {
  // …
}

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

לפני

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 לפי ההוראות באתר התמיכה של Firebase.

קבלת עזרה

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