compilare llama.cpp con Metal

#llama.cpp su Mac: cosa offre Metal

Su macOS, la GPU viene utilizzata tramite Metal, l’API grafica e di calcolo di Apple, e llama.cpp la sfrutta direttamente. Il README del progetto precisa che Apple Silicon gode di supporto di primo livello, ottimizzato tramite ARM NEON, Accelerate e Metal. In pratica, ciò significa che la compilazione predefinita produce già un motore che utilizza la GPU, senza opzioni da aggiungere, e che la memoria unificata evita ogni trasferimento tra il processore e la GPU: il modello è presente in memoria in una sola copia. Il fattore limitante su un Mac è quindi la capacità e la larghezza di banda di questa memoria.

#Prerequisiti

Un Mac Apple Silicon

Da M1 a M5: sono i chip a cui si rivolge questa guida. I Mac con processore Intel non ne traggono quasi alcun vantaggio.

I tool di compilazione Apple

Installa i Command Line Tools con xcode-select --install.

CMake e Git

Disponibili tramite Homebrew: brew install cmake git.

Memoria per il modello

Il riferimento del sito: un 8B in Q4 pesa circa 5 GB, un 14B circa 9 GB, un 32B da 19 a 20 GB, prima del contesto.

xcode-select --install
brew install cmake git

#Installare senza compilare: Homebrew

Se non hai bisogno di opzioni di compilazione particolari, la soluzione più veloce è Homebrew. La documentazione di installazione di llama.cpp indica che la formula viene aggiornata automaticamente a ogni nuova versione del progetto. Ottieni gli stessi eseguibili, pronti all'uso, con Metal.

brew install llama.cpp

Compila tu stesso quando vuoi la versione più recente del repository, testare un branch o modificare un'opzione di compilazione. Altrimenti, Homebrew basta: risparmi il tempo di compilazione e gli aggiornamenti si fanno con brew upgrade.

#1. Compilare con 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)

La documentazione di build è esplicita: su macOS, Metal è attivato per impostazione predefinita e fa eseguire i calcoli sulla GPU. Non occorre aggiungere alcuna opzione. Il vecchio nome del repository, sotto l'account di Georgi Gerganov, reindirizza all'organizzazione ggml-org, dove ora si trova il progetto. I binari si trovano in build/bin, in particolare llama-cli per il terminale e llama-server per l'API.

Due opzioni utili: la documentazione indica che -DGGML_METAL=OFF disattiva Metal durante la compilazione, e che un binario compilato con Metal può essere forzato sul processore con --n-gpu-layers 0, utile per confrontare le velocità.

#2. Avviare un primo modello

I motori recenti sanno scaricare il modello da soli. L'opzione -hf accetta il nome di un repository Hugging Face, con la quantizzazione come suffisso; senza suffisso, viene scelta Q4_K_M per impostazione predefinita. Per un file già scaricato, usa -m con il suo percorso.

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

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

Il numero di livelli caricati sulla GPU si regola con -ngl; il valore predefinito è auto, adatto a un Mac con memoria unificata. Puoi anche scrivere -ngl all per caricare tutto. Non cercare il percorso di un modello nella cartella di Ollama: i suoi file sono memorizzati in un formato interno che non è un GGUF direttamente utilizzabile.

#Servire un'API compatibile con OpenAI tramite llama-server

llama-server espone endpoint compatibili con l'API OpenAI per la chat, le risposte e gli embedding. Per impostazione predefinita, è in ascolto su 127.0.0.1, porta 8080: è raggiungibile solo dal tuo Mac. Per renderlo accessibile dalla rete, occorre specificare esplicitamente --host, e in tal caso è opportuno proteggere l'accesso.

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

• llama.cpp: cos'è e bisogna abbandonare Ollama?
• Ollama vs llama.cpp: quale scegliere

#4. La limitazione della memoria GPU di macOS

Su Apple Silicon, macOS mette a disposizione della GPU solo una parte della memoria unificata. Un modello che supera questa quota viene rifiutato o passa in parte all'esecuzione sul processore, anche se la memoria totale è sufficiente. Il motore mostra il valore effettivo all'avvio: cerca la riga ggml_metal_init: recommendedMaxWorkingSetSize nei log di llama-cli o di llama-server.

