Como Executar Gemma 4 Localmente com Ollama: Guia Completo

Resumo

Gemma 4 foi lançado em 3 de abril de 2026, e o Ollama v0.20.0 adicionou suporte no mesmo dia. Você pode baixar e executar o modelo padrão gemma4:e4b em dois comandos. Este guia te leva pela configuração, seleção de modelo, uso da API e como testar seus endpoints locais do Gemma 4 com Apidog.

Introdução

Google lançou o Gemma 4 em 2 de abril de 2026. Em 24 horas, o Ollama lançou a versão v0.20.0 com suporte total para todas as quatro variantes do modelo.

Para desenvolvedores, isso importa. Gemma 4 não é uma pequena atualização. Ele atinge 89,2% no AIME 2026 em comparação com 20,8% do Gemma 3. Sua pontuação de benchmark de codificação saltou de 110 ELO para 2150 no Codeforces. Você obtém chamada de função nativa, modos de raciocínio configuráveis e uma janela de contexto de 256K nas variantes maiores. Tudo isso roda no seu próprio hardware.

Se você está construindo aplicativos com API, a configuração local desbloqueia algo útil: uma camada de IA rápida e privada para gerar dados de mock, escrever cenários de teste e validar respostas da API sem enviar dados para um servidor remoto.

Este guia cobre tudo, desde a instalação até a sua primeira chamada de API local.

O que há de novo no Gemma 4

Gemma 4 vem com quatro variantes de modelo com capacidades significativamente diferentes.

Aqui está o que o diferencia do Gemma 3:

Raciocínio e codificação. O modelo de 31B atinge 80% no LiveCodeBench v6. O Gemma 3 27B anterior marcou 29,1%. Essa diferença não é uma melhoria gradual; é uma classe diferente de desempenho.

Arquitetura Mixture-of-Experts. A variante de 26B usa MoE com apenas 4 bilhões de parâmetros ativos durante a inferência. Você obtém qualidade quase de ponta a uma fração do custo de computação.

Contexto mais longo. Os modelos de borda E2B e E4B suportam 128K tokens. Os modelos de 26B e 31B estendem isso para 256K, o suficiente para encaixar grandes bases de código ou arquivos de especificação de API em um único prompt.

Chamada de função nativa. Todos os modelos Gemma 4 suportam uso estruturado de ferramentas prontos para uso. Você pode definir um esquema de função e o modelo retorna JSON válido que corresponde a esse esquema, sem truques de engenharia de prompt necessários.

Entrada de áudio e imagem. Os modelos E2B e E4B aceitam entrada de áudio e imagem de resolução variável junto com texto.

Modos de raciocínio. Você pode habilitar ou desabilitar o raciocínio em cadeia de pensamento do modelo por solicitação. Para consultas simples, pule. Para problemas complexos de codificação ou matemática, ative.

Variantes do modelo Gemma 4 explicadas

Antes de baixar qualquer coisa, escolha o modelo certo para o seu hardware:

O modelo e4b é o padrão quando você executa ollama run gemma4. Ele se encaixa na maioria das GPUs de consumidor com 10+ GB de VRAM e roda razoavelmente rápido na memória unificada do Apple Silicon.

A variante 26b MoE é a escolha surpresa. Como apenas 4 bilhões de parâmetros são ativados por token, a inferência é mais próxima de um modelo de 4B em velocidade, enquanto a qualidade se aproxima de um modelo de 13B. Se você tiver 20+ GB de RAM, vale a pena experimentar.

Pré-requisitos

Você precisa do Ollama v0.20.0 ou posterior. Versões anteriores não incluem suporte ao Gemma 4.

Verifique sua versão atual:

ollama --version

Se você estiver em uma versão mais antiga, atualize:

# macOS
brew upgrade ollama

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

No Windows, baixe o instalador mais recente em ollama.com.

Requisitos de hardware:

• gemma4:e2b: 8 GB de RAM mínimo (16 GB recomendado)
• gemma4:e4b: 10 GB de VRAM ou 16 GB de memória unificada
• gemma4:26b: 20+ GB de RAM ou memória unificada
• gemma4:31b: 24 GB de VRAM ou 32 GB de memória unificada

Instalando e executando o Gemma 4

Baixe e execute o modelo e4b padrão:

ollama run gemma4

Isso baixa aproximadamente 9,6 GB na primeira execução e, em seguida, o coloca em uma sessão interativa. Digite uma mensagem para testar:

>>> Quais são os códigos de status HTTP para erros de cliente?

Para executar uma variante específica:

# Modelo edge, menor pegada
ollama run gemma4:e2b

# Modelo MoE, melhor relação qualidade-tamanho
ollama run gemma4:26b

# Modelo flagship completo
ollama run gemma4:31b

Para baixar sem executar imediatamente:

ollama pull gemma4
ollama pull gemma4:26b

Verifique quais modelos você tem:

ollama list

Usando a API Gemma 4 localmente

Ollama expõe uma API REST local em http://localhost:11434. Uma vez que o modelo é baixado, você pode acessá-lo de qualquer cliente HTTP sem iniciar a CLI interativa.

