Llama.cpp in Locale: Guida Completa al Server GGUF in 12 Passi

llama.cpp trasforma una scheda NVIDIA da gaming o un normale server Linux in un endpoint di inferenza compatibile con le API di OpenAI, eliminando abbonamenti, token a consumo e la necessità di inviare prompt fuori dalla rete. Il progetto, scritto in C e C++, carica modelli in formato GGUF e gira su CUDA, Metal, Vulkan o esclusivamente su CPU.

Per chi opera in Italia o in Europa il vantaggio è concreto: i dati rimangono su una macchina controllata dall’utente, semplificando la valutazione GDPR di chatbot interni, assistenti per i contratti o sistemi di ricerca documentale. Strumenti come LM Studio e Ollama si basano, in tutto o in parte, sullo stesso motore; usarlo direttamente richiede qualche comando in più, ma restituisce il controllo completo su flag di compilazione, offload dei layer, cache KV, quantizzazione e parametri del server.

Prerequisiti e ambiente di riferimento

La procedura è stata testata su Ubuntu 24.04 LTS a 64 bit, ma è facilmente adattabile ad altre distribuzioni Linux o a WSL2 su Windows 11, a patto di disporre di una GPU NVIDIA con driver proprietari recenti.

Hardware richiesto:

• GPU NVIDIA con driver proprietario aggiornato (CUDA 12 o superiore consigliato).
• Almeno 60 GB di spazio disco libero per scaricare e convertire i modelli.
• RAM di sistema adeguata per gestire la cache KV (minimo 16 GB consigliati).

Software necessario:

• gcc 13 e g++ 13 (pacchetti predefiniti di Ubuntu 24.04).
• CMake e Git dalle versioni ufficiali.
• CUDA Toolkit versione 12.x o successiva.
• Python 3.12 con venv e pip (usato solo per scaricare e convertire i modelli).
• Accesso a internet per clonare il repository di llama.cpp e scaricare i pesi da Hugging Face.

Una volta soddisfatti i requisiti, è possibile procedere con i 12 passi descritti di seguito.

Passo 1 – Clonare il repository

Aprire il terminale e eseguire:

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

Questo scarica l’ultima build del progetto; poiché non esiste un numero di release tradizionale, è buona pratica annotare il commit corrente con git rev-parse --short HEAD per futura referenza.

Passo 2 – Installare le dipendenze di compilazione

Su Ubuntu 24.04 eseguire:

sudo apt update
sudo apt install -y build-essential cmake git python3-venv python3-pip

Se si prevede di utilizzare CUDA, installare anche il toolkit:

sudo apt install -y nvidia-cuda-toolkit

Passo 3 – Compilare i binari

Il progetto supporta diverse backend; per abilitare CUDA:

mkdir build && cd build
cmake .. -DLLAMACUBLAS=ON -DLLAMANATIVE=ON
make -j$(nproc)

Per un build CPU‑only, omettere le opzioni CUDA. Al termine della compilazione saranno disponibili i binari llama-cli, llama-server, llama-quantize, llama-bench e llama-perplexity.

Passo 4 – Creare un ambiente Python per il download dei modelli

Creare e attivare un virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install huggingface_hub

Questo permette di scaricare i pesi direttamente da Hugging Face senza doverli gestire manualmente.

Passo 5 – Scaricare un modello GGUF

Per questo esempio useremo il modello “Mistral‑7B‑Instruct” in versione Q4KM, disponibile su Hugging Face. Il comando è:

python -m huggingface_hub download TheBloke/Mistral-7B-Instruct-GGUF \
mistral-7b-instruct.Q4KM.gguf --local-dir ./models

Il file mistral-7b-instruct.Q4KM.gguf verrà salvato nella cartella ./models.

Passo 6 – Verificare la compatibilità della VRAM

Un modello da 7 miliardi di parametri a 4 bit occupa circa 3,5 GB di spazio su disco; per una GPU con 8 GB di VRAM, lasciando il 20 % di margine per cache e buffer, il modello è compatibile. Se la VRAM fosse inferiore, considerare una versione Q3KM o Q5KM.

Passo 7 – Configurare il server

Creare un file di servizio systemd nella directory /etc/systemd/system/llama-server.service con il seguente contenuto:

[Unit]
Description=llama.cpp server
After=network.target

[Service]
Type=simple
ExecStart=/path/to/llama.cpp/build/llama-server \
-m /path/to/models/mistral-7b-instruct.Q4KM.gguf \
-c 2048 \
-p 8080 \
--host 0.0.0.0 \
--log-level info
Restart=on-failure
User=llama
Group=llama

