drumih/turbo-fieldfare

二〇二六年八月二十六日·★ 1,587·⑂ 52·Swift·Apache-2.0 ·最新发布 0.3 · 2026-07-29 · GitHub 原仓库

摘要

TurboFieldfare 是一个基于 Swift 和 Metal 的推理运行时，专为 Apple Silicon Mac（包括 8 GB RAM 机型）设计，可在约 2 GB 内存中运行 Gemma 4 26B-A4B 指令微调模型。它通过将 1.35 GB 核心和 FP16 KV cache 保留在内存中，从 SSD 流式加载每个 token 所需的专家，避免加载完整的 14.3 GB 模型。在 8 GB M2 MacBook Air 上实测 decode 速度为 5.1-6.3 tok/s，在 24 GB M5 Pro 上为 31-35 tok/s。项目包含 Mac 应用、CLI 和 OpenAI 兼容服务器，并记录了 103 个实验测量结果。

TurboFieldfare Mac 应用使用 Gemma 4 26B-A4B 生成文本

内存变贵了。所以我给一个 260 亿参数的模型分配了大约 2 GB 的预算。

TurboFieldfare 运行经过指令微调的 Gemma 4 26B-A4B，而无需将整个 14.3 GB 模型加载到内存中。它将共享的 1.35 GB 核心和 FP16 KV cache 保留在内存中，然后仅从 SSD 流式加载每个 token 所需的专家。这使得该模型能够在 8 GB RAM 的 Mac 上运行。

该运行时、流式安装器、CLI 和原生 Mac 应用均使用 Swift 和 Metal 编写。TurboFieldfare 是模型特定的，而不是 MLX 或 llama.cpp 的封装。精选的实验记录总结了跨 kernel、缓存、I/O、prefill 和 decode 的 103 个测量结果。

快速开始

git clone https://github.com/drumih/turbo-fieldfare.git
cd turbo-fieldfare
swift build -c release
.build/release/TurboFieldfareMac

首次运行时，Swift Package Manager 会下载并构建 tokenizer 所需的 Swift 包。完整的 release 构建包括前台 Mac 应用及其配套的 decode-service 可执行文件。

应用打开后，选择 Download，让 TurboFieldfare 获取并重新打包固定的模型（约 15 GB）。准备就绪后，选择 Load Model，输入你的 prompt，然后按 Generate。

概览

指标	值
模型	Gemma 4 26B-A4B IT，总计 260 亿参数，每个 token 约 38.8 亿活跃参数
权重	MLX affine 4-bit，group 64；8-bit router；4-bit 共享和路由专家
内存	约 2 GB 权重和 4K KV cache
存储	已安装的纯文本模型约 14.3 GB
硬件	Apple Silicon Mac；8 GB RAM
平台	macOS 26, Metal 4, Swift 6.2
M2 实测 decode	5.1-6.3 tok/s 在 8 GB M2 MacBook Air 上
M5 实测 decode	31-35 tok/s 在 24 GB M5 Pro 上

测量结果是一个参考点，而非性能上限。Prompt 长度、生成长度、页面缓存状态和硬件都会影响吞吐量。要帮助测量其他 Apple Silicon Mac，请遵循社区基准测试指南。

使用 TurboFieldfare

TurboFieldfare 提供一个原生 Mac 应用、一个命令行界面和一个实验性的回环 OpenAI 兼容服务器。它们使用相同的 .gturbo 模型目录，但一次只能运行一个拥有模型的产品。

Swift 包公开了六个产品：

产品	用途
`TurboFieldfare`	包含运行时和 Metal kernel 的 Swift 库
`TurboFieldfareMac`	用于安装和生成的原生 Mac 应用
`TurboFieldfareDecodeService`	Mac 应用使用的单次本地模型和 Metal 所有者
`TurboFieldfareCLI`	命令行指令聊天和原始补全
`TurboFieldfareServer`	回环 OpenAI 兼容 Chat Completions 服务器
`TurboFieldfareRepack`	流式模型安装器和安装验证器

系统要求

一台 Apple Silicon Mac；已验证的目标是 8 GB M2 MacBook Air
macOS 26 及 Metal 4
Xcode 26 和 Swift 6.2 或更新版本
足够的空闲存储空间用于约 14.3 GB 的模型安装
首次模型安装需要互联网连接

该包仅支持 arm64。不支持较旧的 macOS 和 Metal 版本。

向模型输入 prompt

Mac 应用将你输入的内容视为指令，并自动处理 Gemma 的聊天格式。只需描述任务并包含模型所需的任何上下文。