Gerar uma conclusão

curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma4",
    "prompt": "Escreva uma resposta JSON para um endpoint de API de perfil de usuário",
    "stream": false
  }'

Conclusão de chat (endpoint compatível com OpenAI)

Ollama também suporta o formato de chat do OpenAI:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma4",
    "messages": [
      {
        "role": "user",
        "content": "Gere um mock JSON realista para uma resposta de API de pedido de e-commerce"
      }
    ]
  }'

Cliente Python

import requests

def ask_gemma4(prompt: str, model: str = "gemma4") -> str:
    response = requests.post(
        "http://localhost:11434/api/generate",
        json={
            "model": model,
            "prompt": prompt,
            "stream": False
        }
    )
    response.raise_for_status()
    return response.json()["response"]

result = ask_gemma4("Liste os campos que uma resposta de API de pagamento deve incluir")
print(result)

Usando o SDK Python do OpenAI

Como a API do Ollama é compatível com a do OpenAI, você pode apontar o SDK oficial para sua instância local:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # requerido pelo SDK mas não usado pelo Ollama
)

response = client.chat.completions.create(
    model="gemma4",
    messages=[
        {
            "role": "system",
            "content": "Você gera dados de resposta de API realistas em formato JSON."
        },
        {
            "role": "user",
            "content": "Gere uma resposta de exemplo para um endpoint GET /users/{id}"
        }
    ]
)

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

Usando chamada de função com o Gemma 4

Gemma 4 suporta chamada de função nativa. Você define um esquema de ferramenta e o modelo retorna JSON estruturado que corresponde à sua assinatura de função.

Isso é útil para construir agentes que chamam suas APIs programaticamente:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_user",
            "description": "Recuperar um usuário por ID da API",
            "parameters": {
                "type": "object",
                "properties": {
                    "user_id": {
                        "type": "integer",
                        "description": "O ID de usuário único"
                    },
                    "include_orders": {
                        "type": "boolean",
                        "description": "Se deve incluir o histórico de pedidos"
                    }
                },
                "required": ["user_id"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="gemma4",
    messages=[
        {"role": "user", "content": "Obter usuário 42 com seu histórico de pedidos"}
    ],
    tools=tools,
    tool_choice="auto"
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name)       # get_user
print(tool_call.function.arguments)  # {"user_id": 42, "include_orders": true}

O modelo extrai os parâmetros corretos da linguagem natural e retorna um objeto JSON válido que corresponde ao seu esquema. Nenhuma análise de regex ou limpeza de saída é necessária.

Ativando o modo de raciocínio

Para tarefas complexas como escrever cenários de teste ou analisar especificações de API, você pode habilitar o raciocínio em cadeia de pensamento do Gemma 4:

response = client.chat.completions.create(
    model="gemma4",
    messages=[
        {
            "role": "user",
            "content": "Projetar um cenário de teste completo para uma API de processamento de pagamentos com casos extremos"
        }
    ],
    extra_body={"think": True}
)

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

Para solicitações mais simples, como gerar um único valor de mock, ignore o modo de raciocínio. Ele adiciona latência que você não precisa.

Testando respostas da API Gemma 4 com Apidog

Uma vez que sua instância local do Gemma 4 esteja funcionando, você vai querer testar os endpoints da API sistematicamente. O Apidog lida com isso sem ferramentas extras.

Importe a especificação da API do Ollama. O servidor local do Ollama expõe endpoints REST padrão. Crie um novo projeto no Apidog e adicione a URL base http://localhost:11434.

Defina seus endpoints. Adicione os endpoints que você está testando:

• POST /api/generate para conclusões de turno único
• POST /v1/chat/completions para chat de múltiplos turnos
• GET /api/tags para listar os modelos disponíveis

Configure um Cenário de Teste. No Apidog, um Cenário de Teste encadeia múltiplas requisições com asserções entre elas. Para testar o Gemma 4:

1. Passo 1: GET /api/tags para afirmar que gemma4 aparece na lista de modelos
2. Passo 2: POST /api/generate para enviar um prompt e afirmar que o campo response não está vazio
3. Passo 3: POST /v1/chat/completions para enviar uma mensagem de chat e afirmar que a resposta corresponde ao formato esperado

Use o processador de Extrair Variável do Apidog para capturar a resposta do passo 2 e passá-la para o passo 3. Isso permite que você teste fluxos de conversação multi-turno automaticamente.

Valide esquemas de resposta. O Teste de Contrato do Apidog valida as respostas da API em relação à sua especificação OpenAPI. Defina o formato de resposta esperado para cada endpoint do Gemma 4, então execute testes de contrato após as atualizações do modelo para detectar quaisquer alterações disruptivas no formato da API do Ollama.

Smart Mock para desenvolvimento paralelo. Se o seu backend depende das respostas do Gemma 4, mas você quer que as equipes de frontend trabalhem sem esperar pelo modelo local, o Smart Mock do Apidog gera automaticamente respostas compatíveis com o esquema a partir da sua especificação de API. Defina como uma resposta do Gemma 4 deve ser, e o Smart Mock serve dados realistas sob demanda.

Entrada multimodal com o Gemma 4

Os modelos E2B e E4B aceitam imagens junto com texto. Passe as imagens como strings codificadas em base64:

import base64

with open("api_diagram.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="gemma4:e4b",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{image_data}"
                    }
                },
                {
                    "type": "text",
                    "text": "Descreva o fluxo da API mostrado neste diagrama e identifique possíveis caminhos de erro"
                }
            ]
        }
    ]
)

