TurboFieldfare: 8GB RAM Mac で動作する Gemma 4 26B-A4B

TurboFieldfare は、約 2 GB の RAM を使用して Gemma 4 26B-A4B モデルを推論するための専用 Swift + Metal ランタイムです。 8 GB 搭載の Apple Silicon Mac でも動作可能となるよう設計されています。

クイックスタート

• ローカルサーバー の起動
• ベンチマーク結果
• 貢献度
• 動作原理
• 実験データ
• 参考文献

---

高騰するメモリ環境への対応

現在、メモリ価格が高騰しています。これを受け、260 億パラメータを持つモデルに対して約 2 GB の RAMという制限下での動作を実現しました。

TurboFieldfare は完全なモデルをメモリにロードせずとも、以下の仕組みで動作します：

• 共有コア: メモリ上に共有部分（1.35 GB）と FP16 KV キャッシュを保持。
• ストリーミング推論: 各トークンごとに必要な専門家（Experts）のみを SSD から読み込み。

これにより、8 GB RAM の Macでもモデルを実行可能です。 ※このランタイムは MLX や llama.cpp のラッパーではなく、Gemma 4 に特化した独自実装です。計 103 件の測定データを蓄積しています。

実際に試す方法

以下のコマンドでプロジェクトを取得し、ビルドしてください。

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

最初の起動手順：

1. Swift パッケージのダウンロードとビルドが完了します。
2. フォルダには、ネイティブ Mac アプリ

   TurboFieldfareMac

   とそれをサポートするデコードサービスが含まれます。
3. アプリを起動し、[Download] を選択して、ピン留めされたモデル（約 15 GB）を検出・再パッケージ化します。
4. [Load Model] を選択し、プロンプトを入力後、[Generate] ボタンを押してください。

---

スペックとベンチマーク

指標	値
モデル	Gemma 4 26B-A4B IT（パラメータ数：260 億、アクティブトークン：約 38.8 億）
ウェイト	MLX アフィン 4 ビット、8 ビットルーター、4 ビット共有・ルーティング専門家
メモリ使用量	約 2 GB（ウェイト + 4K 量子化 KV キャッシュ）
ストレージ容量	テキスト専用モデル：約 14.3 GB
ハードウェア要件	Apple Silicon Mac / RAM 8 GB
プラットフォーム	macOS 26, Metal 4, Swift 6.2
M2 (8GB) デコード速度	5.1〜6.3 トークン/秒
M5 Pro (24GB) デコード速度	31〜35 トークン/秒

重要： 上記測定結果は性能の上限を示す参考値です。プロンプト長や生成長さ、キャッシュ状態などによりスループットは変動します。詳細なベンチマークガイドはこちら：コミュニティベンチマークガイド

---

利用可能な製品

TurboFieldfare はネイティブ Mac アプリ、CLI、OpenAI 互換サーバーの 3 つを提供します。これらはすべて同じ

.gturbo

ディレクトリを使用します（同時稼働は推奨されません）。

プロダクト	用途
TurboFieldfare	Swift ライブラリ（ランタイム + Metal カーネル）
TurboFieldfareMac	インストール・生成用のネイティブ Mac アプリ
TurboFieldfareDecodeService	Mac アプリで使用するデコードサービス
TurboFieldfareCLI	コマンドラインチャット・生テキスト完了処理
TurboFieldfareServer	ループバック OpenAI 互換サーバー
TurboFieldfareRepack	ストリーミング型インストーラー・検証ツール

システム要件

• Apple Silicon Mac（M2 MacBook Air 8GB 検証済み）
• macOS 26, Metal 4
• Xcode 26, Swift 6.2+
• 空きストレージ（モデルインストール用：約 14.3 GB）
• インターネット接続（初回インストール時のみ）

互換性注意:

arm64

アーキテクチャ専用。古い macOS/Metal は非対応。

---

設定と操作方法

生成時のデフォルト設定

Mac アプリまたは CLI を使用する場合、以下が初期値です。

• 温度 (Temperature): 0.2
• Top-K: 64
• Top-P: 0.95

注意： 温度を 0 にすると決定論的な出力（greedy）になりますが、モデルは重複や誤りを起こす可能性があるため、必ず確認してください。

対応形式:

