通过官方示例快速上手：在 Swift 中调用 MLX 实现 Apple Silicon GPU 原生推理

Apple 的 MLX 框架正迅速成为在 Apple Silicon 设备上进行本地 AI 推理的事实标准。对于 Swift 开发者而言，mlx-swift-examples 官方示例仓库是最佳的入门起点。它不仅提供了开箱即用的工具和库，更展示了如何将强大的大语言模型无缝集成到原生应用中。本文将摒弃繁杂的理论，直接带你通过官方示例，掌握在 Swift 项目中调用 MLX 实现 GPU 原生推理的核心步骤与最佳实践。

第一步：理解仓库结构，找到你的切入点

克隆 mlx-swift-examples 仓库后，你会看到一个清晰的组织结构。核心内容分为两大类：Applications 和 Tools。Applications 文件夹包含可以直接在 iOS 和 macOS 上运行的完整 App 示例，如 LLMEval（纯文本生成）、VLMEval（图像描述）和功能更全面的 MLXChatExample（聊天应用）。这些是学习如何构建用户界面和处理复杂交互的绝佳模板。而 Tools 文件夹则包含命令行工具，如 llm-tool 和 ExampleLLM，它们是理解核心 API 调用逻辑的“最小可行产品”。对于初学者，建议从 Tools/ExampleLLM 开始，它的代码简洁，能让你快速看到模型运行的效果。

第二步：项目集成，添加 Swift Package 依赖

要在你自己的 Swift 项目中使用 MLX，你需要将其作为依赖项添加。这可以通过两种方式完成。在 Package.swift 文件中，添加如下依赖：.package(url: "https://github.com/ml-explore/mlx-swift-examples/", branch: "main")，然后在你的目标（target）中声明你需要的库，例如 .product(name: "MLXLLM", package: "mlx-swift-examples")。如果你更喜欢图形化操作，在 Xcode 中打开你的项目，进入 File > Add Package Dependencies...，输入仓库 URL https://github.com/ml-explore/mlx-swift-examples/，选择 main 分支即可。集成完成后，你就可以在代码中导入 import MLX 和 import MLXLLM 等模块了。

第三步：核心代码解析，三行代码启动推理

MLX Swift 的 API 设计得非常简洁。根据 WWDC 2025 的官方演示，加载一个模型并生成文本的核心逻辑可以浓缩为以下几步。首先，你需要一个 ModelConfiguration 来指定模型 ID，这个 ID 通常指向 Hugging Face Hub 上 mlx-community 组织下的量化模型，例如 "mlx-community/Mistral-7B-Instruct-v0.3-4bit"。接着，使用共享的 LLMModelFactory 来异步加载模型容器。最后，在模型容器的上下文中，准备输入并调用生成函数。一个最简示例如下：

let modelId = "mlx-community/Mistral-7B-Instruct-v0.3-4bit"
let configuration = ModelConfiguration(id: modelId)
let model = try await LLMModelFactory.shared.loadContainer(configuration: configuration)

try await model.perform { context in
    let input = try await context.processor.prepare(input: UserInput(prompt: "你好，介绍一下你自己。"))
    let stream = try generate(input: input, context: context)
    for await part in stream {
        print(part.chunk ?? "", terminator: "")
    }
}

这段代码展示了 MLX Swift 的优雅：它处理了模型下载、权重加载、分词器初始化等所有底层复杂性，让你专注于业务逻辑。

第四步：进阶技巧，管理对话历史与性能调优

简单的单次提示生成只是开始。要构建一个真正的聊天机器人，你需要管理对话历史，这就要用到“键值缓存”（KV Cache）。KV 缓存能存储之前对话的中间计算结果，避免模型在每次新提问时都从头计算，从而大幅提升响应速度。在 Swift 中启用 KV 缓存非常简单，只需在生成参数中创建并传入一个缓存对象：let cache = context.model.newCache(parameters: generateParameters)，然后将其传递给 TokenIterator。此外，MLX 的核心优势在于其对 Apple Silicon 的深度优化。它利用 Metal 框架在 GPU 上进行加速，并通过“统一内存架构”让 CPU 和 GPU 共享数据，彻底消除了数据拷贝的开销。这意味着你的推理不仅快，而且能效比极高。官方示例中提到的 --memory-stats 参数（在 llm-tool 中）可以帮助你监控内存占用，以便为不同设备（如 iPhone 和 Mac Studio）选择合适的模型精度（如 4bit 或 BF16）。

第五步：超越示例，构建你的生产级应用

官方示例是起点，而非终点。mlx-swift-examples 仓库中的 Libraries 文件夹提供了 MLXLMCommon、MLXLLM、MLXVLM 等可复用的组件，你可以直接将它们集成到你的商业项目中。例如，MLXLMCommon 提供了一个简化的 API，让你可以用 ChatSession 对象进行多轮对话，代码更简洁：let session = ChatSession(model); print(try await session.respond(to: "第一个问题")); print(try await session.respond(to: "第二个问题"))。同时，不要忘记 MLX 不仅支持推理，还支持在设备上进行微调（Fine-tuning）。虽然这在 Swift 端尚未完全铺开，但 Python 端的 mlx_lm.lora 命令已经非常成熟，你可以先在 Mac 上微调模型，再将适配器融合后部署到 Swift 应用中，实现真正的个性化 AI。通过遵循官方示例的模式，你不仅能快速上手，更能构建出高效、稳定、充分利用 Apple Silicon 硬件潜能的下一代 AI 应用。