apple-on-device-ai

Appleプラットフォーム向けオンデバイスAI

オンデバイスMLモデルの選定、デプロイ、最適化に関するガイドです。Apple Foundation Models、Core ML、MLX Swift、llama.cppについて解説します。

目次

• フレームワーク選択ガイド
• Apple Foundation Modelsの概要
• Core MLの概要
• MLX Swiftの概要
• マルチバックエンドアーキテクチャ
• パフォーマンスのベストプラクティス
• よくある間違い
• レビュー用チェックリスト
• 参考資料

フレームワーク選択ガイド

この判断ツリーを使って、用途に合ったフレームワークを選択してください。

Apple Foundation Models

使用する場面： Apple Intelligenceが有効なiOS 26以降／macOS 26以降のデバイスで、テキスト生成、要約、エンティティ抽出、構造化出力、短い対話を行う場合です。アプリ側でAPIキーを管理したり、ネットワーク通信を行ったり、モデルをホストしたりする必要はありません。ただし、システムモデルのアセットが利用可能かどうかは引き続き確認してください。

最適な用途：

• @Generable型を使ったテキストまたは構造化データの生成
• 要約、分類、コンテンツのタグ付け
• Toolプロトコルを使ったツール拡張生成
• オンデバイスのプライバシーを保証する必要があるアプリ

適さない用途： 複雑な数学、コード生成、事実の正確性が求められるタスク、またはiOS 26より前のデバイスを対象とするアプリです。

Core ML

使用する場面： カスタム学習済みモデル（ビジョン、NLP、音声）をすべてのAppleプラットフォームにデプロイする場合です。coremltoolsを使って、PyTorch、TensorFlow、またはscikit-learnのモデルを変換します。

最適な用途：

• 画像分類、物体検出、セグメンテーション
• カスタムNLP分類器、感情分析モデル
• SoundAnalysisとの統合による音声／スピーチモデル
• Neural Engineの最適化が必要なあらゆるシナリオ
• 量子化、パレット化、または枝刈りが必要なモデル

MLX Swift

使用する場面： Apple Silicon上で特定のオープンソースLLM（Llama、Mistral、Qwen、Gemma）を最大スループットで実行する場合です。研究やプロトタイピングにも適しています。

最適な用途：

• Apple Silicon上で持続的なトークン生成速度を最大化する場合
• mlx-communityのHugging Faceモデルを実行する場合
• 自動微分を必要とする研究
• Mac上でのファインチューニングのワークフロー

llama.cpp

使用する場面： GGUFモデル形式を使って、クロスプラットフォームでLLM推論を行う場合です。幅広いデバイスへの対応が必要な本番環境のデプロイに適しています。

最適な用途：

• GGUF量子化モデル（Q4_K_M、Q5_K_M、Q8_0）
• クロスプラットフォームアプリ（iOS + Android + デスクトップ）
• オープンソースモデルエコシステムとの最大限の互換性

クイックリファレンス

シナリオ	フレームワーク
Apple Intelligence対応デバイス（iOS 26以降）でのテキスト生成	Foundation Models
オンデバイスLLMによる構造化出力	Foundation Models（@Generable）
画像分類、物体検出	Core ML
PyTorch／TensorFlowからのカスタムモデル	Core ML + coremltools
特定のオープンソースLLMの実行	MLX Swiftまたはllama.cpp
Apple Siliconで最大スループットを実現	MLX Swift
クロスプラットフォームのLLM推論	llama.cpp
OCRとテキスト認識	Vision framework
感情分析、NER、トークン化	Natural Language framework
デバイス上でのカスタム分類器の学習	Create ML

Apple Foundation Models の概要

Apple Intelligence 対応デバイス上で、システムの言語モデルを使った短文生成、要約、タグ付け、構造化出力、ツール拡張タスクを実行します。セッションを作成する前に、すべてのエントリーポイントで利用可否を確認してください。

import FoundationModels

switch SystemLanguageModel.default.availability {
case .available:
    guard SystemLanguageModel.default.supportsLocale(Locale.current) else {
        // Use locale fallback before generating
        break
    }
    // Proceed with model usage
case .unavailable(.appleIntelligenceNotEnabled):
    // Guide user to enable Apple Intelligence in Settings
case .unavailable(.modelNotReady):
    // System model assets are not ready; show loading state
case .unavailable(.deviceNotEligible):
    // Device cannot run Apple Intelligence; use fallback
case .unavailable(let reason):
    // Unknown or future unavailable reason; use fallback and log reason
}

次にセッションを作成し、共有コンテキストの予算を小さく保ちます。

let session = LanguageModelSession {
    "You are a helpful cooking assistant."
}
session.prewarm()
let response = try await session.respond(to: "Suggest a quick pasta recipe")

必須のガードレール：

