Vai al contenuto

Llama server: come avviare llama.cpp su Windows, macOS e Linux

Illustrazione 3D di una persona al computer collegato a un server locale in una stanza.
Immagine generata con IA

Alla fine di questa guida avrete sul vostro computer una chat nel browser e un’API compatibile con OpenAI, servite entrambe da llama-server. È il server HTTP di llama.cpp: carica un modello in formato GGUF (il formato di file dei modelli usato da llama.cpp) e risponde solo sulla macchina locale finché non gli si dice altrimenti. Il percorso vale per Windows, macOS e Linux: si installano i binari già pronti, si scarica un modello da Hugging Face, si scrive il primo messaggio e si interroga l’API. I comandi sono quelli della documentazione ufficiale, elencata in fondo. Per Ollama e LM Studio ci sono le nostre guide dedicate.

Cosa serve

  • Sistemi coperti: Windows (winget o archivio dalla pagina Releases), macOS (Homebrew, MacPorts o archivio) e Linux (Homebrew, Nix o archivio), come indica install.md. Per macOS, i binari precompilati delle release (arm64 e x64) richiedono macOS 13.3 o successivo, come indica il workflow ufficiale di compilazione; per Windows e Linux le versioni minime non sono indicate nelle fonti.
  • Hardware: la documentazione consultata non dà requisiti minimi di RAM o di processore. Il README del server dice che l’inferenza funziona sia su GPU sia su CPU.
  • Una GPU, se c’è: per usarla serve una build con il backend adatto, cioè la parte che esegue i calcoli sull’hardware. Il README del repository elenca, tra gli altri, CUDA per le GPU NVIDIA, Vulkan e Metal per Apple Silicon.
  • Connessione a internet e spazio su disco per il modello, che si scarica al primo avvio.
  • Un terminale: PowerShell su Windows, il Terminale su macOS, una shell qualsiasi su Linux.

Installare llama.cpp su Windows con winget o con l’archivio delle release

Per llama.cpp su Windows le strade sono due. La prima è winget, il gestore di pacchetti di Windows, da usare in PowerShell. Secondo install.md il pacchetto si aggiorna in automatico a ogni nuova release di llama.cpp.

winget install llama.cpp

La seconda è la pagina Releases del repository, a cui il README rimanda per i binari precompilati («pre-built binaries»). Lì si scarica l’archivio adatto al proprio sistema e alla propria GPU e lo si estrae in una cartella. Per le build CUDA, se le librerie runtime richieste non sono già disponibili, si scarica dalla stessa release anche l’archivio cudart corrispondente e lo si estrae accanto ai binari. Su Windows il programma si chiama llama-server.exe.

Installare llama.cpp su macOS con Homebrew o MacPorts

Su macOS install.md prevede due gestori di pacchetti, e ne basta uno. Con Homebrew la formula si aggiorna da sola a ogni release:

brew install llama.cpp

Con MacPorts invece:

sudo port install llama.cpp

Anche per il Mac la pagina Releases offre archivi già compilati: si scarica quello per la propria architettura e lo si estrae. Per la GPU si usa Metal: build.md, nella parte sulla compilazione, precisa che su macOS Metal è attivo in modo predefinito.

Installare llama.cpp su Linux con Homebrew, Nix o l’archivio delle release

Su Linux install.md indica Homebrew e Nix. Con Homebrew:

brew install llama.cpp

Con Nix, se l’installazione ha i flake abilitati:

nix profile install nixpkgs#llama-cpp

In alternativa si scarica dalla pagina Releases l’archivio adatto al proprio sistema e alla propria GPU, lo si estrae e si avvia ./llama-server da quella cartella. Nella documentazione ufficiale non ci sono pacchetti apt o dnf per installare llama.cpp: i comandi apt-get e dnf che compaiono in build.md servono solo a installare le dipendenze per la compilazione.

In alternativa: compilare llama.cpp da sorgente

