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 集成的音频/语音模型
任何需要 Neural Engine 优化的场景
需要量化、调色板化或剪枝的模型

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 {
        // 在生成之前使用区域设置回退
        break
    }
    // 继续使用模型
case .unavailable(.appleIntelligenceNotEnabled):
    // 引导用户在设置中启用 Apple Intelligence
case .unavailable(.modelNotReady):
    // 系统模型资产未就绪；显示加载状态
case .unavailable(.deviceNotEligible):
    // 设备无法运行 Apple Intelligence；使用回退
case .unavailable(let reason):
    // 未知或未来的不可用原因；使用回退并记录原因
}

然后创建会话并保持其共享上下文预算较小：

let session = LanguageModelSession {
    "你是一个有用的烹饪助手。"
}
session.prewarm()
let response = try await session.respond(to: "建议一个快速的意大利面食谱")

必需的防护措施：

会话是有状态的，一次只接受一个请求；序列化访问并在发出另一个响应之前检查 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 转换（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 端的转换、压缩、分析和框架选择。使用同级 coreml 技能进行 Swift 应用集成、预测 API、运行时配置、Vision 请求连接和详细模型加载。

有关完整转换管道，请参阅 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: "你好"))

按设备选择模型

设备	内存	推荐模型	内存使用
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，取消选中“调试可执行文件”）
在用户交互前为 Foundation Models 调用 session.prewarm()
预编译 Core ML 模型为 .mlmodelc 以加快加载速度
使用 EnumeratedShapes 而非 RangeDim 以优化 Neural Engine
使用 4 位调色板化以获得最佳 Neural Engine 内存/延迟收益
将详细的 Vision、Natural Language 和 Swift Core ML 运行时集成交给同级框架技能

常见错误

未检查可用性。 在未检查 SystemLanguageModel.default.availability 的情况下开始生成，导致不受支持的设备出现失败而非回退 UI。
无回退 UI。 使用 iOS 26 之前版本或没有 Apple Intelligence 的设备用户看不到任何内容。始终提供优雅降级路径。
超出上下文窗口。 token 预算涵盖输入 + 输出。通过 tokenCount(for:) 监控使用情况，并在需要时进行摘要。
对同一会话的并发请求。 LanguageModelSession 一次只支持一个请求。检查 session.isResponding 或序列化访问。
指令中的不可信内容。 放置在指令参数中的用户输入会绕过防护边界。将用户内容保留在提示中。
跳过转换一致性检查。 在固定测试用例上比较源模型和 Core ML 模型，然后在压缩或发布前修复并重新转换。
在 Core ML 跟踪前忘记 model.eval()。 PyTorch 模型在 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：在用户交互前调用会话预暖
[ ] 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 集成、内存管理

你可能还喜欢

nestjs-expert

44Ktesting-qa

You are an expert in Nest.js with deep knowledge of enterprise-grade Node.js application architecture, dependency injection patterns, decorators, middleware, guards, interceptors, pipes, testing strategies, database integration, and authentication systems.

sickn33

获取

observability-and-instrumentation

79Ktesting-qa

Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what happened from the available data.

addyosmani

获取

architecture-patterns

38Ktesting-qa

Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use this skill when designing clean architecture for a new microservice, when refactoring a monolith to use bounded contexts, when implementing hexagonal or onion architecture patterns, or when debugging dependency cycles between application layers.

wshobson

获取

继续探索

浏览 testing-qa 热门 Skills 最近更新

apple-on-device-ai

相关 Skills

Apple 平台上的设备端 AI

目录

框架选择路由

Apple Foundation Models

Core ML

MLX Swift

llama.cpp

快速参考

Apple Foundation Models 概述

Core ML 概述

模型格式

转换管道（coremltools）

验证、修复和重新转换

与 coreml 的边界

MLX Swift 概述

加载和运行 LLM

按设备选择模型

内存管理

多后端架构

性能最佳实践

常见错误

审查清单

参考

你可能还喜欢

nestjs-expert

observability-and-instrumentation

architecture-patterns

继续探索

与 `coreml` 的边界