llama-server: API OpenAI locale con llama.cpp

#Perché llama-server?

Ollama, LM Studio e Jan si basano tutti sullo stesso motore sottostante: llama.cpp. Questo motore include un proprio server HTTP, llama-server, che non ha bisogno di nessuno di questi livelli aggiuntivi. Indichi un file GGUF e ottieni un'API e un'interfaccia web. Nient'altro.

Il vantaggio non è solo estetico. Mentre Ollama decide per te il numero di layer inviati alla GPU, la dimensione del contesto e il modo di suddividere il modello, llama-server espone ogni parametro tramite la riga di comando. Puoi vedere e regolare ciò che accade. È la modalità «manuale» dell'IA locale: più verbosa, ma senza scatole nere.

API compatibile con OpenAI

Endpoint /v1/chat/completions, /v1/completions, /v1/models, /v1/embeddings. Qualsiasi client OpenAI vi si connette senza modifiche.

Controllo dell'offloading

--n-gpu-layers stabilisce precisamente quanti strati vengono caricati nella VRAM. Indispensabile quando il modello supera la capacità della tua scheda.

Interfaccia web integrata

Una chat servita direttamente alla radice del server, senza installare Open WebUI né Docker.

Zero dipendenze pesanti

Un solo binario (qualche decina di MB). Non sono obbligatori né Python, né un container, né un servizio di sistema.

Batching e parallelismo

Batching continuo attivato per impostazione predefinita, diverse richieste simultanee attraverso slot.

#Prerequisiti

Un file GGUF

Il formato di llama.cpp. Disponibile su Hugging Face, o scaricabile direttamente da llama-server tramite -hf (vedi più sotto).

VRAM o RAM

In Q4_K_M, considera circa 2 GB per un modello 3B, circa 5 GB per un 7B, circa 9 GB per un 14B, circa 19 GB per un 32B, circa 40 GB per un 70B.

Un GPU (fortemente consigliato)

RTX 3060 12 GB per iniziare, RTX 4070/4080 nella fascia media, RTX 4090 24 GB o Mac M4 Pro per i modelli di grandi dimensioni. È possibile usare solo la CPU, ma le prestazioni sono lente.

Un terminale

llama-server è controllato dalla riga di comando. Niente di insuperabile, ma non è un'applicazione da doppio clic come LM Studio.

#1. Ottenere llama-server

Tre vie, dalla più rapida alla più performante. Su macOS, Homebrew installa il binario con un solo comando:

brew install llama.cpp

# le binaire s'appelle llama-server
llama-server --version

Su Windows e Linux, il modo più semplice è scaricare un binario precompilato dalle release ufficiali di llama.cpp su GitHub (scegli la variante corrispondente al tuo hardware: CUDA per NVIDIA, Vulkan per una GPU generica o CPU).

https://github.com/ggml-org/llama.cpp/releases

Per ottenere il massimo numero di token al secondo, compila dai sorgenti con il backend della tua GPU. Esempio per NVIDIA con CUDA:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j

# le binaire se trouve dans build/bin/
./build/bin/llama-server --version

#2. Avviare con un GGUF usando un solo comando

Il comando minimo specifica un modello e avvia il server. Qui, un Qwen 3.5 9B in Q4_K_M (la scelta di riferimento per 8 GB nel 2026, 256k di contesto) con tutti gli strati trasferiti alla GPU:

llama-server -m ./qwen3.5-9b-instruct-q4_k_m.gguf -ngl 99 -c 8192

-m

Percorso del file GGUF da servire.

-ngl 99

Numero di layer trasferiti sulla GPU. 99 = «tutti» (il modello ne ha meno; il valore in eccesso viene ignorato senza errori).

-c 8192

Dimensione del contesto in token. Il valore predefinito è spesso 4096; adattala alle tue esigenze e alla tua VRAM.

Non avete il file a portata di mano? llama-server può scaricarlo direttamente da Hugging Face e memorizzarlo in cache, come ollama pull mais integrato:

llama-server -hf bartowski/Qwen3.5-9B-Instruct-GGUF:Q4_K_M -ngl 99 -c 8192

Una volta avviato, il server è in ascolto per impostazione predefinita su http://127.0.0.1:8080. Verifica che sia attivo:

curl http://localhost:8080/health
# {"status":"ok"}

#3. L'API compatibile con OpenAI: collegare qualsiasi app

È il punto di forza decisivo di llama-server. Usa il protocollo di OpenAI, quindi qualsiasi strumento progettato per l'API OpenAI funziona semplicemente cambiando l'URL di base. Una chiamata diretta alla chat con curl:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local",
    "messages": [
      {"role": "system", "content": "Tu réponds en français, de façon concise."},
      {"role": "user", "content": "Explique le format GGUF en une phrase."}
    ],
    "temperature": 0.7
  }'

Il campo model è libero: llama-server serve un solo modello alla volta e ignora in gran parte questo valore. Nell'SDK Python di OpenAI, basta reindirizzare base_url verso il tuo server. La chiave API può essere qualsiasi stringa se non hai impostato --api-key:

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="local",
    messages=[
        {"role": "user", "content": "Donne-moi trois idées de noms pour un projet open source."}
    ],
)
print(resp.choices[0].message.content)