Se nessun binario va bene per il vostro hardware, si può compilare. build.md riporta le istruzioni per ogni sistema e per ogni backend, insieme ai prerequisiti: su Windows Visual Studio 2022 con il carico di lavoro per lo sviluppo desktop C++ e i componenti indicati in build.md, da usare nel Developer Command Prompt o nella Developer PowerShell per VS2022 (oppure w64devkit per Vulkan), il CUDA Toolkit per NVIDIA, il Vulkan SDK per Vulkan. Prima di configurare la build servono anche le librerie di sviluppo OpenSSL 3, che CMake deve rilevare: senza una libreria TLS supportata la compilazione riesce, ma HTTPS resta disattivato e il download con -hf non funziona. Su Debian/Ubuntu il pacchetto è libssl-dev, su Fedora/RHEL openssl-devel. Per una build solo CPU si scarica il codice, si entra nella cartella e si lancia CMake:

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

Per le schede NVIDIA la configurazione si fa con l’opzione CUDA, poi si rilancia la build con il comando di prima. Per Vulkan l’opzione è -DGGML_VULKAN=1. I binari compilati finiscono in build/bin: dalla radice del repository il server si avvia con ./build/bin/llama-server; su Windows, con il generatore Visual Studio e la configurazione Release, con .\build\bin\Release\llama-server.exe. Poi si aggiungono gli argomenti dell’esempio scelto.

cmake -B build -DGGML_CUDA=ON

Scaricare un modello GGUF con -hf e avviare llama-server

L’opzione -hf (forma lunga --hf-repo) scarica il modello da un repository Hugging Face indicato come <utente>/<modello>[:quantizzazione]. La quantizzazione è il livello di compressione dei pesi del modello: se non la indicate, secondo il README del server si usa Q4_K_M, oppure il primo file del repository se Q4_K_M non c’è. Come esempio usiamo Gemma 3 4B nella versione di ggml-org, lo stesso modello degli esempi di multimodal.md. Il modello è soggetto ai Gemma Terms of Use e alla relativa Prohibited Use Policy: consultateli prima di usarlo e, se lo distribuite o lo mettete a disposizione tramite un servizio, rispettate anche i relativi obblighi di distribuzione. Il comando è:

llama-server -hf ggml-org/gemma-3-4b-it-GGUF

Il nome del programma cambia a seconda di come l’avete installato:

  • su Windows si scrive llama-server.exe al posto di llama-server; in PowerShell, dalla cartella dell’archivio estratto, davanti al nome va messo .\, quindi .\llama-server.exe, perché PowerShell non avvia un programma della cartella corrente senza questo prefisso;
  • su Linux e macOS, dalla cartella di un archivio estratto, si scrive ./llama-server;
  • con winget, Homebrew, MacPorts o Nix il nome resta quello del comando.

Al primo avvio parte il download del modello, quindi servono la connessione e lo spazio per il file. Le volte successive llama-server usa la copia in cache: con -cl si vedono i modelli già scaricati, mentre --offline obbliga a usare la cache e blocca l’accesso alla rete. Gemma 3 è tra i modelli con visione di multimodal.md, e -hf scarica in automatico anche il file mmproj per le immagini; se vi basta il testo, aggiungete --no-mmproj.

Due opzioni del README da conoscere subito:

  • -c / --ctx-size imposta la dimensione del contesto, cioè quanti token il modello tiene presenti tra domanda e risposta. Con 0, il valore predefinito, la dimensione viene presa dal modello.
  • -ngl / --gpu-layers indica quanti strati del modello caricare nella memoria della GPU: un numero esatto, auto (il predefinito) o all. Ha effetto solo con le build GPU (CUDA, Vulkan, Metal). C’è anche --fit, attiva in modo predefinito, che regola le opzioni non impostate perché il modello stia nella memoria del dispositivo.

Velocità e consumi di memoria di questo modello non sono indicati nelle fonti.

In alternativa: avviare un file GGUF già sul disco con -m

Se il file .gguf ce l’avete già, l’opzione -m lo carica senza passare da Hugging Face. Questi sono gli esempi ufficiali del README, con un contesto di 2048 token. Su Linux e macOS:

./llama-server -m models/7B/ggml-model.gguf -c 2048

Su Windows, in PowerShell:

llama-server.exe -m models\7B\ggml-model.gguf -c 2048

