Cos'è GGUF? Il formato di file per modelli 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, Jan e la maggior parte delle altre applicazioni per LLM locali eseguono effettivamente. 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 privo di perdite; Q4_0 è ormai obsoleto — si consiglia di preferire i prefissi Q4_K_M.
• IQ (ad esempioIQ2_M, IQ3_XS) che indicano le "i-quants", basate su una matrice di importanza e progettate per comprimere i modelli sotto i 4 bit con minori danni rispetto alle alternative.
• F16 / BF16 / F32 indicano pesi non quantizzati a 16 o 32 bit — la qualità di riferimento, ma con dimensioni massime.

Ecco quanto costano effettivamente le opzioni più comuni, utilizzando come esempio modelli istruzionali da 8 miliardi di parametri della famiglia Llama (le dimensioni sono approssimative e variano leggermente da modello a modello):

Due regole utili: la quantizzazione danneggia i modelli piccoli più di quelli grandi (un modello da 70B a Q3 si comporta molto meglio di uno da 8B a Q3) e al di sotto di Q4 la curva della qualità cala bruscamente. In caso di dubbio, Q4_K_M è l'impostazione predefinita della comunità per una ragione ben precisa.

Scelta della quantizzazione in base alla tua VRAM

La memoria totale necessaria è approssimativamente pari a dimensione del file + cache del contesto + overhead. Prevedere un margine aggiuntivo di 1–2 GB rispetto alla dimensione del file per alcuni migliaia di token di contesto; tale margine va aumentato ulteriormente se si utilizzano contesti molto lunghi. Il modello funziona alla massima velocità quando l'intero carico rientra nella VRAM della GPU; gli strumenti basati su llama.cpp possono scaricare le parti eccedenti nella RAM di sistema, soluzione comunque funzionante ma progressivamente più lenta man mano che aumenta il numero di livelli spostati.

Per valori esatti relativi a un modello specifico e a una determinata lunghezza di contesto, lo strumento Calcolatore VRAM esegue automaticamente i calcoli necessari, mentre una suddivisione dettagliata per singolo modello è disponibile in Requisiti di VRAM per ogni principale modello linguistico di grandi dimensioni (LLM). Se stai scegliendo l'hardware piuttosto che una specifica quantizzazione, inizia da le migliori GPU per LLM locali.

GGUF vs safetensors

Questi due formati coesistono perché servono runtime diversi, non perché uno stia prevalendo sull'altro.

La scelta dipende in realtà dal software che intendi utilizzare: gli strumenti desktop e Ollama richiedono GGUF, mentre gli stack per l'erogazione su GPU e qualsiasi attività che coinvolga il fine-tuning richiedono safetensors. I publisher di modelli rilasciano tipicamente prima i formati safetensors, e la comunità converte in GGUF entro pochi giorni.

Origine dei file GGUF

Quasi tutti i file GGUF sono ospitati su Hugging Face. Labs pubblica occasionalmente GGUF ufficiali, ma la maggior parte proviene da quantizzatori della comunità — account come bartowski, unsloth, lmstudio-community e ggml-org — che convertono ogni nuovo rilascio nell'intera gamma di quantizzazioni disponibili. Un repository chiamato, ad esempio, Meta-Llama-3.1-8B-Instruct-GGUF conterrà un file per ciascun livello di quantizzazione.

Puoi anche convertire autonomamente un modello usando gli strumenti di llama.cpp: convert_hf_to_gguf.py trasforma un modello Hugging Face in un GGUF in F16, mentre il binario llama-quantize (compilato insieme a llama.cpp) lo comprime nella quantizzazione prescelta, ad esempio. modello llama-quantize model-f16.gguf model-Q4_K_M.gguf Q4_K_M.

Caricamento di un file GGUF in Ollama

Ollama può scaricare direttamente repository GGUF da Hugging Face, specificando la quantizzazione dopo i due punti:

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

