Como executar um modelo de 26 bilhões de parâmetros em dois gigabytes de memória em um Mac comum

Se você tem um MacBook Air básico com M2 e 8 GB de memória unificada, executar modelos de linguagem modernos se torna uma história triste. Mesmo um modelo modesto de 14 a 20 bilhões de parâmetros após quantização de 4 bits requer 10 a 16 GB de RAM. O sistema começa a trocar dados agressivamente para o disco, a velocidade de geração cai para frações de um token por segundo, e a interface do macOS começa a congelar.

O engenheiro Andrey Mikhailov resolveu esse problema com um truque de engenharia nada convencional. Ele escreveu do zero um runtime chamado TurboFieldfare que executa o modelo de instrução Gemma 4 26B-A4B do Google em apenas 2 GB de RAM.

Qual é o principal truque da arquitetura

O Gemma 4 26B-A4B é construído sobre uma arquitetura de Mistura de Especialistas (MoE). Possui 26 bilhões de parâmetros no total, mas nem todas as camadas são ativadas para processar um token específico—apenas cerca de 3,88 bilhões de parâmetros.

Normalmente, runtimes como llama.cpp ou MLX carregam todos os pesos do modelo na memória antes de iniciar o trabalho. Para o Gemma de 4 bits, isso é cerca de 14,3 GB. O TurboFieldfare faz as coisas de forma diferente:

• O núcleo compartilhado do modelo pesando 1,35 GB e o KV-cache FP16 para contexto são mantidos em RAM persistente.
• O roteador do modelo em cada camada determina quais 8 especialistas são necessários para o token atual.
• O programa verifica o cache local de especialistas na memória (16 slots com um algoritmo LFU).
• Se o especialista necessário não estiver na RAM, o runtime o carrega rapidamente diretamente do SSD através de chamadas de sistema paralelas pread em buffers acessíveis ao Metal.

Enquanto a GPU calcula o ramo de especialista compartilhado, uma thread CPU paralela consegue ler os pesos ausentes do armazenamento. Como resultado, o consumo máximo de memória cabe em aproximadamente 2 GB.

Sem dependências do llama.cpp e MLX

O projeto é escrito puramente em Swift 6.2 e Metal 4. O autor não criou outro wrapper em torno de bibliotecas C++ existentes—ele escreveu kernels GPU personalizados para quantização, multiplicação de matrizes (GEMV), atenção, MoE, normalização RMSNorm e RoPE.

O repositório inclui quatro utilitários prontos para uso:

1. TurboFieldfareMac — uma aplicação desktop nativa construída com SwiftUI e AppKit com chat integrado, monitoramento de memória e configurações de geração.
2. TurboFieldfareCLI — uma interface de linha de comando para geração em lote e execução orientada por scripts através de arquivos de mensagens JSON.
3. TurboFieldfareServer — um servidor local com uma API compatível com a especificação OpenAI Chat Completions (http://127.0.0.1:8080/v1).
4. TurboFieldfareRepack — um utilitário para streaming de downloads de pesos do Hugging Face diretamente no formato personalizado .gturbo.

O instalador baixa apenas os intervalos de bytes necessários e os empacota em tempo real. Você não precisará primeiro baixar 15 GB de pesos de origem e depois manter mais 15 GB do arquivo convertido junto com ele.

Desempenho no mundo real

Leituras em streaming do disco inevitavelmente criam latência de E/S. Não há milagres: a velocidade de geração depende diretamente da taxa de transferência do SSD e de um cache rápido.

O autor realizou uma série de benchmarks em diferentes gerações de Apple Silicon:

• Em um MacBook Air M2 básico com 8 GB de RAM, a velocidade atinge 5,1–6,3 tokens por segundo. Este é um ritmo confortável para ler texto em tempo real.
• Em um MacBook Pro com M5 Pro e 24 GB de memória, a velocidade de geração atinge 31–35 tokens por segundo.

Para a fase de pré-preenchimento (processamento do prompt de entrada), o autor implementou fragmentação em 128 tokens. Isso ajuda a invocar um único especialista carregado para um grupo de linhas de uma vez, reduzindo perceptivelmente o tempo até o primeiro token.

Como compilar e executar

A compilação requer um Mac com Apple Silicon executando uma versão atual do macOS e Xcode com suporte ao Swift 6.2.

Clone o repositório e compile o projeto em modo release:

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

Após compilar, inicie a aplicação nativa:

.build/release/TurboFieldfareMac

Na primeira execução, clique no botão Download. O aplicativo baixará o modelo (cerca de 15 GB de espaço livre em disco necessário) e preparará o diretório scratch/gemma4.gturbo. Após a conclusão do download, clique em Load Model e digite sua pergunta no campo de entrada.

Se preferir o console, você pode baixar o modelo com um comando separado:

swift run -c release TurboFieldfareRepack \
  --output scratch/gemma4.gturbo \
  --overwrite

Em seguida, passe um arquivo de diálogo para a CLI:

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

E para conectar clientes locais como OpenCode ou scripts Python personalizados, basta iniciar o servidor:

.build/release/TurboFieldfareServer --model scratch/gemma4.gturbo

O servidor escuta na porta 8080 e fornece os endpoints familiares /v1/chat/completions com suporte a streaming e chamadas de ferramentas.

Onde o projeto será útil na prática

Este não é um mecanismo universal para qualquer peso. O TurboFieldfare é estritamente adaptado para um modelo específico—Gemma 4 26B-A4B. Mas dentro de seu nicho, o projeto cobre vários cenários concretos:

• Assistente de desenvolvedor local em laptops de baixo custo. Se você tem 8 GB de RAM, executar um modelo 26B de qualquer outra forma sem congelar todo o sistema é praticamente impossível.
• Servidor em segundo plano para chamadas de ferramentas e análise de texto através da interface loopback sem enviar dados confidenciais para a nuvem.
• Recurso educacional para otimização Metal de baixo nível. O repositório inclui um log de 103 experimentos detalhados com benchmarks para velocidades de leitura, cache e desempenho de kernels GPU.

Se você quiser executar grandes modelos MoE localmente em um MacBook básico ou estiver interessado em escrever shaders Metal personalizados para ML, o repositório definitivamente vale a pena clonar e estudar.