Executando Gemma 4 como um Agente Autônomo Local com Claude Code em 16GB de VRAM

Configuração de Agente Local com Gemma 4 e Claude Code

Um desenvolvedor documentou seu processo de substituir a API Claude da Anthropic por um modelo local Gemma 4 de 31 bilhões de parâmetros para criar um agente de codificação autônomo com acesso completo ao shell via Claude Code CLI. O objetivo era permitir que o LLM local não apenas escrevesse código no chat, mas interagisse autonomamente com o terminal, criasse pastas, lesse estruturas e atuasse como um agente de desenvolvimento proativo.

Hardware e Stack de Software

• Sistema Operacional: Windows 11
• CPU & RAM: Intel Core Ultra 9 285K CPU com 64GB de RAM do sistema
• GPUs: NVIDIA RTX 4060 (8GB) + NVIDIA RTX 3050 (8GB) = 16GB total de VRAM
• Modelo Principal: google_gemma-4-31B-it (GGUF V3)
• Stack de Software:
  • llama.cpp (llama-server) - build mais recente b8672
  • Claude Code CLI - v2.1.92
  • LiteLLM + gateway Python personalizado (agent_router.py) para conectar blocos de streaming da Anthropic às APIs da OpenAI

Problema 1: Falhas na Análise de Chamadas de Ferramentas

Inicialmente, o Gemma 4 se recusava a executar ferramentas através do roteamento de API personalizado, optando por pedir desculpas em vez de agir. Quando forçado a gerar chamadas de ferramentas do sistema nativamente, o Claude Code CLI gerava erros TypeScript: Cannot read properties of undefined (reading 'input_tokens').

A Solução: O Gemma 4 usa um bloco de raciocínio invisível <thought> antes de finalizar a saída. O script agent_router.py esperava blocos de texto contínuos tradicionais, fazendo com que ele pulasse o envio do evento inicial obrigatório message_start da Anthropic. O desenvolvedor modificou o loop de interceptação Python para extrair e combinar explicitamente reasoning_content com saídas padrão, garantindo que o fluxo sempre fosse inicializado com métricas de uso completas. A atualização para o build b8672 do llama.cpp foi obrigatória para o funcionamento adequado do tokenizador.

Problema 2: Limitações da Janela de Contexto

O Claude Code v2.1.92 opera com um prompt de sistema massivo que incorpora a árvore de pastas ativa e instruções do sistema, despejando 7.182 tokens no servidor local durante a inicialização. A configuração inicial n_ctx (janela de contexto) estava limitada a 4096 para economizar VRAM, causando falhas imediatas no servidor.

A Solução: A janela de contexto foi duplicada para 16.384 para acomodar o prompt inicial e o histórico da conversa.

Problema 3: Desafios de Alocação de VRAM

Com uma janela de contexto de 16K para um modelo de 31B, a alocação de VRAM se tornou problemática. Uma janela de contexto de 16K usando configurações padrão requer aproximadamente 6,4 GB apenas para o Cache KV. A sobrecarga do Windows WDDM reserva cerca de 20% da memória da GPU para buffers de exibição/fundo, deixando apenas ~12,8 GB acessíveis dos 16GB totais de VRAM antes de erros CUDA_out_of_memory.

O cálculo inicial mostrou: Modelo (13 GB) + Cache KV (6,4 GB) = 19,4 GB, excedendo a VRAM disponível.

Configuração Final

A Matemática & Solução: O desenvolvedor abandonou o modelo Q3_K_M (~13,7GB) e mudou para o formato IQ3_XS (~12,9GB). O comando otimizado de inicialização do servidor:

bat.\llm-server\llama-server.exe -m D:\gemma4\google_gemma-4-31B-it-IQ3_XS.gguf -c 16384 -ngl 38 -ctk q8_0 -ctv q8_0 --host 127.0.0.1 --port 8080

Flags-chave:

• -ctk q8_0 -ctv q8_0: Quantização de Cache KV de 8 bits que reduziu pela metade a pegada do Cache KV de 6,4 GB
• -c 16384: Janela de contexto de 16K
• -ngl 38: Número de camadas da GPU

Esta configuração executa com sucesso o Gemma 4 como um agente autônomo local em 16GB de VRAM, embora a fonte observe que funciona "quase" perfeitamente com alguns desafios restantes.