在 iOS 上使用自訂模型為圖片加上標籤

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

您可以使用機器學習套件辨識圖片中的實體並加上標籤。這個 API 支援多種自訂圖片分類模型。請參閱使用 ML Kit 自訂模型一文，瞭解模型相容性需求、如何尋找預先訓練模型，以及如何訓練模型。

整合自訂模式的方法有兩種。您可以將該模型封裝至應用程式的資產資料夾內，也可以從 Firebase 動態下載模型。下表比較了這兩個選項。

套裝模型 代管模型
模型是應用程式 APK 的一部分，因此會增加其大小。 此模型不屬於您的 APK。託管於 Firebase 機器學習。
即使 Android 裝置處於離線狀態，也可立即使用模型 隨選下載模型
不需要 Firebase 專案 必須有 Firebase 專案
您必須重新發布應用程式，才能更新模型 不必重新發布應用程式即可推送模型更新
沒有內建 A/B 測試 使用 Firebase 遠端設定輕鬆進行 A/B 版本測試

立即體驗

事前準備

  1. 在 Podfile 中加入 ML Kit 程式庫：

    如何將模型與應用程式組合在一起：

    pod 'GoogleMLKit/ImageLabelingCustom', '3.2.0'

    如要從 Firebase 動態下載模型，請新增 LinkFirebase 依附元件：

    pod 'GoogleMLKit/ImageLabelingCustom', '3.2.0'
pod 'GoogleMLKit/LinkFirebase', '3.2.0'

  2. 安裝或更新專案的 Pod 後，使用 .xcworkspace 開啟 Xcode 專案。Xcode 13.2.1 以上版本支援機器學習套件。

  3. 如要下載模型，請先將 Firebase 新增至您的 iOS 專案 (如果還沒有的話)，那麼建立模型時並不需要這麼做。

1. 載入模型

設定本機模型來源

如何將模型與應用程式整合：

  1. 將模型檔案 (通常以 .tflite 或 .lite 結尾) 複製到您的 Xcode 專案，同時務必選取 Copy bundle resources。模型檔案會包含在應用程式套件中，可供 ML Kit 使用。

  2. 建立 LocalModel 物件，指定模型檔案的路徑：

    Swift

    let localModel = LocalModel(path: localModelFilePath)

    Objective-C

    MLKLocalModel *localModel =
    [[MLKLocalModel alloc] initWithPath:localModelFilePath];

設定 Firebase 代管的模型來源

如要使用遠端託管模型，請建立 RemoteModel 物件，指定您發布模型時指派的名稱：

Swift

let firebaseModelSource = FirebaseModelSource(
    name: "your_remote_model") // The name you assigned in
                               // the Firebase console.
let remoteModel = CustomRemoteModel(remoteModelSource: firebaseModelSource)

Objective-C

MLKFirebaseModelSource *firebaseModelSource =
    [[MLKFirebaseModelSource alloc]
        initWithName:@"your_remote_model"]; // The name you assigned in
                                            // the Firebase console.
MLKCustomRemoteModel *remoteModel =
    [[MLKCustomRemoteModel alloc]
        initWithRemoteModelSource:firebaseModelSource];

然後啟動模型下載工作，指定要允許下載的條件。如果裝置上沒有模型，或有新版模型可用，則工作會以非同步方式從 Firebase 下載模型：

Swift

let downloadConditions = ModelDownloadConditions(
  allowsCellularAccess: true,
  allowsBackgroundDownloading: true
)

let downloadProgress = ModelManager.modelManager().download(
  remoteModel,
  conditions: downloadConditions
)

Objective-C

MLKModelDownloadConditions *downloadConditions =
    [[MLKModelDownloadConditions alloc] initWithAllowsCellularAccess:YES
                                         allowsBackgroundDownloading:YES];

NSProgress *downloadProgress =
    [[MLKModelManager modelManager] downloadModel:remoteModel
                                       conditions:downloadConditions];

許多應用程式均會在其初始化程式碼中啟動下載工作，但您也可以在使用模型前隨時進行這項操作。

設定圖片標籤器

設定模型來源後，請從其中一個來源建立 ImageLabeler 物件。

可用選項如下所示：

選項
confidenceThreshold

偵測到的標籤最低可信度分數。如未設定，系統會使用模型中繼資料指定的任何分類器門檻。如果模型未包含任何中繼資料，或中繼資料未指定分類器的閾值，系統會使用預設門檻值 0.0。
maxResultCount

要傳回的標籤數量上限。如未設定，系統會使用預設值 10。

