Como Rodar Gemma 4 31B Localmente: Unsloth, Ollama, llama.cpp e HuggingFace

O Google DeepMind lançou o Gemma 4 no começo de 2026, e a variante de 31B instruction-tuned acerta em cheio: grande o suficiente pra competir com modelos proprietários em benchmarks de raciocínio, pequeno o suficiente pra rodar numa placa de vídeo decente. Ele faz 85.2% no MMLU Pro e 89.2% no AIME 2026 sem ferramentas, o que coloca ele no mesmo patamar de modelos com o dobro do tamanho.

O problema sempre foi "como eu realmente rodo isso?" Um modelo de 30.7B parâmetros em precisão total precisa de uns 62GB de VRAM. Ninguém tem isso sobrando numa única placa. Mas com a quantização certa e as ferramentas certas, dá pra rodar numa RTX 4090 de 24GB, ou até offload parcialmente pra CPU numa placa de 16GB. Recomendamos usar a LightNode como provedor de VPS se você quiser instâncias GPU sem compromisso.

Esse guia cobre quatro métodos, com o Unsloth como recomendação principal pra maioria das pessoas.

Sumário

1. Visão Geral da Família Gemma 4
2. Requisitos de Hardware
3. Método 1: Unsloth Studio (Recomendado)
4. Método 2: Ollama
5. Método 3: llama.cpp
6. Método 4: HuggingFace Transformers
7. Entendendo os Formatos de Quantização GGUF
8. Dicas de Performance
9. Solução de Problemas
10. Qual Método Escolher?

Visão Geral da Família Gemma 4

O Gemma 4 vem em quatro tamanhos. Escolher o certo importa porque o salto de hardware entre eles é grande.

Variante	Params Totais	Params Ativos	Contexto	Modalidades	Melhor Para
E2B	5.1B	2.3B efetivos	128K	Texto, Imagem, Áudio	Celulares, Raspberry Pi
E4B	8B	4.5B efetivos	128K	Texto, Imagem, Áudio	Notebooks, só CPU
26B A4B (MoE)	25.2B	3.8B ativos	256K	Texto, Imagem	Inferência rápida, menos VRAM
31B (Dense)	30.7B	30.7B	256K	Texto, Imagem	Qualidade máxima

O 26B A4B é o esperto: 25.2B parâmetros totais, mas só 3.8B ativos durante a inferência graças a uma arquitetura Mixture-of-Experts (8 experts ativos de 128, mais 1 compartilhado). Roda quase tão rápido quanto um modelo de 4B enquanto entrega qualidade perto do 31B completo. Se sua GPU tem 12-16GB de VRAM, o 26B A4B em quantização Q4 é provavelmente sua melhor aposta.

O 31B Dense é o foco desse guia. É o modelo completo com todos os parâmetros ativos em cada passada. Melhor qualidade, maiores requisitos de hardware.

Todas as quatro variantes suportam modo de pensamento configurável (raciocínio chain-of-thought), prompts de sistema nativos, function calling e mais de 140 idiomas.

Requisitos de Hardware

Antes de escolher um método, veja com que hardware você está trabalhando.

Para Gemma 4 31B-it

Quantização	VRAM Necessária	Perda de Qualidade	Hardware Típico
FP16 (precisão total)	~62 GB	Nenhuma	A100, múltiplas GPUs
Q8_0 (8-bit)	~32 GB	Desprezível	RTX 4090 (24GB) + offload CPU
Q5_K_M (5-bit)	~22 GB	Mínima	RTX 4090, RTX 3090
Q4_K_M (4-bit)	~18 GB	Pequena	RTX 4080, RTX 3090
Q3_K_M (3-bit)	~14 GB	Notável	RTX 4070, offload parcial

Para Gemma 4 26B A4B (MoE)

Quantização	VRAM Necessária	Perda de Qualidade	Hardware Típico
Q5_K_M	~14 GB	Mínima	RTX 4070 Ti
Q4_K_M	~10 GB	Pequena	RTX 4070, RTX 3080
Q3_K_M	~8 GB	Notável	RTX 4060 Ti 8GB

Se você só tem CPU, as variantes E4B ou E2B rodam tranquilamente. O 31B em CPU é tecnicamente possível mas dolorosamente lento (espere 1-3 tokens/segundo num CPU moderno).

Requisito de RAM: Adicione 8-16GB de RAM do sistema além da VRAM pra overhead do runtime, mais se você estiver fazendo offload de camadas pra CPU.

