Como rodar o Gemma 4 com llama.cpp: Configuração de GGUF, Hardware e Guia de Quantização

O Gemma 4 foi lançado em 2 de abril de 2026 com suporte inicial ao llama.cpp. Se você já sabe que deseja usar o llama.cpp — e não o Ollama ou o LM Studio — este guia oferece os comandos exatos e os números de hardware para obter uma primeira execução estável e, a partir daí, escalar o uso.

Se você ainda está decidindo qual runtime local usar, pule para a seção Quando o llama.cpp faz sentido primeiro.

---

Tamanhos de modelos Gemma 4 em resumo

O Gemma 4 vem em quatro variantes. Antes de baixar qualquer coisa, verifique o seu hardware em relação à tabela abaixo — esta é a fonte mais comum de problemas.

Variante	Arquitetura	Contexto	Modalidades	RAM em 4-bit	RAM em 8-bit	RAM em FP16
E2B	Densos + PLE	128K	Texto, Imagem, Áudio	~4 GB	~5–8 GB	~10 GB
E4B	Densos + PLE	128K	Texto, Imagem, Áudio	~5.5–6 GB	~9–12 GB	~16 GB
26B-A4B	MoE (4B ativos)	256K	Texto, Imagem	~16–18 GB	~28–30 GB	~52 GB
31B	Densa	256K	Texto, Imagem	~17–20 GB	~34–38 GB	~62 GB

RAM aqui significa memória total disponível — a soma da sua VRAM mais a RAM do sistema (caso você esteja distribuindo camadas) ou memória unificada no Apple Silicon. Se o seu total estiver abaixo da coluna de 4 bits, o llama.cpp ainda poderá rodar o modelo usando o descarregamento parcial em disco, mas a velocidade de geração cairá significativamente.

Escolhas rápidas:

• Mac mini M4 (16 GB de memória unificada): E4B em Q8_0, ou 26B-A4B em Q4 se você aceitar velocidades menores.
• 16 GB de VRAM (RTX 4080, RTX 4090 12 GB): E4B em Q8_0 confortavelmente; 26B-A4B em Q4 com sobra de espaço.
• 24 GB de VRAM (RTX 3090 / 4090): 26B-A4B em Q8_0 ou 31B em Q4.
• 8 GB de VRAM: E2B ou E4B apenas em Q4.

26B-A4B vs 31B: O modelo MoE 26B ativa apenas 4 bilhões de parâmetros por token, tornando-o mais rápido e leve que o denso 31B. Escolha o 26B-A4B quando a velocidade for prioritária e sua RAM for limitada; escolha o 31B quando desejar a qualidade máxima e tiver folga de hardware.

---

Quando o llama.cpp faz sentido

O llama.cpp é uma boa escolha quando você deseja:

• Controle total — parâmetros de amostragem personalizados, ajuste de cache KV, modo servidor com endpoints compatíveis com a OpenAI, geração restringida por gramática.
• Inferência focada em CPU — o llama.cpp é um dos runtimes C++ mais otimizados para cargas de trabalho apenas em CPU, incluindo suporte a AVX2/AVX-512 e Apple Metal.
• Scripts e pipelines de CI — um binário único sem dependência de Python torna a integração direta.
• Inferência multimodal através da llama-mtmd-cli e llama-server com --mmproj.

Se você deseja a execução inicial mais fácil possível — download e chat com apenas um comando — o Ollama ou o LM Studio são pontos de entrada com menos fricção. Volte aqui quando precisar de mais controle.

---

Passo 1 — Compilar o llama.cpp

Primeiro, clone o repositório. Use sempre o branch master — os lançamentos com tags costumam demorar mais para receber correções de CUDA e Metal:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

Linux com GPU NVIDIA (CUDA)

Certifique-se de que o CUDA toolkit está instalado (nvcc --version para verificar), então:

apt-get update
apt-get install -y pciutils build-essential cmake curl libcurl4-openssl-dev

cmake llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=ON

cmake --build llama.cpp/build \
  --config Release -j --clean-first \
  --target llama-cli llama-mtmd-cli llama-server llama-gguf-split

cp llama.cpp/build/bin/llama-* llama.cpp/

Verifique se o descarregamento para a GPU está funcionando após o build:

./llama.cpp/llama-cli -m seu-modelo.gguf -p "Olá" -n 5 --n-gpu-layers 99

Se você vir offloaded 0/N layers, o binário foi compilado sem CUDA — limpe o diretório build/ e recompile do zero.

macOS (Apple Silicon — Metal)

O Metal é ativado por padrão no macOS. Você não precisa de -DGGML_CUDA=ON. Apenas compile normalmente:

brew install cmake

cmake llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=OFF

cmake --build llama.cpp/build \
  --config Release -j --clean-first \
  --target llama-cli llama-mtmd-cli llama-server

cp llama.cpp/build/bin/llama-* llama.cpp/

No Apple Silicon, a "VRAM" e a RAM do sistema fazem parte do mesmo pool de memória unificada — portanto, um M3 Pro de 24 GB pode endereçar os 24 GB completos para os pesos do modelo.

Apenas CPU (sem GPU)

cmake llama.cpp -B llama.cpp/build \
  -DBUILD_SHARED_LIBS=OFF \
  -DGGML_CUDA=OFF

cmake --build llama.cpp/build \
  --config Release -j$(nproc) \
  --target llama-cli llama-server

cp llama.cpp/build/bin/llama-* llama.cpp/

O CMake detecta automaticamente o suporte a AVX2/AVX-512 na sua CPU host e ativa as otimizações adequadas. A inferência pela CPU é mais lenta, mas plenamente funcional.

