drumih/turbo-fieldfare

Gemma 4 26B-A4B inference in ~2 GB of RAM on any M-series MacBook

TurboFieldfare – Apple Silicon 上的 Gemma 4 26B 本地推理

是什么

  • 一个 Swift + Metal 运行时，可在任何 Apple-silicon Mac 上运行 260 亿参数的 Gemma 4 26B-A4B 指令微调模型，即使只有 8 GB 内存的设备也能运行。
  • 它不会将完整的 14 GB 检查点加载到内存中。相反，它保持 1.35 GB 的共享核心和 FP16 KV 缓存常驻，并实时从 SSD 流式加载所需的 MoE「专家」权重。
  • 项目提供原生 macOS 应用、命令行工具、Swift 库和回环式 OpenAI 兼容服务器，全部基于自定义 Metal 内核构建。

为何重要

  • 大型语言模型通常需要数十 GB 内存；TurboFieldfare 将推理内存压缩至约 2 GB，使 26B 级模型可在基础配置的 M2 MacBook Air 上使用。
  • 它展示了一种实用的「专家缓存流式传输」技术，可被用于其他混合专家（MoE）模型在内存受限设备上的部署。

核心组件

组件 作用
TurboFieldfare (Swift 库) 核心运行时 + 用于量化 GEMV、注意力、MoE 路由、采样等的 Metal 内核
TurboFieldfareMac SwiftUI/AppKit 图形界面，用于下载、重新打包、加载模型并进行聊天
TurboFieldfareCLI 命令行聊天/补全工具，与相同的 .gturbo 模型目录兼容
TurboFieldfareServer 本地 OpenAI 兼容 HTTP 服务器（仅回环），支持聊天、流式输出和函数工具调用
TurboFieldfareRepack 流式安装器，仅从 Hugging Face 拉取所需字节范围，直接写入自定义 .gturbo 布局，并验证安装
TurboFieldfareDecodeService 小型辅助进程，负责 GUI 的 Metal 上下文

如何开始

  1. 克隆 & 构建
    git clone https://github.com/drumih/turbo-fieldfare.git
cd turbo-fieldfare
swift build -c release   # 构建应用 + 解码服务
.build/release/TurboFieldfareMac
  2. 下载模型 – 应用程序（或 TurboFieldfareRepack）从固定 Hugging Face 检查点流式传输约 15 GB，并创建 .gturbo 目录（scratch/gemma4.gturbo）。
  3. 加载 & 生成 – 点击 加载模型，输入提示，点击 生成（或使用 TurboFieldfareCLI 命令行工具）。
  4. 可选视觉支持 – 运行 TurboFieldfareRepack 时加上 --vision-output 参数，可添加约 1.1 GB 的图像塔包；应用程序/命令行工具随后支持 --image 参数。

支持的硬件与软件

  • Apple-silicon Mac（ARM64）– 已在 8 GB M2 MacBook Air 上测试；M5、M4 等设备也支持。
  • macOS 26 + Metal 4（Xcode 26，Swift 6.2 或更高版本）。
  • 模型需约 15 GB 可用存储空间，推理期间需约 2 GB RAM。

性能快照（来自仓库的基准表）

  • M2 (8 GB)：5.1 – 6.3 tokens / 秒 解码。
  • M5 (24 GB)：31 – 35 tokens / 秒 解码。 社区成员可通过提供的基准指南提交自己的性能数据。

使用细节

  • 提示设置 – 默认：temperature 0.2，top-k 64，top-p 0.95。使用 --temperature 0 可获得确定性输出。
  • KV 缓存 – FP16，滑动窗口层使用 4K 令牌窗口；全注意力层使用线性存储。
  • 图像输入 – 安装视觉包后，CLI 可通过 --image <file> 发送单张图像，GUI 可上传；多轮图像聊天可通过 JSON 消息文件支持。
  • OpenAI 服务器 – 运行在 http://127.0.0.1:8080/v1；支持聊天补全、流式输出和函数工具调用（客户端需授权工具执行）。

开发与贡献

  • 使用 Scripts/test.sh 运行测试套件。
  • 按照“社区基准指南”添加性能结果。
  • 项目采用 Apache 2.0 许可证；模型权重单独下载，遵循原始 Hugging Face 条款。

当前范围与未来计划

  • 在范围内：Apple-silicon Mac 上的文本生成（Gemma 4 26B-A4B）及可选视觉塔。
  • 不在范围内：音频/视频模态、远程服务器部署、非 Apple 硬件。
  • 未来工作：iPhone/iPad 应用及在更多 Apple-silicon 设备上的广泛基准测试。

TL;DR: TurboFieldfare 是一个基于 Swift/Metal 的推理引擎，通过从 SSD 流式传输 MoE 专家，使 26B 参数的 Gemma 4 模型能在低内存 Apple-silicon Mac 上运行。它提供 GUI、CLI 和本地 OpenAI 兼容服务器，全部采用 Apache 2.0 许可证。

相关