core-ml

Core ML 技能

用于在 Apple 平台应用中集成机器学习的综合顾问、生成器和工作流技能。涵盖 Core ML 模型集成、Vision 框架图像分析、NaturalLanguage 框架文本处理、Create ML 训练，以及设备端模型优化。

此技能的启用时机

在用户遇到以下情况时使用此技能：

• 想要为应用添加机器学习能力
• 需要将 Core ML 模型（.mlmodel）集成到 Xcode 项目中
• 想要使用 Vision 框架进行图像分析（人脸、文本识别、人体姿势、对象检测）
• 想要使用 NaturalLanguage 框架处理文本（情感、实体、语言检测）
• 需要使用 Create ML 训练自定义模型
• 想要优化模型以便在设备端使用（量化、剪枝、调色板化）
• 需要在 Core ML 和 Foundation Models（Apple Intelligence）之间做出选择
• 询问图像分类、对象检测、声音分类或表格数据预测
• 想要进行实时相机与机器学习处理

决策指南：Core ML 与 Foundation Models

生成代码前，确定适用的框架。

在以下情况下使用 Foundation Models（Apple Intelligence）：

• 需要通用文本生成、摘要或对话式 AI
• 目标平台为 iOS 26+ / macOS 26+（Foundation Models 需要 Apple Silicon 和最新操作系统）
• 任务涉及开放式语言理解或生成
• 想要从自然语言生成 @Generable 结构化输出
• 查看 apple-intelligence/foundation-models/ 技能了解实现方法

在以下情况下使用 Core ML：

• 需要专用机器学习功能：图像分类、对象检测、声音分类、自定义回归/分类
• 已有训练好的模型（.mlmodel、.mlpackage）或计划训练一个模型
• 需要广泛的设备支持（iOS 14+ / macOS 11+）
• 任务需要特定领域的预测（医学影像、产品识别、自定义 NLP）
• 需要在 Neural Engine 或 GPU 上进行对性能要求较高的推理

在以下情况下使用 Vision 框架（无需自定义模型）：

• 使用 Apple 内置模型进行图像分类
• 人脸检测和面部特征点分析
• 使用 VNRecognizeTextRequest 进行文本识别（OCR）
• 人体和手部姿势检测
• 条形码和 QR 码扫描
• 图像相似度和显著性检测
• 地平线检测、矩形检测

在以下情况下使用 NaturalLanguage 框架（无需自定义模型）：

• 文本情感分析
• 语言识别
• 分词（词、句子、段落边界）
• 命名实体识别（人物、地点、组织）
• 用于相似度比较的词和句子嵌入
• 词形还原和词性标注

生成前检查

1. 项目上下文检测

• 检查部署目标（Core ML 要求 iOS 11+ / macOS 10.13+；Vision 要求 iOS 11+；NaturalLanguage 要求 iOS 12+）
• 检查是否已有机器学习代码或模型
• 确定项目结构和源文件位置
• 确认使用 SwiftUI 还是 UIKit/AppKit

2. 冲突检测

搜索现有的机器学习集成：

Glob: **/*Model*.swift, **/*Classifier*.swift, **/*Predictor*.swift, **/*.mlmodel, **/*.mlmodelc, **/*.mlpackage
Grep: "import CoreML" or "import Vision" or "import NaturalLanguage"

如果找到，请询问用户：

• 扩展现有机器学习配置？
• 替换为新的实现？
• 添加其他模型/功能？

配置问题

通过 AskUserQuestion 询问用户：

1. 您需要什么 ML 能力？

   • 图像分类（识别照片中的物体）
   • 目标检测（使用边界框定位物体）
   • 文本分析（情感、实体、语言）
   • 自定义 Core ML 模型集成
   • Vision 框架（OCR、人脸、姿势）
   • 声音分类
   • 表格数据预测

2. 您有训练好的模型，还是需要训练模型？

   • 我有一个 .mlmodel / .mlpackage 文件
   • 我想使用 Create ML 训练
   • 我想使用 Apple 的内置模型（Vision / NaturalLanguage）

3. 性能要求是什么？

   • 实时（摄像头画面，每次预测 < 33ms）
   • 交互式（由用户发起，可接受 < 500ms）
   • 后台处理（批量处理，对延迟没有要求）

Core ML 模型集成

将模型添加到 Xcode

1. 将 .mlmodel 或 .mlpackage 拖入 Xcode 项目导航器
2. Xcode 会自动生成一个以模型命名的 Swift 类
3. 生成的类提供类型安全的输入/输出接口
4. Xcode 会在构建时将模型编译为 .mlmodelc（针对设备进行优化）

加载模型

// Option 1: Auto-generated class (simplest)
let model = try MyImageClassifier(configuration: MLModelConfiguration())

