GGUF
GGUF est le format à fichier unique utilisé par llama.cpp pour stocker les poids, le tokenizer et les métadonnées d’un LLM, souvent quantifiés sur 4 à 8 bits pour du matériel local.
GGUF est un format de fichier binaire destiné au stockage des modèles exécutés sur GGML, la bibliothèque de tenseurs C à la base de llama.cpp, ainsi que sur les outils qui en sont dérivés. Un fichier GGUF contient tout le nécessaire pour exécuter un grand modèle de langage (LLM) : l'architecture et les hyperparamètres, le vocabulaire du tokenizer, le modèle de conversation et les poids du modèle, généralement compressés par quantification du modèle à une précision de 2 à 8 bits par poids. Le projet llama.cpp a introduit GGUF en août 2023 pour remplacer ses anciens formats GGML, GGMF et GGJT. Ce format est devenu la méthode standard de partage des modèles à poids ouverts pour l'inférence locale sur le CPU d'un ordinateur portable, un Mac Apple Silicon ou un GPU grand public, avec des milliers de dépôts GGUF sur Hugging Face.
Anatomie d'un fichier GGUF#
La spécification GGUF définit quatre parties, dans l'ordre. Un en-tête contient les octets magiques GGUF, la version du format (actuellement 3) et le nombre de tenseurs et d'entrées de métadonnées. Viennent ensuite des métadonnées clé-valeur typées, telles que general.architecture, llama.context_length, tokenizer.ggml.tokens et tokenizer.chat_template, qui intègrent la tokenisation et le format du prompt du modèle directement dans le fichier. Une table répertorie ensuite le nom, la forme, le type de données et le décalage de chaque tenseur ; les données des tenseurs viennent en dernier, alignées par défaut sur des blocs de 32 octets pour que l'environnement d'exécution puisse mapper le fichier en mémoire et le charger presque instantanément. Les lecteurs recherchent les métadonnées par clé, ce qui permet d'ajouter de nouvelles architectures et de nouveaux champs sans rendre les anciens fichiers incompatibles.
Chaque tenseur possède son propre type, ce qui permet de mélanger les précisions dans un même fichier. Le paquet Python gguf, maintenu dans le dépôt llama.cpp, écrit et lit ce format et implémente plusieurs types de quantification :
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}")Il répertorie les deux clés de métadonnées, general.architecture et llama.context_length, puis indique 16,0 bits par poids avec une erreur moyenne de 0,0001 pour F16, 8,5 bits et 0,0045 pour Q8_0, ainsi que 4,5 bits et 0,0719 pour Q4_0. Q8_0 et Q4_0 stockent des blocs de 32 poids avec une échelle FP16 par bloc, d'où le demi-bit supplémentaire.
Types de quantification#
Les types de quantification GGUF se répartissent en trois générations. Les formats de blocs d'origine, comme Q4_0 et Q8_0, utilisent une échelle pour 32 poids. Les quantifications K, comme Q4_K et Q6_K, regroupent les blocs en superblocs de 256 poids avec des échelles quantifiées ; les noms de fichiers tels que Q4_K_M désignent un mélange qui conserve une précision supérieure pour les tenseurs les plus sensibles. Les quantifications I, comme IQ2_XXS et IQ4_XS, atteignent environ 2 à 4 bits par poids, généralement à l'aide d'une matrice d'importance que llama-imatrix calcule à partir de textes d'exemple afin de conserver la plus grande précision pour les poids les plus influents. Parmi les ajouts récents figure MXFP4, le format à virgule flottante de 4 bits utilisé par OpenAI pour publier gpt-oss. La plupart des fichiers GGUF publiés suivent le même processus de conversion :
GGUF et les autres formats de modèles#
- GGML, GGMF et GGJT : Les anciens formats de llama.cpp stockaient les hyperparamètres sous forme de liste non typée, sans champ d'architecture ; l'ajout d'un paramètre rendait donc les fichiers existants incompatibles.
- Safetensors : Format de Hugging Face pour stocker des tenseurs bruts en toute sécurité, généralement en précision simple ou demi-précision, tandis que la configuration et le tokenizer sont conservés dans des fichiers séparés.
- ONNX : Stocke un graphe de calcul complet avec les poids, afin que tout environnement d'exécution compatible avec ONNX puisse exécuter le modèle sans code propre à l'architecture.
Exécuter des modèles GGUF#
llama.cpp exécute les fichiers GGUF depuis la ligne de commande ou sous forme de llama-server, qui expose une API compatible avec OpenAI. Il peut décharger un nombre quelconque de couches vers un GPU, tandis que les autres s'exécutent sur le CPU, ce qui permet d'exécuter un modèle plus volumineux que la mémoire du GPU. Ollama et LM Studio exécutent des modèles GGUF à partir d'une bibliothèque de modèles et d'une interface de conversation, tandis que le Hugging Face Hub affiche dans le navigateur les métadonnées et les types de tenseurs de chaque fichier GGUF. L'inférence locale conserve les prompts sur l'appareil, un point important pour la confidentialité des données et les usages hors ligne de l'IA en périphérie. L'interface LLM d'Ultralytics peut appeler un modèle GGUF servi par llama-server ou Ollama via leurs points de terminaison Chat Completions compatibles avec OpenAI ; un pipeline YOLO26 peut ainsi demander à un modèle local de décrire ses détections sans envoyer de données à une API cloud. Le format dépasse aussi le cadre des modèles de langage : les nœuds personnalisés ComfyUI-GGUF chargent des modèles de diffusion quantifiés, comme FLUX.1, à partir de fichiers GGUF afin qu'ils tiennent dans la mémoire des GPU grand public.










