apple-on-device-ai

Apple 平台裝置端 AI

選擇、部署及最佳化裝置端 ML 模型的指南。涵蓋 Apple Foundation Models、Core ML、MLX Swift 與 llama.cpp。

框架選擇路由器

使用此決策樹為您的使用案例選擇正確的框架。

Apple Foundation Models

使用時機： 在啟用 Apple Intelligence 的 iOS 26+ / macOS 26+ 裝置上進行文字生成、摘要、實體提取、結構化輸出及簡短對話。無需應用程式管理的 API 金鑰、網路往返或模型託管；但仍需處理系統模型資產的就緒狀態。

最適合：

使用 @Generable 類型生成文字或結構化資料
摘要、分類、內容標記
使用 Tool 協定進行工具增強生成
需要保證裝置端隱私的應用程式

不適合： 複雜數學、程式碼生成、事實準確性任務，或目標為 iOS 26 之前版本的應用程式。

Core ML

使用時機： 在所有 Apple 平台上部署自訂訓練模型（視覺、NLP、音訊）。使用 coremltools 從 PyTorch、TensorFlow 或 scikit-learn 轉換模型。

最適合：

影像分類、物體偵測、分割
自訂 NLP 分類器、情感分析模型
透過 SoundAnalysis 整合的音訊/語音模型
任何需要神經網路引擎最佳化的場景
需要量化、調色盤化或剪枝的模型

MLX Swift

使用時機： 在 Apple Silicon 上以最大吞吐量執行特定開源 LLM（Llama、Mistral、Qwen、Gemma）。研究與原型開發。

最適合：

在 Apple Silicon 上達到最高持續 token 生成速率
從 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 框架
情感分析、NER、分詞	Natural Language 框架
在裝置上訓練自訂分類器	Create ML

Apple Foundation Models 概覽

在 Apple Intelligence 裝置上使用系統語言模型進行簡短生成、摘要、標記、結構化輸出及工具增強任務。在建立 session 前，務必檢查每個進入點：

import FoundationModels

switch SystemLanguageModel.default.availability {
case .available:
    guard SystemLanguageModel.default.supportsLocale(Locale.current) else {
        // 在生成前使用語言區域備援
        break
    }
    // 繼續使用模型
case .unavailable(.appleIntelligenceNotEnabled):
    // 引導使用者在設定中啟用 Apple Intelligence
case .unavailable(.modelNotReady):
    // 系統模型資產尚未就緒；顯示載入狀態
case .unavailable(.deviceNotEligible):
    // 裝置無法執行 Apple Intelligence；使用備援方案
case .unavailable(let reason):
    // 未知或未來的不支援原因；使用備援方案並記錄原因
}

然後建立 session 並保持其共享上下文預算較小：

let session = LanguageModelSession {
    "你是一位有用的烹飪助手。"
}
session.prewarm()
let response = try await session.respond(to: "建議一個快速義大利麵食譜")

必要的防護措施：

Session 是有狀態的，一次只接受一個請求；序列化存取，並在發出另一個回應前檢查 isResponding。
指令、工具、結構描述、提示、對話記錄和輸出共享上下文視窗。僅註冊必要的工具，並保持結構描述簡潔。
使用 supportsLocale(_:) 解析語言區域；不要直接比對語言列表。
將不可信的用戶內容放在提示中，絕不要放在指令中。系統防護措施仍會生效，因此請使用備援 UI 處理拒絕及其他生成錯誤。

當任務需要 @Generable、@Guide、串流、工具定義、對話記錄、生成選項、自訂適配器、提示設計或詳細錯誤處理時，請載入 Foundation Models 參考資料。

Core ML 概覽

Apple 用於部署訓練模型的框架。自動分派至最佳運算單元（CPU、GPU 或神經網路引擎）。

模型格式

格式	副檔名	使用時機
`.mlpackage`	目錄（mlprogram）	所有新模型（iOS 15+）
`.mlmodel`	單一檔案（neuralnetwork）	僅限舊版（iOS 11-14）
`.mlmodelc`	已編譯	預先編譯以加快載入速度

新工作一律使用 mlprogram（.mlpackage）。

轉換管線（coremltools）

import coremltools as ct

# PyTorch 轉換（torch.jit.trace）
model.eval()  # 關鍵：在追蹤前務必呼叫 eval()
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")

驗證、修正與重新轉換

在轉換前，凍結具代表性的來源模型測試案例及可接受的輸出/任務容差。
轉換後，對來源模型和 Core ML 模型執行相同的測試案例。
如果輸出一致性或任務指標超出容差，檢查形狀、運算子、精度和預處理；修正轉換並重新執行測試案例。
僅在未壓縮模型通過後才進行壓縮。每次壓縮變更後重新驗證準確性，若未達標則還原或調整變更。
在實體目標裝置上對通過的模型進行效能分析，然後重複直到正確性、延遲、記憶體和套件大小目標全部通過。

與 `coreml` 的界線

此技能負責 Python 端的轉換、壓縮、效能分析及框架選擇。Swift 應用程式整合、預測 API、執行時期設定、Vision 請求連接及詳細模型載入請使用同系列的 coreml 技能。

完整轉換管線請參閱 references/coreml-conversion.md，最佳化技術請參閱 references/coreml-optimization.md。

MLX Swift 概覽

Apple 的 Swift 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: "你好"))

依裝置選擇模型

裝置	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

