Compilar llama.cpp com Metal

#llama.cpp no Mac: o que o Metal oferece

No macOS, a GPU é usada via Metal, a API gráfica e de computação da Apple, e o llama.cpp a utiliza diretamente. O README do projeto informa que o Apple Silicon recebe suporte de primeira classe, com otimizações via ARM NEON, Accelerate e Metal. Na prática, isso significa que a compilação padrão já produz um motor que utiliza a GPU, sem precisar adicionar nenhuma opção, e que a memória unificada evita qualquer transferência entre o processador e a GPU: o modelo ocupa a memória uma única vez. O fator limitante em um Mac é, portanto, a capacidade e a largura de banda dessa memória.

#Pré-requisitos

Um Mac Apple Silicon

M1 a M5: é o foco deste guia. Os Macs com processador Intel quase não se beneficiam disso.

Ferramentas de compilação Apple

Instale as ferramentas de linha de comando com xcode-select --install.

CMake e Git

Disponíveis via Homebrew: brew install cmake git.

Memória para o modelo

O ponto de referência do site: um 8B em Q4 pesa aproximadamente 5 GB, um 14B cerca de 9 GB, um 32B entre 19 e 20 GB, antes do contexto.

xcode-select --install
brew install cmake git

#Instalar sem compilar: Homebrew

Se você não precisar de opções de compilação específicas, a maneira mais rápida é o Homebrew. A documentação de instalação do llama.cpp indica que a fórmula é atualizada automaticamente com cada nova versão do projeto. Você obtém os mesmos executáveis prontos para uso, com Metal.

brew install llama.cpp

Compile você mesmo quando quiser a versão mais recente do repositório, testar uma ramificação ou modificar uma opção de compilação. Caso contrário, o Homebrew é suficiente: você economiza o tempo de compilação e as atualizações são feitas com brew upgrade.

#1. Compilar com Metal

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

cmake -B build
cmake --build build --config Release -j $(sysctl -n hw.ncpu)

A documentação de build é explícita: no macOS, o Metal está ativado por padrão e faz com que os cálculos sejam executados na GPU. Nenhuma opção precisa ser adicionada. O antigo nome do repositório, sob a conta de Georgi Gerganov, redireciona para a organização ggml-org, onde agora está o projeto. Os binários aparecem em build/bin, incluindo llama-cli para o terminal e llama-server para a API.

Duas opções úteis: a documentação indica que -DGGML_METAL=OFF desativa o Metal na compilação e que é possível forçar um binário compilado com Metal a executar no processador usando --n-gpu-layers 0, o que é útil para comparar as velocidades.

#2. Iniciar um primeiro modelo

Os motores recentes sabem baixar o modelo por si mesmos. A opção -hf recebe o nome de um repositório Hugging Face, com a quantização no sufixo; sem sufixo, Q4_K_M é usada por padrão. Para um arquivo já baixado, use -m com o caminho dele.

./build/bin/llama-cli -hf UTILISATEUR/MODELE-GGUF:Q4_K_M

./build/bin/llama-cli -m ~/modeles/mon-modele-Q4_K_M.gguf

O número de camadas colocadas na GPU é definido com -ngl; seu valor padrão é auto, o que se adapta a um Mac com memória unificada. Você também pode escrever -ngl all para carregar tudo. Não procure o caminho de um modelo no diretório de Ollama: seus arquivos são armazenados em um formato interno que não é diretamente utilizável como GGUF.

#Servir uma API compatível com OpenAI com llama-server

O llama-server expõe rotas compatíveis com a API OpenAI para chat, respostas e embeddings. Por padrão, ele escuta em 127.0.0.1, porta 8080: é acessível apenas do seu Mac. Para torná-lo acessível na rede, é necessário especificar --host explicitamente, e então convém proteger o acesso.

./build/bin/llama-server -m ~/modeles/mon-modele-Q4_K_M.gguf --port 8080

• llama.cpp: o que é e vale a pena abandonar o Ollama?
• Ollama vs llama.cpp: qual escolher?

#4. O limite de memória da GPU no macOS

No Apple Silicon, o macOS disponibiliza à GPU apenas uma parte da memória unificada. Um modelo que ultrapassa essa parte é recusado ou passa a usar o processador, mesmo que a memória total seja suficiente. O motor exibe o valor efetivo ao iniciar: procure a linha ggml_metal_init: recommendedMaxWorkingSetSize nos logs do llama-cli ou do llama-server.