Método 1: Unsloth Studio (Recomendado)

O Unsloth é a forma mais fácil de rodar o Gemma 4 localmente. É uma interface web que cuida do download do modelo, seleção de quantização e inferência num pacote só. Funciona no Windows, Linux, macOS e WSL.

Por que Unsloth

• Busca e download de modelos com um clique do HuggingFace
• Escolhe automaticamente a quantização GGUF certa pro seu hardware
• Interface de chat integrada com suporte a imagens, PDFs e documentos
• Tool calling e busca web integrados
• Sandbox de execução de código
• Sem dor de cabeça com linha de comando

Instalação

macOS, Linux, WSL:

curl -fsSL https://unsloth.ai/install.sh | sh

Windows (PowerShell):

irm https://unsloth.ai/install.ps1 | iex

Docker:

docker run -d -e JUPYTER_PASSWORD="mypassword" \
  -p 8888:8888 -p 8000:8000 -p 2222:22 \
  -v $(pwd)/work:/workspace/work \
  --gpus all \
  unsloth/unsloth

Iniciando

unsloth studio -H 0.0.0.0 -p 8888

Abra http://localhost:8888 no navegador. Você vai ver a interface do Unsloth Studio.

Rodando o Gemma 4 31B

1. Busque o modelo: Na barra de busca, digite gemma-4-31B
2. Escolha uma quantização: O Unsloth hospeda arquivos GGUF pré-quantizados. Pra uma GPU de 24GB, selecione Q4_K_M ou Q5_K_M. Pra 16GB, vá com Q3_K_M
3. Download: Clique em download. A variante Q4_K_M tem uns 18GB
4. Comece a conversar: Após o download, o modelo carrega automaticamente na interface de chat

O Unsloth fornece essas variantes GGUF do Gemma 4 31B-it:

Arquivo	Tamanho	Quantização
gemma-4-31B-it-Q3_K_M.gguf	~14 GB	3-bit (equilibrado)
gemma-4-31B-it-Q4_K_M.gguf	~18 GB	4-bit (recomendado)
gemma-4-31B-it-Q5_K_M.gguf	~22 GB	5-bit (alta qualidade)
gemma-4-31B-it-Q6_K.gguf	~26 GB	6-bit (quase sem perdas)
gemma-4-31B-it-Q8_0.gguf	~32 GB	8-bit (praticamente sem perdas)

O repositório no HuggingFace fica em unsloth/gemma-4-31B-it-GGUF.

Usando a Interface de Chat

O chat do Unsloth Studio suporta:

• Conversas de texto com toggle de modo de pensamento
• Upload de imagens: Arraste e solte imagens pra perguntas visuais
• Upload de PDF/DOCX: Extraia e discuta conteúdos de documentos
• Execução de código: O modelo pode escrever e testar código num sandbox
• Prompts de sistema customizados: Defina comportamento e persona

Pra ativar o modo de pensamento do Gemma 4, ative a opção "Thinking" nas configurações do chat. Isso ativa o raciocínio chain-of-thought, onde o modelo trabalha os problemas passo a passo antes de dar a resposta final.

Fine-Tuning com Unsloth

Se você quiser ir além da inferência, o Unsloth também cuida do treinamento:

• Fine-tuning LoRA: Treine adaptadores com até 70% menos VRAM
• Aprendizado por reforço GRPO: A biblioteca RL mais eficiente disponível
• Data Recipes: Crie datasets de treinamento automaticamente a partir de PDFs, CSVs, DOCX
• Suporte multi-GPU: Disponível agora com melhorias chegando

Pra fine-tuning do Gemma 4 31B, você vai precisar de pelo menos uma GPU de 24GB com QLoRA (treinamento quantizado em 4-bit).

Atualizando o Unsloth

Rode o mesmo comando de instalação novamente:

# macOS/Linux/WSL
curl -fsSL https://unsloth.ai/install.sh | sh

# Windows
irm https://unsloth.ai/install.ps1 | iex

Método 2: Ollama

O Ollama é a forma mais rápida de começar se você prefere a linha de comando. Ele cuida do download dos modelos, detecção de GPU e serving automaticamente.

Instalação

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# Baixe de https://ollama.com/download

Rodando o Gemma 4

# Puxe e rode o modelo 31B
ollama run gemma4:31b-it

# Ou a variante MoE menor pra menos VRAM
ollama run gemma4:26b-a4b-it

