llama.cpp: avvio rapido con CLI e Server

Continuo a tornare a llama.cpp per l’inferenza locale: offre un livello di controllo che Ollama e altri strumenti astraggono, e funziona semplicemente. È facile eseguire modelli GGUF in modo interattivo con llama-cli o esporre un’API HTTP compatibile con OpenAI con llama-server.

Se stai ancora decidendo tra approcci locali, self-hosted e cloud, parti dalla guida fondamentale Hosting di LLM nel 2026: Confronto tra Infrastrutture Locali, Self-Hosted e Cloud.

Perché llama.cpp nel 2026

llama.cpp è un motore di inferenza leggero con una tendenza verso:

• la portabilità su CPU e più backend GPU,
• latenza prevedibile su una singola macchina,
• flessibilità di deployment, dai laptop ai nodi on-prem.

Brilla quando si desidera privacy e funzionamento offline, quando è necessario un controllo deterministico sulle flag di runtime, o quando si vuole incorporare l’inferenza in un sistema più grande senza eseguire uno stack Python pesante.

È anche utile comprendere llama.cpp anche se in seguito si sceglie un runtime di server con throughput più elevato. Ad esempio, se l’obiettivo è il massimo throughput di serving su GPU, potrebbe essere utile confrontarlo con vLLM utilizzando: VLLM Quickstart: Serving ad Alte Prestazioni di LLM e puoi fare il benchmark delle scelte degli strumenti in: Ollama vs vLLM vs LM Studio: Il Miglior Modo per Eseguire LLM Localmente nel 2026?.

Se Ollama è specificamente l’alternativa che stai valutando rispetto a llama-server, llama.cpp vs Ollama nel 2026 è il confronto dedicato, con trigger concreti per quando mantenere Ollama e quando passare a llama.cpp diretto.

Installare llama.cpp su Windows, macOS e Linux

Ci sono tre percorsi pratici di installazione, a seconda di si desideri comodità, portabilità o prestazioni massime.

Installazione tramite gestori di pacchetti

Questa è l’opzione più rapida per “averlo in funzione”.

# macOS o Linux
brew install llama.cpp

# Windows
winget install llama.cpp

# macOS (MacPorts)
sudo port install llama.cpp

# macOS o Linux (Nix)
nix profile install nixpkgs#llama-cpp

Suggerimento: dopo l’installazione, verifica che gli strumenti esistano:

llama-cli --version
llama-server --version

Installazione tramite binari precompilati

Se si desidera un’installazione pulita senza compilatori, usa i binari precompilati ufficiali pubblicati nelle release GitHub di llama.cpp. Coprono tipicamente più target OS e più backend (varianti solo CPU e abilitate per GPU).

Un flusso di lavoro comune:

# 1) Scarica l'archivio giusto per il tuo OS e backend
# 2) Estrailo
# 3) Esegui dalla cartella estratta

./llama-cli --help
./llama-server --help

Compilazione da sorgente per l’hardware esatto

Se ti importa di spremere le migliori prestazioni dal tuo backend CPU/GPU, compila da sorgente con CMake.

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

# Build CPU
cmake -B build
cmake --build build --config Release

Dopo la build, i binari si trovano tipicamente qui:

ls -la ./build/bin/

Build GPU in un comando

Abilita il backend che corrisponde al tuo hardware (esempi mostrati per CUDA e Vulkan):

# NVIDIA CUDA
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Vulkan
cmake -B build -DGGML_VULKAN=ON
cmake --build build --config Release

Ubuntu 24.04 + GPU NVIDIA: guida completa alla build

Su Ubuntu 24.04 con una GPU NVIDIA, è necessario il toolkit CUDA e OpenSSL prima della compilazione. Ecco una sequenza testata:

1. Installa il toolkit CUDA 13.1

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin
sudo mv cuda-ubuntu2404.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/13.1.1/local_installers/cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2404-13-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-1