O comando sysctl iogpu.wired_limit_mb permite aumentar esse limite. Ele espera um valor em megabytes: 61.440 para 60 GB, por exemplo. Um colaborador do repositório do llama.cpp lembra que o comando precisa ser executado novamente a cada inicialização, pois a alteração não é persistente, e desaconselha chegar a 100%: o sistema precisa de memória para tudo o que não está reservado pela GPU, e surgem problemas se não sobrar memória suficiente para ele.

# 56 Go pour le GPU sur un Mac de 64 Go (56 x 1024 = 57344)
sudo sysctl iogpu.wired_limit_mb=57344

# Relancez ensuite le modèle et relisez recommendedMaxWorkingSetSize

#Qual modelo para cada capacidade de memória unificada

A memória unificada é compartilhada entre o macOS, seus aplicativos e o modelo, e a GPU recebe apenas uma parte dela. A referência do site situa os pesos de um modelo 8B em Q4 em torno de 5 GB, de um 14B em torno de 9 GB e de um 32B em torno de 19 a 20 GB. O cache de contexto se soma a esses valores. A tabela fornece uma estimativa conservadora; o valor que deve ser tomado como referência é recommendedMaxWorkingSetSize, exibido pelo motor.

Esses valores aproximados são estimativas conservadoras, não medições: um contexto longo, um segundo modelo ou um aplicativo que consuma muitos recursos bastam para mudar o cenário. O guia dedicado à memória apresenta o método completo de cálculo.

• VRAM e memória: quanto é necessário para a IA
• Qual LLM no MacBook Pro M4

#5. As opções que importam

O Flash Attention está em modo automático por padrão: na maioria dos casos, não é necessário ativá-lo manualmente. O cache KV pode ser quantizado com -ctk e -ctv, desde que o Flash Attention esteja ativo; a quantização em q8_0 reduz aproximadamente pela metade a memória do cache em comparação com f16, ao custo de uma pequena perda de precisão que convém verificar nos seus casos de uso. O guia dedicado detalha essa contrapartida.

• Quantizar o KV cache para economizar VRAM
• Flash Attention no llama.cpp

#6. Desempenho por chip: o que os benchmarks públicos medem

O QuelLLM não realiza medições nessas máquinas. A referência é a discussão «Performance of llama.cpp on Apple Silicon M-series» no repositório do llama.cpp, em que cada colaborador executa o mesmo teste com um LLaMA 7B em Q4_0. A tabela abaixo apresenta algumas dessas linhas, com a versão do llama.cpp usada em cada medição: as medições dos chips M1 a M4 foram feitas com a mesma versão, enquanto a dos M5 foi feita com uma versão mais recente.

O limite teórico é a largura de banda dividida pelo peso do modelo (3,56 GiB, ou seja, 3,82 GB). Os chips Pro atingem 71 a 82% desse limite, enquanto o chip Max alcança apenas 58%: a partir de certo nível, a memória não é mais o único fator limitante, e pagar por mais largura de banda traz menos benefício do que a ficha técnica sugere.

Três lições. A geração segue a largura de banda: o M3 Pro, a 150 GB/s, é mais lento que o M2 Pro a 200 GB/s, apesar de seu chip ser de uma geração mais recente. Os chips Max, com largura de banda muito maior, dominam. Por fim, a leitura do prompt deu um salto com os M5: 1.620,64 tokens/s para um M5 Pro, contra 439,78 para um M4 Pro com o mesmo número de núcleos de GPU, ou seja, 3,7 vezes mais. Essa diferença importa para documentos longos e RAG, muito menos para o chat.

Uma boa prática antes de concluir que um Mac é lento: executar novamente o mesmo modelo com -ngl 0, depois com o valor padrão, e comparar. A diferença entre os dois mostra o ganho real proporcionado pela GPU na sua máquina e confirma que o processamento está sendo feito pelo Metal. Anote também a versão do llama.cpp utilizada: as otimizações para Metal evoluem rapidamente, e um binário antigo pode ser significativamente mais lento que uma versão recente.

#Solução de problemas: erros comuns

• MLX versus llama.cpp no Mac: quem vence em 2026?
• Compilar llama.cpp com CUDA
• Quais modelos para 32 GB de memória

• Fonte: repositório oficial do llama.cpp
• Fonte: documentação de compilação do llama.cpp
• Fonte: benchmark público em Apple Silicon
• Fonte: discussão sobre o limite de memória da GPU dos Macs