GGUF

Le format de fichier standard pour faire tourner des LLM en local : modèle, métadonnées et quantification dans un seul fichier.

7 min de lecture

#format
#llama.cpp
#inférence locale

En une phrase

GGUF est le format dans lequel circulent les modèles qu’on fait tourner chez soi : un seul fichier, qui contient les poids mais aussi tout ce qu’il faut pour s’en servir sans rien télécharger d’autre.

L’analogie

Un fichier vidéo .mkv n’est pas un film : c’est une boîte. Dedans, l’image, la bande-son, les sous-titres, les chapitres, et une étiquette qui dit au lecteur comment déplier tout ça. Le même film voyage en .mkv ou en .mp4 sans changer d’une image.

GGUF est la boîte des modèles de langage : les poids, le vocabulaire, et la façon dont le modèle attend qu’on lui parle. Tu la poses sur ton disque, ton logiciel l’ouvre, il sait quoi en faire.

Comment ça marche

D’où vient ce fichier

Georgi Gerganov publie llama.cpp en mars 2023 pour faire tourner LLaMA sur son propre ordinateur. Ses premiers formats de stockage — GGML, puis GGMF et GGJT — cassent à chaque évolution du moteur. GGUF, pour GGML Universal File, les remplace le 21 août 2023 : les fichiers de la génération précédente cessent d’être lus, un script de conversion étant fourni pour rattraper l’existant. Le format en est à sa version 3, sans nouvelle cassure depuis ; le dépôt, lui, est passé du compte personnel de son auteur à l’organisation ggml-org en février 2025.

Ce qu’un conteneur range

Un modèle publié à la façon Hugging Face, c’est un dossier : des fichiers de poids, un config.json qui décrit l’architecture, un tokenizer.json pour le découpage du texte, un autre pour les réglages de génération. Chacun peut manquer, et le programme qui les charge doit savoir d’avance à quoi s’attendre.

GGUF met tout dans un seul fichier binaire, dans un ordre fixe : quatre octets GGUF en guise de signature, le numéro de version, puis les métadonnées, puis la fiche signalétique de chaque tenseur — nom, forme, type, position — et enfin les octets des poids. Les tenseurs y étant alignés, le système d’exploitation peut projeter le fichier tel quel (memory mapping) au lieu de le recopier en RAM : le chargement d’un modèle de 40 Go est quasi instantané, et les pages jamais utilisées ne sont jamais lues.

Les métadonnées, le vrai apport

C’est là que se joue l’écart avec GGML, qui alignait des valeurs sans étiquette dans un ordre que le lecteur devait deviner. GGUF les remplace par des paires clé-valeur typées :

general.architecture — llama, qwen3, gemma3… Le moteur lit cette clé et monte le bon graphe de calcul, que les hyperparamètres voisins dimensionnent : nombre de couches, dimensions, longueur de contexte prévue à l’entraînement.
le vocabulaire du tokeniseur, jeton par jeton, tokens spéciaux compris (voir Token).
tokenizer.chat_template — le texte à trous qui dit comment emballer ta question et la réponse avec les balises qu’attend ce modèle-là. Se tromper de gabarit est le moyen le plus rapide de rendre bête un bon modèle : d’où l’intérêt qu’il voyage avec les poids.

Une clé inconnue est ignorée au lieu de faire échouer les vieux lecteurs : c’est cette tolérance qui a permis au format d’absorber trois ans d’architectures nouvelles.

Lire un nom de fichier, et choisir

Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf se découpe en quatre morceaux, dans l’ordre que recommande la spécification : le modèle, sa taille en paramètres, la variante affinée, et l’encodage — le code de quantification, seul morceau qui change d’un fichier à l’autre dans un même dépôt. La convention n’est qu’une recommandation, mais les deux morceaux qui comptent, la taille et l’encodage, y figurent presque toujours.

Vingt-quatre variantes du même modèle cohabitent ici, de moins de 3 Go à 32 Go. Choisir tient en un geste : lire la taille affichée à côté du fichier et vérifier qu’elle rentre dans ta mémoire vidéo — ou dans ta RAM — avec deux ou trois gigaoctets de marge pour le contexte. En cas de doute, Q4_K_M : 4,92 Go ici contre 32 pour le modèle non compressé.

Quand ça ne tient ni dans un fichier, ni dans la carte

