遷移 Android 應用程式

本指南說明如何從 Android 適用的 Firebase ML Kit 遷移。

更新 Gradle 匯入項目

每個 ML Kit API 只需要一個 ML Kit SDK 依附元件。您不需要指定 firebase-ml-vision 或 firebase-ml-natural-language 等常見程式庫。ML Kit 會為依附於 Google Play 服務的程式庫使用 com.google.android.gms 命名空間。

Vision API

組合模型會隨應用程式一併交付。必須下載精簡模型。部分 API 提供套裝和精簡兩種形式，其他 API 則僅提供其中一種形式：

API組合細
文字辨識x (Beta 版)x
臉部偵測xx
條碼掃描xx
圖片標籤xx
偵測及追蹤物件x-

根據下表，更新模組 (應用程式層級) Gradle 檔案 (通常為 app/build.gradle.kts) 中 ML Kit Android 程式庫的依附元件：

套裝模型

API舊構件新構件
條碼掃描 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舊構件新構件
條碼掃描 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舊構件新構件
無需下載即可使用 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 with downloading 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

如要代管及下載自訂模型，請將模型移至 Cloud Storage，並在應用程式中新增下載邏輯，使用 LocalModel 載入模型。詳情請參閱 Firebase ML 遷移至 Cloud Storage 指南。

Natural Language API

組合模型會隨應用程式一併交付。必須下載精簡模型：

API組合細
語言 IDxx
智慧回覆xx (Beta 版)

根據下表，更新模組 (應用程式層級) Gradle 檔案 (通常為 app/build.gradle.kts) 中 ML Kit Android 程式庫的依附元件：

套裝模型

API舊構件新構件
語言 ID 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舊構件新構件
語言 ID 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.LocalModel

需要手動下載。Firebase 託管的遠端模型已淘汰。詳情請參閱「 Firebase ML 遷移至 Cloud Storage 指南」。
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() 的呼叫會替換為對功能進入點 getClient() 方法的呼叫。
  • 我們已移除 TextRecognizer 的預設例項，因為我們導入了其他程式庫，可辨識中文和韓文等其他文字。如要使用拉丁字母文字辨識模型搭配預設選項，請宣告 com.google.android.gms:play-services-mlkit-text-recognition 的依附元件，並使用 TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS)。
  • 由於我們為 ImageLabeler 和 ObjectDetector 導入了自訂模型支援，因此已移除這兩者的預設例項。舉例來說，如要在 ImageLabeling 中使用基本模型搭配預設選項，請宣告 com.google.mlkit:image-labeling 的依附元件，並在 Java 中使用 ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS)。
  • 所有控制代碼 (偵測器/掃描器/標籤器/翻譯器等) 都可以關閉。請確保不再使用這些物件時，會呼叫 close() 方法。如果您在 Fragment 或 AppCompatActivity 中使用這些項目，其中一種做法是在 Fragment 或 AppCompatActivity 上呼叫 LifecycleOwner.getLifecycle()，然後呼叫 Lifecycle.addObserver。
  • 為保持一致，Vision API 中的 processImage() 和 detectInImage() 已重新命名為 process()。
  • Natural Language API 現在使用「語言代碼」(如 BCP 47 標準所定義)，而非「語言代碼」。
  • 已移除 xxxOptions 類別中的 Getter 方法。
  • InputImage 類別中的 getBitmap() 方法 (取代 FirebaseVisionImage) 不再支援做為公開介面的一部分。請參閱 ML Kit 快速入門範例中的 BitmapUtils.java，取得從各種輸入內容轉換的點陣圖。
  • 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 服務 (又稱「精簡」) (建議) - 這可縮減應用程式大小，且模型可在應用程式之間共用。不過，開發人員必須確保模型已下載完畢，才能首次使用。
  • 使用應用程式的 APK (又稱「套件」) - 這會增加應用程式大小，但表示模型可立即使用。

這兩種實作方式略有不同，「套裝」版本比「精簡」版本多了許多改良功能。如要瞭解這些差異的詳細資訊，請參閱條碼掃描 API 指南。

臉部偵測

臉部偵測 API 的模型提供方式有兩種：

  • 透過 Google Play 服務 (又稱「精簡」) (建議) - 這可縮減應用程式大小，且模型可在應用程式之間共用。不過，開發人員必須確保模型已下載完畢，才能首次使用。
  • 使用應用程式的 APK (又稱「套件」)：這會增加應用程式下載的大小，但表示模型可立即使用。

實作方式相同。

翻譯

  • TranslateLanguage 現在會為常數使用可讀取的名稱 (例如 ENGLISH)，而非語言代碼 (EN)。此外，這些常數現在是 @StringDef，而非 @IntDef，且常數值是相符的 BCP 47 語言代碼。

AutoML Image Labeling (已淘汰)

使用 AutoML 下載圖片標籤的自訂模型已淘汰，並將於 2027 年 6 月 15 日關閉。建議您使用 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 依附元件。步驟如下：

  • 刪除應用程式模組 (應用程式層級) 目錄中的 google-services.json 設定檔，即可移除 Firebase 設定檔。
  • 在模組 (應用程式層級) Gradle 檔案 (通常為 app/build.gradle.kts) 中，將 Google 服務 Gradle 外掛程式替換為嚴格版本比對器外掛程式：

之前

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 {
  // …
}
  • 在專案 (根層級) Gradle 檔案 (build.gradle.kts) 中，將 Google 服務 Gradle 外掛程式類路徑，替換為嚴格版本比對器外掛程式的類路徑：

之前

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 應用程式。

取得協助

如有任何問題，請前往社群頁面，瞭解可與我們聯絡的管道。