core-ml

Core ML スキル

Apple プラットフォームアプリに機械学習を統合するための、アドバイザリー、ジェネレーター、ワークフローを組み合わせたスキルです。Core ML モデルの統合、Vision フレームワークによる画像分析、NaturalLanguage フレームワークによるテキスト処理、Create ML によるトレーニング、デバイス上でのモデル最適化を扱います。

このスキルが有効になるケース

ユーザーが次のことを行いたい場合に、このスキルを使用します。

• アプリに機械学習機能を追加したい
• Core ML モデル（.mlmodel）を Xcode プロジェクトに統合したい
• Vision フレームワークを使って画像を分析したい（顔認識、テキスト認識、身体のポーズ、物体検出）
• NaturalLanguage フレームワークを使ってテキストを処理したい（感情分析、エンティティ、言語検出）
• Create ML でカスタムモデルをトレーニングしたい
• デバイス上で使用するモデルを最適化したい（量子化、枝刈り、パレタイゼーション）
• Core ML と Foundation Models（Apple Intelligence）のどちらを選ぶべきか知りたい
• 画像分類、物体検出、音声分類、表形式データの予測について質問している
• カメラ映像をリアルタイムで機械学習処理したい

選択ガイド：Core ML と Foundation Models

コードを生成する前に、適切なフレームワークを判断します。

次の場合は Foundation Models（Apple Intelligence）を使用します。

• 汎用的なテキスト生成、要約、会話型 AI が必要な場合
• 対象が iOS 26 以降／macOS 26 以降の場合（Foundation Models には Apple Silicon と最新の OS が必要です）
• 自由形式の言語理解または生成を行うタスクの場合
• 自然言語から @Generable の構造化出力を得たい場合
• 実装については apple-intelligence/foundation-models/ スキルを参照してください

次の場合は Core ML を使用します。

• 特化型の機械学習が必要な場合：画像分類、物体検出、音声分類、カスタムの回帰／分類
• トレーニング済みモデル（.mlmodel、.mlpackage）がある場合、またはトレーニングを予定している場合
• 幅広いデバイスをサポートする必要がある場合（iOS 14 以降／macOS 11 以降）
• ドメイン固有の予測が必要なタスクの場合（医用画像、製品認識、カスタム NLP）
• Neural Engine または GPU で高性能な推論が必要な場合

次の場合は Vision フレームワークを使用します（カスタムモデルは不要です）。

• Apple の組み込みモデルを使った画像分類
• 顔検出と顔のランドマーク分析
• VNRecognizeTextRequest によるテキスト認識（OCR）
• 身体と手のポーズ検出
• バーコードと QR コードのスキャン
• 画像の類似性と顕著性の検出
• 水平線検出、矩形検出

次の場合は NaturalLanguage フレームワークを使用します（カスタムモデルは不要です）。

• テキストの感情分析
• 言語の識別
• トークン化（単語、文、段落の境界）
• 固有表現認識（人、場所、組織）
• 類似性比較のための単語と文の埋め込み
• レンマ化と品詞タグ付け

生成前の確認

1. プロジェクトコンテキストの検出

• デプロイメントターゲットを確認します（Core ML は iOS 11 以降／macOS 10.13 以降、Vision は iOS 11 以降、NaturalLanguage は iOS 12 以降が必要です）
• 既存の機械学習コードまたはモデルを確認します
• プロジェクト構成とソースファイルの場所を特定します
• SwiftUI か UIKit／AppKit かを判断します

2. 競合の検出

既存の機械学習統合を検索します。

Glob: **/*Model*.swift, **/*Classifier*.swift, **/*Predictor*.swift, **/*.mlmodel, **/*.mlmodelc, **/*.mlpackage
Grep: "import CoreML" or "import Vision" or "import NaturalLanguage"

見つかった場合は、ユーザーに次の内容を確認します。

• 既存の機械学習設定を拡張しますか？
• 新しい実装に置き換えますか？
• モデル／機能を追加しますか？

設定に関する質問

AskUserQuestion を使ってユーザーに尋ねます。

