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

您可以使用 ML Kit 辨識圖片中的實體並加上標籤。這項 API 支援各種自訂圖片分類模型。如需模型相容性規定、預先訓練模型取得位置，以及如何訓練自有模型的相關指引，請參閱「使用 ML Kit 的自訂模型」。

整合自訂模型的方法有兩種。您可以將模型放入應用程式的資產資料夾中，或從 Cloud Storage 動態下載模型。下表比較這兩個選項。

組合模式 代管模型
模型是應用程式 APK 的一部分，因此會增加 APK 大小。 模型並非 APK 的一部分，而是上傳至 Cloud Storage 後由該服務代管。我們建議使用 Cloud Storage for Firebase。
即使 Android 裝置未連上網路，也能立即使用模型 應用程式必須包含程式碼，才能視需要下載模型
不需要 Firebase 專案 需要 Firebase 專案 (如果使用 Cloud Storage for Firebase)。
您必須重新發布應用程式，才能更新模型 無須重新發布應用程式，即可推送模型更新
沒有內建的 A/B 測試 使用 Firebase 遠端設定進行 A/B 測試

立即試用

事前準備

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

    pod 'GoogleMLKit/ImageLabelingCustom', '8.0.0'

  2. 安裝或更新專案的 Pod 後，請使用 .xcworkspace 開啟 Xcode 專案。Xcode 13.2.1 以上版本支援 ML Kit。

  3. 如要使用 Cloud Storage for Firebase 下載模型，請務必將 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];

設定遠端代管模型來源

如要使用遠端託管模型，您必須使用自己的應用程式邏輯，將模型檔案下載至裝置的本機儲存空間，然後載入為本機模型。建議使用 Cloud Storage for Firebase 託管模型。如需實作詳細資料，請參閱 Firebase ML 遷移至 Cloud Storage 指南。

設定圖片標籤器

設定模型來源後，請從其中一個來源建立 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];

如果您有遠端代管模型，必須先檢查模型是否已下載，才能運作執行。

雖然您只需要在執行標籤器前確認這一點，但如果您同時有遠端代管模型和本機綁定模型，在例項化 ImageLabeler 時執行這項檢查可能很有意義：如果已下載遠端模型，請從該模型建立標籤器，否則請從本機模型建立。

Swift

// Path where your download logic saves the model
let documentDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
let localModelURL = documentDirectory.appendingPathComponent("my_remote_model.tflite")

let model: LocalModel
if FileManager.default.fileExists(atPath: localModelURL.path) {
  // Use the downloaded model
  model = LocalModel(path: localModelURL.path)
} else {
  // Fall back to bundled model
  guard let bundledModelPath = Bundle.main.path(forResource: "model", ofType: "tflite") else { return }
  model = LocalModel(path: bundledModelPath)
}

let options = CustomImageLabelerOptions(localModel: model)
let imageLabeler = ImageLabeler.imageLabeler(options: options)

Objective-C

NSString *documentsDirectory = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
NSString *localModelPath = [documentsDirectory stringByAppendingPathComponent:@"my_remote_model.tflite"];

MLKLocalModel *model;
if ([NSFileManager.defaultManager fileExistsAtPath:localModelPath]) {
  // Use the downloaded model
  model = [[MLKLocalModel alloc] initWithPath:localModelPath];
} else {
  // Fall back to bundled model
  NSString *bundledModelPath = [NSBundle.mainBundle pathForResource:@"model" ofType:@"tflite"];
  model = [[MLKLocalModel alloc] initWithPath:bundledModelPath];
}

MLKCustomImageLabelerOptions *options = [[MLKCustomImageLabelerOptions alloc] initWithLocalModel:model];
MLKImageLabeler *imageLabeler = [MLKImageLabeler imageLabelerWithOptions:options];

如果只有遠端主機代管模型，您應停用模型相關功能 (例如將部分 UI 設為灰色或隱藏)，直到確認模型已下載為止。

Swift

let documentDirectory = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
let localModelURL = documentDirectory.appendingPathComponent("my_remote_model.tflite")
if FileManager.default.fileExists(atPath: localModelURL.path) {
  // Model is already cached, initialize immediately
  self.initializeLabeler(with: localModelURL)
} else {
  // Model is not yet available, show loading UI and start download
  self.showLoadingUI()
  let storage = Storage.storage()
  let modelRef = storage.reference(forURL: "gs://YOUR_BUCKET/path/to/model.tflite")
  modelRef.write(toFile: localModelURL) { url, error in
    self.hideLoadingUI()
    if let error = error {
      // Handle download error
      self.showErrorUI()
    } else if let modelURL = url {
      // Download success, initialize labeler
      self.initializeLabeler(with: modelURL)
    }
  }
}

func initializeLabeler(with modelURL: URL) {
  let localModel = LocalModel(path: modelURL.path)
  let options = CustomImageLabelerOptions(localModel: localModel)
  self.imageLabeler = ImageLabeler.imageLabeler(options: options)
  // Enable ML-related UI features here
  self.enableMLFeatures()
}

Objective-C

NSString *documentsDirectory = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
NSString *localModelPath = [documentsDirectory stringByAppendingPathComponent:@"my_remote_model.tflite"];
NSURL *localModelURL = [NSURL fileURLWithPath:localModelPath];

if ([NSFileManager.defaultManager fileExistsAtPath:localModelPath]) {
  // Model is already cached, initialize immediately
  [self initializeLabelerWithURL:localModelURL];
} else {
  // Model is not yet available, show loading UI and start download
  [self showLoadingUI];

  FIRStorage *storage = [FIRStorage storage];
  FIRStorageReference *modelRef = [storage referenceForURL:@"gs://YOUR_BUCKET/path/to/model.tflite"];

  [modelRef writeToFile:localModelURL
             completion:^(NSURL * _Nullable URL, NSError * _Nullable error) {
               [self hideLoadingUI];
               if (error != nil) {
                 // Handle download error
                 [self showErrorUI];
               } else {
                 // Download success, initialize labeler
                 [self initializeLabelerWithURL:URL];
               }
             }];
}

- (void)initializeLabelerWithURL:(NSURL *)modelURL {
  MLKLocalModel *localModel = [[MLKLocalModel alloc] initWithPath:modelURL.path];
  MLKCustomImageLabelerOptions *options = [[MLKCustomImageLabelerOptions alloc] initWithLocalModel:localModel];
  self.imageLabeler = [MLKImageLabeler imageLabelerWithOptions:options];

  // Enable ML-related UI features here
  [self enableMLFeatures];
}

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 代表圖片中標示的項目。您可以取得每個標籤的文字說明 (如果 LiteRT 模型檔案的中繼資料提供這項資訊)、信賴分數和索引。例如：

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;
}

提升即時效能的訣竅

如要在即時應用程式中標記圖片，請遵循下列指南，盡可能提高影格速率：