Qu’est-ce que GGUF ? Le format de fichier LLM derrière Ollama et llama.cpp, expliqué

GGUF (souvent développé comme « GPT-Generated Unified Format ») est un format binaire permettant de stocker des modèles de langage de grande taille : les poids, le tokenizer et toutes les métadonnées de configuration dans un seul fichier autonome. Il s’agit du format natif de llama.cpp, et c’est celui que Ollama, LM Studio, KoboldCpp, Jan et la plupart des autres applications locales pour LLM exécutent effectivement. Si vous avez déjà téléchargé un fichier se terminant par .gguf, ou récupéré un modèle avec la commande ollama run, vous utilisiez ce format.

Ce que contient réellement un fichier GGUF

Un fichier GGUF commence par les quatre octets ASCII GGUF, suivis d’un numéro de version, d’une section de métadonnées clé-valeur, puis des tenseurs eux-mêmes. Les métadonnées constituent la décision architecturale essentielle : elles stockent l’architecture du modèle, la longueur maximale du contexte, le vocabulaire du tokenizer, le modèle de dialogue (chat template) et les détails de la quantification sous forme de clés nommées, afin qu’un moteur d’exécution puisse charger n’importe quel fichier GGUF sans avoir besoin d’un fichier séparé config.json ou des fichiers de tokeniseur à ses côtés.

Trois conséquences pratiques découlent de cette conception :

• Un seul fichier constitue l’intégralité du modèle. Vous pouvez copier un fichier .gguf d’une machine à une autre, et il fonctionne immédiatement. (Les modèles très volumineux sont parfois divisés en parties numérotées, comme -00001-of-00002.gguf, mais il s’agit néanmoins d’un seul modèle logique.)
• Il est mappable en mémoire. Les environnements d’exécution peuvent utiliser mmap le fichier et charger les poids à la demande par pages, ce qui accélère le chargement et permet de démarrer des modèles plus volumineux que la mémoire RAM disponible.
• La quantification est intégrée au format. Un fichier GGUF stocke déjà les poids compressés à 2–8 bits par poids, ce qui explique pourquoi un modèle de 8 milliards de paramètres peut occuper 4,9 Go au lieu de 16 Go.

Pourquoi GGUF a remplacé GGML

Avant août 2023, llama.cpp utilisait un format appelé GGML (nommé d’après la bibliothèque de tenseurs sous-jacente). GGML fonctionnait, mais présentait un défaut structurel : sa disposition dans le fichier était rigide et non versionnée. À chaque ajout d’une nouvelle fonctionnalité par llama.cpp — nouvelles architectures, méthodes de quantification améliorées, paramètres d’échelle RoPE — le format devait être modifié, rendant ainsi incompatibles tous les fichiers de modèles existants sur tous les disques durs. En quelques mois, les utilisateurs ont dû télécharger à nouveau ou reconvertir l’intégralité de leurs collections de modèles à plusieurs reprises.

GGUF, introduit par le projet llama.cpp en août 2023, a résolu ce problème grâce à deux changements :

• La gestion des versions. Le fichier déclare explicitement sa version de format, afin que les lecteurs sachent précisément comment l’interpréter.
• Des métadonnées clé-valeur extensibles. Toute information supplémentaire (un nouveau champ d’architecture, un modèle de discussion, un hyperparamètre supplémentaire) correspond simplement à une nouvelle clé. Les anciens fichiers, dépourvus de cette clé, restent compatibles ; les nouveaux fichiers, dotés de cette clé, fonctionnent avec les environnements d’exécution mis à jour. Aucune rétro-incompatibilité n’est ainsi introduite.

llama.cpp a abandonné le support de GGML peu après son introduction, et l’écosystème l’a suivi. Aujourd’hui, GGML ne subsiste que comme nom de la bibliothèque de tenseurs sous-jacente ; si vous trouvez un fichier modèle .ggml ou .bin datant de 2023, il ne sera pas chargé par aucun outil actuel, et vous devriez plutôt télécharger une version au format GGUF.

Comment interpréter les suffixes de quantification

Chaque nom de fichier GGUF comporte un suffixe tel que Q4_K_M indiquant le degré d’agressivité de la compression appliquée aux poids. Ce suffixe suit la convention suivante :