生成默认使用温度 0.2、Top-K 64 和 Top-P 0.95。将温度设为 0 可获得确定性的贪婪输出。模型仍可能重复自身或给出错误答案，因此请检查重要结果。

TurboFieldfare 仅支持文本。应用和 CLI 支持用户和模型消息以及可选的系统指导；它们不暴露或执行工具。回环服务器接受函数工具声明，并返回模型生成的工具调用供客户端授权和执行。不支持图像、音频和视频。

Mac 应用

克隆仓库，然后从其根目录运行应用：

swift build -c release
.build/release/TurboFieldfareMac

构建完整的包，以便应用及其配套的 decode 服务都可用。从此检出启动时，应用将模型存储在 scratch/gemma4.gturbo 中。

安装模型

首次启动时，应用会检查可用存储空间并显示下载和安装大小。选择 Download 开始。

安装器永远不会实例化完整的源 checkpoint。它从固定的 Hugging Face 修订版流式加载所需的字节范围，并在它们到达时直接重新打包成 .gturbo 布局。这避免了磁盘上的第二个完整 checkpoint，并限制了临时内存的使用。

首次安装通过受限的 Hugging Face range request 传输约 15 GB。网络速度和 Hugging Face 响应时间各不相同，因此可能需要一段时间。完成的 .gturbo 安装占用约 14.3 GB，并且仅在其清单和文件哈希通过验证后才被接受。安装不会将模型加载到内存中。

加载和生成

安装后：

选择 Load Model。
在编辑器中输入 prompt。
选择 Generate，或按 Command+Return。
使用停止按钮或 Escape 提前结束生成。

状态栏显示生成进度、decode 速度和内存使用情况。使用右侧面板配置采样、上下文长度、专家缓存槽和运行时选项。有关详细信息和默认值，请参阅运行时控制。

命令行界面

CLI 使用现有的 .gturbo 安装。如果你通过 Mac 应用安装了模型，它已经在 scratch/gemma4.gturbo 中可用。否则，从命令行安装：

swift run -c release TurboFieldfareRepack \
  --output scratch/gemma4.gturbo \
  --overwrite

继续已取消或中断的下载：

swift run -c release TurboFieldfareRepack \
  --output scratch/gemma4.gturbo \
  --overwrite \
  --resume

移除已保存的下载状态：

swift run -c release TurboFieldfareRepack \
  --discard-partial \
  --output scratch/gemma4.gturbo

运行时仅接受包含最终 manifest.json 的完整 .gturbo 目录。

验证现有安装而不加载模型：

swift run -c release TurboFieldfareRepack \
  --verify-install \
  --input-gturbo scratch/gemma4.gturbo

指令聊天

将聊天消息放入 JSON 数组，并使用 --messages-file 传递：

[
  {"role": "user", "content": "解释为什么分块 prefill 能减少首 token 延迟同时保持内存受限。"}
]

swift run -c release TurboFieldfareCLI \
  --model scratch/gemma4.gturbo \
  --messages-file messages.json

这会以与 Mac 应用相同的方式格式化消息。CLI 响应限制通过 --max-new 设置，默认为 1,024 个 token。Mac 应用可以生成直到选定的上下文窗口填满。

原始补全

--prompt 可用于原始补全和可重复比较。它将文本直接传递给模型，不进行聊天格式化。对于指令-响应对话，请使用 --messages-file。

swift run -c release TurboFieldfareCLI \
  --model scratch/gemma4.gturbo \
  --prompt "法国的首都是" \
  --max-new 64 \
  --temperature 0

此示例特意请求一个短的贪婪补全。

常见的生成选项包括 --max-context、--temperature、--top-k、--top-p、--repetition-penalty、--seed 和可重复的 --stop 字符串。公共 CLI 使用生产运行时默认值。运行以下命令获取完整选项列表：

swift run -c release TurboFieldfareCLI --help

生成的文本输出到标准输出。计时统计信息输出到标准错误；在脚本中添加 --quiet 可抑制该页脚。

本地 OpenAI 兼容服务器

构建服务器并将其指向已安装的模型：

swift build -c release --product TurboFieldfareServer
.build/release/TurboFieldfareServer \
  --model scratch/gemma4.gturbo

它在 http://127.0.0.1:8080/v1 上监听，并支持 Chat Completions、流式、函数工具和单前缀 prompt 重用。客户端必须授权并运行每个工具调用。将服务器保持在回环接口上；它没有远程身份验证或 TLS。

有关测试请求、Python 和 OpenCode 设置、prompt 重用、工具处理以及支持的 API 子集，请参阅本地服务器。

测试和贡献

串行运行公共测试套件：

Scripts/test.sh