2. Aggiungi CUDA al tuo ambiente (appendi a ~/.bashrc):

# cuda toolkit
export PATH=/usr/local/cuda-13.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-13.1/lib64:$LD_LIBRARY_PATH

Poi esegui source ~/.bashrc o apri un nuovo terminale.

3. Installa le intestazioni di sviluppo di OpenSSL (richieste per una build pulita):

sudo apt update
sudo apt install libssl-dev

4. Compila llama.cpp (dalla directory che contiene il tuo clone di llama.cpp, con CUDA abilitato):

cmake llama.cpp -B llama.cpp/build -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split llama-embedding
cp llama.cpp/build/bin/llama-* llama.cpp

Questa procedura produce llama-cli, llama-mtmd-cli, llama-server, llama-embedding e llama-gguf-split nella directory llama.cpp.

È anche possibile compilare più backend e scegliere i dispositivi in fase di runtime. Questo è utile se si distribuisce la stessa build su macchine eterogenee.

Scegliere un modello GGUF e una quantizzazione

Per eseguire l’inferenza, è necessario un file modello GGUF (*.gguf). GGUF è un formato a file singolo che raggruppa i pesi del modello e i metadati standardizzati richiesti da motori come llama.cpp.

Due modi per ottenere un modello

Opzione A: Usare un file GGUF locale

Scarica o copia un GGUF in ./models/:

mkdir -p models
# Posiziona il tuo GGUF in models/my-model.gguf

Poi esegui tramite percorso:

llama-cli -m models/my-model.gguf -p "Ciao! Spiega cos'è llama.cpp." -n 128

Opzione B: Lasciare che llama.cpp scarichi da Hugging Face

Le build moderne di llama.cpp possono scaricare da Hugging Face e mantenere i file in una cache locale. Questo è spesso il flusso di lavoro più facile per esperimenti rapidi.

# Scarica un modello da HF ed esegui un prompt
llama-cli \
  --hf-repo ggml-org/tiny-llamas \
  --hf-file stories15M-q4_0.gguf \
  -p "C'era una volta," \
  -n 200

È anche possibile specificare la quantizzazione nel selettore del repository e lasciare che lo strumento selezioni un file corrispondente:

llama-cli \
  --hf-repo unsloth/phi-4-GGUF:q4_k_m \
  -p "Riassumi il concetto di quantizzazione in un paragrafo." \
  -n 160

Se in seguito è necessario un flusso di lavoro completamente offline, --offline forza l’uso della cache e impedisce l’accesso alla rete.

Scelta della quantizzazione per l’inferenza locale

La quantizzazione è la risposta pratica alla domanda “Quale quantizzazione GGUF scegliere per l’inferenza locale” perché opera direttamente un compromesso tra qualità, dimensione del modello e velocità.

Un punto di partenza pragmatico:

• inizia con una variante Q4 o Q5 per macchine con priorità CPU,
• passa a una precisione più alta (o una quantizzazione meno aggressiva) quando puoi permetterti la RAM o la VRAM,
• quando il modello “sembra stupido” per il tuo compito, la soluzione è spesso un modello migliore o una quantizzazione meno aggressiva, non solo aggiustamenti del sampling.

Ricorda anche che la finestra di contesto conta: dimensioni di contesto maggiori aumentano l’uso della memoria (a volte drasticamente), anche quando il file GGUF stesso entra nella memoria.

Quickstart di llama-cli e parametri chiave

llama-cli è il modo più rapido per verificare che il modello venga caricato, che il backend funzioni e che i prompt si comportino correttamente.

Esecuzione minima

llama-cli \
  -m models/my-model.gguf \
  -p "Scrivi un breve confronto tra TCP e UDP." \
  -n 200

Esecuzione di chat interattiva

La modalità conversazionale è progettata per template di chat. Abilita tipicamente il comportamento interattivo e formatta i prompt secondo il template del modello.

