GGUF : le format qui fait tenir les modèles sur votre matériel

Vous avez téléchargé un fichier avec l'extension .gguf — probablement depuis Hugging Face — et vous l'avez glissé dans Ollama, LM Studio ou llama.cpp. Ça marche. Mais que contient vraiment ce fichier ? Pourquoi un seul fichier de quelques Go renferme un modèle qui, à l'origine, occupait des centaines de Go ? Dans cet article, on ouvre la boîte : vous comprenez ce que contient un fichier .gguf, pourquoi c'est un format conçu pour l'inférence locale, comment lire un nom de fichier et comment choisir la bonne taille pour votre mémoire.

Si vous voulez comprendre le "pourquoi" numérique de la compression — ce que fait la quantification et où elle perd de la qualité —, reportez-vous à l'article sur la Quantification. Ici, on parle du contenant, pas des mathématiques.

Ce qu'il y a dans un fichier .gguf

GGUF signifie « GGML Unified Format ». C'est le format de fichier standard dans lequel les modèles pour l'inférence locale sont distribués aujourd'hui : un unique fichier binaire qui rassemble tout ce qu'il faut pour charger et exécuter le modèle. Le nom vient du moteur GGML, sur lequel se basent llama.cpp et la plupart des outils d'inférence locale.

GGUF est le successeur de trois formats antérieurs (GGML sans version, GGMF et GGJT). Le choix est guidé par un objectif précis : être non ambigu, c'est-à-dire contenir toutes les informations nécessaires pour charger le modèle, et extensible, c'est-à-dire pouvoir y ajouter de nouvelles informations à l'avenir sans casser les fichiers existants.

Le fichier est organisé en trois blocs, les uns après les autres :

