Modelli GGUF: cos'è e come eseguirli

GGUF (GPT-Generated Unified Format) è il formato file utilizzato dall'ecosistema llama.cpp/ggml per memorizzare un modello pronto per l'inferenza. Un singolo .gguf file contiene i tensori quantizzati più tutti gli elementi necessari per utilizzarli: vocabolario, impostazioni del tokenizer, template di chat e metadati sull'architettura. Ha sostituito il precedente formato GGML nell'agosto 2023 ed è oggi lo standard di fatto per l'esecuzione di modelli su laptop, desktop e CPU.

Cosa contiene effettivamente un file .gguf

Un file GGUF è composto da un header, un blocco di metadati chiave-valore e infine i dati dei tensori. I metadati sono la parte praticamente più rilevante — è proprio grazie a essi che un modello GGUF non richiede file ausiliari. La documentazione GGUF di Hugging Face descrive la struttura del formato e il visualizzatore integrato di metadati del Hub, che ti permette di ispezionare il tipo di quantizzazione, la lunghezza del contesto e il template di chat di un file prima di scaricarne diversi gigabyte.

Tra le chiavi di metadati più comuni figurano l'architettura (llama, qwen3, gemma3, phi3), la lunghezza massima del contesto di addestramento, le impostazioni RoPE, l'intero vocabolario e il template di chat Jinja. Un loader legge questo blocco e si configura autonomamente; non devi specificare manualmente né il tokenizer né il formato dei prompt.

GGUF vs safetensors

	GGUF	safetensors
Runtime principale	llama.cpp, Ollama, LM Studio	PyTorch, vLLM, Transformers, TGI
File per modello	Uno (o frammenti numerati)	Pesi più cartella di configurazione/tokenizer
Quantizzazione	Integrata (Q4_K_M, Q8_0, IQ…)	Solitamente FP16/BF16, oppure varianti GPTQ/AWQ
CPU + offload parziale sulla GPU	Sì, obiettivo fondamentale della progettazione	Limitata e lenta
Servizio batch concorrente	Scarsa	Eccellente
Affinamento (fine-tuning)	No (convertire prima in altro formato)	Sì

Come leggere il nome di un file GGUF

I file sono generalmente denominati Model-Name-8B-Instruct-Q4_K_M.gguf. Il suffisso indica la combinazione di quantizzazione. Il numero rappresenta la larghezza di bit nominale; _K indica k-quants, che mantengono i tensori di attenzione e di embedding a precisione superiore rispetto ai pesi principali della feed-forward; S/M/L sono varianti piccole/medie/grandi di tale combinazione.

Quant	Bits/approssimativi per peso	Dimensione approssimativa, modello da 8 miliardi di parametri	Quando utilizzarlo
Q8_0	~8.5	~8,5 GB	Riferimento quasi senza perdita di qualità; solo per modelli piccoli
Q6_K	~6.6	~6,6 GB	Hai VRAM in eccesso
Q5_K_M	~5.7	~5,7 GB	Predefinito orientato alla qualità
Q4_K_M	~4.9	~4,9 GB	Predefinito usuale
Q4_0	~4.5	~4,5 GB	Obsoleto; alcuni acceleratori lo preferiscono
Q3_K_M	~3.9	~4,0 GB	Per far rientrare un modello più grande in una quantità limitata di VRAM
Q2_K / IQ2	~2,5–3,4	~2,5–3,4 GB	Ultima risorsa; degrado evidente

Considera la colonna «bits per peso» come indicativa. Le dimensioni effettive variano in base all’architettura del modello (un vocabolario ampio aumenta le dimensioni dei tensori di embedding) e alla versione di llama.cpp, poiché i mix di quantizzazione vengono ottimizzati nel tempo. La famiglia IQ (da IQ2_XXS a IQ4_NL) utilizza una calibrazione basata su matrice di importanza per mantenere prestazioni migliori a larghezze di bit molto ridotte, e quantizzatori come quelli di Bartowski e Unsloth pubblicano varianti IQ insieme ai classici K-quants.