• セッションは状態を保持し、一度に 1 件のリクエストのみ受け付けます。アクセスを直列化し、次の応答を発行する前に isResponding を確認してください。
• 指示、ツール、スキーマ、プロンプト、トランスクリプト、出力はすべてコンテキストウィンドウを共有します。必要なツールだけを登録し、スキーマは簡潔に保ってください。
• supportsLocale(_:) でロケールを解決してください。言語リストとの生の照合は避けてください。
• 信頼できないユーザーコンテンツは指示ではなく、プロンプトに含めてください。システムのガードレールは引き続き有効なため、拒否やその他の生成エラーにはフォールバック UI で対処してください。

タスクで @Generable、@Guide、ストリーミング、ツール定義、トランスクリプト、生成オプション、カスタムアダプター、プロンプト設計、または詳細なエラー処理が必要な場合は、Foundation Models のリファレンスを読み込んでください。

Core ML の概要

トレーニング済みモデルをデプロイするための Apple のフレームワークです。最適な計算ユニット（CPU、GPU、または Neural Engine）に自動的に処理を割り当てます。

モデル形式

形式	拡張子	使用する場面
.mlpackage	ディレクトリ（mlprogram）	新しいすべてのモデル（iOS 15 以降）
.mlmodel	単一ファイル（neuralnetwork）	レガシーのみ（iOS 11～14）
.mlmodelc	コンパイル済み	読み込みを高速化するために事前コンパイル済み

新規作業では必ず mlprogram（.mlpackage）を使用してください。

変換パイプライン（coremltools）

import coremltools as ct

# PyTorch conversion (torch.jit.trace)
model.eval()  # CRITICAL: always call eval() before tracing
traced = torch.jit.trace(model, example_input)
mlmodel = ct.convert(
    traced,
    inputs=[ct.TensorType(shape=(1, 3, 224, 224), name="image")],
    minimum_deployment_target=ct.target.iOS18,
    convert_to='mlprogram',
)
mlmodel.save("Model.mlpackage")

検証、修正、再変換

1. 変換前に、代表的なソースモデルのフィクスチャと、許容可能な出力／タスクの許容誤差を固定します。
2. 変換後、同じフィクスチャをソースモデルと Core ML モデルで実行します。
3. 出力の一致度やタスク指標が許容誤差を満たさない場合は、形状、演算子、精度、前処理を調査し、変換を修正してフィクスチャを再実行します。
4. 非圧縮モデルが合格してから圧縮してください。圧縮を変更するたびに精度を再検証し、しきい値を満たさない変更は取り消すか調整します。
5. 合格したモデルを実機のターゲットデバイスでプロファイリングし、正確性、レイテンシ、メモリ、パッケージサイズの目標をすべて満たすまで繰り返します。

coreml との境界

このスキルでは、Python 側での変換、圧縮、プロファイリング、フレームワークの選定を扱います。Swift アプリへの統合、予測 API、ランタイム構成、Vision リクエストの接続、モデル読み込みの詳細には、関連する coreml スキルを使用してください。

変換パイプライン全体については references/coreml-conversion.md を、最適化手法については references/coreml-optimization.md を参照してください。

MLX Swift の概要

Swift 向けの Apple の ML フレームワークです。ユニファイドメモリアーキテクチャにより、Apple Silicon 上で持続的な生成スループットを最大化できます。

LLM の読み込みと実行

import MLX
import MLXLLM
import MLXLMCommon
import MLXLMHFAPI

let container = try await LLMModelFactory.shared.loadContainer(
    from: HubClient.default,
    using: TokenizersLoader(),
    configuration: .init(id: "mlx-community/Qwen3-4B-4bit")
)
let session = ChatSession(container)
print(try await session.respond(to: "Hello"))

デバイス別のモデル選択

デバイス	RAM	推奨モデル	RAM 使用量
iPhone 12-14	4-6 GB	SmolLM2-135M または Qwen 2.5 0.5B	約 0.3 GB
iPhone 15 Pro+	8 GB	Gemma 3n E4B 4-bit	約 3.5 GB
Mac 8 GB	8 GB	Llama 3.2 3B 4-bit	約 3 GB
Mac 16 GB+	16 GB+	Mistral 7B 4-bit	約 6 GB

メモリ管理

1. iOS では総 RAM の 60％を超えないようにしてください。
2. MLX のキャッシュ上限を設定します：Memory.cacheLimit = 512 * 1024 * 1024
3. バックグラウンド移行時やメモリプレッシャー時には、MLX と llama.cpp のモデルをアンロードしてください。MLX では、生成負荷の高いフェーズの後に Memory.clearCache() も呼び出します。
4. より大きなモデルには「Increased Memory Limit」エンタイトルメントを使用してください。
5. MLX Swift と llama.cpp は実機の Apple Silicon で検証してください。Simulator では Metal に依存する推論、メモリ、パフォーマンスを検証できません。

MLX Swift のパターンと llama.cpp の統合について詳しくは、references/mlx-swift.md を参照してください。

マルチバックエンドアーキテクチャ

アプリで複数の AI バックエンド（例：Foundation Models と MLX のフォールバック）が必要な場合：

