drumih/turbo-fieldfare · 上手攻略

• 仓库：drumih/turbo-fieldfare
• 链接：https://github.com/drumih/turbo-fieldfare
• 分类：Apple Silicon · 本地 LLM 推理 · MoE 稀疏化
• 作者：Tom
• 更新：2026-08-02

这是什么

TurboFieldfare 是一个用 Swift 6.2 + Metal 4 从零手写的 Gemma 4 26B-A4B 推理运行时，专为 Apple Silicon Mac 设计。它的核心目标只有一个：让 8 GB 内存的 M 系列 MacBook Air 也能跑 Gemma 4 26B 大模型。

Gemma 4 26B 是一个 MoE（Mixture-of-Experts）架构的指令微调模型，总参数量 26 B，每 token 激活约 3.88 B 参数。模型共 30 层 transformer（25 层滑动窗口注意力 + 5 层全注意力），每层有 128 个路由专家，每步从中选择 8 个。同时还有一个 dense shared expert，与路由专家并行输出。完整模型文本形式约 14.3 GB，传统方式需要全部加载进内存——8 GB Mac 直接 OOM，根本跑不起来。

TurboFieldfare 的解决思路是专家流式化（expert streaming）：

• 约 1.35 GB 共享核心常驻内存（embedding、attention 投影、shared expert、FP16 KV cache）
• 其余 per-layer 路由专家按需从 SSD 读取，每个 token 只需读 8 个专家
• 内存占用压到 ~2 GB，8 GB M2 MacBook Air 完全可跑

这不是 MLX 或 llama.cpp 的包装，而是一个模型专用的高度特化 runtime——Swift 代码直接对接 Metal kernels，不经过任何第三方 ML 框架。

解决什么问题

内存墙是 Apple Silicon 本地跑大模型的核心瓶颈。Gemma 4 26B 的 MoE 结构天然支持稀疏激活，TurboFieldfare 把这个稀疏性工程化为真实的内存节省：

• 路由器每步从 128 个专家选 8 个，稀疏度 93.75%
• 每层一个 layer_XX.bin 文件（128 个专家的 blob），按需 mmap 读取
• 量化方案：embedding/head 用 MLX affine 4-bit（group 64），路由器用 8-bit，shared expert 和 routed experts 用 4-bit
• 嵌入层和 LM head 共享同一套量化权重，避免重复存储

另一个工程亮点是流式安装器（TurboFieldfareRepack）：不下载完整 HuggingFace checkpoint 快照到磁盘再重排，而是直接根据 pinned 版本（mlx-community/gemma-4-26b-a4b-it-4bit at revision 0d77464e）的 index 发起 bounded range requests，逐块读取、打散、重打包进 .gturbo 目录。安装过程最大 scratch buffer 仅 524,288 字节（约 512 KB），15 GB 级别的源数据从不整体落入 Swift 堆。安装完成后 manifest + verified-install.json 双校验，确保完整性。

快速安装

环境要求（硬性）

⚠️ macOS 26 + Metal 4 是硬性门槛。当前（2026-08）macOS 最新稳定版为 15.x，26 仍在 beta 阶段。使用前请确认系统版本。旧版 macOS 构建会报 Swift 6.2 兼容错误。

方式一：Mac 原生 App（推荐入门）

git clone https://github.com/drumih/turbo-fieldfare.git
cd turbo-fieldfare

# 完整构建（包含 Mac App + decode service sibling）
swift build -c release

# 启动 App（从仓库根目录运行，模型存 scratch/gemma4.gturbo）
.build/release/TurboFieldfareMac

App 首次启动后： 1. 自动检测可用存储空间，显示下载大小 2. 点 Download → 流式下载模型（约 15 GB，需时视网络而定） 3. 安装完成后点 Load Model 加载模型 4. 底部状态栏实时显示 tok/s 速度和内存占用 5. 右面板可调 sampling 参数、context 长度、expert-cache 槽数

方式二：CLI（无 GUI）

CLI 需要已有 .gturbo 模型安装（由 App 完成）：

# 交互式聊天（读取已安装模型）
.build/release/TurboFieldfareCLI --model scratch/gemma4.gturbo

方式三：OpenAI 兼容 Server

适合接入现有工具链（需先通过 App 安装模型）：

# 构建 Server
swift build -c release --product TurboFieldfareServer

# 启动（需确认无其他 TurboFieldfare 进程运行）
pgrep -fl 'TurboFieldfareServer|TurboFieldfareMac|TurboFieldfareCLI|TurboFieldfareDecodeService|mlx'
# 若无输出则安全启动：
.build/release/TurboFieldfareServer \
 --model scratch/gemma4.gturbo \
 --port 8080 \
 --max-context 16384

# curl 验证
curl --silent --show-error http://127.0.0.1:8080/health
curl --silent --show-error http://127.0.0.1:8080/v1/models

方式四：仅安装模型（Repack 工具）

不启动任何推理进程，纯粹把 HuggingFace 模型流式安装到本地目录：

swift build -c release --product TurboFieldfareRepack
.build/release/TurboFieldfareRepack \
 --source hf://mlx-community/gemma-4-26b-a4b-it-4bit \
 --target /path/to/gemma4.gturbo

核心用法详解

Mac App 使用

App 把用户输入当作指令，自动处理 Gemma 的 chat formatting，无需手动构造 chat template。

快捷键： - Command+Return 发送（默认）；Settings > Send Message With 可改为直接回车 - Escape 或点停止按钮可提前终止生成

采样默认值： - temperature: 0.2 - Top-K: 64 - Top-P: 0.95

设 temperature 为 0 可得确定性贪婪输出。

OpenAI 兼容 Server 完整调用示例

Python 客户端：

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="local")

