Quickstart di llama.cpp con CLI e Server

Torno sempre a llama.cpp per l’inferenza locale — ti dà il controllo che Ollama e altri astraggono, e funziona semplicemente. È facile eseguire interattivamente i modelli GGUF con llama-cli o esporre un’API HTTP OpenAI-compatibile con llama-server.

Se stai ancora decidendo tra un approccio locale, self-hosted o cloud, inizia con la guida principale LLM Hosting nel 2026: Confronto tra Local, Self-Hosted e Cloud Infrastructure.

Perché llama.cpp nel 2026

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

• portabilità tra CPU e diversi backend GPU,
• latenza prevedibile su una singola macchina,
• flessibilità di deployment, da laptop a nodi on-prem.

Eccelle quando desideri privacy e operazione offline, quando hai bisogno di controllo deterministico sui flag di runtime o quando vuoi integrare l’inferenza in un sistema più grande senza eseguire un stack pesante in Python.

È anche utile comprendere llama.cpp anche se successivamente scegli un runtime server ad alta throughput. Ad esempio, se il tuo obiettivo è la massima throughput di servizio su GPU, potresti anche volerlo confrontare con vLLM utilizzando: vLLM Quickstart: LLM Serving ad Alta Prestazione e puoi effettuare benchmark delle 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

Ci sono tre percorsi pratici per l’installazione, a seconda che tu voglia comodità, portabilità o massima prestazione.

Installa tramite gestori di pacchetti

Questo è l’opzione più veloce per “avviarlo”.

# 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

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

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

Installa tramite binari precompilati

Se desideri un’installazione pulita senza compilatori, usa i binari precompilati ufficiali pubblicati nei rilasci di llama.cpp su GitHub. Di solito coprono diversi target OS e diversi backend (varianti CPU-only e GPU-enabled).

Un workflow comune:

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

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

Compila da sorgente per il tuo hardware specifico

Se ti preoccupi di ottenere le prestazioni massime 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 compilazione, i binari sono tipicamente qui:

ls -la ./build/bin/

Build GPU in un solo 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: walkthrough completo della build

Su Ubuntu 24.04 con una GPU NVIDIA, hai bisogno del toolkit CUDA e OpenSSL prima di compilare. 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 all’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

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

3. Installa le intestazioni di sviluppo OpenSSL (necessarie 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
cp llama.cpp/build/bin/llama-* llama.cpp

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

Puoi anche compilare più backend e scegliere dispositivi al momento dell’esecuzione. Questo è utile se distribuisci lo stesso build su macchine eterogenee.

Scegli un modello GGUF e una quantizzazione

Per eseguire l’inferenza, hai bisogno di un file GGUF del modello (*.gguf). GGUF è un formato a singolo file che include i pesi del modello più i metadati standardizzati necessari per 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 in models/my-model.gguf

Poi eseguilo per percorso:

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

Opzione B: Fai scaricare llama.cpp da Hugging Face

Le costruzioni moderne di llama.cpp possono scaricare da Hugging Face e mantenere i file in una cache locale. Questo è spesso il workflow più semplice per esperimenti veloci.

# Scarica un modello da HF e 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 repository e lasciare lo strumento selezionare 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 workflow completamente offline in futuro, --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é effettua direttamente un compromesso tra qualità, dimensione del modello e velocità.

Un punto di partenza pragmatico:

• inizia con una variante Q4 o Q5 per macchine CPU-first,
• passa a una precisione maggiore (o a 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 l’adattamento del campionamento.

Ricorda anche che la finestra di contesto ha importanza: le dimensioni di contesto più grandi aumentano l’uso della memoria (a volte in modo drammatico), anche quando il file GGUF stesso si adatta.

Quickstart e parametri principali per llama-cli

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

Esecuzione minima

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

Esecuzione interattiva per chat

La modalità conversazione è progettata per i modelli con template di chat. Di solito abilita il comportamento interattivo e formatta i prompt secondo il modello’s template.

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

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

Flag principali di llama-cli che contano

Invece di memorizzare 200 flag, concentra l’attenzione sui quelli che dominano correttezza, latenza e memoria.

Modello e download

Contesto e throughput

Offload GPU e selezione hardware

Campionamento e qualità di 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." \
  --file ./docs/incident-report.txt \
  -n 300

Rendere i risultati più riproducibili

Quando debuggi i prompt, fissa il seme e riduci la casualità:

llama-cli \
  -m models/my-model.gguf \
  -p "Estrai i rischi principali 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 OpenAI per chat, completamenti, embedding e risposte,
• un’interfaccia Web UI per il test interattivo,
• endpoint opzionali per il monitoraggio in produzione.

Avvia un server con un modello locale

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

Per default, ascolta su 127.0.0.1:8080.

Per legare esternamente (ad esempio all’interno di 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 server opzionali ma importanti

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

Esempi di chiamate API

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

Consiglio per distribuzioni reali: se imposti --api-key, puoi inviarlo tramite un’intestazione x-api-key (o continuare a usare le intestazioni Authorization a seconda del tuo gateway).

Client Python OpenAI mirato a llama-server

Con un server compatibile OpenAI, molti client possono funzionare modificando 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 i thread vs dimensione batch in llama.cpp."}
    ],
)

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

Embedding

Gli embedding compatibili OpenAI sono esposti in /v1/embeddings, ma il modello deve supportare una modalità di pooling degli embedding che non è 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 dedicato agli embedding, considera di avviare il server in modalità solo embedding:

llama-server \
  -m models/my-embedding-model.gguf \
  --embeddings \
  --host 127.0.0.1 \
  --port 8080

Prestazioni, monitoraggio e rafforzamento per la produzione

La domanda FAQ “Quali opzioni della riga di comando di llama.cpp influiscono maggiormente sulla velocità e sulla memoria” diventa molto più semplice quando tratti l’inferenza come un sistema:

• Il tetto della memoria è spesso il primo vincolo (RAM sulla CPU, VRAM sulla GPU).
• La dimensione del contesto è un moltiplicatore principale della memoria.
• L’offload dei livelli GPU è spesso la via più veloce per ottenere più 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, centrata sull’ingegneria, vedi: Prestazioni LLM nel 2026: Benchmark, Colli di Bottiglia e Ottimizzazione.

Monitoraggio di llama-server con Prometheus e Grafana

llama-server può esporre metriche compatibili con Prometheus in /metrics quando --metrics è abilitato. Questo si combina naturalmente con le configurazioni di scraping di Prometheus e dashboard Grafana.

Per dashboard e allert specifiche 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 al monitoraggio, metriche, Prometheus & Grafana e Osservabilità per sistemi LLM.

Checklist di base per il rafforzamento

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

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

Vincite rapide per la risoluzione dei problemi

Il modello carica ma le risposte sono strane in chat

Gli endpoint chat funzionano meglio quando il modello ha un template chat supportato. Se le uscite sembrano non strutturate, prova:

• usare llama-cli --conversation più un --system-prompt esplicito,
• verificare che il tuo modello sia una variante istruzione o chat-tuned,
• testare utilizzando l’interfaccia Web del server prima di integrarlo in un’app.

Hai colpito l’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 sulla CPU

Inizia con:

• --threads uguale ai tuoi core fisici,
• dimensioni batch moderate,
• verificando che hai installato una build che corrisponde alla tua macchina (caratteristiche CPU e backend).

Riferimenti

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