// Option 2: Generic MLModel loading (flexible)
let url = Bundle.main.url(forResource: "MyModel", withExtension: "mlmodelc")!
let config = MLModelConfiguration()
config.computeUnits = .all  // CPU + GPU + Neural Engine
let model = try MLModel(contentsOf: url, configuration: config)

// Option 3: Async loading (recommended for large models)
let model = try await MLModel.load(contentsOf: url, configuration: config)

进行预测

// Type-safe prediction with auto-generated class
let input = MyImageClassifierInput(image: pixelBuffer)
let output = try model.prediction(input: input)
print(output.classLabel)       // "cat"
print(output.classLabelProbs)  // ["cat": 0.95, "dog": 0.04, ...]

// Batch predictions
let batch = MLArrayBatchProvider(array: inputs)
let results = try model.predictions(from: batch)

Create ML 训练概览

图像分类

• 最低要求：每个类别 10 张图像；建议：每个类别 40 张以上
• 将图像整理到以类别命名的文件夹中
• 支持 JPEG、PNG、HEIC 格式
• 自动应用数据增强（旋转、翻转、裁剪）
• 基于 Apple 的基础模型进行迁移学习

文本分类

• 训练数据：带标签的文本样本（CSV 或 JSON）
• 使用场景：情感分析、垃圾邮件检测、主题分类、意图识别
• 每个类别至少 10 个样本；建议使用 100 个以上以提高准确率

表格分类 / 回归

• CSV 或 JSON 格式的结构化数据
• 自动进行特征工程
• 支持：Boosted Tree、Random Forest、Linear Regression、Decision Tree

声音分类

• 按类别整理的音频文件
• 环境声音、语音检测、音乐流派
• 每个类别至少 10 个样本，每个样本时长为 15 秒以上

目标检测

• 带有边界框标注的图像（JSON 格式）
• 输出边界框 + 类别标签 + 置信度
• 每个类别至少标注 30 张图像；建议使用 300 张以上

训练方式

• Xcode Create ML App：可视化界面，拖放操作，无需编写代码
• CreateML Framework：在 Swift Playgrounds 或 macOS 应用中以编程方式训练
• coremltools (Python)：将 TensorFlow、PyTorch、ONNX 模型转换为 Core ML 格式

Vision 框架功能

功能	请求类	需要自定义模型？
图像分类	VNClassifyImageRequest	否（内置）
目标检测	VNDetectObjectsRequest（自定义模型）	是
人脸检测	VNDetectFaceRectanglesRequest	否
人脸关键点	VNDetectFaceLandmarksRequest	否
文本识别（OCR）	VNRecognizeTextRequest	否
身体姿势	VNDetectHumanBodyPoseRequest	否
手部姿势	VNDetectHumanHandPoseRequest	否
条形码检测	VNDetectBarcodesRequest	否
图像显著性	VNGenerateAttentionBasedSaliencyImageRequest	否
地平线检测	VNDetectHorizonRequest	否
矩形检测	VNDetectRectanglesRequest	否
图像相似度	VNGenerateImageFeaturePrintRequest	否

Vision 请求处理流程

// Multiple requests on the same image
let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
try handler.perform([
    textRequest,     // OCR
    faceRequest,     // Face detection
    barcodeRequest   // Barcode scanning
])
// Each request's results are populated independently

NaturalLanguage 框架

情感分析

let tagger = NLTagger(tagSchemes: [.sentimentScore])
tagger.string = "This app is amazing!"
let (tag, _) = tagger.tag(at: text.startIndex, unit: .paragraph, scheme: .sentimentScore)
// tag?.rawValue == "0.9" (positive)

语言检测

let language = NLLanguageRecognizer.dominantLanguage(for: "Bonjour le monde")
// language == .french

分词

let tokenizer = NLTokenizer(unit: .word)
tokenizer.string = "Hello, world!"
tokenizer.enumerateTokens(in: text.startIndex..<text.endIndex) { range, _ in
    print(text[range])  // "Hello" then "world"
    return true
}

命名实体识别

let tagger = NLTagger(tagSchemes: [.nameType])
tagger.string = "Tim Cook visited Apple Park in Cupertino."
tagger.enumerateTags(in: text.startIndex..<text.endIndex, unit: .word, scheme: .nameType) { tag, range in
    if let tag, tag != .other {
        print("\(text[range]): \(tag.rawValue)")
        // "Tim": PersonalName, "Cook": PersonalName
        // "Apple Park": OrganizationName, "Cupertino": PlaceName
    }
    return true
}

模型优化

量化（coremltools Python）

通过降低数值精度来减小模型大小：

• Float32 转 Float16：大小约减少 50%，精度损失极小
• Float16 转 Int8：在此基础上再减少约 50%，请仔细测试精度

import coremltools as ct
from coremltools.models.neural_network import quantization_utils