# 普通聊天
response = client.chat.completions.create(
    model="gemma-4-26b-a4b-it",
    messages=[
        {"role": "system", "content": "你是一个有帮助的助手。"},
        {"role": "user", "content": "用一句话解释量子纠缠。"}
    ],
    temperature=0.7,
    max_completion_tokens=256,
)
print(response.choices[0].message.content)

# 工具调用（Server 返回 tool_calls，客户端负责执行）
tools_response = client.chat.completions.create(
    model="gemma-4-26b-a4b-it",
    messages=[{"role": "user", "content": "帮我查一下北京的天气。"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"]
            }
        }
    }],
    tool_choice="auto",
)
# finish_reason == "tool_calls" 时，客户端执行工具并追加结果重新调用

cURL 测试：

curl --silent --show-error http://127.0.0.1:8080/v1/chat/completions \
 -H 'Content-Type: application/json' \
 -d '{
   "model": "gemma-4-26b-a4b-it",
   "messages": [{"role": "user", "content": "Reply with exactly READY."}],
   "temperature": 0,
   "max_completion_tokens": 16
 }'

Prompt KV 复用：默认开启，同一对话历史继续时会报告 usage.prompt_tokens_details.cached_tokens。需关闭可加 --prompt-cache-mode off。

流式输出：设置 "stream": true 即可，支持 stream_options: {"include_usage": true} 收到最终 usage。

不支持的功能：Responses API、旧版 Completions、embeddings、multimodal input、structured output、batching、log probabilities、remote model switching。

典型适用场景

1. 8 GB M 系列 MacBook Air 用户想跑大模型：这是 TurboFieldfare 的核心场景，也是它的独有能力——8 GB M2 上 MLX 需要 8+ GB 物理内存直接 OOM，而 TurboFieldfare ~2 GB 可正常运行。

2. 内存受限多任务环境：需要同时运行 Chrome、IDE、Slack 等应用，不想被 MLX 8-15 GB 内存占用挤掉所有工作空间。

3. 快速本地 demo / 离线创意写作：对延迟不敏感（M2 上 5-6 tok/s，M5 Pro 上 31-35 tok/s），但需要稳定、离线的本地推理能力。

4. API 化本地嵌入：通过 OpenAI 兼容接口接入现有 pipeline，适合 CI/CD 自动化测试、隐私敏感数据处理。

5. Apple 开发者生态集成：Swift + Metal 原生实现，方便嵌入 macOS App，而非跑一个独立的 Python 推理服务。

坑与注意

与同类横向对比

如何选： - 8 GB Mac → TurboFieldfare（唯一选择） - 24+ GB Mac，优先速度 → MLX（快 2-3 倍） - 跨平台 / 需要灵活切换模型 → llama.cpp 或 Ollama - 需要 macOS 旧版本兼容 → Ollama（要求最低）

⚠️ TurboFieldfare vs MLX 的速度对比不公平：TurboFieldfare 的核心价值是在 8 GB 硬件约束下可运行；MLX 对比在 M5 Pro 24 GB 上跑，不在同一条件下。官方 benchmark 本身也注明了两者的硬件条件差异。

一句话推荐结论

如果你有一台 8 GB M 系列 Mac 想本地跑 Gemma 4 26B，TurboFieldfare 是目前已知唯一能把内存占用压到 ~2 GB 的方案——代价是 macOS 26 硬性要求、单一模型锁定、以及比 MLX 慢 2-3 倍的生成速度；24+ GB 内存的 Mac 用户建议直接用 MLX 获得更完整的生态和更快速度。

最小可跑命令清单

# ── 环境 ──────────────────────────────────────────────
# Apple Silicon Mac（实测 M2 8 GB）
# macOS 26 / Metal 4 / Xcode 26 / Swift 6.2
# 约 14.3 GB 可用磁盘空间

# ── 1. 克隆构建 ────────────────────────────────────────
git clone https://github.com/drumih/turbo-fieldfare.git
cd turbo-fieldfare
swift build -c release

# ── 2. 启动 Mac App（交互式）──────────────────────────
# 模型自动从 HuggingFace 流式安装（约 15 GB）
.build/release/TurboFieldfareMac

# ── 3. OpenAI 兼容 Server ─────────────────────────────
#（需先通过 App 完成模型安装）
swift build -c release --product TurboFieldfareServer
.build/release/TurboFieldfareServer \
 --model scratch/gemma4.gturbo \
 --port 8080 \
 --max-context 16384

# 验证
curl --silent http://127.0.0.1:8080/health

来源

• GitHub README：https://github.com/drumih/turbo-fieldfare
• System Design：https://github.com/drumih/turbo-fieldfare/blob/main/docs/SYSTEM_DESIGN.md
• Benchmarks：https://github.com/drumih/turbo-fieldfare/blob/main/docs/BENCHMARKS.md
• OpenAI Server：https://github.com/drumih/turbo-fieldfare/blob/main/docs/OPENAI_SERVER.md
• Prompt KV 复用：README / OpenAI Server 文档
• 社区对比参考：PyImageSearch "Running Gemma 4 Locally: Ollama, llama.cpp, MLX, and More"（2026-07-20）；BirJob "Running Gemma 4 Locally on Apple Silicon: MLX vs llama.cpp"；X/Twitter @kernelpool MLX vs llama.cpp Gemma 4 26B on M3 Ultra 对比（2026-04）

⚠️ 所有 benchmark 数字均来自 README 内嵌文档及社区记录，未经独立复现。TurboFieldfare 官方 benchmark 硬件条件为 8 GB M2 MacBook Air（macOS 26）和 24 GB M5 Pro（macOS 26.5.1, Xcode 26.6, Swift 6.3.3）；MLX 对比同文档注明非公平对比，结果仅供参考，不构成性能承诺。