Al posto di models/7B/ggml-model.gguf (o models\7B\ggml-model.gguf su Windows) va scritto il percorso del vostro file. Anche qui, in PowerShell dalla cartella dell’archivio, mettete .\ davanti a llama-server.exe.

Provare llama-server dall’interfaccia web integrata

Nella tabella delle opzioni del README del server ci sono i valori predefiniti che servono qui: --host vale 127.0.0.1, --port vale 9931 («port to listen (default: 9931)») e l’interfaccia web è attiva («whether to enable the Web UI (default: enabled)»). Con il server avviato e il modello caricato, aprite il browser su http://127.0.0.1:9931 e scrivete un messaggio nella chat.

La porta si cambia con --port, e l’interfaccia si disattiva con --no-ui se vi serve solo l’API.

Interrogare l’API compatibile OpenAI con curl o PowerShell

Tra le funzioni elencate nel README del server ci sono le rotte di chat compatibili con l’API di OpenAI; multimodal.md la indica come /chat/completions. L’indirizzo base è quello del server, quindi http://localhost:9931 con le impostazioni predefinite. Il formato delle richieste e gli esempi sono nella sezione sugli endpoint del README del server, a cui rimanda anche il README del repository alla voce «llama-server REST API»: su Linux e macOS l’esempio curl si copia da lì e si incolla nel terminale, con il server avviato.

Il README non riporta una versione per PowerShell. Su Windows conviene tenere presenti tre cose, che sono note nostre e non della documentazione:

  1. in PowerShell curl può essere un alias di un altro comando: scrivete curl.exe per usare il vero curl, oppure usate Invoke-RestMethod;
  2. le barre rovesciate a fine riga che gli esempi per bash usano per andare a capo non valgono in PowerShell: scrivete tutto su una riga oppure usate il carattere di continuazione di PowerShell;
  3. PowerShell tratta in modo diverso gli apici singoli intorno al JSON e le virgolette doppie al suo interno; con Invoke-RestMethod si evitano problemi mettendo prima il corpo JSON in una variabile.

Esporre il server in rete locale con –host e –api-key

Finché ascolta su 127.0.0.1, llama-server risponde solo al computer su cui gira. L’opzione --host accetta uno o più indirizzi IP su cui ascoltare, separati da virgola: per raggiungerlo da altri dispositivi si indica un indirizzo raggiungibile dalla rete, per esempio 0.0.0.0 per tutte le interfacce. A quel punto chiunque raggiunga la porta può usare il modello.

Per questo, insieme a --host, va sempre aggiunta --api-key seguita da una chiave scelta da voi. Secondo la tabella delle opzioni si possono dare più chiavi separate da virgola, oppure leggerle da un file con --api-key-file, una per riga. I client dovranno presentare la chiave a ogni richiesta, nel modo descritto nella sezione sugli endpoint del README.

--cors-origins decide quali siti web possono interrogare il server dal browser: il predefinito è *, cioè tutti, mentre con il valore speciale localhost sono ammesse solo le richieste dalla stessa origine, come quelle dell’interfaccia integrata. Il nostro consiglio è di restare in rete locale e di non aprire la porta su internet.

Se qualcosa va storto

  • La GPU lavora anche con -ngl 0: secondo build.md la GPU può accelerare alcune parti del calcolo anche con questa opzione. Con le build Metal, --n-gpu-layers 0 disattiva l’inferenza su GPU.
  • Un modello multimodale non si comporta come previsto: multimodal.md avverte che alcuni modelli richiedono un contesto ampio, per esempio -c 8192.

Fermare il server e disinstallare

llama-server si ferma con Ctrl+C nel terminale in cui gira. Per toglierlo dal sistema si usa il comando di rimozione del gestore scelto (winget, Homebrew, MacPorts o Nix): le pagine di llama.cpp non lo riportano, quindi va cercato nella documentazione del gestore. Con l’archivio delle release basta cancellare la cartella estratta. I modelli scaricati con -hf restano nella cache e vanno cancellati a parte.

Documentazione di riferimento

Pagine consultate il 15 novembre 2026:

Leggi anche

  • Gemma
  • GGUF
  • llama-server
  • llama.cpp