/v1/chat/completions

Modalità conversazione, con applicazione automatica del template di chat del modello.

/v1/completions

Completamento di testo grezzo, senza formattazione dei ruoli.

/v1/models

Elenca il modello caricato — utile per i client che richiedono prima l'elenco dei modelli disponibili.

/v1/embeddings

Genera embedding se il server è avviato con --embedding (utile per un RAG fai da te).

#4. n-gpu-layers: il controllo preciso dell’offloading che Ollama nasconde

Un modello è una pila di strati (layers). Ogni strato trasferito nella VRAM viene elaborato dalla GPU, molto velocemente; quelli che restano nella RAM vengono elaborati dalla CPU, lentamente. --n-gpu-layers (o -ngl) determina quanti strati vengono trasferiti alla GPU. È l'impostazione più importante per la velocità.

-ngl 99

Tutto sulla GPU. Da preferire se il modello entra interamente nella VRAM. Velocità massima.

-ngl 20

Offloading parziale: 20 strati sulla GPU, il resto sulla CPU. Il compromesso quando il modello supera la capacità della VRAM.

-ngl 0

Tutto sulla CPU. Lento, ma permette di eseguire un modello molto più grande di quanto possa gestire la tua scheda.

La strategia: aumentare il valore di -ngl il più possibile senza saturare la VRAM. Un modello 14B in Q4 (≈9 GB) entra interamente nella memoria di una RTX 3060 da 12 GB con -ngl 99. Un Qwen 3.8 27B in Q4 (≈18 GB) non ci sta; sulla stessa scheda si effettua un offload parziale — ad esempio -ngl 40 — e si accetta un rallentamento.

# Qwen 3.8 27B Q4 (~18 Go) sur un GPU 12 Go : une partie sur GPU, le reste sur CPU
llama-server -m ./qwen3.8-27b-instruct-q4_k_m.gguf -ngl 40 -c 4096

Per monitorare ciò che entra effettivamente nella VRAM durante il caricamento, tieni d'occhio nvidia-smi in un'altra finestra:

nvidia-smi -l 1

#5. L'interfaccia web inclusa

Non servono Open WebUI né Docker per chattare: llama-server offre un'interfaccia di chat direttamente alla radice del server. Basta aprire l'indirizzo del server in un browser.

http://localhost:8080

Qui troverai una chat completa: cronologia delle conversazioni, regolazione della temperatura e dei parametri di campionamento, gestione dei prompt di sistema e rendering Markdown. È sufficiente per un uso personale quotidiano, senza installare alcun livello software aggiuntivo.

#Quando preferire llama-server a Ollama (e quando restare con Ollama)

llama-server e Ollama utilizzano lo stesso motore. La scelta è un compromesso tra controllo e comodità.

Scegli llama-server

Quando vuoi regolare finemente l'offloading, testare un GGUF specifico di un determinato quantizzatore, evitare un daemon permanente o distribuire un binario unico senza dipendenze su un server.

Scegli llama-server

Quando un modello supera la capacità della tua VRAM: il controllo diretto di -ngl e delle opzioni di memoria fa la differenza tra «impossibile da usare» e «lento ma funzionante».

Resta su Ollama

Quando vuoi passare al volo da un modello all’altro senza riavviare processi, gestire una libreria con ollama pull/list o caricare e scaricare i modelli dalla memoria automaticamente in base alla richiesta.

Resta su Ollama

Quando più applicazioni puntano a modelli diversi sulla stessa porta 11434: Ollama gestisce per te l'instradamento delle richieste e il passaggio da un modello all'altro, mentre llama-server gestisce un solo modello per processo.

#Risoluzione dei problemi

« CUDA out of memory » al caricamento

Il valore di -ngl è troppo alto per la VRAM. Abbassalo (offloading parziale), riduci -c oppure passa a una quantizzazione più leggera (Q4_K_M invece di Q5/Q8).

La GPU non viene utilizzata

Il binario potrebbe essere la variante CPU. Verifica di usare una build CUDA/Metal/Vulkan e che -ngl sia superiore a 0. nvidia-smi deve mostrare VRAM occupata.

Risposte incoerenti o tag visibili

Il template di chat non viene applicato. Riavvia con --jinja per utilizzare il template integrato nel GGUF.

L'applicazione client non trova il modello

Alcuni client interrogano prima /v1/models. Assegna un alias con -a e inserisci questo nome esatto nel campo model della tua applicazione.

Contesto troncato / risposte interrotte

-c è troppo piccolo. Aumenta la dimensione del contesto, tenendo presente che un contesto grande consuma più VRAM.

#Per approfondire

llama-server dà il meglio di sé con un llama.cpp ben compilato e un GGUF ben scelto. Queste guide del sito completano la configurazione:

Compilare llama.cpp con CUDA

Per ottenere un binario ottimizzato per NVIDIA e il massimo numero di token al secondo sulla tua scheda.

Q4, Q5, Q8: quale quantizzazione scegliere

Per trovare il giusto compromesso tra qualità, velocità e VRAM prima di scaricare un GGUF.

llama.cpp vs vLLM vs Exllama

Per confrontare llama-server con gli altri motori di inferenza in base alle tue esigenze di throughput.