Guida rapida a llama.cpp con CLI e Server

Torno sempre su llama.cpp per l’inferenza locale: offre un controllo che Ollama e altri astraggono, e semplicemente funziona. È 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, inizia con la guida principale Hosting LLM nel 2026: Confronto tra Infrastruttura Locale, Self-Hosted e Cloud.

Perché llama.cpp nel 2026

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

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

Brilla quando desideri privacy e funzionamento offline, quando hai bisogno di un controllo deterministico sui flag di runtime, o quando vuoi incorporare l’inferenza in un sistema più ampio senza eseguire uno stack pesante basato su Python.

È anche utile capire llama.cpp anche se in seguito scegli un runtime server con throughput più elevato. Ad esempio, se il tuo obiettivo è il throughput di servizio massimo sulle GPU, potresti volerlo confrontare con vLLM utilizzando: vLLM Quickstart: Servizio LLM ad alte prestazioni e puoi eseguire benchmark sulle scelte degli strumenti in: Ollama vs vLLM vs LM Studio: Il miglior modo per eseguire LLM localmente nel 2026?.

Installa llama.cpp su Windows, macOS e Linux

Esistono tre percorsi pratici di installazione, a seconda che tu cerchi comodità, portabilità o prestazioni massime.

Installazione tramite gestori di pacchetti

Questa è l’opzione più rapida per “farla 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

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

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

Installazione tramite binari precompilati

Se desideri un’installazione pulita senza compilatori, utilizza i binari precompilati ufficiali pubblicati nelle release GitHub di llama.cpp. Coprono tipicamente più target OS e backend (varianti solo CPU e abilitate 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

Compila dal sorgente per la tua hardware esatta

Se ti preme 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

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

Dopo la compilazione, i binari si trovano tipicamente qui:

ls -la ./build/bin/

Compilazioni GPU in un comando

Abilita il backend che corrisponde alla tua 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: procedura completa di compilazione

Su Ubuntu 24.04 con una GPU NVIDIA, hai bisogno del toolkit CUDA e di OpenSSL prima di compilare. Ecco una sequenza testata:

1. Installa CUDA toolkit 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 (aggiungi a ~/.bashrc):

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

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

3. Installa le intestazioni di sviluppo OpenSSL (necessarie per una compilazione 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 backend multipli e scegliere i dispositivi a runtime. Questo è utile se deployi la stessa compilazione su macchine eterogenee.

Scegli un modello GGUF e una quantizzazione

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

Due modi per ottenere un modello

Opzione A: Usa un file GGUF locale

Scarica o copia un GGUF in ./models/:

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

Quindi eseguilo per percorso:

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

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

Le compilazioni 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

Puoi anche specificare la quantizzazione nel selettore del repo 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 hai bisogno di un flusso di lavoro completamente offline in seguito, --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” perché scambia direttamente qualità, dimensione del modello e velocità.

Un punto di partenza pragmatico:

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

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

Quickstart di llama-cli e parametri chiave

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

Esecuzione minima

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

Esecuzione chat interattiva

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

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

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

Principali flag 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

Campionamento 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 "Tu riassumi documenti tecnici. Output massimo cinque punti." \
  --file ./docs/incident-report.txt \
  -n 300

Rendere i risultati più riproducibili

Quando debugghi 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 design." \
  -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 UI 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

Di default, ascolta su 127.0.0.1:8080.

Per legarsi esternamente (ad esempio dentro Docker o in una LAN), specifica host e porta:

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

Flag del server opzionali ma importanti

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

Chiamate API di esempio

Completamenti chat 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 per llama.cpp." }
    ],
    "temperature": 0.7
  }'

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

Client Python OpenAI che punta a llama-server

Con un server compatibile 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)

Embedding

Gli embedding compatibili OpenAI sono esposti a /v1/embeddings, ma il modello deve supportare una modalità di pooling embedding che non sia none.

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

Se esegui un modello di embedding dedicato, considera di lanciare il 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 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

Servizio di più modelli da un unico processo

Gli esempi sopra legano llama-server a un singolo modello all’avvio. Se hai bisogno di passare tra modelli su base per richiesta — senza riavviare il processo — quello è a cosa serve la modalità router. Vedi Modalità router di llama-server: commutazione dinamica del modello senza riavvii.

Prestazioni, monitoraggio e hardening per la produzione

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

• Soglia di memoria è solitamente il primo vincolo (RAM su CPU, VRAM su GPU).
• Dimensione del contesto è un moltiplicatore di memoria importante.
• Offload layer GPU è spesso il percorso più veloce verso token più alti al secondo.
• Dimensioni del batch e thread possono migliorare il throughput ma possono anche aumentare la pressione sulla memoria.

Per una visione più profonda, orientata all’ingegneria, vedi: Prestazioni LLM nel 2026: Benchmark, Colli di Bottiglia e Ottimizzazione.

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

Monitoraggio di llama-server con Prometheus e Grafana

llama-server può esporre metriche compatibili Prometheus a /metrics quando --metrics è abilitato. Questo si abbina naturalmente alle config di scrape Prometheus e ai dashboard di Grafana.

Per dashboard e alert specifici per llama.cpp (e vLLM, TGI): Monitorare l’inferenza LLM in produzione (2026): Prometheus & Grafana per vLLM, TGI, llama.cpp. Guide più ampie: Osservabilità: Guida al Monitoraggio, Metriche, Prometheus & Grafana e Osservabilità per Sistemi LLM.

Checklist di hardening di base

Quando il tuo llama-server è raggiungibile oltre localhost:

• usa --api-key (o --api-key-file) affinché le richieste siano autenticate,
• evita di legarti a 0.0.0.0 a meno che non ne abbia bisogno,
• considera TLS tramite i flag SSL del server o termina TLS a un proxy inverso,
• limita la concorrenza con --parallel per proteggere la latenza sotto carico.

Risoluzione rapida dei 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:

• usare llama-cli --conversation più un --system-prompt esplicito,
• verificare che il tuo modello sia una variante istruita o ottimizzata per la chat,
• testare usando l’interfaccia Web UI del server prima di collegarlo a un’app.

Riscontri fuori memoria

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,
• convalidando di aver installato una compilazione che corrisponde alla tua macchina (caratteristiche CPU e backend).

Riferimenti

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