Cos'è GGUF? Il formato di file per LLM alla base di Ollama e llama.cpp, spiegato

GGUF (generalmente espanso come GPT-Generated Unified Format) è un formato di file binario per memorizzare modelli linguistici di grandi dimensioni: i pesi, il tokenizer e tutti i metadati di configurazione in un unico file autosufficiente. È il formato nativo di llama.cpp, ed è ciò che Ollama, LM Studio, KoboldCpp, gennaio e la maggior parte delle altre applicazioni locali LLM in realtà vengono eseguite. Se hai mai scaricato un file con estensione .gguf, oppure scaricato un modello con ollama run, stavi utilizzando questo formato.

Cosa contiene effettivamente un file GGUF

Un file GGUF inizia con quattro byte ASCII GGUF, seguiti da un numero di versione, da una sezione di metadati chiave-valore e quindi dai tensori stessi. I metadati rappresentano la decisione progettuale fondamentale: memorizzano l'architettura del modello, la lunghezza massima del contesto, il vocabolario del tokenizer, il template per le conversazioni e i dettagli della quantizzazione sotto forma di chiavi denominate, in modo che un runtime possa caricare qualsiasi file GGUF senza aver bisogno di un file separato config.json o i file del tokenizer accanto ad esso.

Da questa progettazione derivano tre conseguenze pratiche:

• Un singolo file rappresenta l’intero modello. È possibile copiare un file .gguf tra macchine diverse e funzionerà immediatamente. (I modelli molto grandi vengono talvolta suddivisi in parti numerate, ad esempio -00001-of-00002.gguf, ma si tratta comunque di un unico modello logico.)
• Il file è mappabile in memoria. I runtime possono utilizzare la funzione mmap per caricare il file e caricare i pesi su richiesta (on demand), rendendo così il caricamento rapido e consentendo l’avvio di modelli più grandi della RAM disponibile.
• La quantizzazione è integrata nel formato. Un file GGUF memorizza già i pesi compressi con una precisione compresa tra 2 e 8 bit per peso, motivo per cui un modello da 8 miliardi di parametri può occupare solo 4,9 GB invece che 16 GB.

Perché GGUF ha sostituito GGML

Prima di agosto 2023, llama.cpp utilizzava un formato chiamato GGML (dal nome della libreria tensoriale sottostante). GGML funzionava, ma presentava un difetto strutturale: la disposizione dei dati nel file era rigida e non prevedeva alcuna gestione delle versioni. Ogni volta che llama.cpp introduceva una nuova funzionalità — nuove architetture, metodi di quantizzazione migliorati, parametri per la scalatura RoPE — il formato doveva essere modificato, e ogni file di modello esistente su ogni disco rigido diventava inutilizzabile. Gli utenti erano costretti a riscaricare o riconvertire intere collezioni di modelli più volte nell’arco di pochi mesi.

GGUF, introdotto dal progetto llama.cpp ad agosto 2023, ha risolto questo problema con due modifiche:

• Gestione delle versioni. Il file dichiara esplicitamente la propria versione del formato, permettendo ai lettori di sapere esattamente come analizzarlo.
• Metadati chiave-valore estensibili. Nuove informazioni (ad esempio un nuovo campo per l’architettura, un template per le conversazioni, un iperparametro aggiuntivo) corrispondono semplicemente a nuove chiavi. I vecchi file privi di tali chiavi continuano a caricarsi regolarmente; i nuovi file che le contengono funzionano correttamente nei runtime aggiornati. Nulla viene invalidato retroattivamente.

llama.cpp ha abbandonato il supporto per GGML poco dopo, e l’intero ecosistema lo ha seguito. Oggi GGML sopravvive unicamente come nome della libreria tensoriale sottostante; se trovate un file di modello .ggml o .bin del 2023, non verrà caricato da nessuno strumento attuale e dovrete invece scaricare una versione in formato GGUF.

Come interpretare i suffissi della quantizzazione

Ogni nome di file GGUF include un suffisso come Q4_K_M che indica il grado di compressione applicato ai pesi. Il criterio è il seguente:

• Il numero che segue la lettera Q rappresenta approssimativamente il numero di bit per peso: Q4 ≈ 4 bit, Q8 ≈ 8 bit. Minori bit equivalgono a un file più piccolo e a una qualità inferiore.
• _K indica i più recenti metodi di "k-quant" (quantizzazione k), che allocano bit aggiuntivi ai tensori più influenti sulla qualità dell’output. A parità di dimensione, una quantizzazione K offre prestazioni migliori rispetto allo stile precedente.
• _S / _M / _L (small/medium/large) sono varianti all’interno della famiglia K — _M mantiene alcuni tensori particolarmente sensibili a una precisione superiore rispetto a _S.
• _0 (come in Q8_0, Q4_0) indica la più vecchia e semplice quantizzazione a blocchi. Q8_0 è ancora ampiamente utilizzato perché a 8 bit il metodo semplice è già quasi lossless; Q4_0 è per lo più obsoleto — preferisci Q4_K_M.
• IQ prefissi (IQ2_M, IQ3_XS…) sono «i-quants» costruiti con una matrice di importanza, usati per comprimere modelli sotto i 4 bit con meno danno rispetto alle alternative.
• F16 / BF16 / F32 significa pesi non quantizzati a 16 o 32 bit — la qualità di riferimento, alla dimensione massima.

Ecco cosa costano in pratica le opzioni comuni, utilizzando modelli Llama-class 8B instruct come esempio (le dimensioni sono approssimative e variano leggermente da modello a modello):

Quant	Dimensione file (modello 8B)	Qualità rispetto a F16	Quando usare
F16	~16,1 GB	Riferimento	Benchmarking, ulteriore quantizzazione; raramente vale la pena eseguire
Q8_0	~8,5 GB	Praticamente indistinguibile	Hai VRAM in abbondanza e vuoi la massima qualità
Q6_K	~6,6 GB	Perdita trascurabile	Ottima qualità con un significativo risparmio di spazio
Q5_K_M	~5,7 GB	Perdita molto minore	Un buon compromesso
Q4_K_M	~4,9 GB	Perdita piccola, solitamente accettabile	Lo standard predefinito. Miglior qualità per gigabyte per la maggior parte delle persone
Q3_K_M	~4,0 GB	Degradazione evidente	Solo quando Q4 genuinamente non entra
Q2_K / IQ2	~3,2 GB	Degradazione significativa	Ultima risorsa; un modello più piccolo a Q4 è spesso migliore

Due regole utili: la quantizzazione danneggia i modelli piccoli più di quelli grandi (un 70B a Q3 tiene molto meglio di un 8B a Q3), e sotto Q4 la curva di qualità cala ripidamente. In caso di dubbio, Q4_K_M è il default della comunità per una ragione.

Scelta della quantizzazione in base alla tua VRAM

La memoria totale necessaria è circa dimensione file + cache del contesto + overhead. Prevedi 1–2 GB in più rispetto alla dimensione del file per qualche migliaio di token di contesto, di più se esegui contesti lunghi. Il modello funziona più velocemente quando tutto questo entra nella VRAM della GPU; gli strumenti basati su llama.cpp possono scaricare il resto nella RAM di sistema, che funziona ancora ma diventa molto più lento quanto più layer vanno a finire lì.

VRAM	Cosa entra comodamente
8 GB	Modelli 7–8B a Q4_K_M o Q5_K_M
12 GB	8B a Q8_0, o 12–14B a Q4_K_M
16 GB	14B a Q5_K_M / Q6_K
24 GB	~32B a Q4_K_M, o 14B a Q8_0 con contesto lungo

Per i numeri esatti su un modello specifico e una lunghezza di contesto, il Calcolatore VRAM fa l'aritmetica per te, e c'è una suddivisione per modello in Requisiti di VRAM per ogni principale modello linguistico di grandi dimensioni (LLM). Se stai scegliendo l'hardware piuttosto che un quant, inizia con le migliori GPU per LLM locali.

GGUF vs safetensors

Questi due formati coesistono perché servono runtime diversi, non perché uno stia vincendo.

	GGUF	safetensors
Progettato per	llama.cpp e il suo ecosistema	L'ecosistema Hugging Face / PyTorch
Contenuti	Pesi + tokenizer + config in un unico file	Solo tensori; config e tokenizer sono file JSON separati
Quantizzazione	Integrata nel formato (Q4_K_M ecc.)	Solitamente FP16/BF16; quantizzata tramite metodi separati (GPTQ, AWQ)
Runtime tipici	Ollama, LM Studio, llama.cpp, KoboldCpp, Jan	transformers, vLLM, TGI, SGLang
Punto di equilibrio	Hardware consumer, GPU ibrida con CPU, uso singolo	GPU da datacenter, serving ad alto throughput, training

La decisione riguarda in realtà quale software si esegue: gli strumenti desktop e Ollama richiedono GGUF; gli stack per l’hosting su GPU e qualsiasi attività che coinvolga il fine-tuning richiedono safetensors. I publisher di modelli rilasciano tipicamente prima i file safetensors, e la comunità li converte in GGUF entro pochi giorni.

Origine dei file GGUF

