Rodando Agentes de Código AI no Seu Mac: Um Guia Prático

Por Que Ficar Offline?

Todo mundo já passou por isso. Você está no meio de uma sessão de código, a produtividade finalmente fluindo, e então—internet cai. Seu assistente de IA baseado na nuvem se torna completamente inútil, e você fica ali, olhando para o código sem saber o que fazer.

Foi exatamente o que me aconteceu最近, e isso me motivou a finalmente explorar como rodar um agente de IA para programação totalmente offline. O que descobri me surpreendeu: com a configuração certa, você consegue um desempenho bastante respeitável no Apple Silicon, muitas vezes superando soluções especializadas para Mac.

A Configuração Que Realmente Funciona

Depois de bastante teste e benchmark, aqui está a configuração que deliverou os melhores resultados no meu M1 Max com 64GB de memória unificada:

Stack Principal:

• llama.cpp compilado com aceleração Metal
• Gemma 4 26B-A4B em formato GGUF (quantizado para Q4)
• Modelo draft com Multi-Token Prediction (MTP) para decodificação especulativa
• Projetor multimodal do Gemma 4 para suporte a screenshots
• Pi como agente de programação via terminal

Essa não é necessariamente a configuração mais poderosa que você poderia montar teoricamente, mas é o ponto ideal para usabilidade real. Você quer velocidade medida em tokens por segundo, não minutos por resposta.

Os Números Que Importam

Rodei benchmarks consistentes usando este prompt em todas as configurações:

"Escreva uma função Python compacta que faz parse de um unified diff e retorna os arquivos alterados. Depois explique dois edge cases."

Cada teste gerou aproximadamente 128 tokens, dando uma comparação justa da velocidade de geração.

Desempenho Base:

Rodando Gemma 4 diretamente pelo llama.cpp com Metal, conseguimos 58.2 tokens por segundo. Isso é utilizável, mas sendo honesto? Parecia lento durante sessões reais de programação onde você faz múltiplas chamadas de ferramentas e espera respostas.

A Diferença do MTP:

É aqui que as coisas ficam interessantes. Multi-Token Prediction permite que o modelo "especule" vários tokens à frente, aceitando predições corretas e fazendo rollback das incorretas. Com o modelo draft MTP Q8 habilitado, o desempenho saltou para 72.2 tokens por segundo — uma melhoria de 24% sem nenhuma mudança no modelo principal.

O processamento do prompt permaneceu essencialmente o mesmo (por volta de 297-299 tokens/segundo), mas é a velocidade de geração que importa para workflows de agente. Você não fica submetendo novos prompts constantemente — está esperando o modelo gerar respostas, tomar decisões e executar ferramentas.

Testei contagens de draft tokens de 1 a 6, e no meu M1 Max, 3 draft tokens atingiu o ponto ideal. Valores acima de 4 realmente começaram a deixar as coisas mais lentas, o que faz sentido — mais especulação significa mais trabalho desperdiçado quando as predições estão erradas.

llama.cpp vs. MLX: O Vencedor Surpresa

Aqui está o que me pegou de surpresa: eu esperava que o MLX (framework nativo de ML da Apple) dominasse, já que é otimizado especificamente para Apple Silicon. A realidade foi diferente.

| Runtime | Geração tok/s | |---------|------------------| | llama.cpp Metal + MTP | 72.2 | | llama.cpp Metal | 58.2 | | MLX-LM (Unsloth 4-bit) | 45.8 | | MLX-LM (padrão 4-bit) | 43.9 | | MLX-LM (OptiQ 4-bit) | 38.1 |

Llama.cpp com MTP foi aproximadamente 58% mais rápido que a melhor configuração em MLX. Os anos de trabalho de otimização que foram investidos no llama.cpp claramente valeram a pena — ele roda excellentemente no macOS apesar de ser multiplataforma.

Adicionando Capacidades de Visão

Para uma experiência completa de agente de programação, você quer poder enviar screenshots. Talvez queira que o agente veja o que ele construiu, ou revise uma mudança de UI que você acabou de fazer.

O problema? Apenas o Gemma 4 12B é nativamente multimodal. O modelo 26B que estamos usando precisa do projetor multimodal externo carregado junto.

Quando adicionei o projetor --mmproj no llama.cpp, ele anunciou corretamente as capacidades multimodais ao Pi, e as saídas de ferramentas de imagem começaram a fluir corretamente. Mais importante ainda, isso não introduziu nenhuma desaceleração mensurável — a velocidade de geração permaneceu em 72.2 tokens por segundo.

A Experiência No Dia a Dia

Com essa configuração, você está olhando para aproximadamente 17GB de arquivos de modelo (16GB para o modelo principal, mais o head MTP e o projetor). Para alguém com 64GB de memória unificada, isso é totalmente gerenciável.

O Pi como agente fornece uma interface limpa via terminal que se conecta à API compatível com OpenAI que o modo server do llama.cpp expõe. Isso significa que você pode usar com qualquer ferramenta que suporte o formato de API da OpenAI, dando flexibilidade sem vendor lock-in.

O maior benefício? Quando sua internet falha — e vai falhar, no pior momento possível — você continua programando. O agente pode ser levemente mais lento que alternativas na nuvem, mas é responsivo o suficiente para manter seu fluxo de trabalho.

Começando

Você vai precisar compilar o llama.cpp com suporte a Metal habilitado. O projeto tem uma documentação sólida para builds no macOS, e uma vez compilado, o modo server te dá aquele endpoint compatível com OpenAI.

Para modelos, as quantizações GGUF da Unsloth no Hugging Face são bem otimizadas. Você vai querer a quantização Q4_K_XL para o modelo principal e o modelo draft MTP Q8 correspondente.

Ajuste seu valor de --spec-draft-n-max — comece em 3 e teste de 1 a 6 para encontrar o que funciona melhor no seu hardware específico. Diferentes configurações de Apple Silicon podem ter pontos ideais diferentes.

Vale a Pena?

Se você programa regularmente com assistentes de IA e tem o hardware (mínimo de 16GB, 32GB+ recomendado), com certeza. A independência de conectividade por si só já torna valioso, e com o MTP trazendo velocidades de geração para território genuinamente utilizável, a experiência é surpreendentemente polida.

Você não vai igualar a inteligência de classe GPT-4 com esses modelos abertos, mas para completion de código, refatoração, assistência em debugging e tarefas gerais de agente de programação? É mais capaz do que a maioria das pessoas espera, e é seu — rodando localmente, privately, sem latência spikes ou outages de serviço.

As ferramentas amadureceram significativamente. Se você já tentou modelos locais antes e ficou decepcionado com a velocidade, dê uma chance a essa configuração. O MTP muda consideravelmente a equação.