Il consenso della comunità — non una misurazione di Convly — è che Q4_K_M rappresenti il punto ottimale, e che la qualità diminuisca drasticamente al di sotto di circa 3 bit per peso: i modelli piccoli subiscono un degrado più rapido rispetto ai modelli grandi alla stessa quantizzazione.

Dimensionamento: quali modelli GGUF sono compatibili con la tua GPU

La dimensione del file costituisce il minimo, non il totale. Aggiungi la cache KV relativa alla tua lunghezza di contesto, più circa 500 MB–1 GB di overhead. Queste cifre a 4 bit provengono da database dei modelli Convly:

Modello	VRAM a 4 bit	Contesto	GPU realistico
Gemma 3 4B	~3 GB	128K	Qualsiasi scheda da 6 GB, GPU integrata
Mistral 7B	~4,5 GB	32K	Scheda da 8 GB
Llama 3.1 8B	~5 GB	128K	Scheda da 8 GB
Qwen3 14B	~9 GB	128K	Scheda da 12 GB
Phi-4	~9 GB	16K	Scheda da 12 GB
Gemma 3 27B	~16 GB	128K	Scheda da 24 GB
Qwen3 32B	~20 GB	128K	Scheda da 24 GB
Llama 3.3 70B	~40 GB	128K	2×24 GB oppure 48 GB di memoria unificata
DeepSeek R1 (completo)	~400 GB	128K	Solo su server multi-GPU

I modelli Mixture-of-Experts rappresentano qui la trappola. Qwen3 30B-A3B attiva solo ~3 miliardi di parametri per token, ma richiede comunque la presenza residente di tutti i ~18 GB. Nell’estremo, il database indica una dimensione di Kimi K3 di circa 1,4 TB a 4 bit — un file GGUF esiste in linea di principio, ma nessuna singola macchina in tuo possesso potrà contenerlo. Per un valore esatto relativo alla tua lunghezza di contesto, usa Calcolatore VRAM oppure la suddivisione per modello presente in Requisiti di VRAM per ogni principale modello linguistico di grandi dimensioni (LLM). Se stai ancora scegliendo l’hardware, le migliori GPU per LLM locali analizza il rapporto VRAM/dollaro.

Dove scaricare modelli GGUF

• Hugging Face — filtra l’elenco dei modelli con library=gguf. La maggior parte dei repository include tutte le quantizzazioni in un unico repository; scarica solo il file di cui hai bisogno, non l’intero repository.
• libreria Ollama — ollama.com/library fornisce file GGUF preconfezionati con il template di chat già configurato. Consulta Elenco modelli Ollama.
• LM Studio — la scheda «Scopri» integrata nell’app ricerca i repository GGUF su Hugging Face e segnala quali quantizzazioni sono compatibili con la RAM/VRAM rilevata sul tuo sistema. Guida passo passo: Guida completa a LM Studio.

I modelli di grandi dimensioni vengono forniti suddivisi in parti (shard) model-00001-of-00003.gguf e così via. Scarica tutti gli shard nella stessa cartella e punta il loader sullo shard 00001 — esso individuerà automaticamente gli altri.

Eseguire modelli GGUF su Linux

Compila llama.cpp con il supporto 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

I binari vengono generati in build/bin/. Avvia un server compatibile con l’API OpenAI:

./build/bin/llama-server -m ~/models/model-Q4_K_M.gguf -c 8192 -ngl 99 --port 8080

-ngl (--n-gpu-layers) è il parametro di offload: 99 significa «tutti i layer sulla GPU»; 0 indica l’utilizzo esclusivo della CPU, mentre valori intermedi suddividono il modello quando quest’ultimo non entra interamente nella GPU. -c imposta la lunghezza massima del contesto; lasciarla al valore massimo addestrato dal modello può richiedere più VRAM rispetto a quella occupata dai pesi stessi. L’endpoint risultante è http://localhost:8080/v1/chat/completions.