model = ct.models.MLModel("MyModel.mlmodel")

# Float16 quantization (safe default)
model_fp16 = quantization_utils.quantize_weights(model, nbits=16)
model_fp16.save("MyModel_fp16.mlmodel")

# Int8 quantization (aggressive, test accuracy)
model_int8 = quantization_utils.quantize_weights(model, nbits=8)
model_int8.save("MyModel_int8.mlmodel")

调色板化

使用 k-means 聚类减少权重的唯一取值：

from coremltools.optimize.coreml import palettize_weights, OpPalettizerConfig

config = OpPalettizerConfig(nbits=4)
model_palettized = palettize_weights(model, config)

剪枝

移除接近零的权重（稀疏模型）：

from coremltools.optimize.torch.pruning import MagnitudePruner, MagnitudePrunerConfig

config = MagnitudePrunerConfig(target_sparsity=0.75)
pruner = MagnitudePruner(model, config)

优化指南

• 优化后始终进行准确性基准测试
• 从 Float16 开始（最安全，投入产出比最高）
• 在目标设备上测试（神经引擎的行为与 GPU 不同）
• 使用 Xcode Instruments > Core ML Performance 进行性能分析

性能模式

计算单元选择

let config = MLModelConfiguration()

// Best performance — let system choose CPU, GPU, or Neural Engine
config.computeUnits = .all

// CPU only — predictable latency, no GPU/NE contention
config.computeUnits = .cpuOnly

// CPU + Neural Engine — good balance, avoids GPU contention with UI
config.computeUnits = .cpuAndNeuralEngine

// CPU + GPU — when Neural Engine unavailable
config.computeUnits = .cpuAndGPU

用于提升 UI 响应速度的异步预测

func classify(_ image: UIImage) async throws -> String {
    let model = try await MLModelManager.shared.model(named: "Classifier")
    // Prediction runs off main thread via structured concurrency
    let input = try MLDictionaryFeatureProvider(dictionary: ["image": image.pixelBuffer!])
    let result = try await Task.detached {
        try model.prediction(from: input)
    }.value
    return result.featureValue(for: "classLabel")?.stringValue ?? "unknown"
}

批处理

// Process multiple images efficiently
let inputs = images.map { MyModelInput(image: $0.pixelBuffer!) }
let batch = MLArrayBatchProvider(array: inputs)
let results = try model.predictions(from: batch)

for i in 0..<results.count {
    let output = results.features(at: i)
    print(output.featureValue(for: "classLabel")?.stringValue ?? "")
}

在安装时编译模型

// Compile .mlmodel to .mlmodelc at install (not runtime)
// This is done automatically when you add .mlmodel to Xcode target
// For downloaded models, compile once and cache:
let compiledURL = try MLModel.compileModel(at: downloadedModelURL)
let permanentURL = appSupportDir.appendingPathComponent("MyModel.mlmodelc")
try FileManager.default.copyItem(at: compiledURL, to: permanentURL)

生成流程

步骤 1：确定能力

根据用户对配置问题的回答，从 templates.md 中选择合适的模板。

步骤 2：生成核心文件

能力	生成的文件
任意 Core ML	MLModelManager.swift
图像分类	ImageClassifier.swift
文本分析	TextAnalyzer.swift
Vision 请求	VisionService.swift
自定义模型	ModelConfig.swift + 特定模型的预测器
相机 + ML	CameraMLPipeline.swift

步骤 3：确定文件位置

检查项目结构：

• 如果存在 Sources/ -> Sources/ML/
• 如果存在 App/Services/ -> App/Services/ML/
• 如果存在 App/ -> App/ML/
• 否则 -> ML/

输出格式

生成后，提供：

创建的文件

ML/
├── MLModelManager.swift        # Central model lifecycle management
├── ImageClassifier.swift       # Vision-based image classification (if needed)
├── TextAnalyzer.swift          # NaturalLanguage wrapper (if needed)
├── ModelConfig.swift           # Compute unit configuration
└── VisionService.swift         # Vision request pipeline (if needed)

集成步骤

1. 将 .mlmodel 文件添加到 Xcode 项目中（如果使用自定义模型）
2. 导入生成的 ML 服务文件
3. 在应用的依赖注入中初始化服务
4. 从视图/视图模型调用预测方法
5. 处理错误并显示结果

测试

• 使用已知测试输入及预期输出
• 验证置信度阈值
• 在目标设备上分析预测延迟
• 测试模型不可用时的优雅降级

参考资料

• patterns.md — 架构模式、模型管理器、Vision 流程、相机 + ML、测试
• templates.md — 适用于所有 ML 能力的生产就绪 Swift 代码模板
• Apple 文档：Core ML 文档
• Apple 文档：Vision 文档
• Apple 文档：NaturalLanguage 文档
• Apple 文档：Create ML 文档