Formato GGUF: cos’è e come eseguirne uno

A versione GGUF del modello è un modello linguistico di grandi dimensioni impacchettato nel formato di file GGUF — un contenitore monofile che include i pesi quantizzati, il tokenizer, gli iperparametri e il template per i prompt. È stato creato da Georgi Gerganov e dal progetto llama.cpp nell’agosto 2023 per sostituire il precedente formato GGML. GGUF rende possibile scaricare un singolo file, puntarci un runtime e ottenere un LLM locale funzionante su un laptop o una workstation.

Cos’è realmente GGUF

GGUF sta per GPT-Generated Unified Format. Strutturalmente è un file binario dotato di intestazione, di un blocco di metadati chiave-valore, di un indice dei tensori e dei dati tensoriali stessi. La specifica ufficiale GGUF nel repository ggml ne definisce la struttura.

Due proprietà sono fondamentali per l’utente:

• Autosufficiente. Il file contiene il tokenizer, i token speciali, gli ID EOS/BOS, il template di chat e i metadati sull’architettura. Non hai bisogno di un file separato tokenizer.json o config.json accanto ad esso.
• Mappabile in memoria. I runtime usano mmap() per caricare il file, quindi l’avvio è quasi istantaneo e il sistema operativo carica i pesi su richiesta. Questo spiega perché un file GGUF da 40 GB si apre in pochi secondi anche su un SSD lento.

GGUF ha sostituito GGML perché quest’ultimo non prevedeva alcun sistema di versioning, mescolava metadati e pesi e si rompeva ogni volta che veniva introdotta una nuova architettura. GGUF invece è versionato ed estensibile.

Quantizzazione: la convenzione di denominazione

La maggior parte dei file GGUF che scarichi è quantizzata — ovvero i pesi sono memorizzati con meno bit rispetto all’originale in FP16. Il suffisso nel nome del file indica lo schema utilizzato. Le famiglie attuali sono documentate nel README di quantize di llama.cpp.

Quant	Bit per peso (approssimativi)	Utilizzo tipico
Q2_K	~2.6	Più piccolo, perdita di qualità percettibile
Q3_K_M	~3.9	Compressione aggressiva
Q4_K_M	~4.8	Valore predefinito più comune — buon compromesso tra dimensioni e qualità
Q5_K_M	~5.7	Qualità superiore, file più grande
Q6_K	~6.6	Quasi senza perdita rispetto a FP16
Q8_0	~8.5	Effettivamente senza perdita, circa il doppio della dimensione di Q4
F16 / BF16	16	Riferimento non quantizzato

Il _K Le varianti k-quants usano una precisione variabile per blocco di tensori. I suffissi _M / _S / _L indicano preset di miscelazione a blocchi di media, piccola o grande dimensione. Le varianti più recenti (es. IQ IQ4_XS ) utilizzano una calibrazione basata su matrice di importanza per ottenere una qualità migliore con lo stesso budget di bit.utilizza la calibrazione della matrice di importanza per ottenere una qualità superiore con lo stesso budget di bit.

Come regola generale per la VRAM, prendi la dimensione del file su disco e aggiungi circa 1–3 GB per la cache KV in contesti brevi, e ancora di più per contesti lunghi. Da database dei modelli Convly: Llama 3.1 8B richiede circa 5 GB in quantizzazione a 4 bit, Llama 3.3 70B circa 40 GB e Mistral 7B circa 4,5 GB. Per modelli di dimensioni superiori, il tabella dei requisiti di VRAM è la ricerca più veloce.

Dove trovare i file GGUF

Quasi tutte le distribuzioni GGUF avvengono su Hugging Face. Cerca il nome del modello seguito da «GGUF». Tra i re-quantizzatori affidabili figurano bartowski, Qwen (ufficiale per Qwen3), lmstudio-community, unsloth e MaziyarPanahi. Meta, Google, Mistral e Microsoft pubblicano alcuni build ufficiali GGUF; per gli altri, la comunità esegue la quantizzazione partendo dai modelli rilasciati in formato safetensors.

Un repository contiene tipicamente un file per ogni livello di quantizzazione, ad esempio Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf. Per modelli superiori ai ~50 GB, il file è suddiviso in frammenti (shard) denominati -00001-of-00003.gguf; i runtime li caricano automaticamente a partire dal primo shard.

Eseguire un modello GGUF

Linux