# Ou os modelos dense menores
ollama run gemma4:e4b-it
ollama run gemma4:e2b-it

O Ollama quantiza automaticamente pra Q4_K_M por padrão. Se você quiser uma quantização diferente:

# Rode com quantização específica
ollama run gemma4:31b-it-q5_K_M

Usando a API

O Ollama expõe uma API local na porta 11434:

import requests

response = requests.post('http://localhost:11434/api/chat', json={
    "model": "gemma4:31b-it",
    "messages": [
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "Write a Python function to merge two sorted lists."}
    ],
    "stream": False
})

print(response.json()['message']['content'])

Prós e Contras do Ollama

Prós: Zero configuração, detecção automática de GPU, CLI limpa, servidor de API incluído, gerenciamento simples de modelos.

Contras: Menos opções de quantização que o llama.cpp, suporte a imagem não disponível pra todos os modelos (verifique compatibilidade atual), menos controle sobre parâmetros de inferência.

Método 3: llama.cpp

Pra controle máximo sobre quantização, uso de memória e parâmetros de inferência, o llama.cpp é o caminho. É o que roda por baixo dos panos do Ollama e do Unsloth pra inferência GGUF.

Compilando do Código Fonte

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

# Com suporte CUDA (NVIDIA)
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

# Com suporte Metal (macOS Apple Silicon)
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release -j$(nproc)

# Só CPU
cmake -B build
cmake --build build --config Release -j$(nproc)

Baixando o Modelo GGUF

Pegue o modelo quantizado do repositório do Unsloth no HuggingFace:

# Instale huggingface-cli
pip install huggingface-hub

# Download Q4_K_M (recomendado pra GPUs de 24GB)
huggingface-cli download unsloth/gemma-4-31B-it-GGUF \
  gemma-4-31B-it-Q4_K_M.gguf \
  --local-dir ./models

# Ou Q5_K_M pra melhor qualidade
huggingface-cli download unsloth/gemma-4-31B-it-GGUF \
  gemma-4-31B-it-Q5_K_M.gguf \
  --local-dir ./models

Rodando o Modelo

# Chat básico
./build/bin/llama-cli \
  -m ./models/gemma-4-31B-it-Q4_K_M.gguf \
  -ngl 99 \
  -c 8192 \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64 \
  -p "You are a helpful assistant.\nUser: Explain quantum computing in simple terms.\nAssistant:"

Flags importantes:

• -ngl 99: Offload todas as camadas pra GPU. Reduza esse número se você não tiver VRAM suficiente (ex.: -ngl 40 faz offload de cerca de dois terços das camadas)
• -c 8192: Comprimento do contexto em tokens. Aumente até 256K pra documentos longos, mas mais contexto usa mais VRAM
• --temp 1.0: O Google recomenda temperature=1.0 pro Gemma 4
• --top-p 0.95 e --top-k 64: Parâmetros de sampling recomendados

Iniciando um Servidor

./build/bin/llama-server \
  -m ./models/gemma-4-31B-it-Q4_K_M.gguf \
  -ngl 99 \
  -c 8192 \
  --host 0.0.0.0 \
  --port 8080 \
  --temp 1.0 \
  --top-p 0.95 \
  --top-k 64

Depois acesse a interface web em http://localhost:8080 ou chame a API compatível com OpenAI:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="unused")

response = client.chat.completions.create(
    model="gemma-4-31b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Write a Rust function to reverse a linked list."}
    ]
)

print(response.choices[0].message.content)

Estratégia de Offload pra GPU

Se sua GPU não tem VRAM suficiente pro modelo completo, você pode dividir camadas entre GPU e CPU:

# Pra uma GPU de 16GB com o modelo Q4 (~18GB total)
# Offload umas 40 camadas pra GPU, resto pra CPU
./build/bin/llama-cli \
  -m ./models/gemma-4-31B-it-Q4_K_M.gguf \
  -ngl 40 \
  -c 4096

Isso roda mais lento que offload completo pra GPU mas cabe em placas menores. Espere uns 5-15 tokens/segundo dependendo do seu CPU e de quantas camadas você faz offload.

Método 4: HuggingFace Transformers

Se você está construindo uma aplicação e precisa de controle programático, o HuggingFace Transformers dá acesso direto ao modelo com precisão total ou quantização customizada.

Instalação

pip install -U transformers torch accelerate

Pra suporte a imagens:

pip install -U transformers torch torchvision accelerate

Rodando em Precisão Total (62GB+ VRAM)

