Formats de fichiers de modèles

Une livraison de modèle n'est pas un fichier — c'est un checkpoint reconditionné par moteur. Cette page cartographie les formats que vous croiserez réellement en local : GGUF pour le monde llama.cpp, safetensors pour la pile PyTorch/HF, quants GPU natifs des moteurs, et ONNX pour les runtimes embarqués. Choisissez d'abord le moteur ; le format suit.

GGUF : un fichier, tout dedans

Un fichier .gguf emballe les poids du modèle, le vocabulaire du tokenizer, le gabarit de conversation et les métadonnées par tenseur dans un seul binaire. Un téléchargement, zéro configuration, et chaque appli parlant GGUF exécute le même fichier : llama.cpp et llama-server, Ollama, LM Studio, Jan, KoboldCpp. Le format est mmapable, donc les poids streament depuis le disque page par page — le démarrage est rapide et le cache de pages de l'OS fait la mise en cache gratuitement.

Anatomie du nom de fichier, champ par champ, pour Qwen3-8B-Q4_K_M.gguf :

Inspectez n'importe quel GGUF sans le charger :

python gguf-py/gguf/scripts/gguf_dump.py model.gguf

general.architecture     : qwen3
general.name             : Qwen3 8B
qwen3.context_length     : 32768
tokenizer.ggml.model     : gpt2 (BPE)
tokenizer.chat_template  : {%- ... un template Jinja ... %}

Ce bloc de métadonnées explique pourquoi un GGUF « marche directement » à travers cinq applis différentes : le moteur lit l'architecture, construit le graphe, charge le tokenizer, et les interfaces de chat appliquent le gabarit embarqué. Pas de chasse à la config, pas de décalage de vocabulaire, pas de téléchargement de tokenizer séparé.

Safetensors : le natif de Hugging Face

Safetensors est un conteneur volontairement ennuyeux : un en-tête JSON de noms de tenseurs, formes et dtypes suivi d'octets bruts. Il ne stocke que des tenseurs — aucun code exécutable, contrairement aux checkpoints .bin façon pickle, dangereux à charger aveuglément — et il supporte le mmap zéro-copie, raison pour laquelle le démarrage PyTorch est rapide. Transformers, vLLM, SGLang, TRL et tout l'écosystème de fine-tuning le parlent nativement.

Parce qu'il ne stocke que des tenseurs, un modèle fonctionnel, c'est tout le répertoire du dépôt :

model-00001-of-00004.safetensors   ← shards de poids (~5 GB chacun)
model-00002-of-00004.safetensors
model-00003-of-00004.safetensors
model-00004-of-00004.safetensors
model.safetensors.index.json        ← carte des shards : nom de tenseur → fichier shard
config.json                         ← architecture + hyperparamètres
generation_config.json              ← réglages d'échantillonnage par défaut
tokenizer.json                      ← le tokenizer lui-même
tokenizer_config.json               ← le gabarit de conversation vit ici

Le sharding existe parce qu'un checkpoint 70B FP16 fait ~140 GB — un seul fichier serait ingérable. Si vous servez avec vLLM, vous téléchargez tous les shards ; il n'y a pas de raccourci « juste le fichier 4 bits » dans une livraison safetensors. Le service quantifié est un dépôt séparé (une variante AWQ ou GPTQ du même modèle).

Quants GPU natifs des moteurs : AWQ, GPTQ, EXL2

Ces formats existent pour les serveurs d'inférence GPU, où le débit compte plus que le confort du fichier :

• AWQ — quantification sensible aux activations. Des prompts de calibration trouvent les ~1% de canaux de poids dont les activations dépendent le plus ; ils reçoivent un scaling protégé, tout le reste passe en 4 bits. Qualité quasi originale à 4 bits avec des noyaux rapides ; le choix 4 bits par défaut dans vLLM.
• GPTQ — le quant GPU classique, descendant de la quantification « optimal brain » : quantifier couche par couche, en compensant l'erreur de chaque couche contre les poids pas encore quantifiés. 4 bits, noyaux GPU uniquement, encore partout dans les configs de service.
• EXL2 — le format d'exllamav2 à bits variables par poids. Un dépôt peut se poser à, disons, 4.65 bpw en mélangeant des tenseurs 2–8 bits pour que le total atterrisse exactement sous votre plafond VRAM. L'outil pour quand Q4 ne tient pas mais Q3 ferait mal.

Les trois exigent des données de calibration et une conversion unique, et aucun ne tourne sur CPU.

ONNX, MLX, FP16/BF16 bruts

ONNX est le format portable de graphe de calcul : exportez un modèle transformers une fois, exécutez-le partout où onnxruntime tourne — machines Windows sans CUDA, téléphones, démos WebGPU en navigateur. onnxruntime peut aussi quantifier le graphe en INT8 pour CPU. Vous payez le frottement d'installation et souvent la vitesse de pointe ; vous gagnez la portabilité vers des machines sans pile PyTorch. L'embarqué et l'edge sont son terrain de prédilection, pas le chat de bureau.

MLX est le framework de tableaux d'Apple pour Apple Silicon ; l'org mlx-community reconditionne la plupart des grandes livraisons au format MLX, 4 et 8 bits compris. Sur un Mac série M exécutant mlx-lm, c'est votre format — voir Apple Silicon.

Les checkpoints FP16/BF16 bruts comptent quand vous voulez une référence sans perte, une base de fine-tuning ou une source de conversion. Le BF16 garde la plage d'exposant 8 bits du FP32 et échange des bits de mantisse contre elle — bien plus stable à l'entraînement que le FP16, aux mêmes 2 octets par poids. Un modèle 7–8B en FP16/BF16 fait ~16 GB de poids seuls, avant tout contexte.

Quel format pour quel moteur

Mélanger les formats est l'erreur classique du débutant : pointer vLLM vers un .gguf, ou llama.cpp vers des shards safetensors. Aucun des deux ne marche — le moteur sort une erreur ou exige d'abord une conversion.

Chemins de conversion

Le chemin standard d'un dépôt Hugging Face vers un fichier local tient en deux étapes — convertir le checkpoint en GGUF 16 bits, puis quantifier vers le bas :

git clone https://github.com/ggerganov/llama.cpp
pip install -r llama.cpp/requirements.txt

# 1. convertir le checkpoint HF (safetensors) en GGUF
python llama.cpp/convert_hf_to_gguf.py ./Qwen3-8B --outtype bf16 --outfile qwen3-8b-bf16.gguf

# 2. quantifier à la taille cible
llama-quantize qwen3-8b-bf16.gguf qwen3-8b-Q4_K_M.gguf Q4_K_M

En pratique, vous convertissez rarement vous-même : les quantificateurs comme bartowski et mradermacher publient chaque taille de chaque livraison notable en quelques heures. Convertissez vous-même quand vous avez un fine-tune privé, voulez un I-quant calibré imatrix, ou avez besoin d'une cible de bits non standard — détails dans quantification.

Les modèles d'embedding — la moitié récupération du RAG — se livrent dans les mêmes formats : GGUF pour l'endpoint d'embedding de llama.cpp, safetensors pour sentence-transformers. Même règle que tout ce qui précède : accordez le format au moteur que vous exécuterez réellement.

Voir aussi : quantification · familles de modèles · moteurs · RAG