llama.cpp: Guida rapida con CLI e Server

llama.cpp è un motore di inferenza in C/C++ per modelli GGUF: llama-cli per la chat interattiva, llama-completion per prompt scriptizzati e llama-server per un’API HTTP compatibile con OpenAI.

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

Perché llama.cpp nel 2026

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

• portabilità tra CPU e molteplici 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 serve controllo deterministico sui flag di runtime, o quando si vuole incorporare l’inferenza in un sistema più ampio senza eseguire uno stack pesante basato su Python.

È utile comprendere llama.cpp anche se in seguito si sceglie un runtime server con throughput maggiore. Ad esempio, se l’obiettivo è il throughput massimo di serving su GPU, potresti volerlo confrontare con vLLM utilizzando: vLLM Quickstart: Serving ad Alte Prestazioni per LLM e puoi effettuare benchmark delle scelte di tool in: Ollama vs vLLM vs LM Studio: Il modo migliore per eseguire LLM Localmente nel 2026?.

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

Installazione di llama.cpp su Windows, macOS e Linux

I comandi seguenti corrispondono a llama.cpp v0.6.0 (5 ottobre 2026). Un’entrata nel catalogo per lo stesso runtime — inferenza GGUF su CPU e backend acceleratori, versionata per commit di build — si trova alla riferimento runtime llama.cpp su LLM Systems. Ci sono quattro percorsi pratici di installazione, a seconda che tu desideri comodità, portabilità o prestazioni massime.

Installazione tramite gestori di pacchetti

Questa è l’opzione più rapida per “farlo funzionare”.

# 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

# Ubuntu (universe). Questo pacchetto è molto indietro rispetto all'upstream:
# 8681+dfsg contro la build corrente b11433 / v0.6.0, quindi i flag più recenti mancheranno.
sudo apt install llama.cpp-tools

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

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

Installazione tramite binari precompilati