Per un file già presente sul disco, crea un file di testo semplice denominato Modelfile contenente:

FROM ./my-model.gguf

quindi registrarlo ed eseguirlo:

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

Le versioni attuali di Ollama leggono automaticamente il template di chat incorporato nei metadati GGUF; se un modello importato produce output illeggibile, la soluzione consiste generalmente nell’aggiungere esplicitamente una riga TEMPLATE al file Modelfile. La guida completa a Ollama tratta in modo approfondito i Modelfile.

Caricamento di un file GGUF in LM Studio

Il metodo standard è il downloader integrato: apri la scheda Discover, cerca un modello e LM Studio elenca le quantizzazioni GGUF disponibili, indicando quali sono compatibili con il tuo hardware. Per importare un file già presente sul disco, usa l’interfaccia a riga di comando (lms import path/to/model.gguf) oppure copialo nella cartella dei modelli di LM Studio — il percorso predefinito esatto varia in base alla versione e al sistema operativo, ma la scheda My Models lo mostra e consente di modificarlo. I file devono risiedere in una struttura di sottocartelle del tipo publisher/model-name/ per essere riconosciuti. Consulta la guida completa a LM Studio per la procedura dettagliata.

Domande frequenti

GGUF è supportato solo su CPU o utilizza anche la GPU?

Entrambe le opzioni. llama.cpp è nato come progetto di inferenza su CPU, ma trasferisce i layer del modello sulla GPU (CUDA, Metal, Vulkan, ROCm) ed esegue l’intero modello sulla GPU quando questo entra interamente nella VRAM. Ollama e LM Studio gestiscono automaticamente la suddivisione tra CPU e GPU; usando direttamente llama.cpp, puoi controllarla tramite il flag -ngl (numero di layer da assegnare alla GPU).

Qual è la differenza tra Q4_K_M e Q4_K_S?

Entrambe sono quantizzazioni k-quants da ~4 bit; la lettera indica la variante dimensionale. _M (medium) mantiene una maggiore precisione per i tensori più sensibili alla qualità rispetto a _S (small), risultando quindi leggermente più grande e leggermente più performante. La differenza è minima: scegli _M a meno che gli ultimi centinaia di megabyte non facciano la differenza per far entrare il modello nella memoria disponibile.

Quanta qualità si perde effettivamente con la quantizzazione?

Con Q8_0 e Q6_K la perdita è praticamente nulla — test ciechi faticano a distinguerli dall’originale in formato F16. Q4_K_M comporta una lieve perdita misurabile, che la maggior parte degli utenti non nota mai durante una conversazione, sebbene possa influire su compiti particolarmente precisi come la generazione di codice o calcoli matematici. Al di sotto di Q4 la degradazione diventa evidente, e i modelli più piccoli ne risentono di più rispetto a quelli più grandi.

Posso usare GGUF con transformers o vLLM?

Esiste un supporto limitato, ma non è il percorso nativo: transformers può dequantizzare alcuni file GGUF al momento del caricamento, mentre vLLM dispone di un supporto sperimentale per GGUF, la cui compatibilità varia in base all’architettura. Se stai sviluppando su questi stack, preferisci il formato safetensors; GGUF va considerato piuttosto come il formato nativo per i runtime della famiglia llama.cpp.

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

I modelli molto grandi vengono partizionati in parti denominate ad esempio model-00001-of-00002.gguf, principalmente per rimanere al di sotto dei limiti di dimensione imposti dalle piattaforme di hosting. Conserva tutti i file nella stessa cartella e punta il tuo runtime sul primo — llama.cpp e gli strumenti basati su di esso caricheranno automaticamente le parti rimanenti.

Una volta individuata la quantizzazione compatibile con il tuo hardware, la domanda pratica successiva è quale modello utilizzare: la database di modelli tabella comparativa elenca specifiche tecniche, requisiti di VRAM e prezzi per 37 modelli attuali, mentre i migliori modelli locali per Ollama