Un très gros modèle arrive découpé : llama-gguf-split le tranche en morceaux numérotés -00001-of-00003.gguf, plus faciles à héberger et à télécharger. Tu ne pointes que sur le premier, le moteur trouve les suivants à côté.

L’autre découpage est matériel. Un modèle est une pile de couches identiques, et chacune peut vivre dans la mémoire de la carte graphique ou dans la RAM. L’option --n-gpu-layers de llama.cpp fixe combien on en met sur le GPU ; elle vaut auto par défaut, le moteur mesurant ce qui rentre. C’est le déchargement partiel : un modèle plus gros que ta carte tourne quand même, au prix de la vitesse — la cadence suit la partie la plus lente.

Fabriquer un GGUF

Le script convert_hf_to_gguf.py de llama.cpp prend un dossier de modèle Hugging Face et en sort un GGUF non compressé, que llama-quantize décline ensuite en variantes ; le Space gguf-my-repo enchaîne les deux dans un navigateur. Le script doit connaître l’architecture, et une architecture inédite demande un correctif : d’où les modèles qui n’arrivent en GGUF que quelques jours après leur sortie.

Dans la vraie vie

Tu lances ollama run, ou tu cliques dans LM Studio : dans les deux cas tu télécharges un GGUF. Ollama le range en blocs nommés par leur empreinte SHA-256, mais le contenu reste un GGUF ordinaire, et ollama run hf.co/<compte>/<dépôt>:Q4_K_M va le chercher sur le Hub. llamafile, chez Mozilla.ai, colle carrément le fichier et le moteur dans un seul exécutable.
Hugging Face en a fait un format de première classe : fin août 2026, son filtre library=gguf recense près de 200 000 dépôts, et un visualiseur en affiche métadonnées et tenseurs sans rien télécharger. Trois comptes reviennent chez les pourvoyeurs de variantes : bartowski, unsloth, et ggml-org pour les versions officielles.
Janvier 2025 : Unsloth publie DeepSeek-R1, 671 milliards de paramètres ramenés de 720 à 131 Go, livrés en trois fichiers DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf.
Août 2025 : llama.cpp prend en charge gpt-oss le jour de sa sortie, et son modèle de 120 milliards de paramètres tourne sur une carte de 16 Go en renvoyant une partie de ses experts au processeur.

Idées reçues

« GGUF, c’est un modèle. » Non, un emballage. Le même Llama circule en safetensors sur Hugging Face et en GGUF pour tourner chez toi : mêmes poids, boîte différente. Et rien n’oblige un GGUF à être compressé — le format accepte le 16 bits comme le 2 bits.
« GGUF et llama.cpp, c’est du processeur. » Périmé. Le projet est né en 2023 pour faire tourner LLaMA sur un simple CPU, et la réputation lui est restée collée ; son dépôt liste aujourd’hui CUDA, Metal, Vulkan, ROCm, SYCL et une dizaine d’autres cibles. Il sait répartir un modèle entre carte et processeur, ce qui n’est pas la même chose que se passer du GPU.
« Un GGUF ne contient pas de code, donc rien ne peut m’arriver. » Le fichier ne s’exécute pas, vrai gain sur le vieux format de PyTorch, bâti sur le pickle de Python, dont la simple lecture pouvait déclencher un programme. Mais l’analyseur qui le lit peut être piégé : Databricks et Cisco Talos y ont trouvé en 2024 des débordements de mémoire déclenchables avec un fichier fabriqué exprès, et le genre est réapparu depuis. Télécharge chez des comptes établis, et tiens ton moteur à jour.

Pour aller plus loin

La spécification du format GGUF — ggml (EN) : structure binaire, clés de métadonnées, convention de nommage des fichiers.
GGUF sur le Hub — Hugging Face (EN) : le visualiseur de métadonnées, la table des types de quantification, l’outil gguf-my-repo.
Auto-héberger ses IA : matériel et optimisation de l’inférence — Jérôme Flesch, LinuxFr, 2026 (FR) : choisir sa variante, décharger les couches, arbitrer entre mémoire vidéo et RAM.
Le dépôt llama.cpp — ggml-org (EN) : le moteur qui a créé le format, et la liste à jour des matériels pris en charge.
GGML GGUF File Format Vulnerabilities — Neil Archibald, Databricks, 2024 (EN) : ce qu’un fichier fabriqué exprès fait au programme qui le lit.