llama-cli \
  -m models/my-model.gguf \
  --conversation \
  --system-prompt "Sei un assistente conciso di ingegneria dei sistemi." \
  --ctx-size 4096

Per terminare la generazione quando il modello stampa una specifica sequenza, usa un reverse prompt. Questo è particolarmente utile in modalità interattiva.

Flag principali di llama-cli che contano

Piuttosto che memorizzare 200 flag, concentrati su quelli che dominano correttezza, latenza e memoria.

Modello e download

Contesto e throughput

Offload GPU e selezione hardware

Sampling e qualità dell’output

Esempi di carichi di lavoro con llama-cli

Riassumere un file, non solo un prompt

llama-cli \
  -m models/my-model.gguf \
  --system-prompt "Riassumi documenti tecnici. Output massimo di cinque punti elenco." \
  --file ./docs/incident-report.txt \
  -n 300

Rendere i risultati più riproducibili

Quando si stanno debuggando i prompt, fissa il seed e riduci la casualità:

llama-cli \
  -m models/my-model.gguf \
  -p "Estrai i rischi chiave da questa nota di progettazione." \
  -n 200 \
  --seed 42 \
  --temp 0,2

Quickstart di llama-server con API compatibile OpenAI

llama-server è un server HTTP integrato che può esporre:

• endpoint compatibili con OpenAI per chat, completamenti, embedding e risposte,
• un’interfaccia Web per test interattivi,
• endpoint di monitoraggio opzionali per visibilità in produzione.

Avviare un server con un modello locale

llama-server \
  -m models/my-model.gguf \
  -c 4096

Per impostazione predefinita, ascolta su 127.0.0.1:8080.

Per collegarsi esternamente (ad esempio all’interno di Docker o in una LAN), specificare host e porta:

llama-server \
  -m models/my-model.gguf \
  -c 4096 \
  --host 0.0.0.0 \
  --port 8080

Flag opzionali ma importanti del server

Se si esegue in contenitori, molte impostazioni possono essere controllate anche tramite variabili d’ambiente LLAMA_ARG_*.

Esempi di chiamate API

Chat completions con curl

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      { "role": "system", "content": "Sei un assistente utile." },
      { "role": "user", "content": "Dammi un rapido check-list di llama.cpp." }
    ],
    "temperature": 0.7
  }'

Suggerimento per deploy reali: se si imposta --api-key, è possibile inviarlo tramite un header x-api-key (o continuare a usare gli header di Authorization a seconda del gateway).

Client Python OpenAI puntato a llama-server

Con un server compatibile con OpenAI, molti client possono funzionare cambiando solo base_url.

import openai

client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-no-key-required",
)

resp = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "Sei un assistente conciso."},
        {"role": "user", "content": "Spiega threads vs batch size in llama.cpp."},
    ],
)

print(resp.choices[0].message.content)

Embeddings

Gli embeddings compatibili con OpenAI sono esposti in /v1/embeddings, ma il modello deve supportare una modalità di pooling di embedding diversa da none.

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "input": ["hello", "world"],
    "model": "GPT-4",
    "encoding_format": "float"
  }'

Se si esegue un modello di embedding dedicato, si potrebbe prendere in considerazione l’avvio del server in modalità solo embedding:

llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

o se si desidera eseguire llama-cpp con un modello di embedding su CPU:

CUDA_VISIBLE_DEVICES="" llama-server \
  -m models/Qwen3-Embedding-0.6B-Q8_0.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --pooling last \
  --port 8080

provalo così:

CUDA_VISIBLE_DEVICES="" llama-embedding \
  -m /path/to/Qwen3-Embedding-0.6B-Q8_0.gguf \
  -p "il tuo testo qui" \
  --pooling last \
  --verbose-prompt

Servire più modelli da un unico processo

