drumih/turbo-fieldfare

TurboFieldfare – Apple Silicon 上での Gemma 4 26B のデバイス内推論

何であるか

• 任意の Apple-silicon Mac で 260 億パラメータの Gemma 4 26B-A4B 指示チューニングモデルを実行できる Swift + Metal ランタイム。8 GB RAM のマシンでも動作可能。
• 14 GB のフルチェックポイントをメモリにロードするのではなく、1.35 GB の共有コアと FP16 KV キャッシュを常駐させ、必要な MoE「エキスパート」重みを SSD からオンザフライでストリーミングする。
• プロジェクトはネイティブ macOS アプリ、CLI、Swift ライブラリ、ループバック型 OpenAI 互換サーバーを提供しており、すべてカスタム Metal カーネルに基づいている。

なぜ重要か

• 大規模言語モデルは通常数十GBのRAMが必要だが、TurboFieldfare は推論を約2GBにまで圧縮し、ベース仕様の M2 MacBook Air でも 26B スケールのモデルを実用可能にする。
• 限られたメモリデバイス上で他の mixture-of-experts (MoE) モデルに再利用可能な実用的な「エキスパートキャッシュストリーミング」技術を示している。

主要コンポーネント

コンポーネント	役割
TurboFieldfare (Swift ライブラリ)	量子化 GEMV、アテンション、MoE ルーティング、サンプリングなどを行うコアランタイム + Metal カーネル
TurboFieldfareMac	Hugging Face からモデルをダウンロード・再パッケージ化・ロードし、チャットできる SwiftUI/AppKit GUI
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 で CLI を使用）。
4. オプションのビジョンサポート – --vision-output を指定して TurboFieldfareRepack を実行すると、約1.1 GB の画像タワー・パックが追加される。アプリ/CLI は --image <file> 引数を受け入れるようになる。

対応ハードウェア & ソフトウェア

• Apple-silicon Macs (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 では添付で1枚の画像を送信可能。複数ターンの画像チャットは 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 は、SSD から MoE エキスパートをストリーミングすることで、低メモリの Apple-silicon Mac 上で 26B パラメータの Gemma 4 モデルを実行可能な Swift/Metal ベースの推論エンジン。GUI、CLI、ローカル OpenAI 互換サーバーを提供し、Apache 2.0 ライセンス下で公開されている。