1. どの ML 機能が必要ですか？

   • 画像分類（写真内のオブジェクトを識別）
   • オブジェクト検出（バウンディングボックスでオブジェクトの位置を特定）
   • テキスト分析（感情、エンティティ、言語）
   • カスタム Core ML モデルの統合
   • Vision フレームワーク（OCR、顔、ポーズ）
   • 音声分類
   • 表形式データの予測

2. トレーニング済みモデルをお持ちですか？ それともトレーニングが必要ですか？

   • .mlmodel / .mlpackage ファイルを持っています
   • Create ML でトレーニングしたいです
   • Apple の組み込みモデル（Vision / NaturalLanguage）を使いたいです

3. パフォーマンス要件はありますか？

   • リアルタイム（カメラ映像、予測ごとに 33ms 未満）
   • インタラクティブ（ユーザーが開始し、500ms 未満なら許容）
   • バックグラウンド処理（バッチ、レイテンシは重要ではない）

Core ML モデルの統合

Xcode へのモデルの追加

1. .mlmodel または .mlpackage を Xcode のプロジェクトナビゲーターにドラッグします
2. Xcode がモデル名を使って Swift クラスを自動生成します
3. 生成されたクラスは、型安全な入力／出力インターフェイスを提供します
4. Xcode はビルド時に .mlmodelc にコンパイルします（デバイス向けに最適化されます）

モデルの読み込み

// Option 1: Auto-generated class (simplest)
let model = try MyImageClassifier(configuration: MLModelConfiguration())

// Option 2: Generic MLModel loading (flexible)
let url = Bundle.main.url(forResource: "MyModel", withExtension: "mlmodelc")!
let config = MLModelConfiguration()
config.computeUnits = .all  // CPU + GPU + Neural Engine
let model = try MLModel(contentsOf: url, configuration: config)

// Option 3: Async loading (recommended for large models)
let model = try await MLModel.load(contentsOf: url, configuration: config)

予測の実行

// Type-safe prediction with auto-generated class
let input = MyImageClassifierInput(image: pixelBuffer)
let output = try model.prediction(input: input)
print(output.classLabel)       // "cat"
print(output.classLabelProbs)  // ["cat": 0.95, "dog": 0.04, ...]

// Batch predictions
let batch = MLArrayBatchProvider(array: inputs)
let results = try model.predictions(from: batch)

Create ML トレーニングの概要

画像分類

• 最小数：カテゴリごとに 10 枚。推奨数：カテゴリごとに 40 枚以上
• カテゴリ名を付けたフォルダーに画像を整理します
• JPEG、PNG、HEIC 形式に対応しています
• データ拡張が自動的に適用されます（回転、反転、クロップ）
• Apple のベースモデルによる転移学習

テキスト分類

• トレーニングデータ：ラベル付きのテキストサンプル（CSV または JSON）
• 使用例：感情分析、スパム検出、トピック分類、インテント認識
• クラスごとに最低 10 サンプル。精度を高めるには 100 サンプル以上を推奨します

表形式データの分類／回帰

• CSV または JSON 形式の構造化データ
• 特徴量エンジニアリングを自動で実行
• 対応モデル：Boosted Tree、Random Forest、Linear Regression、Decision Tree

音声分類

• カテゴリごとに整理された音声ファイル
• 環境音、音声検出、音楽ジャンル
• カテゴリごとに最低 10 サンプル、各サンプルは 15 秒以上

オブジェクト検出

• バウンディングボックスのアノテーションを付けた画像（JSON 形式）
• バウンディングボックス、クラスラベル、信頼度を出力します
• クラスごとにアノテーション付き画像が最低 30 枚。300 枚以上を推奨します

トレーニング方法

• Xcode Create ML App：視覚的なインターフェイス、ドラッグ＆ドロップ、コード不要
• CreateML Framework：Swift Playgrounds または macOS アプリでプログラムからトレーニング
• coremltools (Python)：TensorFlow、PyTorch、ONNX のモデルを Core ML 形式に変換

Vision フレームワークの機能