Due precisazioni sulle versioni: nella versione precedente la flag CMake era LLAMA_CUBLAS e i binari erano stati rinominati (main → llama-cli, server → llama-server) nel 2024. Controlla il file README del repository che hai clonato per verificare i dettagli della build. Per GPU AMD o Intel, sostituisci la flag CUDA con quella corrispondente per ROCm/Vulkan/SYCL documentata nel repository, invece di procedere per tentativi.

Se utilizzi Ollama, i modelli risiedono in /usr/share/ollama/.ollama/models quando viene eseguito come servizio di sistema, oppure ~/.ollama/models per un'installazione utente. Vedere come installare Ollama.

Eseguire modelli GGUF su macOS

Apple Silicon è insolitamente performante con GGUF perché la memoria unificata consente alla GPU di accedere alla maggior parte della RAM di sistema: su un Mac da 64 GB è possibile caricare un modello da ~40 GB a 4 bit da 70 miliardi di parametri, che su PC richiederebbe due schede da 24 GB.

brew install llama.cpp
llama-server -m ~/models/model-Q4_K_M.gguf -c 8192 --port 8080

L'offload su Metal è abilitato nella build Homebrew, quindi in genere non è necessario -ngl. macOS limita la quantità di RAM che la GPU può allocare (regolabile tramite un iogpu sysctl, il cui valore varia a seconda della versione di macOS), quindi lasciare una certa quantità di RAM disponibile per il sistema operativo. Ollama memorizza i modelli in ~/.ollama/models; LM Studio utilizza ~/.lmstudio/models nelle versioni attuali e ~\/\.cache\/lm-studio\/models in quelle più vecchie — la scheda "I miei modelli" mostra e permette di modificare il percorso effettivo.

Eseguire modelli GGUF su Windows

Tre possibili vie, dalla più semplice alla più complessa:

1. LM Studio — Installatore grafico, ricerca integrata dei modelli all'interno dell'applicazione e interruttore per avviare un server locale. La scelta migliore per chi non è sviluppatore.
2. Ollama — Installatore nativo per Windows; i modelli vengono salvati in C:\Users\<tuo-utente>\.ollama\models. Impostare la variabile d'ambiente OLLAMA_MODELS per spostarli da unità di sistema. Contesto: che cos'è Ollama.
3. Binari precompilati di llama.cpp — La pagina delle Release su GitHub pubblica build Windows zippate per ogni backend (CUDA, Vulkan, CPU). Estrai l'archivio ed esegui llama-server.exe -m model.gguf -ngl 99 da PowerShell. Scegli la build CUDA per le GPU NVIDIA; Vulkan è la soluzione sicura e compatibile con tutti i vendor (AMD e Intel Arc).

Avvertenze specifiche per Windows: la scansione in tempo reale di Windows Defender rallenta il primo caricamento di file multi-gigabyte, mentre eseguire llama.cpp all'interno di WSL2 comporta un consumo aggiuntivo di RAM per la macchina virtuale. Le build native per Windows sono generalmente la via più semplice.

Caricare un qualsiasi modello GGUF in Ollama

Le versioni recenti di Ollama possono scaricare direttamente da Hugging Face:

ollama run hf.co//:Q4_K_M

Per un file locale, crea un file Modelfile nella stessa directory:

FROM ./model-Q4_K_M.gguf

poi ollama create my-model -f Modelfile e ollama run my-model. Se il file GGUF non include un template di chat utilizzabile, aggiungi una riga TEMPLATE e PARAMETER stop — le direttive supportate nel file Modelfile sono cambiate nel tempo, quindi controlla ollama help create per la tua versione. Scelte selezionate: i migliori modelli linguistici locali per Ollama.

Quando GGUF non è la soluzione adatta