---

Passo 2 — Escolher um GGUF e baixá-lo

Qual quantização escolher

Quantização	Tamanho do arquivo (aprox.)	Qualidade	Ideal para
Q8_0	~1× o tamanho de Q4	Próximo ao FP16	E2B e E4B quando você tem folga na RAM
Q4_K_M	Médio	Bom equilíbrio	26B-A4B e 31B em VRAM de 24 GB
UD-Q4_K_XL	Ligeiramente maior que Q4_K_M	Melhor que Q4_K_M	26B-A4B e 31B; Formato dinâmico da Unsloth
Q2_K	Menor de todos	Queda de qualidade notável	Apenas se você não tiver outra opção

Os pontos de partida recomendados pela Unsloth (que mantém a principal coleção de GGUF):

• E2B / E4B → comece com Q8_0
• 26B-A4B / 31B → comece com UD-Q4_K_XL

---

Passo 3 — Executar inferência de texto

O llama.cpp define automaticamente o tamanho do contexto — você não precisa passar o parâmetro -c. Use os parâmetros abaixo, que correspondem aos padrões oficiais recomendados pelo Google.

Chat interativo com llama-cli

E4B (Q8_0):

export LLAMA_CACHE="unsloth/gemma-4-E4B-it-GGUF"

./llama.cpp/llama-cli \
  -hf unsloth/gemma-4-E4B-it-GGUF:Q8_0 \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  -cnv

Servidor compatível com OpenAI (llama-server)

Inicie um servidor local na porta 8080 que qualquer ferramenta com um cliente OpenAI possa chamar:

./llama.cpp/llama-server \
  -m unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  --port 8080

Em seguida, teste com curl:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4",
    "messages": [{"role": "user", "content": "Explique o que é atenção em um parágrafo."}]
  }'

---

Passo 4 — Inferência Multimodal (imagem)

O Gemma 4 suporta entrada de imagens no llama.cpp desde o lançamento, mas isso exige um segundo arquivo GGUF: o projetor multimodal (mmproj). O projetor cuida da codificação da imagem antes que o modelo de linguagem a processe.

O que você precisa

1. O GGUF do modelo de linguagem (o mesmo usado para texto)
2. O arquivo mmproj-BF16.gguf do mesmo repositório do Hugging Face

Executar com llama-mtmd-cli (CLI)

./llama.cpp/llama-mtmd-cli \
  --model unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --mmproj unsloth/gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64

Você poderá então referenciar imagens na conversa usando a sintaxe [img]caminho/para/imagem.jpg[/img].

Executar com llama-server (API)

./llama.cpp/llama-server \
  --model unsloth/gemma-4-26B-A4B-it-GGUF/gemma-4-26B-A4B-it-UD-Q4_K_XL.gguf \
  --mmproj unsloth/gemma-4-26B-A4B-it-GGUF/mmproj-BF16.gguf \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  --port 8080

Nota sobre áudio: O E2B e o E4B suportam entradas de áudio nativamente, mas o suporte a áudio no llama.cpp ainda está em desenvolvimento ativo em abril de 2026. A inferência de texto e imagem está totalmente estável.

---

Solução de problemas comuns

"offloaded 0 layers" após o build

A compilação com CUDA não foi vinculada corretamente. Limpe o diretório de build e recompile:

rm -rf llama.cpp/build
# Repita os passos do cmake com -DGGML_CUDA=ON

Falta de memória (OOM) no carregamento

Sua memória total é inferior ao tamanho do modelo, mesmo após a quantização. Opções:

1. Mude para uma quantização menor (ex: Q4_K_M → Q2_K).
2. Use uma variante menor do modelo (ex: 31B → 26B-A4B, ou 26B-A4B → E4B).
3. Use --n-gpu-layers N com um valor menor de N para carregar menos camadas na VRAM — o restante usará a RAM do sistema com velocidade reduzida.

---

Perguntas Frequentes

O llama.cpp suporta oficialmente o Gemma 4? Sim. O suporte ao Gemma 4 foi incluído no lançamento em 2 de abril de 2026. Todos os quatro tamanhos de modelos funcionam com llama-cli, llama-server e llama-mtmd-cli.

Posso rodar o Gemma 4 em um Mac mini? Sim. Um Mac mini M4 com 16 GB de memória unificada pode rodar o E4B em Q8_0 confortavelmente, ou o 26B-A4B em Q4 com velocidade aceitável. O M4 Pro (24 GB) lida com o 26B-A4B em Q8_0.

Preciso de uma GPU? Não. O llama.cpp roda apenas com CPU. O descarregamento para a GPU (CUDA ou Metal) melhora significativamente os tokens por segundo, mas a inferência por CPU é totalmente suportada e prática para modelos menores como o E2B e o E4B.

---

Próximos passos

Assim que a inferência de texto estiver estável, os próximos passos naturais são:

• Tentar o 26B-A4B para um salto significativo de qualidade em relação ao E4B com apenas um pequeno aumento de exigência de hardware.
• Experimentar entradas multimodais usando a llama-mtmd-cli.
• Comparar o llama.cpp com o Ollama se você desejar um fluxo de trabalho diário mais simples.

O erro mais comum é baixar o maior modelo disponível antes de confirmar que o menor roda bem. Uma configuração estável do E4B é mais útil do que uma de 31B que roda a 1 token por segundo.

---

Guias relacionados

• Requisitos de hardware do Gemma 4
• Comparação de modelos Gemma 4
• Como rodar o Gemma 4 no Ollama
• Como rodar o Gemma 4 no LM Studio
• Guia da API do Gemma 4