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

适用场景： 在所有 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 的设备上，使用系统语言模型进行短文本生成、摘要、标注、结构化输出和工具增强任务。在创建会话前，为每个入口点设置检查：

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")

必要的防护措施：

• 会话具有状态，每次只能接受一个请求；请串行处理访问，并在发起下一次响应前检查 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 概述

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: "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. 在实体 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 处理。除非产品明确选择非本地回退方案，否则请将日记等 私人用户内容保留在设备上。

性能最佳实践

1. 在调试器外运行以获得准确的基准测试结果（Xcode：Cmd-Opt-R，取消勾选 “Debug Executable”）
2. 在用户交互前调用 Foundation Models 的 session.prewarm()
3. 将 Core ML 模型预编译为 .mlmodelc，以加快加载速度
4. 使用 EnumeratedShapes 而非 RangeDim，以优化神经引擎
5. 使用 4-bit 调色板化，以获得最佳的神经引擎内存／延迟提升
6. 将详细的 Vision、Natural Language 和 Swift Core ML 运行时 集成交由相关框架技能处理

常见错误

1. 未检查可用性。 未检查 SystemLanguageModel.default.availability 就开始生成，会导致不受支持的设备报错，而不是显示回退 UI。
2. 没有回退 UI。 使用 iOS 26 之前版本或不支持 Apple Intelligence 的设备上的用户将看不到任何内容。务必提供平稳降级路径。
3. 超出上下文窗口。 令牌预算涵盖输入 + 输出。通过 tokenCount(for:) 监控用量，并在必要时进行摘要。
4. 在一个会话上并发请求。 LanguageModelSession 一次只支持一个请求。请检查 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 上内存占用超过 60%（MLX Swift）。 大型模型会导致因内存不足而被终止。
10. 相信 MLX 模拟器结果。 依赖 Metal 的行为必须在实体设备上验证；Simulator 只能用于 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：已设置缓存限制、清理缓存并卸载模型
• 所有模型访问均通过协调器 actor 串行处理
• 并发：模型类型和工具实现符合 Sendable，或通过 @MainActor 隔离
• 已在实体设备上进行测试（而非模拟器）

参考资料

• 基础模型 API -- LanguageModelSession、@Generable、工具调用、提示词设计
• Core ML 转换 -- 从 PyTorch、TensorFlow 和其他框架转换模型
• Core ML 优化 -- 量化、调色板化、剪枝、性能调优
• MLX Swift 与 llama.cpp -- MLX Swift 模式、llama.cpp 集成、内存管理