Compila llama.cpp da sorgente oppure installa il binario precompilato. 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
./build/bin/llama-cli -m ~/models/llama-3.1-8b-instruct-Q4_K_M.gguf 
    -p "Spiega GGUF in un solo paragrafo." -n 256 -ngl 99

Il -ngl Il flag «n-gpu-layers» determina quanti strati del transformer vengono spostati sulla GPU. Impostalo abbastanza alto da far entrare l’intero modello nella VRAM; se esaurisci memoria, riducilo e i restanti strati rimarranno sulla CPU. Per esporre un’API HTTP compatibile con OpenAI, usa llama-server che di default ascolta sulla porta 8080.

macOS

Su Apple Silicon, llama.cpp utilizza automaticamente il backend Metal. Installalo tramite Homebrew:

brew install llama.cpp
llama-cli -m ~/models/qwen3-8b-Q5_K_M.gguf -p "Ciao" -ngl 99

La memoria unificata implica che il limite massimo è rappresentato dalla RAM totale meno l’overhead del sistema operativo. Un Mac con chip M da 32 GB gestisce agevolmente Qwen3 da 14B o -ngl il limite è dato dalla RAM totale meno l'overhead del sistema operativo. Un Mac con chip M e 32 GB di RAM esegue agevolmente Qwen3 14B o Gemma 3 12B in quantizzazione Q4_K_M — il database indica rispettivamente ~9 GB e ~8 GB di utilizzo di VRAM.

Per un’interfaccia grafica (GUI), LM Studio è la scelta più comune su Mac. Scarica automaticamente i file GGUF da Hugging Face e fornisce un server locale compatibile con l’API OpenAI.

Windows

Tre percorsi pratici:

• Ollama. Installa da ollama.com/download, quindi ollama run llama3.1:8b. Ollama scarica autonomamente le proprie versioni curate di GGUF. Per caricare un file arbitrario, crea un file Modelfile contenente una riga FROM ./mymodel.gguf ed esegui ollama create mymodel -f Modelfile. Consulta la nostra Guida all'installazione di Ollama.
• LM Studio. Installazione in un clic, navigazione e download di GGUF tramite interfaccia grafica, con regolatore per l’offload GPU.
• binari precompilati di llama.cpp. Il progetto fornisce zippati precompilati per Windows (CPU, CUDA e Vulkan) sulla pagina delle release su GitHub. Estrai l’archivio ed esegui llama-cli.exe nello stesso modo usato su Linux.

Per quanto riguarda la scelta della GPU, la guida GPU per LLM locali illustra le attuali opzioni rapporto prezzo/VRAM.

GGUF vs Safetensors vs AWQ vs GPTQ

Formato	Runtime principale	Precisione	Ideale per
GGUF	llama.cpp, Ollama, LM Studio	2–8 bit + F16	CPU, inferenza mista CPU/GPU, Apple Silicon, singolo utente
Safetensors (FP16/BF16)	Transformers, vLLM	16 bit	Addestramento, ricerca, inferenza in piena precisione
AWQ	vLLM, AutoAWQ	4 bit	Servizio GPU ad alta velocità di elaborazione
GPTQ	vLLM, ExLlamaV2	3–8 bit	Inferenza GPU-only con batching
MLX	MLX (Apple)	4–16 bit	Solo per Apple Silicon

Scegli GGUF quando il target è un singolo utente su hardware eterogeneo o quando vuoi garantire che il modello possa essere eseguito anche su CPU. Scegli vLLM con safetensors AWQ/GPTQ quando devi servire molti utenti concorrenti su una GPU datacenter.

Quando GGUF non è la soluzione giusta

GGUF presuppone inferenza monostream con batch size pari a 1. Il throughput è molto inferiore rispetto a vLLM o TensorRT-LLM sotto carico concorrente e non supporta l’attenzione paginata (paged attention). Se stai esponendo un’API destinata a traffico reale, un deployment in FP16 o AWQ su vLLM supererà GGUF in termini di token/sec/dollaro, anche prima di considerare il tempo di sviluppo impiegato.