from transformers import AutoProcessor, AutoModelForCausalLM

MODEL_ID = "google/gemma-4-31B-it"

processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    dtype="auto",
    device_map="auto"
)

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Explain the difference between TCP and UDP."},
]

text = processor.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
    enable_thinking=False
)

inputs = processor(text=text, return_tensors="pt").to(model.device)
input_len = inputs["input_ids"].shape[-1]

outputs = model.generate(**inputs, max_new_tokens=1024)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)
result = processor.parse_response(response)
print(result)

Rodando com Quantização 4-bit (18GB VRAM)

from transformers import AutoProcessor, AutoModelForCausalLM, BitsAndBytesConfig

MODEL_ID = "google/gemma-4-31B-it"

# Config de quantização 4-bit
quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16
)

processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    quantization_config=quantization_config,
    device_map="auto"
)

Processando Imagens

O modelo 31B suporta entrada de texto e imagem:

from transformers import AutoProcessor, AutoModelForMultimodalLM

MODEL_ID = "google/gemma-4-31B-it"

processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForMultimodalLM.from_pretrained(
    MODEL_ID,
    dtype="auto",
    device_map="auto"
)

messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://example.com/photo.jpg"},
            {"type": "text", "text": "Describe what you see in this image."}
        ]
    }
]

inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    add_generation_prompt=True,
).to(model.device)

input_len = inputs["input_ids"].shape[-1]
outputs = model.generate(**inputs, max_new_tokens=512)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)
result = processor.parse_response(response)
print(result)

Ativando o Modo de Pensamento

O Gemma 4 suporta raciocínio chain-of-thought. Ative com enable_thinking=True:

text = processor.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
    enable_thinking=True  # Ativa modo de raciocínio
)

Quando o pensamento está ativo, o modelo gera seu raciocínio interno seguido da resposta final. Use processor.parse_response(response) pra separar o pensamento da resposta.

Entendendo os Formatos de Quantização GGUF

Se você está baixando arquivos GGUF, vai ver vários sufixos. Eis o que eles significam na prática.

Formato	Bits	Tamanho (31B)	Quando Usar
Q8_0	8-bit	~32 GB	Melhor qualidade, precisa de 32GB+ VRAM
Q6_K	6-bit	~26 GB	Quase sem perdas, 24GB+ VRAM
Q5_K_M	5-bit	~22 GB	Ponto ideal qualidade/tamanho
Q4_K_M	4-bit	~18 GB	Melhor equilíbrio, cabe em GPU de 24GB
Q3_K_M	3-bit	~14 GB	GPU menor, alguma perda de qualidade
Q2_K	2-bit	~10 GB	Medidas desesperadas, degradação notável

Minha recomendação: Q4_K_M pra GPUs de 24GB, Q5_K_M se você puder gastar os 4GB extra. A diferença de qualidade entre Q4_K_M e Q5_K_M é mensurável em benchmarks mas difícil de perceber no uso casual. Abaixo de Q3_K_M não vale a pena a não ser que não tenha outra opção.

O sufixo _K_M significa "K-quantization, medium". Também existem variantes _K_S (small, mais compressão) e _K_L (large, menos compressão). _K_M é a recomendação padrão.

Dicas de Performance

Gerenciamento do Comprimento do Contexto

O Gemma 4 31B suporta até 256K tokens de contexto, mas cada token no contexto consome VRAM. Algumas diretrizes práticas:

• 4K tokens: Confortável em qualquer GPU que comporte o modelo
• 8K tokens: Padrão pra maioria das conversas, ainda confortável
• 32K tokens: Precisa de uns 4-6GB extra de VRAM dependendo da quantização
• 128K+ tokens: Requer VRAM substancial ou offload agressivo

Comece com -c 8192 e aumente só quando precisar.

Parâmetros de Sampling

O Google recomenda essas configurações pro Gemma 4:

temperature = 1.0
top_p = 0.95
top_k = 64

Essas são diferentes do que a maioria dos modelos usa. Não use temperature=0.7 com o Gemma 4; ele é treinado pra temperature=1.0 e produz resultados melhores nessa configuração.

Flash Attention

Se você está usando HuggingFace Transformers, ative o Flash Attention pra inferência mais rápida e menor uso de memória:

model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID,
    attn_implementation="flash_attention_2",
    device_map="auto"
)

Isso requer pip install flash-attn e uma GPU compatível (a maioria das RTX NVIDIA funciona).

Setup Multi-GPU