Isso é útil para analisar diagramas de arquitetura, revisar capturas de tela de documentação da API ou extrair dados de imagens que sua API precisa processar.

Problemas comuns e soluções

O Ollama diz que o modelo não foi encontrado. Execute ollama pull gemma4 primeiro, ou verifique com ollama list.

Inferência lenta na CPU. Gemma 4 é otimizado para GPU. Em máquinas somente com CPU, espere 1-3 tokens por segundo no modelo e4b. Use gemma4:e2b para melhor desempenho na CPU.

Erros de falta de memória. Verifique sua VRAM ou memória unificada disponível com ollama ps. Se o modelo for muito grande, mude para gemma4:e2b (7.2 GB).

Modelo não carregando no Apple Silicon. Ollama 0.20.0 adicionou suporte a MLX para Apple Silicon em prévia. Se você estiver em uma versão mais antiga do Ollama, atualize primeiro.

Porta já em uso. Se outra coisa estiver usando a porta 11434, defina uma porta personalizada: OLLAMA_HOST=0.0.0.0:11435 ollama serve.

Respostas são cortadas. Aumente a janela de contexto em sua requisição: adicione "options": {"num_ctx": 8192} ao seu corpo JSON.

Gemma 4 vs outros modelos locais

A vantagem do Gemma 4 é a variante MoE 26B. Com 18 GB, ele oferece qualidade quase de ponta com 4B de parâmetros ativos no tempo de inferência, proporcionando melhores tokens por segundo do que qualquer um dos modelos densos maiores nesta lista.

Para tarefas puras de codificação, o modelo de 31B é competitivo com modelos muito maiores. Para implantação em edge ou laptops, o e2b roda em menos de 8 GB.

Conclusão

Gemma 4 com Ollama é uma das configurações locais mais capazes disponíveis atualmente. A instalação leva dois comandos. O modelo padrão roda na maioria das máquinas de desenvolvedor. E o salto na qualidade de raciocínio e codificação em relação ao Gemma 3 é substancial.

Comece com ollama run gemma4, teste a API com Apidog para garantir que seus endpoints se comportem como esperado, então escolha a variante certa para sua carga de trabalho com base na tabela de modelos acima.

Para equipes que constroem recursos baseados em API em cima do Gemma 4, emparelhar a inferência local com o Smart Mock e Cenários de Teste do Apidog oferece um ciclo de desenvolvimento completo sem dependências remotas.

Perguntas Frequentes

Como atualizo o Gemma 4 no Ollama quando uma nova versão é lançada? Execute ollama pull gemma4 novamente. O Ollama verifica a versão mais recente e baixa apenas o que mudou.

Posso executar o Gemma 4 em uma máquina sem GPU? Sim, mas é lento. Espere 1-3 tokens por segundo na CPU. O modelo e2b é a opção mais prática para máquinas somente com CPU.

Qual a diferença entre gemma4:e2b e gemma4:e4b? Ambos são modelos "efetivos" densos otimizados para hardware de borda. O E4B tem mais parâmetros e lida melhor com raciocínios complexos. O E2B é menor e suporta entrada de áudio. Para a maioria das tarefas de texto, o e4b é o padrão mais adequado.

O Gemma 4 funciona com LangChain e LlamaIndex? Sim. Ambos os frameworks suportam Ollama como backend. Aponte o provedor Ollama para http://localhost:11434 e use gemma4 como o nome do modelo.

A API local do Gemma 4 é compatível com código escrito para a API do OpenAI? Na maioria das vezes, sim. O endpoint /v1/chat/completions do Ollama segue o formato do OpenAI. Mude base_url para http://localhost:11434/v1 e api_key para qualquer string não vazia. A maioria das chamadas do SDK do OpenAI funciona sem alterações.

Como uso o modo de raciocínio do Gemma 4? Passe "think": true no parâmetro extra_body ao usar o SDK do OpenAI, ou adicione "think": true ao corpo JSON de nível superior em chamadas diretas à API. Desative-o para tarefas simples para reduzir a latência.

Posso servir o Gemma 4 para outras máquinas na minha rede? Sim. Inicie o Ollama com OLLAMA_HOST=0.0.0.0:11434 ollama serve e outras máquinas poderão acessá-lo no seu endereço IP na porta 11434.

Qual é o melhor modelo Gemma 4 para tarefas de desenvolvimento de API? Para gerar dados de mock e escrever casos de teste, o e4b é o equilíbrio certo de velocidade e qualidade. Para análise complexa de especificações ou revisão de arquitetura, o modelo MoE 26b oferece melhores resultados sem o custo do 31B completo.