機能	リクエストクラス	カスタムモデルが必要か
画像分類	VNClassifyImageRequest	いいえ（組み込み）
オブジェクト検出	VNDetectObjectsRequest（カスタムモデル）	はい
顔検出	VNDetectFaceRectanglesRequest	いいえ
顔のランドマーク検出	VNDetectFaceLandmarksRequest	いいえ
テキスト認識（OCR）	VNRecognizeTextRequest	いいえ
ボディポーズ	VNDetectHumanBodyPoseRequest	いいえ
手のポーズ	VNDetectHumanHandPoseRequest	いいえ
バーコード検出	VNDetectBarcodesRequest	いいえ
画像顕著性	VNGenerateAttentionBasedSaliencyImageRequest	いいえ
水平線検出	VNDetectHorizonRequest	いいえ
長方形検出	VNDetectRectanglesRequest	いいえ
画像の類似性	VNGenerateImageFeaturePrintRequest	いいえ

Vision リクエストのパイプライン

// Multiple requests on the same image
let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
try handler.perform([
    textRequest,     // OCR
    faceRequest,     // Face detection
    barcodeRequest   // Barcode scanning
])
// Each request's results are populated independently

NaturalLanguage フレームワーク

感情分析

let tagger = NLTagger(tagSchemes: [.sentimentScore])
tagger.string = "This app is amazing!"
let (tag, _) = tagger.tag(at: text.startIndex, unit: .paragraph, scheme: .sentimentScore)
// tag?.rawValue == "0.9" (positive)

言語検出

let language = NLLanguageRecognizer.dominantLanguage(for: "Bonjour le monde")
// language == .french

トークン化

let tokenizer = NLTokenizer(unit: .word)
tokenizer.string = "Hello, world!"
tokenizer.enumerateTokens(in: text.startIndex..<text.endIndex) { range, _ in
    print(text[range])  // "Hello" then "world"
    return true
}

固有表現認識

let tagger = NLTagger(tagSchemes: [.nameType])
tagger.string = "Tim Cook visited Apple Park in Cupertino."
tagger.enumerateTags(in: text.startIndex..<text.endIndex, unit: .word, scheme: .nameType) { tag, range in
    if let tag, tag != .other {
        print("\(text[range]): \(tag.rawValue)")
        // "Tim": PersonalName, "Cook": PersonalName
        // "Apple Park": OrganizationName, "Cupertino": PlaceName
    }
    return true
}

モデルの最適化

量子化（coremltools Python）

数値精度を下げてモデルサイズを縮小します。

• Float32 から Float16：サイズを約 50% 縮小し、精度の低下は最小限
• Float16 から Int8：さらに約 50% 縮小。精度を慎重にテストしてください

import coremltools as ct
from coremltools.models.neural_network import quantization_utils

model = ct.models.MLModel("MyModel.mlmodel")

# Float16 quantization (safe default)
model_fp16 = quantization_utils.quantize_weights(model, nbits=16)
model_fp16.save("MyModel_fp16.mlmodel")

# Int8 quantization (aggressive, test accuracy)
model_int8 = quantization_utils.quantize_weights(model, nbits=8)
model_int8.save("MyModel_int8.mlmodel")

パレタイゼーション

k-means クラスタリングを使って重みの固有値の数を減らします。

from coremltools.optimize.coreml import palettize_weights, OpPalettizerConfig

config = OpPalettizerConfig(nbits=4)
model_palettized = palettize_weights(model, config)

プルーニング

ゼロに近い重みを削除します（スパースモデル）。

from coremltools.optimize.torch.pruning import MagnitudePruner, MagnitudePrunerConfig

config = MagnitudePrunerConfig(target_sparsity=0.75)
pruner = MagnitudePruner(model, config)

最適化のガイドライン

• 最適化後は必ず精度をベンチマークします
• まず Float16 から始めます（最も安全で、労力に対する効果が最も高い方法です）
• 対象デバイスでテストします（Neural Engine の動作は GPU と異なります）
• Xcode Instruments > Core ML Performance でプロファイリングします

