GGUF (GGML Universal File) ist ein binäres Dateiformat, das entwickelt wurde, um sowohl Tensoren als auch Metadaten in einer einzigen Datei zu speichern und so ein schnelles Speichern und Laden von Modelldaten zu ermöglichen. Es wurde im August 2023 vom llama.cpp-Projekt eingeführt, um die Abwärtskompatibilität zu verbessern, als Unterstützung für weitere Modellarchitekturen hinzugefügt wurde. GGUF löste frühere Formate des Projekts wie GGML ab und wird typischerweise durch die Konvertierung von Modellen erzeugt, die mit anderen Machine-Learning-Bibliotheken wie PyTorch entwickelt wurden. Das Format ist zum Standard für die Verteilung quantisierter Large Language Models für die lokale Inferenz geworden und wird nativ von Tools wie llama.cpp, Ollama, LM Studio, GPT4All, Jan und koboldcpp unterstützt. Stand 2026 werden Zehntausende von GGUF-Checkpoints auf Hugging Face gehostet, das eine erstklassige Integration bietet, einschließlich eines Metadaten-Viewers, eines Inferenz-Endpunkt-Dienstes und einer JavaScript-Parser-Bibliothek.
Geschichte
Die Modelldateiformate des llama.cpp-Projekts durchliefen vier benannte Phasen: GGML, GGMF, GGJT und GGUF. Das ursprüngliche GGML-Format war ein schlanker Tensor-Container, der Modell-Hyperparameter und Tokenizer-Informationen fest im Lader kodierte; das Hinzufügen einer neuen Modellarchitektur oder eines Quantisierungsschemas erforderte in der Regel Codeänderungen, die die Kompatibilität mit vorhandenen Dateien brachen.
Als llama.cpp im Laufe des Jahres 2023 wuchs und zusätzliche Architekturen über Llama hinaus unterstützte - darunter Mistral, Falcon und andere - wurden diese Einschränkungen zunehmend schwer zu handhaben. GGUF wurde am 21. August 2023 als abwärtsinkompatibler Nachfolger eingeführt, wobei die Spezifikation durch Pull-Request #302 im ggerganov/ggml-Repository formalisiert wurde. Das Format übernimmt das Gesamtlayout von GGJT, ersetzt jedoch dessen flache Hyperparameter-Liste durch ein strukturiertes Schlüssel-Wert-Metadatensystem, das das Hinzufügen neuer Felder - Architekturdetails, Tokenizer-Vokabulare, Trainingsparameter - ermöglicht, ohne den Lader zu ändern oder ältere Modelle zu brechen.
Das Format selbst hat drei interne Versionen durchlaufen. Version 1 etablierte die grundlegende Struktur; Version 2 fügte explizite Ausrichtungspadding zur Unterstützung von Memory-Mapping hinzu; und Version 3, die aktuelle Version, fügte optionale Big-Endian-Unterstützung hinzu.
Design
GGUF konzentriert sich auf Quantisierung, also die Reduzierung der Präzision der Modellgewichte. Dies kann zu geringerem Speicherverbrauch und höherer Geschwindigkeit führen, allerdings auf Kosten einer reduzierten Modellgenauigkeit. Das Format ist darauf ausgelegt:
- In sich geschlossen - eine einzige Datei enthält die Tensoren, den Tokenizer und alle Metadaten, die zum Laden und Ausführen des Modells benötigt werden, wodurch begleitende Konfigurationsdateien überflüssig werden.
- Memory-mappable - Tensordaten sind ausgerichtet (standardmäßig auf eine 32-Byte-Grenze), sodass Gewichte direkt über Zeiger aufgerufen werden können, ohne die gesamte Datei in den RAM zu laden, was es ermöglicht, Modelle, die größer als der verfügbare Speicher sind, über Betriebssystem-Paging zu bedienen.
- Erweiterbar - der Schlüssel-Wert-Metadatenblock ermöglicht das Hinzufügen neuer Felder, ohne die Kompatibilität mit älteren Lesern zu brechen.
GGUF unterstützt quantisierte Integer-Typen von 2 Bit bis 8 Bit, gängige Gleitkomma-Datenformate wie float32, float16 und bfloat16 sowie 1,58-Bit-Quantisierung. Mehrere "K-quant"-Varianten (wie Q4_K, Q5_K und Q6_K) verwenden ein blockbasiertes Schema mit separaten Skalen- und Minimalwerten pro Superblock, was bei einer gegebenen Bitbreite im Allgemeinen eine bessere Qualität bietet als die einfacheren Legacy-Quantisierungen wie Q4_0 und Q8_0. GGUF enthält die Informationen, die zum Ausführen eines GPT-ähnlichen Sprachmodells erforderlich sind, wie das Tokenizer-Vokabular, die Kontextlänge, Tensorinformationen und andere Attribute.
Dateistruktur
Eine GGUF-Datei besteht aus vier aufeinanderfolgenden Abschnitten: einem Header fester Größe, einem Schlüssel-Wert-Metadatenblock, einem Tensorinformationsblock und den Tensordaten selbst.
Byte-Ebene-Struktur (Little-Endian)
Vor Version 3 waren Dateien implizit Little-Endian; Version 3 erlaubt Big-Endian-Speicherung, enthält jedoch kein Flag zur Angabe der Endianness, sodass diese aus dem Kontext abgeleitet werden muss.
#### Metadatenblock
Der Metadatenblock ist eine Sequenz von typisierten Schlüssel-Wert-Paaren. Schlüssel sind namespaced Zeichenfolgen (zum Beispiel general.*, tokenizer.* oder ein architekturspezifisches Präfix wie llama.*), und Werte können Skalare, Zeichenfolgen oder Arrays sein - einschließlich mehrdimensionaler Arrays.
#### Tensorinformationsblock
Für jeden Tensor speichert der Informationsblock seinen Namen, die Anzahl der Dimensionen, die Form, den Datentyp und den Byte-Offset innerhalb des nachfolgenden tensor_data[]-Bereichs. Das Benennungsschema ist über Architekturen hinweg standardisiert (zum Beispiel blk.0.ffn_gate.weight), sodass Lader Gewichte unabhängig vom Quell-Framework lokalisieren können.
#### Tensordaten
Die Tensordaten folgen auf den Informationsblock und beginnen an der nächsten Ausrichtungsgrenze. Der Ausrichtungswert selbst wird in den Metadaten unter dem Schlüssel general.alignment gespeichert; wenn er fehlt, beträgt der Standardwert 32 Byte. Die Ausrichtung der Daten auf diese Weise ermöglicht das direkte Memory-Mapping der Datei: Tensorgewichte können über Zeiger ohne zusätzliche Kopie gelesen werden, was für SIMD-Operationen, GPU-DMA-Transfers und CPU-Cache-Effizienz wichtig ist.
Werkzeuge
Modelle aus anderen Frameworks werden typischerweise mit dem Skript convert_hf_to_gguf.py aus llama.cpp in GGUF konvertiert, das Hugging-Face-Checkpoints (häufig in safetensors-Form) liest und eine GGUF-Datei in einer gewählten Basispräzision wie f16 oder bf16 ausgibt. Die resultierende Datei kann dann mit dem Dienstprogramm llama-quantize in eines der GGUF-Integer-Formate requantisiert werden, und sehr große Modelle können mit llama-gguf-split auf mehrere Dateien aufgeteilt werden.
Das llama.cpp-Projekt stellt außerdem eine C/C++-API (deklariert in ggml/include/gguf.h) und ein Python-Paket, gguf-py, zum programmatischen Lesen und Schreiben von GGUF-Dateien bereit.
Verbreitung
GGUF ist das native Modellformat von llama.cpp und von Ollama, das llama.cpp als Inferenz-Backend verwendet; Ollama-Modelle, die aus seiner Registry gezogen werden, sind intern GGUF-Dateien, und beliebige GGUF-Dateien von Hugging Face können geladen werden, indem man sie als hf.co/{user}/{repo} referenziert. Andere Inferenzanwendungen, die GGUF direkt konsumieren, umfassen LM Studio, GPT4All, Jan und koboldcpp.
Hugging Face unterstützt das Format als erstklassigen Bürger auf seinem Modell-Hub und bietet einen GGUF-Metadaten-Viewer, Filterung nach dem gguf-Tag, eine Inferenz-Endpunkt-Integration und eine große Sammlung von Community-hochgeladenen GGUF-Checkpoints.