Se você tem múltiplas GPUs, device_map="auto" no Transformers cuida da divisão automaticamente. Pra llama.cpp:

./build/bin/llama-cli \
  -m ./models/gemma-4-31B-it-Q4_K_M.gguf \
  -ngl 99 \
  -ts 1,1 \  # Divide igualmente entre 2 GPUs
  -c 8192

Solução de Problemas

Out of Memory (CUDA OOM)

O problema mais comum. Soluções em ordem de desespero:

1. Use uma quantização menor: Troque de Q5 pra Q4, ou Q4 pra Q3
2. Reduza o comprimento do contexto: Baixe -c de 8192 pra 4096 ou 2048
3. Offload pra CPU: Reduza -ngl pra fazer offload de algumas camadas
4. Use a variante 26B A4B MoE: Mesmo nível de qualidade, fração da VRAM
5. Use a variante E4B: Roda em qualquer coisa

Inferência Lenta na CPU

Se você está rodando em CPU, espere 1-3 tokens/segundo pro modelo 31B. Opções:

• Troque pro modelo E4B ou E2B (10-20 tok/s em CPU)
• Use uma instância cloud com GPU (LightNode oferece opções de VPS com GPU)
• Compile o llama.cpp com os conjuntos de instruções do seu CPU habilitados (AVX2, AVX-512)

Falhas no Download do Modelo

O arquivo Q4_K_M tem uns 18GB. Se o download fica falhando:

# Use huggingface-cli com suporte a resumo
huggingface-cli download unsloth/gemma-4-31B-it-GGUF \
  gemma-4-31B-it-Q4_K_M.gguf \
  --local-dir ./models \
  --local-dir-use-symlinks False

Ou use um gerenciador de downloads que suporte resumo. O CDN do HuggingFace pode ser instável pra arquivos grandes.

Erros de "Model not supported"

Certifique-se de que você está usando a versão mais recente das ferramentas. O Gemma 4 é novo e versões antigas do llama.cpp, Ollama e Transformers não suportam ele:

# Atualize llama.cpp
cd llama.cpp && git pull && cmake --build build --config Release -j$(nproc)

# Atualize Ollama
ollama pull gemma4:31b-it  # Isso atualiza automaticamente se necessário

# Atualize Transformers
pip install -U transformers

Qual Método Escolher?

Cenário	Melhor Método
Você quer uma GUI, não quer mexer no terminal	Unsloth Studio
Você quer o setup mais rápido, CLI tá valendo	Ollama
Você precisa de controle máximo sobre a inferência	llama.cpp
Você está construindo uma aplicação	HuggingFace Transformers
Você tem VRAM limitada (8-16GB)	Unsloth ou Ollama com Q3/Q4
Você tem 24GB+ VRAM	Qualquer método, use Q4_K_M ou Q5_K_M
Você precisa de compreensão de imagens	Unsloth Studio ou HuggingFace Transformers
Você quer fazer fine-tuning	Unsloth (treinamento LoRA/GRPO integrado)

Pra maioria das pessoas que estão começando, o Unsloth Studio é o caminho de menor resistência. Instale, busque Gemma 4, escolha uma quantização que caiba na sua GPU e comece a conversar. O processo todo leva uns 15 minutos da instalação até a primeira conversa.

Se você está confortável com o terminal e só quer rodar o modelo, o Ollama te leva lá em dois comandos. E se você precisa de acesso programático ou está construindo algo em cima do modelo, o HuggingFace Transformers com quantização 4-bit te dá a API Python completa.

Considerações Finais

Rodar o Gemma 4 31B localmente ficou surpreendentemente prático. Há um ano, um modelo de 30B nesse nível de qualidade seria um projeto de pesquisa. Agora é um processo de 15 minutos com Unsloth ou Ollama, e roda em hardware de consumidor que você pode comprar hoje.

O modelo em si se sai bem contra alternativas proprietárias em tarefas de raciocínio, código e multimodalidade. 256K de contexto, modo de pensamento integrado, compreensão de imagens e function calling fazem ele genuinamente útil pra trabalho de verdade, não só experimentação.

Pra hospedar o modelo numa GPU remota, a LightNode oferece instâncias VPS com GPU com cobrança por hora, então você pode subir uma quando precisar e desligar quando não precisar.

O model card do Gemma 4 no HuggingFace tem os detalhes técnicos completos, e o repositório GGUF do Unsloth tem todas as variantes quantizadas prontas pra download.