[Install]
WantedBy=multi-user.target

Modificare /path/to con il percorso reale del binario e del modello. Il flag -c 2048 imposta la dimensione della cache KV a 2048 token; adeguarlo in base alle esigenze dell’applicazione.

Passo 8 – Avviare e abilitare il servizio

sudo systemctl daemon-reload
sudo systemctl enable llama-server
sudo systemctl start llama-server
sudo systemctl status llama-server

Il server risponderà sulla porta 8080 con endpoint compatibili con le API di OpenAI (/v1/completions, /v1/chat/completions, ecc.).

Passo 9 – Testare l’API

Con curl è possibile inviare una semplice richiesta di chat:

curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"mistral-7b-instruct","messages":[{"role":"user","content":"Ciao, come stai?"}]}'

Il server restituirà una risposta JSON contenente il completamento generato dal modello.

Passo 10 – Monitorare le risorse

Utilizzare nvidia-smi per osservare l’utilizzo della VRAM e htop per la RAM di sistema. Se la cache KV supera le previsioni, aumentare il valore del flag -c o ridurre la lunghezza del contesto nelle richieste.

Passo 11 – Ottimizzare la quantizzazione

Se il modello scelto è troppo grande per la VRAM disponibile, è possibile ricreare una versione più compressa con llama-quantize. Esempio per passare da Q4KM a Q3KM:

./build/llama-quantize ./models/mistral-7b-instruct.Q4KM.gguf ./models/mistral-7b-instruct.Q3KM.gguf Q3KM

Il nuovo file sarà più piccolo, ma con un degrado di qualità visibile soprattutto su compiti complessi.

Passo 12 – Aggiornare e mantenere il servizio

Periodicamente controllare il repository di llama.cpp per nuove commit:

git pull origin master
git rev-parse --short HEAD   # annotare il nuovo commit
cd build && make -j$(nproc)   # ricompilare
sudo systemctl restart llama-server

Conservare la mappatura tra commit, opzioni di compilazione e versioni di modello facilita il debug e la replica in ambienti di staging.

Confronto con alternative comuni

La tabella seguente riassume le differenze principali tra i quattro strumenti di inferenza locale più diffusi:

Strumento	Punto di forza	Limite principale	Uso tipico
llama.cpp	Controllo totale, binario unico, supporto GGUF	Curva di apprendimento più alta	Server, edge, quantizzazione personalizzata
Ollama	Installazione in un comando, catalogo pronto	Meno parametri esposti	Sviluppo rapido, prototipi
LM Studio	Interfaccia grafica e server integrato	App desktop, meno adatta ai server	Prove su PC, uso individuale
vLLM	Throughput elevato con molti utenti	Richiede GPU e setup Python più pesanti	Servizi con molte richieste parallele

La regola pratica è: se serve una demo in dieci minuti, partire da Ollama o LM Studio; se serve un servizio stabile su una macchina precisa, con parametri documentati e riproducibili, llama.cpp ripaga l’investimento già dopo la prima settimana.

Scelta della quantizzazione: guida rapida

Il formato GGUF indica quanti bit usa ogni peso. La tabella riassume le opzioni più comuni:

• Q8_0 – 8 bit: quasi identica all’originale, richiede abbondante VRAM.
• Q6_K – 6 bit: ottimo compromesso, qualità molto vicina all’originale.
• Q5KM – 5 bit: buona per GPU di fascia alta, qualità ottimale.
• Q4KM – 4 bit: scelta predefinita per la maggior parte dei casi, perdita contenuta.
• Q3KM – 3 bit: degrado visibile, usato solo quando la memoria è molto limitata.
• F16 – 16 bit: formato di riferimento per la conversione, non consigliato per l’uso diretto.

Per stimare la dimensione del file, moltiplicare i parametri (in miliardi) per i bit, dividere per 8 e aggiungere un margine del 10‑15 % per cache KV e buffer di calcolo.

Considerazioni finali sulla GDPR e sicurezza

Poiché tutti i dati restano sulla macchina locale, non è necessario inviare informazioni sensibili a terzi. È comunque consigliabile:

• Abilitare il firewall e limitare l’accesso alla porta 8080 solo a IP autorizzati.
• Utilizzare TLS termination tramite un reverse proxy (ad esempio Nginx) per criptare le comunicazioni.
• Loggare le richieste in modo da poter ricostruire eventuali audit GDPR.

Con questi accorgimenti, llama.cpp fornisce una soluzione di inferenza locale robusta, scalabile e conforme alle normative europee, ideale per imprese che desiderano mantenere il pieno controllo sui propri modelli linguistici.