如果您只有本機組合模型，只要從 LocalModel 物件建立標籤人員即可：

Swift

let options = CustomImageLabelerOptions(localModel: localModel)
options.confidenceThreshold = NSNumber(value: 0.0)
let imageLabeler = ImageLabeler.imageLabeler(options: options)

Objective-C

MLKCustomImageLabelerOptions *options =
    [[MLKCustomImageLabelerOptions alloc] initWithLocalModel:localModel];
options.confidenceThreshold = @(0.0);
MLKImageLabeler *imageLabeler =
    [MLKImageLabeler imageLabelerWithOptions:options];

如果您有遠端代管的模型，在執行模型之前，必須檢查是否已下載該模型。您可以使用模型管理員的 isModelDownloaded(remoteModel:) 方法，檢查模型下載任務的狀態。

雖然您只需要在執行標籤人員之前進行確認，但如果您同時擁有遠端託管模型和本機組合模型，那麼在對 ImageLabeler 執行個體化時，可能必須執行這項檢查：如果遠端遠端標籤建立的是已下載的模型，或是在本機模型中建立標籤人員。

Swift

var options: CustomImageLabelerOptions!
if (ModelManager.modelManager().isModelDownloaded(remoteModel)) {
  options = CustomImageLabelerOptions(remoteModel: remoteModel)
} else {
  options = CustomImageLabelerOptions(localModel: localModel)
}
options.confidenceThreshold = NSNumber(value: 0.0)
let imageLabeler = ImageLabeler.imageLabeler(options: options)

Objective-C

MLKCustomImageLabelerOptions *options;
if ([[MLKModelManager modelManager] isModelDownloaded:remoteModel]) {
  options = [[MLKCustomImageLabelerOptions alloc] initWithRemoteModel:remoteModel];
} else {
  options = [[MLKCustomImageLabelerOptions alloc] initWithLocalModel:localModel];
}
options.confidenceThreshold = @(0.0);
MLKImageLabeler *imageLabeler =
    [MLKImageLabeler imageLabelerWithOptions:options];

如果您只有遠端託管的模型，在停用模型下載之前，請先停用模型相關功能 (例如顯示為灰色或隱藏 UI 的部分)。

只要將觀察器附加至預設的通知中心，即可取得模型下載狀態。務必在觀察器區塊中使用 self 的弱參照，因為下載可能需要一些時間，而且下載作業可以在下載完成時釋出。例如：

Swift

NotificationCenter.default.addObserver(
    forName: .mlkitModelDownloadDidSucceed,
    object: nil,
    queue: nil
) { [weak self] notification in
    guard let strongSelf = self,
        let userInfo = notification.userInfo,
        let model = userInfo[ModelDownloadUserInfoKey.remoteModel.rawValue]
            as? RemoteModel,
        model.name == "your_remote_model"
        else { return }
    // The model was downloaded and is available on the device
}

NotificationCenter.default.addObserver(
    forName: .mlkitModelDownloadDidFail,
    object: nil,
    queue: nil
) { [weak self] notification in
    guard let strongSelf = self,
        let userInfo = notification.userInfo,
        let model = userInfo[ModelDownloadUserInfoKey.remoteModel.rawValue]
            as? RemoteModel
        else { return }
    let error = userInfo[ModelDownloadUserInfoKey.error.rawValue]
    // ...
}

Objective-C

__weak typeof(self) weakSelf = self;

[NSNotificationCenter.defaultCenter
    addObserverForName:MLKModelDownloadDidSucceedNotification
                object:nil
                 queue:nil
            usingBlock:^(NSNotification *_Nonnull note) {
              if (weakSelf == nil | note.userInfo == nil) {
                return;
              }
              __strong typeof(self) strongSelf = weakSelf;

              MLKRemoteModel *model = note.userInfo[MLKModelDownloadUserInfoKeyRemoteModel];
              if ([model.name isEqualToString:@"your_remote_model"]) {
                // The model was downloaded and is available on the device
              }
            }];

[NSNotificationCenter.defaultCenter
    addObserverForName:MLKModelDownloadDidFailNotification
                object:nil
                 queue:nil
            usingBlock:^(NSNotification *_Nonnull note) {
              if (weakSelf == nil | note.userInfo == nil) {
                return;
              }
              __strong typeof(self) strongSelf = weakSelf;

              NSError *error = note.userInfo[MLKModelDownloadUserInfoKeyError];
            }];

2. 準備輸入圖片

使用 UIImage 或 CMSampleBuffer 建立 VisionImage 物件。