• Le chiffre qui suit « Q » correspond approximativement au nombre de bits alloués par poids : Q4 ≈ 4 bits, Q8 ≈ 8 bits. Moins de bits signifient un fichier plus petit, mais aussi une qualité moindre.
• _K désigne les méthodes de « k-quant » plus récentes, qui allouent davantage de bits aux tenseurs les plus critiques pour la qualité des sorties. À taille égale, une quantification K surpasse la méthode ancienne.
• _S / _M / _L (petit/moyen/grand) désignent des variantes au sein d’une même famille K — _M conserve quelques tenseurs particulièrement sensibles à une précision supérieure par rapport à _S.
• _0 (comme dans Q8_0, Q4_0) indique la méthode ancienne et plus simple de quantification par blocs. Q8_0 reste largement utilisée, car à 8 bits la méthode simple est déjà quasiment sans perte ; Q4_0 est aujourd’hui obsolète — privilégiez plutôt les préfixes Q4_K_M.
• IQ (tels queIQ2_M, IQ3_XS…), qui désignent des « i-quants » construits à l’aide d’une matrice d’importance, permettant de comprimer les modèles sous la barre des 4 bits avec moins de dégradation que les alternatives.
• F16 / BF16 / F32 signifie des poids non quantifiés en 16 ou 32 bits — qualité de référence, mais avec une taille maximale.

Voici le coût pratique des options courantes, illustré à l’aide de modèles instruct Llama de classe 8B (les tailles sont approximatives et varient légèrement selon le modèle) :

Deux règles utiles : la quantification nuit davantage aux petits modèles qu’aux grands (un modèle de 70 milliards de paramètres en Q3 se comporte bien mieux qu’un modèle de 8 milliards en Q3), et en dessous de Q4, la courbe de qualité chute fortement. En cas de doute, Q4_K_M est la valeur par défaut communautaire pour une bonne raison.

Choisir une quantification adaptée à votre VRAM

La mémoire totale requise est approximativement égale à taille du fichier + cache de contexte + surcharge. Prévoyez 1 à 2 Go supplémentaires par rapport à la taille du fichier pour quelques milliers de jetons de contexte, voire davantage si vous utilisez des contextes très longs. Le modèle s’exécute le plus rapidement lorsque l’ensemble de ces éléments tient entièrement dans la VRAM du GPU ; les outils basés sur llama.cpp peuvent décharger le reste dans la mémoire système, ce qui fonctionne encore mais ralentit considérablement à mesure que davantage de couches sont déplacées.

Pour obtenir des chiffres précis sur un modèle et une longueur de contexte donnés, Calculateur de VRAM effectue automatiquement les calculs, et une analyse détaillée par modèle est disponible dans Exigences en VRAM pour chaque grand modèle de langage (LLM). Si vous choisissez du matériel plutôt qu’un niveau de quantification, commencez par les meilleurs GPU pour les LLM locaux.

GGUF contre safetensors

Ces deux formats coexistent car ils servent des environnements d’exécution différents, et non parce que l’un l’emporte sur l’autre.

La décision dépend essentiellement du logiciel que vous utilisez : les outils bureautiques et Ollama privilégient GGUF, tandis que les piles de service GPU et tout ce qui implique un affinage nécessitent safetensors. Les éditeurs de modèles publient généralement d’abord des versions safetensors, et la communauté les convertit en GGUF en quelques jours.

D’où proviennent les fichiers GGUF

Presque tous les fichiers GGUF sont hébergés sur Hugging Face. Certains laboratoires publient occasionnellement des versions officielles GGUF, mais la plupart proviennent de quantificateurs communautaires — des comptes tels que bartowski, unsloth, lmstudio-community et ggml-org — qui convertissent chaque nouvelle version dans toute la gamme des niveaux de quantification. Un dépôt nommé, par exemple, Meta-Llama-3.1-8B-Instruct-GGUF contiendra un fichier par niveau de quantification.

Vous pouvez également convertir vous-même un modèle à l’aide des outils fournis avec llama.cpp : convert_hf_to_gguf.py transforme un modèle Hugging Face en un GGUF en F16, et le binaire llama-quantize (compilé lors de la construction de llama.cpp) le compresse selon le niveau de quantification choisi, par exemple. modèle llama-quantize model-f16.gguf model-Q4_K_M.gguf Q4_K_M.

Chargement d’un fichier GGUF dans Ollama

Ollama peut télécharger directement des dépôts GGUF depuis Hugging Face ; la méthode de quantification est indiquée après le signe deux-points :

ollama run hf.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF:Q4_K_M