func respond(to prompt: String) async throws -> String {
    if SystemLanguageModel.default.isAvailable {
        return try await foundationModelsRespond(prompt)
    } else if canLoadMLXModel() {
        return try await mlxRespond(prompt)
    } else {
        throw AIError.noBackendAvailable
    }
}

競合を防ぐため、すべてのモデルアクセスをコーディネーターアクター経由で直列化します：

actor ModelCoordinator {
    func withExclusiveAccess<T>(_ work: () async throws -> T) async rethrows -> T {
        try await work()
    }
}

カスタム Core ML モデルについては、ここでは変換／最適化の引き継ぎ先のみを示します。 Swift アプリへの統合、モデルの読み込み、Vision との連携、予測のライフサイクルは coreml に任せます。ジャーナルなどの非公開ユーザーコンテンツは、製品で明示的に 非ローカルのフォールバックを選択しない限り、デバイス上に保持してください。

パフォーマンスのベストプラクティス

1. 正確なベンチマークを行うにはデバッガーを使わずに実行します（Xcode：Cmd-Opt-R を押し、「Debug Executable」のチェックを外します）
2. ユーザー操作の前に、Foundation Models に対して session.prewarm() を呼び出します
3. 読み込みを高速化するため、Core ML モデルを .mlmodelc に事前コンパイルします
4. Neural Engine の最適化には RangeDim より EnumeratedShapes を使用します
5. Neural Engine のメモリ／レイテンシを最も改善するには、4 ビットのパレタイゼーションを使用します
6. Vision、Natural Language、Swift Core ML ランタイムの詳細な統合は、関連するフレームワークスキルに任せます

よくある間違い

1. 利用可能かどうかを確認しない。 SystemLanguageModel.default.availability を確認せずに生成を開始すると、未対応デバイスでフォールバック UI ではなくエラーが発生します。
2. フォールバック UI がない。 iOS 26 より前のバージョンを使うユーザーや Apple Intelligence に対応していないデバイスでは、何も表示されません。必ず適切な縮退動作を用意してください。
3. コンテキストウィンドウを超過する。 トークン予算は入力と出力の合計です。tokenCount(for:) で使用状況を監視し、必要に応じて要約してください。
4. 1 つのセッションで同時リクエストを送る。 LanguageModelSession がサポートするリクエストは一度に 1 つです。session.isResponding を確認するか、アクセスを直列化してください。
5. 信頼できないコンテンツを指示に含める。 instructions パラメーターにユーザー入力を設定すると、ガードレールの境界を回避できます。ユーザーコンテンツはプロンプトに含めてください。
6. 変換後の同等性チェックを省略する。 固定フィクスチャを使ってソースモデルと Core ML モデルを比較し、圧縮または出荷する前に問題を修正して再変換してください。
7. Core ML のトレース前に model.eval() を忘れる。 PyTorch モデルは torch.jit.trace の前に評価モードにする必要があります。学習モードの成果物は出力を破損させます。
8. neuralnetwork 形式を使う。 新しい Core ML モデルでは常に mlprogram（.mlpackage）を使用してください。従来の neuralnetwork 形式は非推奨です。
9. iOS で RAM の 60% を超過する（MLX Swift）。 大きなモデルは OOM による強制終了を引き起こします。
10. MLX シミュレーターの結果を信頼する。 Metal に依存する動作は実機で検証してください。シミュレーターは UI／制御フローのスモークテストにのみ使用します。
11. MLX キャッシュをクリアしない。 モデルのアンロードと Memory.clearCache() をセットで行ってください。

レビューチェックリスト

• フレームワークの選択がユースケースと対象 OS バージョンに合っている
• Foundation Models：各 API 呼び出しの前に利用可能かどうかを確認している
• Foundation Models：モデルが利用できない場合に適切なフォールバックがある
• Foundation Models：ユーザー操作の前にセッションのプリウォームを呼び出している
• Foundation Models：@Generable のプロパティが論理的な生成順になっている
• Foundation Models：トークン予算を考慮している（contextSize を確認）
• Core ML：iOS 15 以降ではモデル形式が mlprogram（.mlpackage）になっている
• Core ML：ソースモデルと Core ML モデルの同等性が固定フィクスチャとタスクの許容範囲で確認されている
• Core ML：圧縮モデルを再検証し、対象の実機でプロファイリングしている
• MLX Swift：モデルサイズが対象デバイスの RAM に適している
• MLX Swift：キャッシュ制限を設定し、キャッシュをクリアし、モデルをアンロードしている
• すべてのモデルアクセスをコーディネーターアクター経由で直列化している
• 並行処理：モデル型とツールの実装が Sendable に準拠しているか、@MainActor で分離されている
• 実機でテストしている（シミュレーターではない）

参考資料

• Foundation Models API -- LanguageModelSession、@Generable、ツール呼び出し、プロンプト設計
• Core ML Conversion -- PyTorch、TensorFlow、その他のフレームワークからのモデル変換
• Core ML Optimization -- 量子化、パレタイズ、プルーニング、パフォーマンス調整
• MLX Swift & llama.cpp -- MLX Swift のパターン、llama.cpp の統合、メモリ管理