1. L'en-tête (header). Il commence par une signature de 4 octets qui contient l'inscription GGUF (les octets 0x47 0x47 0x55 0x46, lus comme un entier en little-endian donnent 0x46554747). C'est le « coup de tête » qui dit au programme : « oui, c'est un fichier GGUF ». Suivent la version du format (aujourd'hui 3, qui a aussi introduit le support big-endian), le nombre de tenseurs du fichier et le nombre de paires clé-valeur de métadonnées.
2. Les métadonnées et l'index des tenseurs. Les métadonnées sont des paires clé-valeur typées : nom du modèle, architecture, longueur de contexte, taille des têtes d'attention, tokenizer et bien plus. Juste après vient la liste des tenseurs : pour chacun, nom, dimensions, type de données et offset (où commence ses données brutes).
3. Les données brutes des tenseurs. Le corps réel du fichier : tous les poids, déjà dans leur représentation finale (flottant ou quantifiée), disposés de façon à pouvoir être chargés par un simple accès mémoire.

Un détail qui compte en pratique : le fichier utilise un alignement global (32 octets par défaut) et chaque tenseur commence à un offset multiple de cet alignement. Ce n'est pas un caprice : c'est exactement ce qu'il faut au système d'exploitation pour charger le fichier efficacement, comme vous le verrez ci-dessous.

Pourquoi un seul fichier compte

Trois propriétés font de GGUF le bon format pour l'usage local :

• Tout dans un fichier. Pas besoin d'un fichier de configuration à part, d'un tokenizer séparé ou d'un dossier de poids. Ouvrez le .gguf et vous avez le modèle complet, prêt. Pour le distribuer, une copie suffit ; pour le charger, un chemin suffit.
• Compatible mmap. mmap (« memory map ») est le mécanisme par lequel le système d'exploitation associe un fichier à la mémoire du programme sans le charger tout entier d'un coup. Grâce à l'alignement des tenseurs, llama.cpp peut charger un modèle de plusieurs dizaines de Go simplement en le « mappant » : le chargement est quasi instantané et la mémoire n'est utilisée que pour les parties réellement nécessaires. C'est l'une des raisons pour lesquelles un modèle quantifié démarre en quelques secondes, même sur un disque lent.
• Extensible. Les nouvelles versions de GGUF peuvent ajouter des métadonnées ou des types de tenseurs sans invalider les fichiers anciens. Un fichier .gguf que vous téléchargez aujourd'hui restera lisible par les outils de demain.

Les tenseurs et les types de quantification

Chaque tenseur a un type, qui indique comment ses poids sont représentés en mémoire. Il y a les types « classiques » en point flottant (F16, BF16) et une famille de types quantifiés : Q8_0, Q4_K_M, Q5_K_M, Q6_K et ainsi de suite, jusqu'à des formats très récents sur 4 bits comme MXFP4. Le type est un nombre ; le format l'indique pour chaque tenseur, afin que le lecteur sache exactement comment le décoder.

Combien pèse vraiment chaque type ? Le tableau ci-dessous est la mesure officielle de llama.cpp pour un modèle d'environ 8 milliards de paramètres (Llama 3.1 8B). Lignes = type, colonnes = bits par poids et taille en Gio :

Type	Bits/poids	Taille (Gio)
Q4_K_M	4.89	4.58
Q5_K_M	5.70	5.33
Q6_K	6.56	6.14
Q8_0	8.50	7.95
F16	16.00	14.96

Lisez ainsi : un modèle 8B à pleine précision (F16) occupe environ 15 Gio ; dans le même fichier, au même modèle quantifié en Q4_K_M, il occupe 4.58 Gio. C'est le même réseau de poids, emballé dans moins de bits. Les nombres exacts pour les modèles de 70B et 405B sont utiles quand vous passez à de plus grandes tailles : pour Llama 3.1, le fichier original passe de 280.9 Gio à 43.1 Gio en Q4_K_M, et de 1625.1 Gio à 249.1 Gio pour le modèle de 405B.

Comment lire le nom d'un fichier .gguf

Les fichiers .gguf suivent une convention de nommage pensée pour être lue d'un coup d'œil, composée de morceaux séparés par des tirets. L'ordre typique est : NomModèle-Taille-Finetune-Version-Quantification[-Type][-Fragment]. Un exemple réel :

Llama-3.1-8B-Instruct-v2.0-Q4_K_M.gguf

• Llama-3.1 — le modèle de base
• 8B — la classe de paramètres (8 milliards)
• Instruct — le fine-tune (modèle instruit pour suivre les instructions)
• v2.0 — la version
• Q4_K_M — l'encoding, c'est-à-dire le niveau de quantification

Quand un modèle est trop grand pour un seul fichier, il est divisé en fragments (shards) avec la notation -00001-of-00005 : le premier sur cinq, le deuxième sur cinq, et ainsi de suite. Dans ce cas, les fichiers vont tous dans le même dossier et l'outil les charge ensemble.

Comment choisir la taille pour votre mémoire

La règle pratique qui relie ce format à votre matériel : la taille du fichier en Gio, plus une marge pour le cache de contexte et pour le système d'exploitation, doit tenir dans la mémoire dont vous disposez. Pour une GPU, « dont vous disposez » signifie la VRAM ; pour une CPU, la RAM.

Partez du modèle qui vous intéresse et du type qui vous sert (en général Q4_K_M est le point de départ raisonnable). Puis faites deux calculs :

• 8B en Q4_K_M ≈ 4.58 Gio de fichier. Avec un contexte moyen, il entre confortablement dans une GPU de 8 Gio.
• 70B en Q4_K_M ≈ 43.1 Gio de fichier. Il faut beaucoup plus de mémoire, ou un mix CPU+GPU qui répartit les tenseurs.
• 405B en Q4_K_M ≈ 249.1 Gio de fichier. Territoire workstation, pas grand public.

La bonne nouvelle : parce que le format enregistre chaque tenseur par nom et par type, les outils d'inférence peuvent éparpiller les tenseurs entre GPU et CPU — les couches qui tiennent en VRAM dans la GPU, les autres en RAM — et le fichier reste unique. C'est la raison pour laquelle un modèle plus grand que votre VRAM peut tout de même tourner, juste un peu plus lentement.

Comment arriver à un .gguf

Deux voies, toutes deux courantes. La première est la plus pratique : vous téléchargez le fichier déjà prêt depuis un dépôt sur Hugging Face (beaucoup d'organisations publient la famille de quantifications de leur modèle, et l'espace officiel ggml-org permet même de construire votre propre quant sur mesure). La deuxième, pour ceux qui veulent le faire eux-mêmes, est en deux phases : on convertit le modèle original au format GGUF en haute précision (avec convert_hf_to_gguf.py), puis on applique la quantification avec llama-quantize, en choisissant le type de sortie. Dans les deux cas, le résultat est ce même fichier .gguf que vous glissez dans votre outil.

En résumé

• Un fichier .gguf est tout dans un fichier : poids, métadonnées et tokenizer, prêts pour l'inférence locale.
• L'en-tête porte la signature GGUF, la version, le nombre de tenseurs et de métadonnées ; les tenseurs sont alignés pour un chargement rapide via mmap.
• Chaque tenseur a un type (F16, Q8_0, Q4_K_M, …) qui détermine la taille du fichier : pour un modèle 8B, de 14.96 Gio en F16 à 4.58 Gio en Q4_K_M.
• Le nom de fichier se lit d'un coup d'œil : modèle, taille, fine-tune, version, quantification, fragment éventuel.
• Pour choisir : taille du fichier + cache de contexte + système, dans votre VRAM ou votre RAM. Le format permet d'éparpiller les tenseurs entre GPU et CPU.

Sources et lecture approfondie : Spécifications officielles GGUF et guide de quantification de llama.cpp, qui contient les tailles exactes par type.

Article généré par IA