Pour un fichier déjà présent sur votre disque, créez un fichier texte brut nommé Modelfile contenant :

FROM ./my-model.gguf

puis enregistrez-le et exécutez-le :

ollama create my-model -f Modelfile
ollama run my-model

Les versions actuelles d’Ollama lisent automatiquement le modèle de conversation (chat template) intégré aux métadonnées GGUF ; si un modèle importé produit une sortie illisible, la solution consiste généralement à ajouter explicitement une ligne TEMPLATE dans le fichier Modelfile. Le guide complet d’Ollama traite en profondeur les fichiers Modelfile.

Chargement d’un fichier GGUF dans LM Studio

La méthode habituelle consiste à utiliser le téléchargement intégré : ouvrez l’onglet Découvrir, recherchez un modèle, et LM Studio affiche les versions GGUF quantifiées disponibles, en indiquant celles qui sont compatibles avec votre matériel. Pour importer un fichier déjà présent sur votre disque, utilisez l’interface en ligne de commande (CLI) (lms import path/to/model.gguf) ou placez-le directement dans le répertoire des modèles de LM Studio — le chemin par défaut exact varie selon la version et le système d’exploitation, mais l’onglet Mes modèles l’affiche et vous permet de le modifier. Les fichiers doivent être organisés dans une structure de sous-dossiers du type éditeur/nom-du-modèle/ pour être reconnus. Consultez le guide complet de LM Studio pour un tutoriel détaillé.

Questions fréquemment posées

GGUF fonctionne-t-il uniquement sur CPU ou exploite-t-il aussi le GPU ?

Les deux. llama.cpp a été initialement conçu comme un projet d’inférence sur CPU, mais il décharge désormais certaines couches du modèle vers le GPU (via CUDA, Metal, Vulkan ou ROCm), et peut même s’exécuter entièrement sur GPU lorsque le modèle tient entièrement dans la mémoire vidéo (VRAM). Ollama et LM Studio gèrent automatiquement la répartition entre CPU et GPU ; avec llama.cpp directement, vous contrôlez ce comportement à l’aide de l’option -ngl (nombre de couches transférées sur le GPU).

Quelle est la différence entre Q4_K_M et Q4_K_S ?

Ces deux formats sont des quantifications k-quants d’environ 4 bits ; la lettre indique la variante de taille. _M (moyenne) conserve davantage de tenseurs sensibles à la qualité à une précision supérieure par rapport à _S (petite), ce qui la rend légèrement plus volumineuse et légèrement plus performante. La différence est minime — choisissez _M sauf si les derniers centaines de mégaoctets font la différence pour que le modèle tienne dans votre VRAM.

Quelle perte de qualité réelle subit-on avec la quantification ?

Avec Q8_0 et Q6_K, la perte est quasiment nulle — des tests à l’aveugle peinent à les distinguer des versions en F16. Q4_K_M présente une légère dégradation mesurable, généralement imperceptible dans les échanges conversationnels, bien qu’elle puisse avoir un impact sur des tâches exigeantes comme la génération de code ou les calculs mathématiques. En dessous de Q4, la dégradation devient nette, et les petits modèles en souffrent davantage que les grands.

Puis-je utiliser GGUF avec transformers ou vLLM ?

Un support existe, mais il est limité et non natif : transformers peut déquantifier certains fichiers GGUF au chargement, tandis que vLLM propose un support expérimental de GGUF, dont la disponibilité dépend de l’architecture. Si vous développez sur ces frameworks, privilégiez plutôt le format safetensors ; GGUF doit être considéré comme le format standard pour les environnements d’exécution de la famille llama.cpp.

Pourquoi mon modèle est-il découpé en plusieurs fichiers .gguf ?

Les modèles très volumineux sont fragmentés en parties nommées, par exemple model-00001-of-00002.gguf, principalement pour rester sous les limites de taille imposées par les plateformes d’hébergement. Conservez tous les fragments dans le même dossier et pointez votre environnement d’exécution vers le premier fichier — llama.cpp et les outils qui s’appuient dessus chargent automatiquement les autres.

Une fois que vous connaissez la quantification adaptée à votre matériel, la question pratique suivante est de choisir quel modèle y charger — le base de données de modèles répertorie les caractéristiques techniques, les besoins en VRAM et les prix de 37 modèles actuels, tandis que les meilleurs modèles locaux pour Ollama constitue une bonne sélection pour commencer.