在开始模型运行之前，关闭内存密集型应用并检查 memory_pressure -Q。如果报告可用内存很少，请推迟运行。一次只运行一个 TurboFieldfare 应用、decode 服务、CLI、服务器、测试或其他本地模型进程。

要贡献可比较的性能结果，请遵循社区基准测试指南。

推理引擎的工作原理

在每个 transformer 层，Metal 从常驻权重计算 attention 和 router。CPU 使用 router 的前 8 个专家 ID 针对该层的 16 槽 LFU 缓存进行规划，然后通过受限的并行 pread 调用填充缺失，这些调用指向 Metal 可见的缓冲区。Metal 在这些读取运行时计算常驻共享专家分支，然后组合共享和路由输出。

Prompt prefill 使用最多 128 个 token 的块，以便一个获取的专家可以服务多行。生成一次一个 token 地重复路由层循环。安装器应用相同的受限内存规则：它直接将远程范围重新打包成 .gturbo，而不暂存完整的 shard 或 tensor。

有关模型架构的视觉介绍，请参阅 Maarten Grootendorst 的 A Visual Guide to Gemma 4。

系统设计解释了 .gturbo 布局、内存所有权、prefill、router 交接、cb1/io/cb2 阶段、Metal kernel 和正确性不变量。

状态和范围

TurboFieldfare 当前包括：

远程流式重新打包为 .gturbo 模型格式
经过指令微调的 Gemma 4 26B-A4B，带有经过验证的纯文本聊天格式
4-bit MLX affine embedding、attention、共享专家和路由专家权重，以及 8-bit router
用于量化 GEMV、attention、MoE、归一化、RoPE、采样和生产融合的自定义 Metal kernel
SSD 支持的路由专家流式传输，带有受限的专家缓存
分块单 prompt prefill 和逐 token 生成
FP16 KV 存储，带有用于 25 个滑动窗口层的受限循环存储和用于 5 个全 attention 层的线性存储
精确的 split-K/V decode attention，具有不同的归一化 K 和 V 路径
一个 Swift 库、流式安装器、命令行界面、回环 OpenAI 兼容服务器和原生 SwiftUI/AppKit Mac 应用，带有单次本地 decode 服务

当前范围是在至少 8 GB RAM 的 Apple Silicon Mac 上，从固定的 Gemma 4 26B-A4B 指令 checkpoint 进行纯文本推理。

未来工作

构建 iPhone 和 iPad 应用，然后在移动硬件上测量推理速度和内存使用。
对更多 Apple Silicon Mac 进行基准测试，特别是基础 16 GB M4 Mac mini 和其他 8 GB 机型。

实验和技术文档

塑造 TurboFieldfare 的实验解释了最大的收益、看似合理但失败的思路，以及在更强验证下被推翻的早期结果。详细的实验记录保留了所有 103 个经过审计的条目作为可选证据。

有用的入口点：

本地 OpenAI 兼容服务器
系统设计
基准测试
塑造 TurboFieldfare 的实验
实验清单和摘要
实现参考资料

许可证和模型条款

TurboFieldfare 的源代码和文档根据 Apache License 2.0 许可。

模型权重不包含在内。安装器会从固定的 Hugging Face checkpoint 单独下载它们，并且权重仍受其来源条款的约束。有关模型和 Swift 包许可证审查，请参阅 THIRD_PARTY_NOTICES.md。

TurboFieldfare 是一个独立的研究项目。它与 Google 没有关联、赞助或认可关系。

后记与项目名称

感谢你查看这个项目！

我叫 Andrey Mikhaylov。你可以在 LinkedIn 上找到我。我是 TurboFieldfare 的作者，也是一名 iOS 和 Metal 工程师。我的大部分工作涉及图像、视频和设备端 AI。

我将这个项目献给我的妻子 Sasha，她是我认识的最支持我的人。即使在我最困难的时期，她也始终站在我身边。她热爱野生动物，喜欢观鸟，并自愿加入我们当地的观鸟社区。因为她，我也与鸟类和自然更加亲近。

TurboFieldfare 以田鸫（fieldfare）命名，它是鸫科的一员，也是我最喜欢的鸟。它不是最显眼或颜色最鲜艳的鸟，但它绝对有自己的个性和独特之处。我认为这个项目也是如此：它可能不是最实用的，但我用我最喜欢的工具（尤其是 Metal）在我最喜欢的领域——设备端 ML 推理——构建了它。它绝对有自己的个性和独特之处。

下次你在户外时，摸摸草地，听听鸟鸣。有时这是你能做的最美好的事情。如果可以，请支持你当地的野生动物社区。他们做着重要的工作。

谢谢！

译自 GitHub · 项目涌现 · 录于二〇二六年八月二十六日