GGUF
GGUF è il formato a file singolo che llama.cpp usa per archiviare i pesi, il tokenizer e i metadati di un LLM, spesso quantizzati a 4-8 bit per l'hardware locale.
GGUF è un formato di file binario per memorizzare modelli eseguiti su GGML, la libreria C per tensori alla base di llama.cpp, e sugli strumenti costruiti su di essa. Un singolo file GGUF contiene tutto ciò che serve per eseguire un modello linguistico di grandi dimensioni (LLM): architettura e iperparametri, vocabolario del tokenizer, modello di chat e pesi del modello, solitamente compressi tramite quantizzazione del modello a un intervallo compreso tra 2 e 8 bit per peso. Il progetto llama.cpp ha introdotto GGUF nell'agosto 2023 per sostituire i precedenti formati GGML, GGMF e GGJT, e il formato è diventato lo standard per condividere modelli a pesi aperti destinati all'inferenza locale su una CPU di laptop, un Mac con Apple Silicon o una GPU consumer; su Hugging Face sono presenti migliaia di repository GGUF.
Com'è fatto un file GGUF#
La specifica GGUF definisce quattro parti, in quest'ordine. Un'intestazione contiene i byte magici GGUF, la versione del formato (attualmente 3) e il numero di tensori e voci di metadati. Seguono metadati tipizzati chiave-valore, come general.architecture, llama.context_length, tokenizer.ggml.tokens e tokenizer.chat_template, che incorpora nel file la tokenizzazione e il formato dei prompt del modello. Una tabella elenca poi il nome, la forma, il tipo di dati e l'offset di ogni tensore; i dati dei tensori vengono per ultimi, allineati per impostazione predefinita a multipli di 32 byte, così che il runtime possa mappare il file in memoria e caricarlo quasi istantaneamente. I lettori cercano i metadati tramite chiave, perciò è possibile aggiungere nuove architetture e campi senza compromettere i file più vecchi.
Ogni tensore ha un tipo proprio, quindi un singolo file può combinare precisioni diverse. Il pacchetto Python gguf, gestito nel repository llama.cpp, scrive e legge il formato e implementa diversi tipi di quantizzazione:
import numpy as np
from gguf import GGMLQuantizationType, GGUFReader, GGUFWriter
from gguf.quants import dequantize, quantize
weights = np.random.default_rng(0).standard_normal((1024, 1024)).astype(np.float32)
# A GGUF file holds metadata key-value pairs plus named tensors, each with its own type
writer = GGUFWriter("tiny.gguf", arch="llama")
writer.add_context_length(4096)
for qtype in [GGMLQuantizationType.F16, GGMLQuantizationType.Q8_0, GGMLQuantizationType.Q4_0]:
writer.add_tensor(f"weight.{qtype.name}", quantize(weights, qtype), raw_dtype=qtype)
writer.write_header_to_file()
writer.write_kv_data_to_file()
writer.write_tensors_to_file()
writer.close()
# Read the file back: metadata keys, then each tensor's bits per weight and rounding error
reader = GGUFReader("tiny.gguf")
print([name for name in reader.fields if not name.startswith("GGUF.")])
for tensor in reader.tensors:
error = np.abs(dequantize(tensor.data, tensor.tensor_type).reshape(weights.shape) - weights).mean()
print(f"{tensor.tensor_type.name}: {8 * tensor.n_bytes / weights.size:.1f} bits per weight, mean error {error:.4f}")Elenca le due chiavi di metadati, general.architecture e llama.context_length, quindi riporta 16,0 bit per peso con un errore medio di 0,0001 per F16, 8,5 bit e 0,0045 per Q8_0, e 4,5 bit e 0,0719 per Q4_0. Q8_0 e Q4_0 memorizzano blocchi di 32 pesi con una scala FP16 per blocco, da cui deriva il mezzo bit aggiuntivo.
Tipi di quantizzazione#
I tipi di quantizzazione GGUF appartengono a tre generazioni. I formati a blocchi originali, come Q4_0 e Q8_0, usano una scala ogni 32 pesi. I K-quants, come Q4_K e Q6_K, raggruppano i blocchi in superblocchi da 256 pesi con scale quantizzate; nomi di file come Q4_K_M indicano una combinazione che mantiene i tensori più sensibili a precisione maggiore. Gli I-quants, come IQ2_XXS e IQ4_XS, raggiungono circa 2-4 bit per peso, in genere guidati da una matrice di importanza che llama-imatrix calcola a partire da testo campione, così che i pesi più influenti mantengano la precisione maggiore. Tra le aggiunte più recenti c'è MXFP4, il formato a virgola mobile a 4 bit usato da OpenAI per rilasciare gpt-oss. La maggior parte dei file GGUF pubblicati segue lo stesso percorso di conversione:
GGUF e gli altri formati di modello#
- GGML, GGMF e GGJT: I precedenti formati llama.cpp memorizzavano gli iperparametri come un elenco non tipizzato senza un campo per l'architettura, perciò l'aggiunta di un parametro comprometteva i file esistenti.
- Safetensors: Il formato di Hugging Face per archiviare in modo sicuro tensori grezzi, solitamente a precisione intera o dimezzata, mantenendo la configurazione e il tokenizer in file separati.
- ONNX: Memorizza un grafo computazionale completo insieme ai pesi, così che qualsiasi runtime compatibile con ONNX possa eseguire il modello senza codice specifico per l'architettura.
Eseguire modelli GGUF#
llama.cpp esegue i file GGUF dalla riga di comando o come llama-server, che espone un'API compatibile con OpenAI, e può trasferire alla GPU un numero qualsiasi di livelli lasciando gli altri sulla CPU; così è possibile eseguire anche un modello più grande della memoria della GPU. Ollama e LM Studio eseguono modelli GGUF tramite una libreria di modelli e un'interfaccia di chat, mentre l'Hugging Face Hub mostra nel browser i metadati e i tipi di tensore di ogni file GGUF. L'inferenza locale mantiene i prompt sul dispositivo, un aspetto importante per la privacy dei dati e per gli usi di edge AI offline. L'interfaccia LLM di Ultralytics può chiamare un modello GGUF servito da llama-server o da Ollama tramite i rispettivi endpoint Chat Completions compatibili con OpenAI, così che una pipeline YOLO26 possa chiedere a un modello locale di descrivere i rilevamenti senza inviare dati a un'API cloud. Il formato si estende anche oltre i modelli linguistici: i nodi personalizzati ComfyUI-GGUF caricano da file GGUF modelli di diffusione quantizzati come FLUX.1, così che possano entrare nella memoria delle GPU consumer.