GGUF è ottimizzato per un singolo utente alla volta. Per gestire molte richieste simultanee o per sfruttare il parallelismo tensoriale su più GPU, si consigliano invece i formati safetensors con vLLM o SGLang. Inoltre, eseguire localmente non è automaticamente più economico: i servizi ospitati offrono tariffe come Llama 3.3 70B $0,10 in ingresso / $0,32 in uscita per ogni milione di token, mentre i modelli ospitati di fascia alta come Claude Sonnet 5 costano $2,00 in ingresso / $10,00 in uscita per ogni milione di token su contesti da 1 milione di token. Calcola il tuo volume di utilizzo con la Calcolatore dei costi API e il Calcolatore del punto di pareggio tra auto-hosting e utilizzo di API prima di acquistare una GPU.

Domande frequenti

Cosa significa GGUF e in che cosa differisce da GGML?

GGUF sta per GPT-Generated Unified Format. GGML era il formato precedente dello stesso progetto; rompeva la compatibilità ogni volta che venivano introdotti nuovi metadati. GGUF ha aggiunto un blocco estensibile di metadati chiave-valore, consentendo di integrare nuove architetture e opzioni senza invalidare i file esistenti. I file GGML precedenti a GGUF .bin non vengono più caricati nelle versioni attuali di llama.cpp.

Quale quantizzazione devo scaricare?

Inizia con Q4_K_M. Se il modello lascia ancora liberi diversi GB di VRAM, passa a Q5_K_M o Q6_K. Se non entra in memoria, preferisci un modello più piccolo in Q4_K_M piuttosto che lo stesso modello in Q2_K — un modello da 14 miliardi di parametri a 4 bit offre generalmente prestazioni migliori rispetto a uno da 32 miliardi di parametri forzato a 2 bit. Verifica l'adattamento con la Calcolatore VRAM alla lunghezza di contesto prevista.

Posso eseguire modelli GGUF senza una GPU?

Sì — l'inferenza su CPU è esattamente ciò per cui GGUF è stato progettato. La velocità è limitata dalla larghezza di banda della memoria, quindi ci si aspetta pochi token al secondo (singola cifra) per un modello da 7–8 miliardi di parametri in Q4_K_M su RAM desktop tipica dual-channel, e prestazioni ancora inferiori per modelli più grandi. I modelli più piccoli, come Gemma 3 4B (~3 GB a 4 bit), rappresentano la scelta pratica per l'inferenza su CPU.

Posso convertire autonomamente un modello di Hugging Face in GGUF?

Sì. llama.cpp include uno script di conversione (convert_hf_to_gguf.py nelle versioni attuali; il nome del file usava trattini nelle versioni precedenti) che genera un file GGUF in F16, dopodiché il binario llama-quantize lo comprime in una quantizzazione target. Controlla l'opzione --help nella copia clonata dello script e verifica che la tua architettura sia supportata prima di avviare la conversione — le architetture non supportate falliscono durante la fase di conversione.

I modelli GGUF supportano la visione o le chiamate a strumenti (tool calling)?

La chiamata agli strumenti (tool calling) funziona quando il template di chat del modello lo definisce esplicitamente e il loader utilizzato rispetta tale template. Per i modelli multimodali è necessario un secondo file — un file GGUF mmproj che contiene il proiettore visivo, da caricare insieme ai pesi testuali. Lo strumento multimodale di llama.cpp è stato rinominato e riorganizzato più volte, quindi segui sempre la documentazione corrente del repository anziché tutorial obsoleti.

La quantizzazione modifica la finestra contestuale?

No. Il contesto è una proprietà del modello, non della quantizzazione: Llama 3.3 70B ha un contesto di 128K e Llama 4 Scout di 10M, indipendentemente dal fatto che tu utilizzi F16 o Q4_K_M. Ciò che cambia è se puoi permetterti la cache KV necessaria per quel contesto nella memoria disponibile. Confronta contesto e costi tra modelli sulla Classifica LLM.