Gli esempi sopra legano llama-server a un singolo modello all’avvio. Se è necessario cambiare modelli su base per richiesta — senza riavviare il processo — è a questo che serve la modalità router. Vedi llama-server router mode: commutazione dinamica dei modelli senza riavvii. Per un flusso scriptabile di scarico di tutti i modelli che libera la VRAM senza riavviare il router, vedi Scarica Tutti i Modelli del Router llama.cpp Senza Riavviare.

Prestazioni, monitoraggio e indurimento per la produzione

La domanda frequente “Quali opzioni da riga di comando di llama.cpp sono più importanti per velocità e memoria” diventa molto più facile quando si tratta l’inferenza come un sistema:

• Il limite di memoria è di solito il primo vincolo (RAM su CPU, VRAM su GPU).
• La dimensione del contesto è un moltiplicatore di memoria importante.
• L’offload dei layer sulla GPU è spesso il percorso più rapido verso un maggiore numero di token al secondo.
• Le dimensioni del batch e i thread possono migliorare il throughput, ma possono anche aumentare la pressione sulla memoria.

Per una visione più approfondita e incentrata sull’ingegneria, vedi: Prestazioni LLM nel 2026: Benchmark, Colli di Bottiglia e Ottimizzazione.

Se si desidera risultati misurati in stile llama-cli su una GPU della classe 16 GB—token al secondo, VRAM e carico GPU durante lo sweep del contesto (19K / 32K / 64K) su GGUF densi e MoE—vedi Benchmark LLM con 16 GB VRAM su llama.cpp (velocità e contesto).

Per Qwen 3.6 in particolare, llama.cpp supporta ora la decodifica speculativa con Multi-Token Prediction (MTP) integrata che può aumentare significativamente il throughput di generazione. Per una guida completa che copre tutti i metodi di decodifica speculativa in llama.cpp, vedi Decodifica Speculativa. Per i benchmark specifici di MTP di Qwen 3.6, vedi Qwen 3.6 MTP vs Standard su GPU 16GB.

Monitoraggio di llama-server con Prometheus e Grafana

llama-server può esporre metriche compatibili con Prometheus in /metrics quando --metrics è abilitato. Si abbina naturalmente alle config di scrape di Prometheus e alle dashboard Grafana.

Per dashboard e alert specifici per llama.cpp (e vLLM, TGI): Monitoraggio dell’Inferenza LLM in Produzione (2026): Prometheus & Grafana per vLLM, TGI, llama.cpp. Guide più ampie: Osservabilità: Guida a Monitoraggio, Metriche, Prometheus & Grafana e Osservabilità per Sistemi LLM.

Checklist base per l’indurimento

Quando il tuo llama-server è raggiungibile oltre localhost:

• usa --api-key (o --api-key-file) in modo che le richieste siano autenticate,
• evita di collegarti a 0.0.0.0 a meno che non ne hai bisogno,
• considera TLS tramite le flag SSL del server o termina TLS su un reverse proxy,
• restringi la concorrenza con --parallel per proteggere la latenza sotto carico.

Soluzioni rapide per i problemi

Il modello si carica ma le risposte sono strane in chat

Gli endpoint di chat sono migliori quando il modello ha un template di chat supportato. Se gli output sembrano non strutturati, prova:

• usando llama-cli --conversation più un --system-prompt esplicito,
• verificando che il tuo modello sia una variante istruzione o chat-tuned,
• testando usando l’interfaccia Web del server prima di collegarla a un’app.

Si incontra out of memory

Riduci il contesto o scegli una quantizzazione più piccola:

• abbassa --ctx-size,
• riduci --n-gpu-layers se il problema è la VRAM,
• passa a un modello più piccolo o a una quantizzazione più compressa.

È lento su CPU

Inizia con:

• --threads uguale ai tuoi core fisici,
• dimensioni del batch moderate,
• validando di aver installato una build che corrisponde alla tua macchina (funzionalità CPU e backend).

Riferimenti

• Repository e documentazione ufficiali di llama.cpp
• Documentazione ufficiale delle flag CLI
• Documentazione ufficiale di llama-server e dettagli API