パフォーマンスのパターン

計算ユニットの選択

let config = MLModelConfiguration()

// Best performance — let system choose CPU, GPU, or Neural Engine
config.computeUnits = .all

// CPU only — predictable latency, no GPU/NE contention
config.computeUnits = .cpuOnly

// CPU + Neural Engine — good balance, avoids GPU contention with UI
config.computeUnits = .cpuAndNeuralEngine

// CPU + GPU — when Neural Engine unavailable
config.computeUnits = .cpuAndGPU

UI の応答性を保つための非同期予測

func classify(_ image: UIImage) async throws -> String {
    let model = try await MLModelManager.shared.model(named: "Classifier")
    // Prediction runs off main thread via structured concurrency
    let input = try MLDictionaryFeatureProvider(dictionary: ["image": image.pixelBuffer!])
    let result = try await Task.detached {
        try model.prediction(from: input)
    }.value
    return result.featureValue(for: "classLabel")?.stringValue ?? "unknown"
}

バッチ処理

// Process multiple images efficiently
let inputs = images.map { MyModelInput(image: $0.pixelBuffer!) }
let batch = MLArrayBatchProvider(array: inputs)
let results = try model.predictions(from: batch)

for i in 0..<results.count {
    let output = results.features(at: i)
    print(output.featureValue(for: "classLabel")?.stringValue ?? "")
}

インストール時にモデルをコンパイル

// Compile .mlmodel to .mlmodelc at install (not runtime)
// This is done automatically when you add .mlmodel to Xcode target
// For downloaded models, compile once and cache:
let compiledURL = try MLModel.compileModel(at: downloadedModelURL)
let permanentURL = appSupportDir.appendingPathComponent("MyModel.mlmodelc")
try FileManager.default.copyItem(at: compiledURL, to: permanentURL)

生成プロセス

ステップ 1：機能を特定する

設定に関する質問へのユーザーの回答に基づいて、templates.md から適切なテンプレートを選択します。

ステップ 2：コアファイルを生成する

機能	生成されるファイル
すべての Core ML	MLModelManager.swift
画像分類	ImageClassifier.swift
テキスト分析	TextAnalyzer.swift
Vision リクエスト	VisionService.swift
カスタムモデル	ModelConfig.swift + モデル固有の予測器
カメラ + ML	CameraMLPipeline.swift

ステップ 3：ファイルの場所を特定する

プロジェクトの構成を確認します：

• Sources/ がある場合 -> Sources/ML/
• App/Services/ がある場合 -> App/Services/ML/
• App/ がある場合 -> App/ML/
• それ以外の場合 -> ML/

出力形式

生成後、次の内容を提示します：

作成したファイル

ML/
├── MLModelManager.swift        # Central model lifecycle management
├── ImageClassifier.swift       # Vision-based image classification (if needed)
├── TextAnalyzer.swift          # NaturalLanguage wrapper (if needed)
├── ModelConfig.swift           # Compute unit configuration
└── VisionService.swift         # Vision request pipeline (if needed)

組み込み手順

1. .mlmodel ファイルを Xcode プロジェクトに追加します（カスタムモデルを使用する場合）
2. 生成された ML サービスファイルをインポートします
3. アプリの依存性注入でサービスを初期化します
4. ビュー／ビューモデルから予測メソッドを呼び出します
5. エラーを処理し、結果を表示します

テスト

• 期待される出力が分かっているテスト入力を使用します
• 信頼度のしきい値を確認します
• 対象デバイスで予測のレイテンシをプロファイリングします
• モデルが利用できない場合に適切にフォールバックすることをテストします

参考資料

• patterns.md — アーキテクチャパターン、モデルマネージャー、Vision パイプライン、カメラ + ML、テスト
• templates.md — すべての ML 機能に対応した、本番環境向けの Swift コードテンプレート
• Apple ドキュメント：Core ML Documentation
• Apple ドキュメント：Vision Documentation
• Apple ドキュメント：NaturalLanguage Documentation
• Apple ドキュメント：Create ML Documentation