GGUF (GGML Universal File) est un format de fichier binaire conçu pour stocker à la fois des tenseurs et des métadonnées dans un seul fichier, permettant un enregistrement et un chargement rapides des données de modèle. Introduit en août 2023 par le projet llama.cpp, il a été créé pour améliorer la compatibilité ascendante à mesure que la prise en charge de nouvelles architectures de modèles était ajoutée. GGUF a remplacé les formats antérieurs utilisés par le projet, tels que GGML, et est généralement produit en convertissant des modèles développés avec d'autres bibliothèques de Machine learning comme PyTorch. Le format est devenu la norme pour distribuer des grands modèles de langage quantifiés pour l'inférence locale, pris en charge nativement par des outils tels que llama.cpp, Ollama, LM Studio, GPT4All, Jan et koboldcpp. En 2026, des dizaines de milliers de points de contrôle GGUF sont hébergés sur Hugging Face, qui offre une intégration de premier ordre, notamment un visualiseur de métadonnées, un service de points de terminaison d'inférence et une bibliothèque d'analyse syntaxique JavaScript.
Historique
Les formats de fichiers de modèle utilisés par le projet llama.cpp ont évolué à travers quatre étapes nommées : GGML, GGMF, GGJT et GGUF. Le format GGML d'origine était un conteneur de tenseurs mince qui codait en dur les hyperparamètres du modèle et les informations du tokeniseur dans le chargeur ; l'ajout de la prise en charge d'une nouvelle architecture de modèle ou d'un schéma de quantification nécessitait généralement des modifications de code qui cassaient la compatibilité avec les fichiers existants.
Alors que llama.cpp s'est développé en 2023 pour prendre en charge des architectures supplémentaires au-delà de Llama - notamment Mistral, Falcon et d'autres - ces limitations sont devenues de plus en plus difficiles à gérer. GGUF a été introduit le 21 août 2023 en tant que successeur incompatible avec les versions antérieures, avec la spécification formalisée via la demande d'extraction #302 dans le dépôt ggerganov/ggml. Le format hérite de la disposition générale de GGJT mais remplace sa liste plate d'hyperparamètres par un système structuré de métadonnées clé-valeur, permettant d'ajouter de nouveaux champs - détails d'architecture, vocabulaires de tokeniseur, paramètres d'entraînement - sans modifier le chargeur ni casser les modèles plus anciens.
Le format lui-même a connu trois versions internes. La version 1 a établi la structure de base ; la version 2 a ajouté un remplissage d'alignement explicite pour prendre en charge le mappage mémoire ; et la version 3, la version actuelle, a ajouté la prise en charge facultative du big-endian.
Conception
GGUF se concentre sur la quantification, l'action de réduire la précision des poids du modèle. Cela peut entraîner une réduction de l'utilisation de la mémoire et une augmentation de la vitesse, au prix d'une précision réduite du modèle. Le format est conçu pour être :
- Autonome - un seul fichier contient les tenseurs, le tokeniseur et toutes les métadonnées nécessaires pour charger et exécuter le modèle, éliminant le besoin de fichiers de configuration associés.
- Mappable en mémoire - les données des tenseurs sont alignées (par défaut sur une limite de 32 octets) afin que les poids puissent être accédés directement via des pointeurs sans charger tout le fichier en RAM, permettant de servir des modèles plus grands que la mémoire disponible via la pagination du système d'exploitation.
- Extensible - le bloc de métadonnées clé-valeur permet d'ajouter de nouveaux champs sans casser la compatibilité avec les lecteurs plus anciens.
GGUF prend en charge les types entiers quantifiés de 2 à 8 bits, les formats de données à virgule flottante courants tels que float32, float16 et bfloat16, et la quantification à 1,58 bit. Plusieurs variantes « K-quant » (telles que Q4_K, Q5_K et Q6_K) utilisent un schéma basé sur des blocs avec des valeurs d'échelle et de minimum séparées par super-bloc, donnant généralement une meilleure qualité à une largeur de bits donnée que les quantifications héritées plus simples telles que Q4_0 et Q8_0. GGUF contient les informations nécessaires pour exécuter un modèle de langage de type GPT, telles que le vocabulaire du tokeniseur, la longueur du contexte, les informations sur les tenseurs et d'autres attributs.
Structure du fichier
Un fichier GGUF se compose de quatre sections séquentielles : un en-tête de taille fixe, un bloc de métadonnées clé-valeur, un bloc d'informations sur les tenseurs et les données des tenseurs elles-mêmes.
Structure au niveau des octets (little-endian)
Avant la version 3, les fichiers étaient implicitement little-endian ; la version 3 permet le stockage big-endian mais n'inclut pas de drapeau indiquant l'endianness, qui doit donc être déduit du contexte.
#### Bloc de métadonnées
Le bloc de métadonnées est une séquence de paires clé-valeur typées. Les clés sont des chaînes de caractères avec espace de noms (par exemple general.*, tokenizer.*, ou un préfixe spécifique à l'architecture tel que llama.*), et les valeurs peuvent être des scalaires, des chaînes ou des tableaux - y compris des tableaux multidimensionnels.
#### Bloc d'informations sur les tenseurs
Pour chaque tenseur, le bloc d'informations stocke son nom, son nombre de dimensions, sa forme, son type de données et son décalage en octets dans la région tensor_data[] suivante. Le schéma de nommage est standardisé entre les architectures (par exemple, blk.0.ffn_gate.weight), afin que les chargeurs puissent localiser les poids quel que soit le framework source.
#### Données des tenseurs
Les données des tenseurs suivent le bloc d'informations et commencent à la limite d'alignement suivante. La valeur d'alignement est elle-même stockée dans les métadonnées sous la clé general.alignment ; si absente, elle est par défaut de 32 octets. Aligner les données de cette manière est ce qui permet au fichier d'être mappé directement en mémoire : les poids des tenseurs peuvent être lus via des pointeurs sans copie supplémentaire, ce qui est important pour les opérations SIMD, les transferts DMA GPU et l'efficacité du cache CPU.
Outillage
Les modèles stockés dans d'autres frameworks sont généralement convertis en GGUF à l'aide du script convert_hf_to_gguf.py fourni avec llama.cpp, qui lit les points de contrôle Hugging Face (généralement sous forme safetensors) et émet un fichier GGUF dans une précision de base choisie telle que f16 ou bf16. Le fichier résultant peut ensuite être re-quantifié dans l'un des formats entiers GGUF avec l'utilitaire llama-quantize, et les très grands modèles peuvent être partitionnés sur plusieurs fichiers avec llama-gguf-split.
Le projet llama.cpp expose également une API C/C++ (déclarée dans ggml/include/gguf.h) et un package Python, gguf-py, pour lire et écrire des fichiers GGUF par programmation.
Adoption
GGUF est le format de modèle natif de llama.cpp et d'Ollama, qui utilise llama.cpp comme backend d'inférence ; les modèles Ollama extraits de son registre sont des fichiers GGUF en interne, et des fichiers GGUF arbitraires de Hugging Face peuvent être chargés en les référençant comme hf.co/{utilisateur}/{dépôt}. D'autres applications d'inférence qui consomment directement GGUF incluent LM Studio, GPT4All, Jan et koboldcpp.
Hugging Face prend en charge le format en tant que citoyen de premier ordre sur son hub de modèles, fournissant un visualiseur de métadonnées GGUF, un filtrage par la balise gguf, une intégration de points de terminaison d'inférence et une grande collection de points de contrôle GGUF téléchargés par la communauté.