GGUF, safetensors : comprendre les formats de modèles

#Pourquoi ces formats existent

Un LLM, une fois entraîné, n'est qu'un énorme sac de nombres : les poids (weights), c'est-à-dire les milliards de paramètres qui encodent ce que le modèle « sait ». Le format de fichier, c'est simplement la façon dont ces nombres sont rangés sur le disque. Il faut décider comment les stocker, comment les relire vite, et quelles informations annexes (le vocabulaire, l'architecture, les réglages) embarquer à côté.

Historiquement, ces poids étaient sauvegardés au format .bin de PyTorch (pickle Python), pratique mais lent à charger et surtout dangereux : un fichier pickle peut exécuter du code arbitraire à l'ouverture. Deux formats se sont imposés pour régler des problèmes différents. safetensors répond au besoin des chercheurs et des plateformes : un stockage sûr et rapide, fidèle à la précision d'origine. GGUF répond au besoin de l'inférence locale : un fichier unique, compact, quantifié, prêt à tourner sur un CPU ou un GPU grand public.

#safetensors : le format Hugging Face

safetensors est le format par défaut de l'écosystème Hugging Face. Créé pour remplacer le pickle PyTorch, son premier argument est dans son nom : la sûreté. Le fichier ne contient que des données (les tenseurs de poids) et un petit en-tête JSON décrivant leur forme et leur type. Aucun code exécutable, donc aucun risque d'ouvrir un fichier piégé. Bonus : le chargement est plus rapide grâce au memory-mapping, qui permet de lire les poids directement depuis le disque sans tout copier en RAM d'abord.

Sûr par conception

Pas de code exécutable, contrairement aux anciens .bin/.pt en pickle. On peut télécharger un safetensors sans craindre l'exécution de code.

Pleine précision

Les poids sont généralement stockés en FP16 ou BF16 (16 bits), voire FP32. C'est la précision d'entraînement, celle qui sert de référence.

Fait pour être transformé

C'est le format de départ pour le fine-tuning, la fusion de modèles (merge), la quantification ou la conversion vers d'autres formats.

Souvent découpé

Un gros modèle est réparti en plusieurs fichiers (shards) accompagnés d'un index JSON, car un seul fichier de dizaines de Go serait ingérable.

Le revers : un safetensors en FP16 est volumineux. Un modèle 7B pèse environ 14 Go (2 octets par paramètre), un 70B autour de 140 Go. Pour l'entraînement et la recherche sur GPU serveur, c'est le bon choix. Pour faire tourner un modèle sur votre machine, c'est souvent trop lourd — d'où l'intérêt de la quantification et du GGUF.

#GGUF : le format de l'inférence locale

GGUF (GPT-Generated Unified Format) est le format né du projet llama.cpp, le moteur d'inférence qui fait tourner des LLM efficacement sur CPU comme sur GPU. Il a remplacé l'ancien format GGML en 2023. Son idée maîtresse : tout mettre dans un seul fichier. Les poids, le vocabulaire du tokenizer, les métadonnées d'architecture (nombre de couches, taille de contexte), le template de chat — tout est empaqueté ensemble. Vous téléchargez un fichier, vous le lancez, ça marche.

Fichier unique et autonome

Poids + tokenizer + métadonnées dans un seul .gguf. Pas de dossier de config à assembler, pas de dépendance Python à installer.

Quantifié

Conçu pour embarquer des poids compressés (4, 5, 6, 8 bits). C'est ce qui rend les gros modèles accessibles sur du matériel grand public.

CPU + GPU + offload

llama.cpp peut répartir les couches entre GPU et RAM système. On fait tourner un modèle plus gros que sa VRAM, au prix d'un peu de vitesse.

Portable

Le même fichier .gguf fonctionne sur Windows, macOS (Metal), Linux, avec Ollama, LM Studio, Jan, ou llama.cpp directement.

La quantification est le cœur du sujet. Elle consiste à stocker chaque poids sur moins de bits (4 au lieu de 16, par exemple), ce qui divise la taille par 3 à 4 avec une perte de qualité minime si on choisit bien. C'est ce qui permet à un modèle 7B de tenir dans ~5 Go de VRAM au lieu de 14. Les niveaux courants qu'on rencontre : Q4_K_M (le meilleur compromis, recommandé par défaut), Q5_K_M (un cran au-dessus en qualité), Q8_0 (quasi sans perte, plus lourd) et FP16 (non quantifié, référence).

#Pourquoi Ollama et LM Studio veulent du GGUF

Ollama et LM Studio sont bâtis au-dessus de llama.cpp (ou d'un moteur équivalent), et llama.cpp parle nativement GGUF. Ce n'est pas un caprice : c'est ce qui rend ces outils si simples. Comme le GGUF contient déjà le tokenizer, l'architecture et le template de chat, l'outil n'a rien à deviner. Il lit le fichier, alloue la mémoire, et vous répond. Pas d'environnement Python, pas de dépendances à résoudre, pas de config à écrire.

Quand vous faites `ollama pull llama3.2`, Ollama télécharge en réalité un GGUF depuis sa registry et le range dans son magasin de modèles. Vous ne voyez jamais le fichier, mais c'est bien du GGUF sous le capot. LM Studio, lui, vous montre explicitement les fichiers GGUF disponibles et leurs quantifications au moment du téléchargement.

# Ollama récupère un GGUF depuis sa registry et le sert sur localhost:11434
ollama pull llama3.2
ollama run llama3.2

# Vérifier que le daemon répond
curl http://localhost:11434/api/tags

#Lire un nom de fichier sans se tromper

Sur Hugging Face, les noms de fichiers GGUF suivent une convention lisible une fois qu'on connaît le code. Prenez un exemple typique : `Qwen2.5-7B-Instruct-Q4_K_M.gguf`. Chaque morceau porte une information.

Qwen2.5

La famille et la version du modèle.

7B

Le nombre de paramètres : 7 milliards. C'est le premier indicateur de la VRAM nécessaire.

Instruct

La variante entraînée pour suivre des consignes et dialoguer (par opposition à -base, brut, non aligné pour le chat).

Q4_K_M

La quantification : 4 bits, variante K_M (medium). Le compromis qualité/taille recommandé par défaut.

.gguf

Le format. Vous savez qu'il tournera dans Ollama, LM Studio ou llama.cpp sans conversion.

Le suffixe de quantification est la partie la plus utile à décoder. Le chiffre indique le nombre de bits par poids ; les lettres K_S / K_M / K_L désignent des variantes (Small, Medium, Large) qui protègent plus ou moins les couches sensibles. Plus le chiffre est haut, plus le fichier est gros et fidèle.

Q4_K_M

~4 bits, medium. Le choix par défaut : la meilleure qualité pour la taille dans l'immense majorité des cas.

Q5_K_M

~5 bits. Un cran de qualité en plus, fichier un peu plus lourd. Bon si la VRAM le permet.

Q8_0

8 bits. Quasiment indiscernable du non-quantifié, mais deux fois plus lourd que Q4. Pour les puristes ou les tâches exigeantes.

Q2_K / Q3_K

2-3 bits. Très compact mais qualité dégradée, visible. À réserver aux cas où la mémoire est vraiment critique.

FP16 / F16

Non quantifié, pleine précision 16 bits. La référence, mais lourd — autant rester sur safetensors dans ce cas.

#Lequel télécharger selon son outil

La question pratique se résume à : quel outil je vais utiliser ? Le format découle de la réponse, pas l'inverse.

Ollama, LM Studio, Jan, llama.cpp

→ GGUF. Ces outils sont faits pour ça. Choisissez la quantification selon votre VRAM (Q4_K_M par défaut).

vLLM, TGI, Transformers (Python)

→ safetensors. Ces moteurs serveur chargent le format Hugging Face natif, souvent en FP16 ou avec leur propre quantification (AWQ, GPTQ).

Fine-tuning, merge, quantification maison

→ safetensors. C'est le format de travail : on part de la pleine précision pour transformer le modèle.

Vous ne savez pas encore

→ GGUF quantifié si c'est pour un usage local sur votre machine. C'est le plus simple et le plus économe.

Pour choisir la bonne quantification, alignez-vous sur votre VRAM. Repères en Q4 : un modèle 3B tient dans ~2 Go, un 7B dans ~5 Go, un 14B dans ~9 Go, un 32B dans ~19 Go, un 70B dans ~40 Go. Une RTX 3060 12 Go fait tourner confortablement du 7B à 14B en Q4 ; une RTX 4090 24 Go vise le 32B ; pour du 70B, il faut viser une carte à grande VRAM ou un Mac à mémoire unifiée (M4 Pro 24-48 Go).

#Convertir safetensors vers GGUF

Parfois, un modèle n'est publié qu'en safetensors (fréquent le jour d'une sortie) et vous voulez le faire tourner dans Ollama. Il faut alors le convertir en GGUF, puis éventuellement le quantifier. L'outil de référence est le script `convert_hf_to_gguf.py` fourni par llama.cpp. Le processus se fait en deux temps : d'abord convertir en GGUF pleine précision, ensuite quantifier avec l'outil `llama-quantize`.

1. 01
   Récupérer llama.cpp et ses dépendances

   Clonez le dépôt llama.cpp et installez les dépendances Python du script de conversion. C'est lui qui contient convert_hf_to_gguf.py.
2. 02
   Télécharger le modèle safetensors

   Récupérez le dossier complet du modèle depuis Hugging Face (poids .safetensors + config.json + fichiers du tokenizer). Tout doit être présent, pas seulement les poids.
3. 03
   Convertir en GGUF FP16

   Lancez convert_hf_to_gguf.py sur le dossier du modèle. Vous obtenez un .gguf en pleine précision (16 bits), volumineux mais fidèle.
4. 04
   Quantifier en Q4_K_M

   Passez le GGUF FP16 dans llama-quantize en choisissant le niveau voulu (Q4_K_M par défaut). Le fichier final est 3 à 4 fois plus léger.
5. 05
   Importer dans Ollama

   Écrivez un Modelfile pointant sur le .gguf quantifié et créez le modèle avec ollama create. Il est alors utilisable comme n'importe quel modèle Ollama.

# 1. Cloner llama.cpp et installer les dépendances de conversion
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
pip install -r requirements.txt

# 2. Convertir le dossier safetensors en GGUF pleine précision
python convert_hf_to_gguf.py ./mon-modele-hf --outfile mon-modele-f16.gguf --outtype f16

# 3. Quantifier en Q4_K_M (compromis recommandé)
./llama-quantize mon-modele-f16.gguf mon-modele-Q4_K_M.gguf Q4_K_M

# Créer un Modelfile minimal
printf 'FROM ./mon-modele-Q4_K_M.gguf\n' > Modelfile

# Enregistrer le modèle dans Ollama
ollama create mon-modele -f Modelfile
ollama run mon-modele

#Les autres formats qu'on croise

GGUF et safetensors couvrent l'essentiel, mais quelques autres noms apparaissent au fil des téléchargements. Les connaître évite les mauvaises surprises.

.bin / .pt (pickle)

L'ancien format PyTorch. Fonctionnel mais non sûr (peut exécuter du code). Progressivement remplacé par safetensors — à éviter si une alternative existe.

GPTQ / AWQ

Des quantifications côté GPU pour vLLM et Transformers, stockées en safetensors. Rapides sur GPU NVIDIA, mais pas lisibles par Ollama/llama.cpp.

MLX

Le format d'Apple pour son framework MLX, optimisé pour la puce Apple Silicon. Utilisé par certaines apps Mac natives, distinct du GGUF.

ONNX

Un format d'échange multi-framework, surtout côté déploiement industriel et edge. Rare pour l'usage LLM local grand public.

GGML

L'ancêtre de GGUF (même projet). Obsolète : si vous croisez du .ggml, cherchez la version .gguf équivalente.

#Questions fréquentes

GGUF ou safetensors, lequel est meilleur ?

Ni l'un ni l'autre dans l'absolu : ils servent des usages différents. GGUF pour faire tourner un modèle en local (Ollama, LM Studio), safetensors pour l'écosystème Hugging Face, le fine-tuning et les moteurs serveur. Le « meilleur » dépend de votre outil.

Un GGUF est-il moins bon qu'un safetensors ?

Un GGUF quantifié perd un peu de précision par rapport au safetensors FP16 d'origine. En Q4_K_M ou Q5_K_M, la différence est minime et rarement perceptible à l'usage. En Q2/Q3, elle devient visible.

Puis-je utiliser un safetensors directement dans Ollama ?

Pas directement pour la plupart des cas : Ollama attend du GGUF. Il faut convertir le safetensors en GGUF avec llama.cpp au préalable. Certaines versions récentes acceptent l'import de safetensors, mais le GGUF reste la voie fiable.

Pourquoi tant de fichiers sur une page Hugging Face ?

Un modèle est souvent découpé en plusieurs shards (safetensors ou GGUF), plus les fichiers de config et de tokenizer. Pour du GGUF, vous voulez généralement un seul fichier par quantification (ou tous les morceaux d'une série découpée).

#Pour aller plus loin

Maintenant que les formats n'ont plus de secret, ces guides prolongent naturellement le sujet.

Choisir sa quantification (Q4, Q5, Q8, FP16)

Le guide détaillé pour trancher entre les niveaux de quantification d'un GGUF selon votre VRAM et vos besoins de qualité.

Ollama c'est quoi et comment ça marche

Comprendre l'outil qui télécharge et sert les GGUF en local, avec les commandes de base.

Comprendre la fenêtre de contexte

L'autre paramètre qui pèse sur la mémoire : les tokens et le contexte, à combiner avec le choix de quantification.