• テキスト専用チャット形式のみサポート。
• ツールの呼び出し機能は非公開（サーバーのみ関数ツール宣言を受け付く）。
• 画像・音声・動画はサポートしない。

---

アプリでの使用方法

モデルのインストール

1. リポジトリをクローンし、ルートからビルドしてください。
2. アプリ起動時、[Download] を選択。
3. インストーラーが Hugging Face から必要なバイト範囲をストリーミングして

   .gturbo

   形式に再パッケージ化します（フルチェックポイントは展開しません）。

ロードと生成

インストール完了後：

1. [Load Model] を選択。
2. コーポレーター（入力欄）にプロンプトを入力。
3. [Generate] または

   Command+Return

   で開始。
4. 停止ボタンまたは

   Escape

   キーで中断可能。

ステータスバー情報: 生成進捗、デコード速度、メモリ使用量を表示します。

---

コマンドラインインターフェース (CLI)

既存の

.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

# インストール検証（モデル読み込みなし）
swift run -c release TurboFieldfareRepack \
  --verify-install \
  --input-gturbo scratch/gemma4.gturbo

指示付きチャット (Instruction Chat)

JSON フォーマットのメッセージファイルを指定します。

[
  {"role": "user", "content": "Why does chunked prefill reduce time to first token while keeping memory bounded?"}
]

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

※応答制限は

--max-new

で設定可能（デフォルト：1,024 トークン）。Mac アプリではコンテキストウィンドウが満杯になるまで生成を続行します。

生完了処理 (Raw Completion)

チャット形式を使わず、生のテキスト完結を処理します。

swift run -c release TurboFieldfareCLI \
  --model scratch/gemma4.gturbo \
  --prompt "The capital of France is" \
  --max-new 64 \
  --temperature 0

主なオプション:

--max-context

,

--temperature

,

--top-k

,

--repetition-penalty

など。 全オプション確認：

swift run -c release TurboFieldfareCLI --help

※生成結果は標準出力、統計情報は標準エラーに出力されます（フッター抑制は

--quiet

）。

---

ローカル OpenAI 互換サーバー

起動方法

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

• URL:

  http://127.0.0.1:8080/v1

• 機能: チャット補完、ストリーミング、関数ツール利用、プレフィックス再利用。
• 注意: 単機ループバック接続用。リモート認証/TLS は非対応。

詳細なセットアップや API サブセットは ローカルサーバー 参照してください。

---

推論エンジンの動作原理

Metal と CPU の連携により、以下のように動作します：

• 変換層毎の処理: Metal がメモリ上のウェイトから注意力とルーターを計算。
• CPU 計画: ルーター上位 8 エクスパート ID を使用し、LFU キャッシュ（16 スロット）に計画。ミスヒットは有界並列リードコールで対応。
• 結合処理: Metal は読み込み中に共有エキスパート分岐を計算し、出力を結合。

主な技術的特徴:

• プリフィル: 最大 128 トークン/チャンクでの取得済みエキスパートサポート。
• 生成: ルーティングされた層ループを逐トークン実行。
• ストレージ: 有界循環ストレージ（スライドウィンドウ 25 層）、線形ストレージ（フルアテンション 5 層）。
• カスタム Metal カーネル: GEMV、注意力、MoE、正規化など全要素対応。

現在の範囲: Apple Silicon Mac (RAM 8GB+) における、ピン留めされた Gemma 4 26B-A4B チェックポイントからのテキスト専用推論に限られます。

---

ライセンスと免責事項

• ソースコード・ドキュメントは Apache License 2.0。
• モデルウェイトは含まず、インストール時は別個に Hugging Face からダウンロードします。
• ライセンス詳細:

  THIRD_PARTY_NOTICES.md

  を参照。
• TurboFieldfare は独立した研究プロジェクトで、Google とは無関係です。

---

おわりに：プロジェクト名の由来

Andrey Mikhaylov（iOS/Metal エンジニア）による開発。妻のサシャに献呈します。

名前の由来は、スズメ目の一種である「フィールドファー」(fieldfare) です。 派手さはないものの、独自の個性と特徴を持つ鳥のように、このプロジェクトも実用的でなくても構わないが、大好きな分野（オンデバイス ML 推論）で構築されたユニークなツールです。

外に出て自然に触れることをお勧めします。