Si rivela inoltre inefficace per i modelli di dimensioni più elevate. Kimi K3 richiede circa 1,4 TB di VRAM in formato 4-bit e DeepSeek V4-Pro richiede invece circa 800 GB — si tratta di distribuzioni su più nodi, non di carichi di lavoro GGUF per desktop. E per i modelli di ultima generazione ospitati in cloud, come Claude Sonnet 4.6 a 3 USD in ingresso / 15 USD in uscita per ogni milione di token oppure Gemini 3.6 Flash a 1,50 USD in ingresso / 7,50 USD in uscita, non esistono pesi locali da convertire. Fai i conti sul calcolatore self-hosting vs API prima di impegnarti nell’acquisto di una GPU.

Convertire un modello in GGUF

Se un modello è disponibile su Hugging Face in formato safetensors ma nessuno lo ha ancora quantizzato, il flusso di lavoro è il seguente:

# nella repository llama.cpp
pip install -r requirements.txt
python convert_hf_to_gguf.py /percorso/verso/hf-model --outfile model-f16.gguf
./build/bin/llama-quantize model-f16.gguf model-Q4_K_M.gguf Q4_K_M

Lo script di conversione supporta soltanto le architetture già integrate in llama.cpp — ad esempio llama, mistral, qwen2/3, gemma, phi e una lista sempre crescente di altre. Per architetture nuove è necessario prima modificare il codice. I nomi dei file e le opzioni della riga di comando nello script sono cambiati tra le diverse versioni di llama.cpp, quindi verifica python convert_hf_to_gguf.py --help rispetto al commit su cui hai eseguito la compilazione.

Domande frequenti

GGUF è la stessa cosa di GGML?

No. GGML era il formato precedente utilizzato da llama.cpp fino a metà 2023. GGUF lo ha sostituito ad agosto 2023 introducendo un’intestazione con numero di versione, metadati incorporati e un layout stabile dei tensori. I vecchi file .bin GGML non vengono più caricati dalla versione attuale di llama.cpp; devi trovare una versione GGUF già riquantizzata.

Quale quantizzazione devo scaricare?

Inizia con Q4_K_M. È il formato che garantisce la massima compatibilità con l’hardware disponibile e comporta una perdita di qualità minima rispetto all’FP16 per la maggior parte dei modelli con oltre 7 miliardi di parametri. Passa a Q5_K_M o Q6_K se hai VRAM in eccesso e ti interessa migliorare l’accuratezza nelle attività di programmazione o ragionamento. Scendi a Q3_K_M oppure a una variante IQ3 solo se il modello non riesce ad adattarsi alla memoria disponibile in alcun altro modo.

Posso modelli GGUF utilizzare la mia GPU?

Sì. llama.cpp supporta CUDA (NVIDIA), ROCm (AMD), Metal (Apple), Vulkan (multi-vendor) e SYCL (Intel). L’opzione -ngl trasferisce i layer sulla GPU. Se l’intero modello entra nella VRAM, le prestazioni in termini di throughput sono vicine a quelle ottenibili con runtime GPU dedicati; nel caso di offload parziale, la velocità dipende dal livello più lento (CPU o GPU) che contiene il layer più lento.

GGUF funziona con modelli per visione o audio?

Parzialmente. llama.cpp supporta modelli multimediali nello stile di LLaVA tramite un file mmproj GGUF abbinato che contiene il proiettore visivo. Il supporto per Qwen-VL, Gemma 3 Vision e modelli simili è stato progressivamente aggiunto nel tempo, ma rimane in ritardo rispetto alle versioni testuali. I modelli audio come Whisper utilizzano invece un proprio formato correlato gestito da whisper.cpp, non dal binario principale di llama.cpp.

Come scelgo un modello GGUF adatto al mio hardware?

Cerca il modello nel database dei modelli Convly per conoscere il suo consumo di VRAM in versione 4-bit, quindi sottrai 1–3 GB di margine per il contesto e l’overhead del sistema operativo. Su una GPU da 24 GB, Qwen3 32B (~20 GB) o Gemma 3 27B (~16 GB) in Q4 sono scelte confortevoli. Il Calcolatore VRAM gestisce contesti più lunghi, il che fa crescere significativamente la cache KV.

I file GGUF sono sicuri da eseguire?

I pesi sono semplicemente numeri — a differenza dei checkpoint basati su pickle Python, GGUF non esegue codice durante il caricamento. Il rischio consiste in un file malevolmente costruito che sfrutti un bug nel parser del runtime. Limitati a uploader affidabili su Hugging Face (bartowski, unsloth, lmstudio-community, account ufficiali dei vendor) e tieni aggiornati llama.cpp, Ollama o LM Studio .