VNCoreMLRequest — その概要、iOS の Core ML に対する Vision リクエスト

VNCoreMLRequest とは?

VNCoreMLRequest は VNRequest のサブクラスで、iOS 11 で Vision とともに追加され、Vision のコンテキストで Core ML モデルを実行できます。Core ML モデルが必要とするすべての画像プリプロセシング（リサイズ、クロップ、正規化、色空間変換）を処理します。

VNCoreMLRequest がなければ、開発者は UIImage/CGImage を必要なサイズの MultiArray (MLMultiArray) や PixelBuffer (CVPixelBuffer) に手動で変換する必要があります。VNCoreMLRequest はこのプロセスを自動化します: VNImageRequestHandler を通じて CGImage を渡すだけで、VNCoreMLRequest がモデル入力にスケーリングします。

VNCoreMLRequest はすべての VNRequest 機能を継承します: completion handler、regionOfInterest、複数のリクエストを同時に実行できる能力、VNImageRequestHandler および VNSequenceRequestHandler のサポート。

import Vision
import CoreML

// 1. モデルをロードしてラップする
guard let model = try VNCoreMLModel(
    for: MobileNetV2().model)
else { return }

// 2. VNCoreMLRequest を作成する
let request = VNCoreMLRequest(model: model) { req, _ in
    guard let results = req.results
        as? [VNClassificationObservation]
    else { return }
    for r in results.prefix(3) {
        print("\\(r.identifier): \\(r.confidence)")
    }
}

// 3. ハンドラーを通じて実行する
let handler = VNImageRequestHandler(cgImage: image, options: [:])
try handler.perform([request])

VNCoreMLRequest は、画像 (Image Feature)、MultiArray、Double など、さまざまな入力タイプのモデルをサポートしています。画像の場合、Vision は自動的に CGImage を必要なサイズと色空間の CVPixelBuffer に変換します。他の入力データタイプの場合は、Vision なしで Core ML を直接使用すべきです。

Apple WWDC 2023 によると、VNCoreMLRequest は、画像処理に Core ML を使用するすべての iOS アプリの 40% で使用されています。これは、iOS アプリに ML モデルを統合する最も人気のある方法です。

VNCoreMLModel: Core ML モデルのラッパー

VNCoreMLModel は、Core ML モデル (MLModel) を Vision で使用できるように適応させるラッパーです。モデルの入力および出力データを Vision が理解できる形式に変換します: 画像 → CVPixelBuffer、結果 → VNObservation。

VNCoreMLModel の初期化は、モデルと Vision の互換性を確認します: モデルは入力として画像 (Image Feature) を受け入れ、分類 (MLMultiArray または Dictionary) を返す必要があります。モデルが不兼容の場合、イニシャライザーはエラーをスローします。

import Vision
import CoreML

// オプション 1: .mlmodel から (ビルド時にコンパイル)
let model1 = try VNCoreMLModel(
    for: MyVisionModel().model)

// オプション 2: .mlmodelc から (デバイス上でコンパイル)
let compiledURL = Bundle.main.url(
    forResource: "MyVisionModel",
    withExtension: "mlmodelc")!
let model2 = try VNCoreMLModel(
    for: MLModel(contentsOf: compiledURL))

VNCoreMLModel は、最初のロード後にモデルをメモリにキャッシュします。同じモデルを再読み込むと、キャッシュされたインスタンスが返され、以降のリクエストを効率化します。ただし、モデルが 100 MB \u3092超える場合、リソースが不足していると iOS がメモリからアンロードすることがあります — この場合、VNCoreMLModel が自動的にモデルを再読み込みます。

Create ML でトレーニングされたモデルの場合、VNCoreMLModel は追加設定なしで動作します。Create ML は Vision が自動認識できる正しいメタデータを付してモデルをエクスポートします — VNCoreMLModel(model:) にモデルを渡すだけです。

imageCropAndScaleOption の設定

imageCropAndScaleOption は VNCoreMLRequest の重要なプロパティで、Vision がソース画像を Core ML モデル入力サイズに変換する方法を決定します。正しいオプションを選ぶことは、分類の正確さに直接影響します。

.centerCrop は画像を中央から正方形にクロップし、その後モデル入力サイズにスケールします。中央に位置する物体でトレーニングされたモデルに適しています（大部分の ImageNet 分類器）。.scaleFill は画像をアスペクト比を保ちずに入力サイズに引き伸ばします。高速ですが、余角がみをゆがみます。.scaleFit はアスペクト比を保ちながらスケールし、端に letterbox（黒框）を追加します。

import Vision

let request = VNCoreMLRequest(model: model)

// .centerCrop — 中央の物体を対象とする場合 (デフォルト)
request.imageCropAndScaleOption = .centerCrop

// .scaleFill — 均一なテクスチャの場合 (ゆがみなし)
request.imageCropAndScaleOption = .scaleFill

// .scaleFit — 物体の比例が重要な場合
request.imageCropAndScaleOption = .scaleFit

推奨: 大多数の分類モデルには .centerCrop を使用します — 正確さとパフォーマンスの最も良いバランスが得られます。モデルがアスペクト比を保った画像（例えば、書類写真の異常検出）でトレーニングされている場合は、letterbox 付きの .scaleFit を選択します。

Apple Developer Documentation 2024 によると、imageCropAndScaleOption の間違った選択は、モデルの正確さを 15–25% 高まえます。例えば、フレームの端にある顔に対して .scaleFill を使用すると、.centerCrop で一部が切り取られたり、.scaleFill で比例がゆがんだりすることがあります。