記憶體管理

在 iOS 上絕不超過總 RAM 的 60%
設定 MLX 快取限制：Memory.cacheLimit = 512 * 1024 * 1024
在背景化或記憶體壓力時卸載 MLX 和 llama.cpp 模型；對於 MLX，在大量生成階段後也呼叫 Memory.clearCache()
對較大模型使用「增加記憶體限制」權利
在實體 Apple Silicon 上驗證 MLX Swift 和 llama.cpp；模擬器無法執行依賴 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 序列化所有模型存取，防止競爭：

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

對於自訂 Core ML 模型，僅在此處提及轉換/最佳化交接：將 Swift 應用程式整合、模型載入、Vision 連接及預測生命週期交給 coreml。將私人用戶內容（例如日記）保留在裝置上，除非產品明確選擇非本地備援。

效能最佳實務

在除錯器外執行以獲得準確基準（Xcode：Cmd-Opt-R，取消勾選「Debug Executable」）
在使用者互動前為 Foundation Models 呼叫 session.prewarm()
預先編譯 Core ML 模型為 .mlmodelc 以加快載入速度
使用 EnumeratedShapes 而非 RangeDim 以最佳化神經網路引擎
使用 4 位元調色盤化以獲得最佳神經網路引擎記憶體/延遲增益
將詳細的 Vision、Natural Language 及 Swift Core ML 執行時期整合交給同系列的框架技能

常見錯誤

未檢查可用性。 在未檢查 SystemLanguageModel.default.availability 的情況下開始生成，會讓不支援的裝置出現失敗而非備援 UI。
無備援 UI。 使用 iOS 26 之前版本或沒有 Apple Intelligence 的裝置用戶看不到任何內容。務必提供優雅的降級路徑。
超出上下文視窗。 token 預算涵蓋輸入 + 輸出。透過 tokenCount(for:) 監控使用量，並在必要時進行摘要。
對同一個 session 發出並行請求。 LanguageModelSession 一次只支援一個請求。檢查 session.isResponding 或序列化存取。
將不可信內容放在指令中。 用戶輸入放在 instructions 參數中會繞過防護邊界。將用戶內容保留在提示中。
跳過轉換一致性檢查。 在固定測試案例上比較來源模型和 Core ML 模型，然後在壓縮或發布前修正並重新轉換。
在 Core ML 追蹤前忘記呼叫 model.eval()。 PyTorch 模型必須在 eval 模式下才能進行 torch.jit.trace。訓練模式的人工產物會破壞輸出。
使用 neuralnetwork 格式。 新的 Core ML 模型一律使用 mlprogram（.mlpackage）。舊版 neuralnetwork 格式已棄用。
在 iOS 上超過 60% RAM（MLX Swift）。 大型模型會導致 OOM 終止。
信任 MLX 模擬器結果。 在實體裝置上驗證依賴 Metal 的行為；模擬器僅適用於 UI/控制流程的冒煙測試。
未清除 MLX 快取。 模型卸載時應搭配 Memory.clearCache()。

審查核對清單

[ ] 框架選擇符合使用案例與目標 OS 版本
[ ] Foundation Models：每次 API 呼叫前檢查可用性
[ ] Foundation Models：模型不可用時有優雅備援
[ ] Foundation Models：在使用者互動前呼叫 session prewarm
[ ] Foundation Models：@Generable 屬性按邏輯生成順序排列
[ ] Foundation Models：已考量 token 預算（檢查 contextSize）
[ ] Core ML：模型格式為 mlprogram（.mlpackage）適用於 iOS 15+
[ ] Core ML：來源/Core ML 一致性通過固定測試案例與任務容差
[ ] Core ML：壓縮模型已重新驗證並在實體目標上進行效能分析
[ ] MLX Swift：模型大小適合目標裝置 RAM
[ ] MLX Swift：已設定快取限制、清除快取、卸載模型
[ ] 所有模型存取透過協調器 actor 序列化
[ ] 並行：模型類型與工具實作符合 Sendable 或隔離於 @MainActor
[ ] 已執行實體裝置測試（非模擬器）

參考資料

Foundation Models API -- LanguageModelSession、@Generable、工具呼叫、提示設計
Core ML 轉換 -- 從 PyTorch、TensorFlow 及其他框架轉換模型
Core ML 最佳化 -- 量化、調色盤化、剪枝、效能調校
MLX Swift 與 llama.cpp -- MLX Swift 模式、llama.cpp 整合、記憶體管理

您可能也喜歡

tdd-rust

81Ktesting-qa

TDD workflow for RTK filter development. Red-Green-Refactor with Rust idioms. Real fixtures, token savings assertions, snapshot tests with insta. Auto-triggers on new filter implementation.

rtk-ai

獲取

constraint-driven-development

91Ktesting-qa

Establishes a project's quality bar as a written contract and stops agents quietly lowering it. Interviews the user on which dimensions matter, supplies sane default thresholds when they have no number in mind, records everything in CONSTRAINTS.md, and watches the diff for a weakened bar — new @ts-ignore or eslint-disable suppressions, skipped or deleted tests, assertions stripped out, unimplemented stubs, thresholds edited down. Use when no quality bar is written down, when the user says "set up constraints" or "define our standards", when an agent keeps silencing checks or skipping tests to get to green, when you need a coverage or performance threshold and don't know what number to pick, or when an agent writes more code than anyone will read.