EdgeRunner：纯 Swift 实现的 Apple Silicon 本地 LLM 推理引擎\n\n## 背景与动机\n\n随着大语言模型（LLM）的快速发展，越来越多的开发者希望在本地设备上运行这些模型，以保护隐私并降低延迟。然而，大多数现有的本地推理方案都依赖于 C++ 实现的底层库（如 llama.cpp），这在 Apple 生态系统中增加了额外的构建复杂性和依赖管理成本。\n\nEdgeRunner 的出现正是为了解决这一问题。它是一个完全用 Swift 编写的 LLM 推理引擎，直接利用 Apple 的 Metal 框架进行 GPU 加速，实现了真正的"纯 Swift"解决方案。\n\n## 核心特性与技术亮点\n\n### 1. 纯 Swift/Metal 实现\n\nEdgeRunner 最显著的特点是完全使用 Swift 语言和 Metal 计算着色器构建，没有任何 C++ 依赖。这不仅简化了构建流程，还使得代码更易于 Swift 开发者理解和维护。Metal 原生计算内核针对 Apple Silicon 进行了深度优化，充分发挥了 M 系列芯片的 GPU 性能。\n\n### 2. 直接 GGUF 格式支持\n\nEdgeRunner 支持直接加载 GGUF（GPT-Generated Unified Format）格式的量化模型，无需任何转换步骤。支持的量化类型包括：\n- Q8_0（推荐用于测试）\n- Q4_0、Q4_K_M\n- Q2_K、Q3_K\n- Q5_0、Q5_1、Q5_K、Q6_K\n\n这意味着用户可以直接从 Hugging Face 等平台下载现成的 GGUF 模型并立即使用。\n\n### 3. 内存映射加载与高效缓存\n\nEdgeRunner 采用内存映射（memory-mapped）技术加载模型，实现了即时启动和最小内存占用。例如，Qwen3-0.6B 模型仅需约 700MB 内存。同时，KV Cache 的实现确保了自回归生成的高效性。\n\n### 4. 性能表现\n\n在 Apple M3 Max 上的基准测试显示，EdgeRunner 在 Qwen3-0.6B-Q8_0 模型上达到了每秒 230+ token 的解码速度，首 token 时间仅为 3.5 毫秒。与 llama.cpp 和 MLX 相比，EdgeRunner 在保持竞争力的同时提供了纯 Swift 的简洁性。\n\n## 架构设计\n\nEdgeRunner 采用分层模块设计，从底层到高层依次为：\n\n1. EdgeRunnerMetal：底层 Metal 计算内核\n2. EdgeRunnerIO：模型加载（GGUF、SafeTensors）\n3. EdgeRunnerCore：采样、分词、图执行\n4. EdgeRunner：面向用户的公共 API 门面\n\n这种分层架构使得开发者可以根据需要选择不同级别的控制。对于快速原型开发，可以使用简单的 EdgeRunner 类；对于需要精细控制的场景，可以直接操作 LlamaLanguageModel 和 SamplingPipeline。\n\n## 使用示例\n\n### 基础流式生成\n\nswift\nimport EdgeRunner\n\nlet runner = try await EdgeRunner(modelPath: "Qwen3-0.6B-Q8_0.gguf")\n\n// 流式输出\nfor try await token in runner.stream("Once upon a time", maxTokens: 100) {\n print(token, terminator: "")\n}\n\n\n### 高级采样配置\n\nswift\nlet text = try await runner.generate(\n "Write a story about",\n maxTokens: 200,\n sampling: SamplingConfiguration(\n temperature: 0.7,\n topP: 0.9,\n topK: 40,\n repetitionPenalty: 1.1\n )\n)\n\n\n### 细粒度推理控制\n\nswift\nlet model = try await LlamaLanguageModel.load(\n from: modelURL,\n configuration: ModelConfiguration(contextWindowSize: 2048)\n)\n\nvar tokens = [model.bosTokenID ?? 1]\nfor _ in 0..<100 {\n let next = try await model.nextToken(\n for: tokens,\n sampling: SamplingConfiguration(temperature: 0)\n )\n guard next != model.eosTokenID else { break }\n tokens.append(next)\n}\n\n\n## 系统要求与安装\n\nEdgeRunner 要求：\n- macOS 26.0+ 或 iOS 26.0+\n- Apple Silicon（M1 或更新）\n- Swift 6.2+\n- Xcode 26 beta 或更新版本\n\n安装非常简单，可以通过 Swift Package Manager 添加依赖：\n\nswift\ndependencies: [\n .package(url: "https://github.com/christopherkarani/EdgeRunner.git", from: "0.1.0")\n]\n\n\n## 支持的模型\n\n当前版本主要支持 Qwen3 系列模型：\n- Qwen3 0.6B、1.7B、4B（Q8_0 量化）\n\n未来计划支持 Llama 3、Mistral、Phi-3 等更多模型架构。\n\n## 隐私与离线能力\n\nEdgeRunner 完全在设备本地运行，无需网络连接，所有数据都保留在用户设备上。这对于处理敏感信息的应用场景尤为重要，如医疗、金融或个人隐私相关的 AI 助手。\n\n## 开发状态与路线图\n\nEdgeRunner 目前处于 beta 阶段，核心功能已经稳定：\n- ✅ 快速推理（~230+ tok/s）\n- ✅ GGUF Q8_0 量化支持\n- ✅ KV Cache 高效生成\n- ⚠️ 分词器（BPE）基础实现\n- 🚧 多模型支持（目前仅 Qwen）\n\n## 结语\n\nEdgeRunner 代表了本地 LLM 推理的一个重要方向：在保持高性能的同时，提供与原生开发环境无缝集成的体验。对于 Apple 生态系统的开发者来说，这是一个值得关注的新选择。随着 Swift 6 和 Apple Silicon 的持续演进，纯 Swift 实现的推理引擎有望在未来发挥更大的作用。