他の VNRequest との組み合わせ

VNCoreMLRequest の主な強み は、他の VNRequest と一つの perform() コールで組み合わせられることです。これにより、パイプラインを構築できます: まず顔を検出し (VNDetectFaceRectanglesRequest)、その後カスタム Core ML モデル (VNCoreMLRequest) を通じて各顔を分類します。

VNCoreMLRequest は regionOfInterest もサポートします — この領域を設定すると、Vision は Core ML モデルに渡す前に、画像を指定された矩形にクロップします。これはパイプラインにとって重要です: 顔検出後、そのボックスを VNCoreMLRequest の regionOfInterest として渡します。

import Vision

// 1. 顔検出
let faceRequest = VNDetectFaceRectanglesRequest()

// 2. Core ML を通じた情動分類
guard let emotionModel = try VNCoreMLModel(
    for: EmotionClassifier().model)
else { return }

let emotionRequest = VNCoreMLRequest(model: emotionModel)
try handler.perform([faceRequest, emotionRequest])

// 3. 各顔に regionOfInterest を設定
for face in faceRequest.results as? [VNFaceObservation] ?? [] {
    emotionRequest.regionOfInterest = face.boundingBox
    try handler.perform([emotionRequest])
    // 情動分類結果を処理
}

制限: VNCoreMLRequest の regionOfInterest は、モデルが同じサイズと比例の画像でトレーニングされている場合に意味があります。モデルが完全な正方形入力 (224x224) を期待する場合、regionOfInterest を伴う .centerCrop が最も良い結果を得られます。

Apple ML Research によると、regionOfInterest を通じた “検出 → 分類” パイプラインは、画像全体の分類と比較して 20–30% の正確さ向上が得られます。これは、ML モデルが背景ノイズなしに関係のある領域のみを受け取るためです。

VNCoreMLRequest の結果処理

VNCoreMLRequest は、結果を VNClassificationObservation（分類モデルの場合）または VNCoreMLFeatureValueObservation（回帰および他のタイプの場合）として返します。結果のタイプは、Core ML モデルの出力データに依存します。

VNClassificationObservation には、identifier（クラス名）と confidence が含まれます。softmax 出力をもつモデルは、confidence の降順に並べたこれらの観察の配列を返します。VNCoreMLFeatureValueObservation には、任意の MLFeatureValue が含まれます — MultiArray、Double、String、Dictionary のいずれかです。

// 分類モデルの場合
if let classificationResults = request.results
    as? [VNClassificationObservation] {
    for result in classificationResults
        where result.confidence > 0.5 {
        print("\\(result.identifier): \\(result.confidence)")
    }
}

// 回帰モデルの場合 (特徴値)
if let featureResults = request.results
    as? [VNCoreMLFeatureValueObservation] {
    for result in featureResults {
        let value = result.featureValue
        print("\\(result.featureName): \\(value)")
    }
}

Confidence によるフィルタリング: Apple は、一般的な分類器では confidence < 0.3、クリティカルなアプリでは < 0.7 の結果を排除することを推奨しています。バランスのとれたデータセットでトレーニングされたモデルでは、confidence は正しい回答の確率と相関しますが、それを保証するものではありません。

VNCoreMLFeatureValueObservation.featureName は、モデルの出力レイヤー名（例えば “classLabel” または “features”）に対応します。これにより、複数の出力をもつモデルを扱うことができます — 各出力は、固有の featureName をもつ別々の観察で表現されます。

最良プラクティスとパフォーマンス

VNCoreMLRequest は Neural Engine (A12+)、GPU、CPU で動作するように最適化されています。Vision は、モデルの種類とサイズに応じて最も適したデバイスを自動選択します。しかし、適切な設定によりパフォーマンスをさらに向上させることができます。

メモリ管理

Core ML モデル は、最初の VNCoreMLRequest でメモリにロードされ、アプリがアンロードされるまでそこに留まります。200 MB を超えるモデルの場合、Apple は必要に応じてロードし、MLModel.release() を通じてアンロードすることを推奨しています。VNCoreMLModel はキャッシングを自己管理しますが、autoreleasepool を通じて制御することができます。

バッチ処理

バッチ処理のために、1つの VNCoreMLRequest を作成し、異なる VNImageRequestHandler で再利用します。画像ごとに新しい VNCoreMLRequest を作成しないでください — 繰り返しモデルロードにより処理が遅はかります。10+ 画像の処理では、リクエストの再利用により 40% までのパフォーマンス向上が得られます。

// 正しい: すべての画像に対して単一リクエスト
let batchSize = 20
let batchRequest = VNCoreMLRequest(model: model)

for i in 0..<batchSize {
    let handler = VNImageRequestHandler(
        cgImage: images[i],
        options: [:])
    try handler.perform([batchRequest])
    // 各コールで batchRequest.results を更新
}

デバイス選択: デフォルトでは、Vision は A12+ デバイス上の互換性のあるモデルに対して Neural Engine を選択します。モデルが Neural Engine をサポートしていない場合、Vision は GPU または CPU を使用します。MLModelConfiguration.computeUnits を通じて強制的にデバイスを指定できますが、Apple は自動選択を推奨しています。

Apple Performance Benchmarks 2024 によると、Neural Engine (iPhone 15 Pro) 上の VNCoreMLRequest は MobileNetV2 分類を 3–5 ms で処理し、GPU 上では 8–12 ms、CPU 上では 20–30 ms です。この違は、30+ フレーム/秒を処理するリアルタイムアプリでは重要です。