Licenza YOLO
Torna al glossario di Ultralytics

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.

Esplora le soluzioni

La visione artificiale nello sport

La visione artificiale nello sport

Scopri come Ultralytics YOLO alimenta la computer vision nello sport con il tracciamento di giocatori e palloni, l'analisi delle prestazioni, gli approfondimenti per gli allenatori e la riabilitazione degli atleti.
Scopri di più
Computer vision per immagini aeree

Computer vision per immagini aeree

Trasforma immagini aeree e riprese da drone in informazioni utili in tempo reale per agricoltura, acquacoltura, conservazione e analisi geospaziale con Ultralytics YOLO.
Scopri di più
Computer vision nel settore aerospaziale

Computer vision nel settore aerospaziale

Applica la visione artificiale nel settore aerospaziale con Ultralytics YOLO per l'ispezione degli aeromobili, il rilevamento di FOD sulle piste, le operazioni di terra aeroportuali e il rilevamento di difetti nei materiali compositi.
Scopri di più
Visione artificiale nella sicurezza

Visione artificiale nella sicurezza

Proteggi ogni sito con i modelli Ultralytics YOLO. L'IA visiva alimenta il monitoraggio perimetrale, il rilevamento delle minacce, il riconoscimento delle targhe e la sicurezza sul lavoro.
Scopri di più
Visione artificiale nella robotica

Visione artificiale nella robotica

Dai più potenza alle macchine intelligenti con i modelli Ultralytics YOLO. Nell'ambito della robotica, l'IA visiva alimenta la navigazione autonoma, la percezione, il tracciamento degli oggetti e il controllo in tempo reale.
Scopri di più
Visione artificiale nella logistica

Visione artificiale nella logistica

Semplifica la logistica con i modelli Ultralytics YOLO. L'IA per la visione consente l'ispezione dei pacchi, la selezione, il tracciamento dei veicoli e il monitoraggio della sicurezza nei magazzini in tempo reale.
Scopri di più
Visione artificiale nel commercio al dettaglio

Visione artificiale nel commercio al dettaglio

Ripensa il commercio al dettaglio con i modelli Ultralytics YOLO. L'IA per la visione consente di tracciare le scorte, monitorare gli scaffali, gestire le code e ottenere informazioni più approfondite sui clienti.
Scopri di più
Visione artificiale in ambito sanitario

Visione artificiale in ambito sanitario

Crea soluzioni sanitarie con i modelli Ultralytics YOLO. In ambito sanitario, l'IA per la visione consente di elaborare più rapidamente le immagini mediche, migliorare la diagnostica e monitorare i pazienti.
Scopri di più
Computer vision nella produzione

Computer vision nella produzione

Ottimizza la produzione con i modelli Ultralytics YOLO. La visione basata sull'IA migliora il controllo qualità, il rilevamento dei difetti, la conformità ai requisiti sui DPI e l'automazione delle linee di assemblaggio.
Scopri di più
Computer vision nel settore automobilistico

Computer vision nel settore automobilistico

Applica la computer vision al settore automobilistico con i modelli Ultralytics YOLO. La visione basata sull'IA migliora la sicurezza stradale, i sistemi di assistenza alla guida e l'automazione dei veicoli, per strade più intelligenti.
Scopri di più
Visione artificiale in agricoltura

Visione artificiale in agricoltura

Porta l'IA visiva nell'agricoltura intelligente con i modelli Ultralytics YOLO. Gestisci il monitoraggio delle colture, il tracciamento del bestiame e l'agricoltura di precisione per ottenere raccolti più abbondanti e intelligenti.
Scopri di più

Costruiamo insieme il futuro dell'IA!

Inizia il tuo percorso verso il futuro del machine learning