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 記憶體。

效能快照（來自倉儲的基準表）

  • 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 許可證。

相關