SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场coreml

coreml

智能体与模型

查看项目

更新于 10-16 09:11

技能介绍

用途

本技能用于在 iOS 应用中加载、配置和运行 Core ML 模型，覆盖 Swift 侧集成：模型加载、预测、MLTensor、性能分析与部署。目标平台为 iOS 26+ 与 Swift 6.3，除特别说明外向后兼容至 iOS 14。

范围边界：Python 侧的模型转换、优化（量化、调色板化、剪枝）和框架选择属于 apple-on-device-ai 技能；本技能只负责 Swift 集成。

主要能力

加载模型

  • 自动生成类：将 .mlpackage 或 .mlmodelc 拖入 Xcode 后会生成带类型输入/输出的 Swift 类，示例中使用 MLModelConfiguration 并设置 computeUnits = .all。
  • 手动加载：当模型在运行时下载或存储在 bundle 外时，可从 URL 加载。
  • 异步加载（iOS 16+）：使用 MLModel.load(contentsOf:configuration:) 避免阻塞主线程，大模型建议使用。
  • 运行时编译：可用 MLModel.compileModel(at:) 在设备上将 .mlpackage 或 .mlmodel 编译为 .mlmodelc，适用于从服务器下载的模型；文档提醒缓存编译后的 URL，避免每次启动重复编译，应复制到持久位置（如 Application Support）。

模型配置

MLModelConfiguration 控制计算单元、GPU 访问和模型参数。计算单元取值包括 .all（CPU + GPU + 神经引擎，默认）、.cpuOnly（CPU，适用于后台任务、音频会话或 GPU 繁忙时）、.cpuAndGPU（需要 GPU 但模型含 ANE 不支持的算子）、.cpuAndNeuralEngine（兼容模型下最佳能效）。配置属性示例包含 allowLowPrecisionAccumulationOnGPU。

进行预测

  • 使用自动生成类：提供类型化输入/输出结构体，示例读取 classLabel 与 classLabelProbs。
  • 使用 MLDictionaryFeatureProvider：适用于输入动态或编译时未知的场景。
  • 异步预测（iOS 17+）。
  • 批量预测：通过 MLArrayBatchProvider 一次处理多个输入以提升吞吐。
  • 有状态预测（iOS 18+）：使用 MLState 支持跨预测维持状态的模型（序列模型、LLM、音频累加器）；每次预测调用传入同一 state。文档说明 State 不是 Sendable，应在单一 actor 或 task 中使用；可为并发流调用 model.makeState() 创建独立状态。

MLTensor（iOS 18+）

MLTensor 是用于前后处理的 Swift 原生多维数组，操作惰性执行，需调用 .shapedArray(of:) 物化结果。支持创建、重塑、数学运算（softmax、归一化）以及与 MLMultiArray 互转。

使用 MLMultiArray

MLMultiArray 是非图像模型输入输出的主要数据交换类型。文档给出创建三维数组 [batch, sequence, features]、写入值、读取值以及通过数据指针零拷贝创建数组的示例。

图像预处理

图像模型期望 CVPixelBuffer 输入。文档提供从 CGImage 创建 CVPixelBuffer 的函数示例；使用 Vision 的 VNCoreMLRequest 会自动处理，只有当直接进行 MLModel 预测时才需要手动转换。

多模型流水线

当下游的前处理或后处理需要独立模型时可串联模型（preprocessor -> main model -> postprocessor）。Xcode 管理的流水线可在 .mlpackage 中使用 pipeline 模型类型，各子模型在最佳计算单元上运行。

Vision 集成

可使用 Vision 运行 Core ML 图像模型并获得自动图像预处理（缩放、归一化、色彩空间、方向）。现代方式为 CoreMLRequest（iOS 18+），旧方式为 VNCoreMLRequest。文档提醒完整的 Vision 框架模式（文本识别、条码检测、文档扫描）见 vision-framework 技能。

性能分析

  • MLComputePlan（iOS 17.4+）：在运行预测前检查每个算子将使用的计算设备，示例遍历主函数算子并打印 deviceUsage 与 estimatedCost。
  • Instruments：使用 Core ML 模板分析模型加载时间、预测延迟（按算子细分）、计算设备调度（每算子 CPU/GPU/ANE）与内存分配；建议在调试器外运行以获得准确结果。

模型部署

对比了多种部署策略（打包进应用、按需资源、Background Assets（iOS 16+）、CloudKit/服务器）的优缺点。大小考虑：App Store 应用包上限 4 GB；蜂窝下载限制 200 MB（可申请例外）；超过 50 MB 的模型使用 ODR 标签；预编译为 .mlmodelc 可跳过设备端编译。文档给出按需资源加载的 NSBundleResourceRequest 示例。

内存管理

  • 进入后台时卸载模型引用以释放 GPU/ANE 内存，回到前台重新加载。
  • 后台任务使用 .cpuOnly，因为后台处理无法使用 GPU 或 ANE，设置 .cpuOnly 可避免静默回退和资源争用。
  • 共享模型实例：不要从同一已编译模型创建多个 MLModel 实例，应使用 actor 提供共享访问。
  • 监控内存压力：大模型（>100 MB）可能触发内存警告，注册 UIApplication.didReceiveMemoryWarningNotification 并在压力下释放缓存模型。

常见错误

文档列举多项对照原则：不要在主线程加载模型（应使用异步 API 或后台 actor）；不要每次启动重新编译 .mlpackage（应编译一次并持久缓存）；不要无故硬编码 .cpuOnly（应使用 .all 让系统选择）；不要忽略 MLFeatureValue 类型不匹配（应精确匹配类型，图像用 MLFeatureValue(pixelBuffer:) 而非原始数据）；不要每次预测都新建 MLModel 实例（应加载一次并复用）；不要跳过模型加载与预测的错误处理（应捕获错误并提供回退）；不要假设所有算子都运行在神经引擎上（应用 MLComputePlan 验证每算子调度）；不要手动处理图像后再交给 Vision + Core ML（应让 CoreMLRequest 或 VNCoreMLRequest 处理预处理，Vision 会正确处理方向、缩放和像素格式转换）。

审查清单

清单涵盖：异步加载模型、适当设置 computeUnits、复用模型实例、可用时使用自动生成类、错误处理、持久缓存运行时编译的模型、图像输入走 Vision 流水线、使用 MLComputePlan 验证设备调度、多输入时使用批量预测、模型大小与部署策略匹配、在目标设备（尤其低内存旧设备）测试内存、在调试器外运行预测以获得准确性能测量。

参考资料

  • 模式与代码：references/coreml-swift-integration.md
  • 模型转换与优化（Python 侧）：见 apple-on-device-ai 技能
  • Apple 文档：Core ML、MLModel、MLComputePlan