Il comando sysctl iogpu.wired_limit_mb permette di aumentare questo limite. Richiede un valore in megabyte: 61 440 per 60 GB, ad esempio. Un collaboratore del repository di llama.cpp ricorda che il comando va eseguito di nuovo a ogni avvio, perché l'impostazione non è persistente, e sconsiglia di arrivare al 100 %: il sistema ha bisogno di memoria per tutto ciò che non è vincolato dalla GPU, e le cose vanno male se non gliene si lascia abbastanza.

# 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

#Quale modello per quale quantità di memoria unificata

La memoria unificata è condivisa tra macOS, le tue applicazioni e il modello, e la GPU ne riceve solo una parte. Il sito indica che i pesi di un modello 8B in Q4 sono intorno a 5 GB, quelli di un 14B intorno a 9 GB e quelli di un 32B intorno a 19–20 GB. A questi si aggiunge la cache del contesto. La tabella fornisce un ordine di grandezza prudenziale; il valore di riferimento è recommendedMaxWorkingSetSize, visualizzato dal motore.

Questi ordini di grandezza sono stime prudenziali, non misurazioni: un contesto lungo, un secondo modello o un'applicazione che consuma molte risorse bastano a cambiare la situazione. La guida dedicata alla memoria fornisce il metodo di calcolo completo.

• VRAM e memoria: quanta ne serve per l'IA
• Quale LLM su MacBook Pro M4

#5. Le opzioni che contano

Flash Attention è in modalità automatica per impostazione predefinita: nella maggior parte dei casi non è necessario attivarla manualmente. La cache KV si quantizza con -ctk e -ctv, a condizione che Flash Attention sia attiva; la quantizzazione in q8_0 dimezza all'incirca la memoria della cache rispetto a f16, al prezzo di una lieve perdita di precisione che è meglio verificare nei tuoi casi d'uso. La guida dedicata illustra il compromesso in dettaglio.

• Quantizzare la cache KV per risparmiare VRAM
• Flash Attention in llama.cpp

#6. Prestazioni per chip: ciò che misurano i benchmark pubblici

QuelLLM non misura queste macchine. Il riferimento è la discussione «Performance of llama.cpp on Apple Silicon M-series» nel repository di llama.cpp, dove ogni contributore esegue lo stesso test su un LLaMA 7B in Q4_0. La tabella qui sotto ne riporta alcune righe, indicando la versione di llama.cpp usata per ogni misurazione: le misurazioni dei chip da M1 a M4 sono state eseguite con la stessa versione, mentre quella usata per gli M5 è più recente.

Il limite teorico è la banda passante divisa per il peso del modello (3,56 GiB, cioè 3,82 GB). I chip Pro raggiungono dal 71 all'82% di questo limite, mentre il chip Max ne raggiunge soltanto il 58%: a partire da un certo livello, la memoria non è più l'unico collo di bottiglia e pagare per una maggiore banda passante rende meno di quanto la scheda tecnica lasci intendere.

Tre insegnamenti. La generazione segue la banda passante: il M3 Pro, a 150 GB/s, è più lento del M2 Pro a 200 GB/s, nonostante appartenga a una generazione di chip più recente. I chip Max, con una banda passante molto più elevata, dominano. Infine, la lettura del prompt ha fatto un salto con i M5: 1 620,64 token/s per un M5 Pro, contro 439,78 per un M4 Pro con lo stesso numero di core GPU, cioè 3,7 volte di più. Questa differenza conta per i documenti lunghi e il RAG, molto meno per la chat.

Una buona abitudine prima di concludere che un Mac è lento: rilanciare lo stesso modello con -ngl 0, poi con il valore predefinito, e confrontare. La differenza tra i due mostra il contributo effettivo della GPU sulla tua macchina e conferma che il calcolo passa effettivamente attraverso Metal. Annota anche la versione di llama.cpp utilizzata: le ottimizzazioni Metal evolvono rapidamente e un binario datato può essere nettamente più lento di una versione recente.

#Risoluzione dei problemi: errori comuni

• MLX vs llama.cpp su Mac: chi vince nel 2026?
• Compilare llama.cpp con CUDA
• Quali modelli per 32 GB di memoria

• Fonte: repository ufficiale di llama.cpp
• Fonte: documentazione per la compilazione di llama.cpp
• Fonte: benchmark pubblico su Apple Silicon
• Fonte: discussione sulla limitazione della memoria GPU dei Mac