Se desideri un’installazione pulita senza compiler, utilizza i binari precompilati ufficiali pubblicati nei rilasci GitHub di llama.cpp. In genere coprono più target OS e più backend (varianti solo CPU e varianti 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

Esecuzione del container ufficiale

Il progetto pubblica immagini server sul GitHub Container Registry. L’immagine CPU è ghcr.io/ggml-org/llama.cpp:server; l’immagine CUDA è :server-cuda. Il container deve ascoltare su tutte le interfacce, poiché il bind predefinito è ancora 127.0.0.1:

docker run --gpus all -p 8080:8080 \
  -v /path/to/models:/models \
  ghcr.io/ggml-org/llama.cpp:server-cuda \
  -m models/my-model.gguf -c 4096 --host 0.0.0.0 -ngl all

Compilazione dal sorgente per l’esatta configurazione hardware

Se ti interessa spremere le migliori prestazioni dal tuo backend CPU/GPU, compila dal 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, hai bisogno del toolkit CUDA e OpenSSL prima della compilazione. Ecco una sequenza testata:

1. Installa il toolkit CUDA 13.1. Questa guida fissa l’installer locale 13.1.1. Un toolkit più recente dal repository Ubuntu 24.04 di NVIDIA segue gli stessi passi di pin-file e deb locale con nomi file aggiornati.

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 all’ambiente (aggiungi 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 gli header di sviluppo di OpenSSL (necessari per una build pulita):

sudo apt update
sudo apt install libssl-dev

4. Compila llama.cpp (dalla directory contenente 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

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

Puoi anche compilare più backend e scegliere i dispositivi in fase di esecuzione. Questo è utile se distribuischi la stessa build su macchine eterogenee.

Scegli un modello GGUF e una quantizzazione

Per eseguire l’inferenza, hai bisogno di un file di modello GGUF (*.gguf). GGUF è un formato a file singolo che raccoglie i pesi del modello e i metadati standardizzati necessari per motori come llama.cpp.

Due modi per ottenere un modello

Opzione A: Utilizza 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 indicandolo per percorso:

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

Opzione B: Lascia 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ù semplice 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 \
  -st

Puoi anche 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 \
  -st

Se in seguito hai bisogno di 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 dovresti scegliere per l’inferenza locale”, poiché scambia direttamente qualità, dimensione del modello e velocità.

Un punto di partenza pragmatico:

• parti da una variante Q4 o Q5 per macchine a prevalenza 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 correzione è spesso un modello migliore o una quantizzazione meno aggressiva, non solo regolazioni del sampling.

Ricorda anche che la finestra di conteggio conta: dimensioni di contesto più grandi aumentano l’uso della memoria (a volte drasticamente), anche quando il file GGUF stesso è contenuto.

Quickstart di llama-cli e parametri chiave

llama-cli è il modo più veloce per validare che il tuo modello carichi, che il tuo backend funzioni e che i tuoi prompt si comportino correttamente.

llama-cli è un client di chat interattiva dalla riscrittura di dicembre 2025. Quando il modello include un template di chat, la modalità conversazione è attiva di default e --no-conversation viene rifiutato con un rinvio a llama-completion. Quel secondo binario è il vecchio llama-cli: un prompt in ingresso, una completion in uscita, adatto per script e pipe. Dal nuovo client, --single-turn (-st) genera una risposta ed esce.

Una risposta, poi esci

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

Lo stesso prompt attraverso il binario non interattivo:

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

Esecuzione di chat interattiva

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

--conversation non è più necessario. Per terminare la generazione quando il modello stampa una sequenza specifica, usa un prompt inverso.

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

Carichi di lavoro di esempio con llama-cli

Riassumere un file, non solo un prompt

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

Rendere i risultati più riproducibili

Quando stai debuggando 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 \
  -st

Quickstart di llama-server con API compatibile OpenAI

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

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

Avvio di 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 bind esterno (ad esempio all’interno di Docker o di una LAN), specifica host e porta:

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

Flag opzionali ma importanti per il server

Se esegui in container, molte impostazioni possono essere controllate anche tramite variabili d’ambiente LLAMA_ARG_*.

Chiamate API di esempio

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 una checklist rapida di llama.cpp." }
    ],
    "temperature": 0.7
  }'

Suggerimento per deploy reali: se imposti --api-key, puoi inviarlo tramite un header x-api-key (o continuare a usare header Authorization a seconda del tuo gateway).

Client Python OpenAI puntato a llama-server

Con un server compatibile con OpenAI, molti client possono funzionare cambiando solo base_url — questo è anche il modo in cui agenti di ricerca come lukeswade/deep-research parlano direttamente a llama-server, senza un livello di adapter separato. Sistemi di Deep Research Self-Hosted: 12 Tool Confrontati copre quel progetto e altri puntati a endpoint locali compatibili con OpenAI.

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 embedding compatibili con OpenAI sono esposti a /v1/embeddings, ma il modello deve supportare una modalità di pooling per embedding che non sia 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 esegui un modello di embedding dedicato, considera 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 vuoi eseguire llama-cpp con 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 in questo modo:

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

Serving di più modelli da un singolo processo

Gli esempi sopra legano llama-server a un singolo modello all’avvio. Se hai bisogno di alternare tra modelli su base per richiesta — senza riavviare il processo — è a questo che serve la modalità router. Vedi llama-server router mode: cambio dinamico di modello senza riavvio. Per un flusso scriptabile di unload-all che libera la VRAM senza riavviare il router, vedi Scaricare tutti i modelli router di llama.cpp senza riavviare.

Prestazioni, monitoraggio e hardening per la produzione

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

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

Per una vista più approfondita, orientata all’ingegneria, vedi: Prestazioni LLM nel 2026: Benchmark, Colli di Bottiglia & Ottimizzazione.

Se vuoi risultati misurati in stile llama-cli su una GPU di classe 16 GB — token al secondo, VRAM e carico GPU mentre spazzi il contesto (19K / 32K / 64K) tra GGUF densi e MoE — vedi Benchmark LLM su 16 GB VRAM con llama.cpp (velocità e contesto).

Per Qwen 3.6, llama.cpp supporta la decodifica speculativa Multi-Token Prediction integrata. Attivala con --spec-type draft-mtp; --spec-draft-n-max imposta quanti token la testata draft propone (default 3). v0.6.0 estende quel stesso percorso MTP a Qwen4Exp. Per il confronto dei metodi, vedi Speculative Decoding. Per i numeri misurati di Qwen 3.6 su 16 GB, vedi Qwen 3.6 MTP vs Standard su GPU 16GB.

Monitoraggio di llama-server con Prometheus e Grafana

llama-server espone metriche compatibili con Prometheus a /metrics solo quando è abilitato --metrics. Punta un job di scrape Prometheus a quel percorso. Le dashboard e le soglie di allerta per llama.cpp, vLLM e TGI si trovano in Monitoraggio dell’Inferenza LLM in Produzione (2026): Prometheus & Grafana per vLLM, TGI, llama.cpp.

Checklist base di hardening

Quando il tuo llama-server è raggiungibile oltre il localhost:

• usa --api-key (o --api-key-file) in modo che le richieste siano autenticate,
• evita il bind a 0.0.0.0 a meno che non ne hai bisogno,
• considera TLS tramite i flag SSL del server o termina TLS su un reverse proxy,
• limita la concorrenza con --parallel per proteggere la latenza sotto carico,
• lascia --tools e --agent disattivati. Entrambi sono sperimentali ed espongono operazioni su file e shell tramite l’API; abilitare entrambi restringe anche il CORS al localhost.

Soluzioni rapide per il troubleshooting

Il modello 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:

• passare un --system-prompt esplicito (la modalità conversazione è già il default in llama-cli),
• verificare che il tuo modello sia una variante instruction o chat-tuned,
• testare usando l’interfaccia Web del server prima di collegarlo a un’app. v0.6.0 ha ricostruito quell’UI con un browser per Hugging Face Hub, quindi un modello può essere scaricato dalla pagina e non solo dal CLI.

I modelli di ragionamento avvolgono la risposta in tracce di ragionamento. --reasoning off sopprime ciò, e --reasoning-format deepseek sposta la traccia in reasoning_content anziché in content.

Hai esaurito la memoria

Riduci il contesto o scegli una quantizzazione più piccola:

• abbassa --ctx-size,
• riduci --n-gpu-layers se il problema è la VRAM, o imposta --cpu-moe così i pesi degli esperti di un modello MoE restano in RAM,
• passa a un modello più piccolo o a una quantizzazione più compressa,
• quantizza la KV cache con --cache-type-k q8_0 --cache-type-v q8_0.

Il contesto o lo split GPU non sono quelli richiesti

--fit è attivo di default e riscrive le impostazioni di memoria che hai lasciato non impostate, mirando a lasciare 1024 MiB liberi su ogni dispositivo (--fit-target). Ridurrà il contesto, ma mai sotto --fit-ctx (4096), e solo se non hai passato -c. Non toccherà la disposizione dei layer una volta passato qualsiasi -ngl. --fit off disabilita il meccanismo. Se i log dicono n_gpu_layers already set by user, il tuo -ngl esplicito è ciò che ha caricato, e fit non salverà un out-of-memory da esso.

È lento su CPU

Inizia con:

• --threads uguale ai tuoi core fisici,
• dimensioni di 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 dei flag CLI
• Documentazione ufficiale di llama-server e dettagli API