Quasi tutti i file GGUF si trovano su Hugging Face. I lab occasionalmente pubblicano GGUF ufficiali, ma la maggior parte proviene da quantizzatori della comunità — account come bartowski, unsloth, lmstudio-community e ggml-org — che convertono ogni nuova release nell'intera gamma di quantizzazioni. Un repository con un nome come Meta-Llama-3.1-8B-Instruct-GGUF contiene un file per ogni livello di quant.

Puoi anche convertire un modello tu stesso con gli strumenti di llama.cpp: convert_hf_to_gguf.py trasforma un modello di Hugging Face in un GGUF F16, e il llama-quantize binary (compilato quando compili llama.cpp) lo comprime al tuo quant scelto, ad es. llama-quantize model-f16.gguf model-Q4_K_M.gguf Q4_K_M.

Caricare un GGUF in Ollama

Ollama può estrarre repository GGUF direttamente da Hugging Face, con il quant specificato dopo i due punti:

ollama run hf.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF:Q4_K_M

Per un file che hai già su disco, crea un file di testo semplice denominato Modelfile contenente:

FROM ./my-model.gguf

quindi registralo ed eseguilo:

ollama create my-model -f Modelfile
ollama run my-model

Le versioni attuali di Ollama leggono il template di chat incorporato nei metadati GGUF; se un modello importato produce un output confuso, la soluzione è solitamente aggiungere una linea esplicita TEMPLATE al Modelfile. La Guida completa di Ollama copre i Modelfile in profondità.

Caricare un GGUF in LM Studio

Il percorso normale è lo scaricatore integrato: apri la scheda Discover, cerca un modello e LM Studio elenca i quant GGUF disponibili, segnalando quali si adattano al tuo hardware. Per importare un file che hai già, usa la CLI (lms import path/to/model.gguf) oppure posizionalo nella directory dei modelli di LM Studio — il percorso predefinito esatto varia per versione e OS, ma la scheda My Models lo mostra e ti permette di cambiarlo. I file devono trovarsi in una struttura di sottocartelle publisher/model-name/ per essere riconosciuti. Vedi la Guida completa di LM Studio per la procedura completa.

Pronto a eseguirne uno? La nostra guida ai modelli GGUF tratta dimensionamento, download ed esecuzione su Linux, macOS e Windows.

Domande frequenti

GGUF è solo CPU, o usa anche la GPU?

Entrambi. llama.cpp è nato come progetto di inferenza CPU, ma scarica i layer del modello sulla GPU (CUDA, Metal, Vulkan, ROCm) e viene eseguito interamente su GPU quando il modello si adatta alla VRAM. Ollama e LM Studio gestiscono automaticamente la divisione CPU/GPU; con llama.cpp direttamente la controlli con il flag -ngl (numero di layer GPU).

Qual è la differenza tra Q4_K_M e Q4_K_S?

Entrambi sono k-quant a ~4 bit; la lettera è la variante di dimensione. _M (medium) mantiene più tensori sensibili alla qualità a precisione più alta di _S (small), quindi è leggermente più grande e leggermente migliore. La differenza è piccola — scegli _M a meno che gli ultimi pochi centinaia di megabyte non decidano se il modello si adatta.

Quanto si riduce effettivamente la qualità con la quantizzazione?

A Q8_0 e Q6_K, praticamente nulla — i test ciechi faticano a distinguerli da F16. Q4_K_M mostra una piccola perdita misurabile che la maggior parte degli utenti non nota mai in chat, anche se può importare per compiti precisi come la generazione di codice o la matematica. Sotto Q4 il degrado diventa evidente, e i modelli piccoli soffrono più di quelli grandi.

Posso usare GGUF con transformers o vLLM?

Il supporto esiste ma è limitato e non è il percorso nativo — transformers può dequantizzare alcuni file GGUF al caricamento, e vLLM ha supporto GGUF sperimentale che varia per architettura. Se stai costruendo su quegli stack, usa safetensors; GGUF va trattato come il formato per la famiglia di runtime llama.cpp.

Perché il mio modello è suddiviso in più file .gguf?

I modelli molto grandi vengono suddivisi in parti denominate come model-00001-of-00002.gguf, principalmente per restare entro i limiti di dimensione dei file sulle piattaforme di hosting. Mantieni tutte le parti nella stessa cartella e punta il tuo runtime alla prima — llama.cpp e gli strumenti costruiti su di esso caricano il resto automaticamente.

Una volta che sai quale quant si adatta al tuo hardware, la prossima domanda pratica è quale modello mettervi — il database di modelli elenca specifiche, esigenze di VRAM e prezzi per 37 modelli attuali, e i migliori modelli locali per Ollama è una buona lista di partenza da cui iniziare.