GGUF

GGUF est un format de fichier unique utilisé pour stocker des modèles destinés à l'inférence avec GGML, contenant les métadonnées du modèle et les tenseurs. Il prend en charge de nombreux types de données quantifiés (voir le tableau des types de quantification), ce qui permet d'économiser une quantité importante de mémoire.

Charger des modèles GGUF

Installez kernels, sinon le chemin packé bascule sur une déquantification complète au chargement.

pip install kernels

Les poids restent compressés lorsque le noyau du Hub ggml-org/ggml-quantization est disponible. Le chargeur utilise MPS par défaut lorsque ce noyau est présent et exécute les produits matriciels directement sur les blocs compressés. Si le noyau n’est pas disponible, le modèle est déquantifié au chargement.

from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "unsloth/Qwen3.5-4B-GGUF"
filename = "Qwen3.5-4B-Q4_K_M.gguf"

model = AutoModelForCausalLM.from_pretrained(model_id, gguf_file=filename)
tokenizer = AutoTokenizer.from_pretrained(model_id, gguf_file=filename)

Le même chargement fonctionne pour Qwen3.5 MoE.

moe_model_id = "unsloth/Qwen3.5-35B-A3B-GGUF"
moe_filename = "Qwen3.5-35B-A3B-Q4_K_M.gguf"

moe_model = AutoModelForCausalLM.from_pretrained(moe_model_id, gguf_file=moe_filename)
moe_tokenizer = AutoTokenizer.from_pretrained(moe_model_id, gguf_file=moe_filename)

Le chemin « packed » prend actuellement en charge Qwen3.5 et Qwen3.5 MoE. Les chargements « packed » utilisent automatiquement float32, car c’est plus rapide sur MPS. Si vous définissez un autre dtype, le chargeur renvoie un avertissement. Les autres architectures passent par le chargeur legacy.

Attention

Sur MPS, avec les noyaux installés, ggml-attn est l'attention par défaut lors du chargement d'un fichier GGUF : il s'agit du même noyau flash-attention que celui utilisé par llama.cpp pour le décodage et le préremplissage. Si le noyau ne peut pas être récupéré, le modèle conserve son implémentation d'attention. Le passage de attn_implementation (par exemple "sdpa") a toujours la priorité.

Vous pouvez également le passer explicitement :

model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, attn_implementation="ggml-org/ggml-attn"
)

Déquantiser

La déquantisation dépaquetise chaque poids au moment du chargement et restitue un modèle dense classique. C'est la solution de repli lorsque le chemin rapide et compressé ne s'applique pas. Vous pouvez également la demander explicitement avec GgufConfig.

import torch

from transformers import AutoModelForCausalLM, GgufConfig

quantization_config = GgufConfig(dequantize=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id, gguf_file=filename, quantization_config=quantization_config, dtype=torch.bfloat16
)

Vous obtenez un modèle dense classique dans le dtype que vous avez transmis.

Les architectures autres que Qwen3.5 et Qwen3.5 MoE passent par le chargeur legacy, qui effectue toujours la déquantification.

Le chargeur legacy prend en charge Llama, Mistral, Qwen2, Qwen2Moe, Phi3, Bloom, Falcon, StableLM, GPT2, Starcoder2 et plus.

Servir

transformers serve répertorie chaque fichier .gguf d’un dépôt comme un modèle distinct. Un modèle GGUF est nommé <repo>:<file>.gguf, car un dépôt contient plusieurs quantifications et l’identifiant doit préciser laquelle charger. Les requêtes l’identifient de la même manière.

transformers serve unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q4_K_M.gguf