如果您使用 UIImage，請按照下列步驟操作：

  • 使用 UIImage 建立 VisionImage 物件。請務必指定正確的 .orientation。

    Swift

    let image = VisionImage(image: UIImage)
visionImage.orientation = image.imageOrientation

    Objective-C

    MLKVisionImage *visionImage = [[MLKVisionImage alloc] initWithImage:image];
visionImage.orientation = image.imageOrientation;

如果您使用 CMSampleBuffer，請按照下列步驟操作：

  • 指定 CMSampleBuffer 中包含的圖片資料方向。

    如何取得圖片方向：

    Swift

    func imageOrientation(
  deviceOrientation: UIDeviceOrientation,
  cameraPosition: AVCaptureDevice.Position
) -> UIImage.Orientation {
  switch deviceOrientation {
  case .portrait:
    return cameraPosition == .front ? .leftMirrored : .right
  case .landscapeLeft:
    return cameraPosition == .front ? .downMirrored : .up
  case .portraitUpsideDown:
    return cameraPosition == .front ? .rightMirrored : .left
  case .landscapeRight:
    return cameraPosition == .front ? .upMirrored : .down
  case .faceDown, .faceUp, .unknown:
    return .up
  }
}

    Objective-C

    - (UIImageOrientation)
  imageOrientationFromDeviceOrientation:(UIDeviceOrientation)deviceOrientation
                         cameraPosition:(AVCaptureDevicePosition)cameraPosition {
  switch (deviceOrientation) {
    case UIDeviceOrientationPortrait:
      return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationLeftMirrored
                                                            : UIImageOrientationRight;

    case UIDeviceOrientationLandscapeLeft:
      return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationDownMirrored
                                                            : UIImageOrientationUp;
    case UIDeviceOrientationPortraitUpsideDown:
      return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationRightMirrored
                                                            : UIImageOrientationLeft;
    case UIDeviceOrientationLandscapeRight:
      return cameraPosition == AVCaptureDevicePositionFront ? UIImageOrientationUpMirrored
                                                            : UIImageOrientationDown;
    case UIDeviceOrientationUnknown:
    case UIDeviceOrientationFaceUp:
    case UIDeviceOrientationFaceDown:
      return UIImageOrientationUp;
  }
}
  • 使用 CMSampleBuffer 物件和方向建立 VisionImage 物件：

    Swift

    let image = VisionImage(buffer: sampleBuffer)
image.orientation = imageOrientation(
  deviceOrientation: UIDevice.current.orientation,
  cameraPosition: cameraPosition)

    Objective-C

     MLKVisionImage *image = [[MLKVisionImage alloc] initWithBuffer:sampleBuffer];
 image.orientation =
   [self imageOrientationFromDeviceOrientation:UIDevice.currentDevice.orientation
                                cameraPosition:cameraPosition];

3. 執行映像檔標籤器

若要為圖片中的物件加上標籤，請將 image 物件傳遞至 ImageLabeler 的 process() 方法。

非同步：

Swift

imageLabeler.process(image) { labels, error in
    guard error == nil, let labels = labels, !labels.isEmpty else {
        // Handle the error.
        return
    }
    // Show results.
}

Objective-C

[imageLabeler
    processImage:image
      completion:^(NSArray *_Nullable labels,
                   NSError *_Nullable error) {
        if (label.count == 0) {
            // Handle the error.
            return;
        }
        // Show results.
     }];

同步：

Swift

var labels: [ImageLabel]
do {
    labels = try imageLabeler.results(in: image)
} catch let error {
    // Handle the error.
    return
}
// Show results.

Objective-C

NSError *error;
NSArray *labels =
    [imageLabeler resultsInImage:image error:&error];
// Show results or handle the error.

4. 取得已加上標籤的實體相關資訊

如果圖片標籤作業成功，系統會傳回 ImageLabel 的陣列。每個 ImageLabel 都代表圖片標籤。您可以取得每個標籤的文字說明 (如果 TensorFlow Lite 模型檔案的中繼資料有提供)、可信度分數和索引。例如：

Swift

for label in labels {
  let labelText = label.text
  let confidence = label.confidence
  let index = label.index
}

Objective-C

for (MLKImageLabel *label in labels) {
  NSString *labelText = label.text;
  float confidence = label.confidence;
  NSInteger index = label.index;
}

改善即時成效的訣竅

如果您想在即時應用程式中為圖片加上標籤，請遵守下列規範，以達到最佳畫面更新率：