Guida all'installazione · Intermedio · 20 min

Compilare ed eseguire llama.cpp dai sorgenti

llama.cpp è l'implementazione di riferimento in C e C++ alla base della maggior parte degli strumenti per LLM locali, inclusi Ollama e LM Studio. Compilarlo dai sorgenti ti dà un controllo più fine su quantizzazione, sampling e backend di accelerazione da usare. Su Apple Silicon tende anche a essere la via più veloce.

Quando usare llama.cpp direttamente

Usa i binari upstream quando vuoi le ottimizzazioni più recenti (le release spesso precedono di settimane i pacchetti delle distribuzioni), quando ti serve uno schema di quantizzazione che i wrapper a valle non espongono, o quando vuoi scriptare un flusso di inferenza ad alto throughput senza un daemon in più. Per chattare ogni tanto la compilazione non vale la fatica; per quello esiste Ollama.

Passo 1. Installa la toolchain di compilazione

macOS

xcode-select --install
brew install cmake

Linux (Debian / Ubuntu)

sudo apt update
sudo apt install build-essential cmake git
# For NVIDIA acceleration:
sudo apt install nvidia-cuda-toolkit

Windows

Installa Visual Studio Build Tools (con il workload C++), CMake e Git. Il CUDA toolkit è facoltativo ma consigliato su GPU NVIDIA. Con questi strumenti nel path, compilare da PowerShell è lineare.

Passo 2. Clona e compila

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

# Pick exactly one backend below.

# Apple Silicon (Metal):
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release -j

# NVIDIA (CUDA):
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j

# AMD (ROCm):
cmake -B build -DGGML_HIP=ON -DAMDGPU_TARGETS=gfx1100
cmake --build build --config Release -j

# Vulkan (cross-vendor GPU, less mature):
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release -j

# CPU-only:
cmake -B build
cmake --build build --config Release -j

La compilazione produce diversi binari in build/bin/. I due che userai di più sono llama-cli (chat interattiva) e llama-server (il server HTTP compatibile OpenAI).

Passo 3. Scegli una quantizzazione GGUF

llama.cpp usa il formato GGUF. Il suffisso di quantizzazione che scegli è il compromesso tra spazio su disco, uso di memoria e qualità. Tre varianti valgono come punto di partenza.

• Q4_K_M — la variante a 4 bit più diffusa. Buona qualità, ingombro contenuto, il default sensato per la maggior parte dell'uso desktop.
• Q5_K_M — un miglioramento percepibile rispetto a Q4 con circa il 25% di memoria in più. Ne vale la pena quando hai margine.
• Q8_0 — quantizzazione a 8 bit. Qualità molto vicina ai pesi originali, utile per benchmark o produzione dove la dimensione conta meno.

I modelli già quantizzati si trovano su Hugging Face sotto account come TheBloke, bartowski e unsloth. Scegli il file GGUF che corrisponde alla quantizzazione che hai deciso.

# Example: Qwen 2.5 7B Instruct, Q4_K_M
huggingface-cli download bartowski/Qwen2.5-7B-Instruct-GGUF \
  Qwen2.5-7B-Instruct-Q4_K_M.gguf \
  --local-dir ./models --local-dir-use-symlinks False

Passo 4. Prima inferenza

./build/bin/llama-cli \
  --model ./models/Qwen2.5-7B-Instruct-Q4_K_M.gguf \
  --ctx-size 8192 \
  --n-gpu-layers 999 \
  --prompt "Explain how PagedAttention reduces KV cache memory."

Il flag --n-gpu-layers scarica sulla GPU tutti i layer che ci stanno. Impostarlo a un numero grande equivale a dire “tutto quello che riesci”. Se la VRAM non basta, llama.cpp si rifiuta di caricare e ti dice quanti layer è riuscito a gestire; abbassa il numero finché il modello non entra, oppure scegli una quantizzazione più piccola.

Passo 5. Servi un'API compatibile OpenAI

./build/bin/llama-server \
  --model ./models/Qwen2.5-7B-Instruct-Q4_K_M.gguf \
  --ctx-size 8192 \
  --n-gpu-layers 999 \
  --host 0.0.0.0 \
  --port 8080 \
  --parallel 4 \
  --cont-batching

Il server ascolta su http://localhost:8080 con un endpoint chat completions compatibile OpenAI su /v1/chat/completions. --parallel definisce quante richieste concorrenti gestisce, e --cont-batching attiva il continuous batching per un throughput maggiore quando c'è più di una richiesta in volo.

Passo 6. Quantizza un modello per conto tuo

Se vuoi convertire e quantizzare un modello appena uscito su Hugging Face, il flusso è chiaro ma richiede più passaggi. Prima converti in GGUF, poi quantizza.

# Convert from a Hugging Face snapshot to FP16 GGUF
python convert_hf_to_gguf.py ./snapshots/some-model \
  --outfile ./models/some-model.f16.gguf \
  --outtype f16

# Quantize to Q4_K_M
./build/bin/llama-quantize \
  ./models/some-model.f16.gguf \
  ./models/some-model.Q4_K_M.gguf \
  Q4_K_M

Risoluzione degli errori più comuni

La build CUDA fallisce per un compilatore incompatibile

Il CUDA toolkit è esigente sul compilatore host che accetta. Su Ubuntu 24.04 con una versione CUDA recente può servire installare g++-12 e indicarlo esplicitamente a CMake: cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_HOST_COMPILER=g++-12.

Il server si blocca alla prima richiesta dopo il riavvio

Quasi sempre è il warm-up del modello. La prima generazione dopo il caricamento spende tempo a costruire la KV cache. Le richieste successive sono veloci.

I token al secondo sembrano pochi per la tua GPU

Verifica che la GPU sia davvero in uso (nvidia-smi su Linux). Controlla che --n-gpu-layers sia abbastanza alto da tenere l'intero modello sulla GPU. Conferma che la flash attention risulti attiva nel banner di avvio del server.

Prossimi passi

Con llama-server in funzione puoi collegarci qualsiasi client compatibile OpenAI. Abbinalo a Open WebUI per un'interfaccia di chat, oppure integralo in VS Code tramite Continue.dev. Per carichi multi-GPU o multi-tenant llama.cpp non basta; in quel caso passa a vLLM.