Unsloth :
pourquoi et comment

Pourquoi Unsloth s'est imposé

Si vous fine-tunez des LLM en 2026 et que vous n'utilisez pas Unsloth, vous payez 2× trop cher votre GPU. C'est la vérité simple qui explique son adoption rapide : 2× plus rapide à qualité égale, 60 % moins de mémoire. Et l'API reste compatible avec Hugging Face Transformers et TRL, donc la migration est triviale.

Mais l'efficacité d'Unsloth n'est pas magique. Elle vient de choix d'ingénierie précis. Comprendre ces choix permet de mieux utiliser l'outil et d'identifier ses limites.

D'où vient le gain

Unsloth gagne en performance par trois leviers cumulatifs : kernels Triton custom, gradient checkpointing optimisé, et compilation graph-level.

① Kernels Triton custom

Triton (de Philippe Tillet, OpenAI) est un langage Python-like qui compile vers du CUDA optimisé. Unsloth a réécrit en Triton les opérations critiques du fine-tuning : attention, RoPE, LayerNorm, RMSNorm, MLP, cross-entropy loss.

Pourquoi c'est plus rapide : les kernels par défaut de PyTorch font beaucoup d'allers-retours mémoire GPU↔HBM. Les kernels Unsloth fusionnent les opérations, réduisant les écritures intermédiaires. Pour une attention par exemple, au lieu de :

Q = linear(x)  # écrit Q en HBM
K = linear(x)  # écrit K en HBM
V = linear(x)  # écrit V en HBM
A = softmax(Q @ K.T)  # lit Q, K, écrit A
out = A @ V  # lit A, V, écrit out

Unsloth fait tout dans un seul kernel fusionné qui ne sort de la SRAM que le résultat final. Gain typique : ×2 sur l'attention seule.

② FlashAttention-2/3 intégré

FlashAttention de Tri Dao (Stanford) est la référence pour l'attention efficace. Unsloth utilise FlashAttention-3 sur Hopper (H100/H200) avec ses optimisations de tiling — division du calcul d'attention en blocs qui tiennent dans la SRAM rapide du GPU.

Gain : l'attention passe de O(N²) en mémoire à O(N), permettant des séquences beaucoup plus longues sans OOM. Une séquence de 32K tokens en BF16 sur Mistral 7B tient en 24 GB avec FlashAttention-3, contre 70+ GB en attention naïve.

③ Gradient checkpointing « unsloth »

Le gradient checkpointing classique recompute les activations en backward pass pour économiser la mémoire — au coût de calcul. La version Unsloth est plus aggressive et plus intelligente : recompute seulement les opérations baratées (LayerNorm, activations), garde celles qui coûtent cher (matmul lourdes).

Résultat : 60 % de mémoire en moins par rapport au checkpointing PyTorch standard, avec seulement 10-20 % d'overhead de recompute. Net positif sur la plupart des configurations.

④ Compilation graph-level

Unsloth utilise torch.compile (introduit avec PyTorch 2.0) pour générer un graphe compilé optimisé du training step entier. Gain supplémentaire 10-20 %, à condition d'avoir une taille de batch stable (ce qui est presque toujours le cas en fine-tuning).

Méthodes supportées

Unsloth est compatible avec toutes les méthodes de fine-tuning modernes via TRL. Voici l'état au printemps 2026 :

Modèles supportés

Unsloth supporte explicitement : Llama (toutes versions), Mistral (incl. Large 3, Codestral, Ministral), Gemma 2/3, Phi-3/4, Qwen 2/3, DeepSeek (V2/V3/R1), StarCoder, et de nombreuses dérivées. La liste s'étend avec chaque release majeure de modèle open-weight.

Pour qu'un modèle soit supporté, Unsloth doit avoir réécrit les kernels critiques pour son architecture (attention, RoPE, etc.). C'est pourquoi les modèles très exotiques mettent quelques semaines à être supportés après leur sortie.

Exemple concret — LoRA sur Mistral 7B

Voici un exemple complet de fine-tuning LoRA en SFT, sur un dataset d'instructions, avec tracking MLflow et tout l'outillage de production.

from unsloth import FastLanguageModel
from trl import SFTTrainer, SFTConfig
from datasets import load_dataset
import mlflow

# 1. Chargement du modèle quantifié 4-bit (QLoRA)
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Mistral-7B-Instruct-v0.3-bnb-4bit",
    max_seq_length=4096,
    load_in_4bit=True,
)

# 2. Configuration des adapters LoRA — ~0.5% des params trainables
model = FastLanguageModel.get_peft_model(
    model,
    r=32,                # Rang de la décomposition
    lora_alpha=64,       # Scaling factor (alpha = 2r typique)
    lora_dropout=0,      # 0 est optimal en LoRA selon les papers
    bias="none",
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                    "gate_proj", "up_proj", "down_proj"],
    use_gradient_checkpointing="unsloth",  # Le secret pour −60% mémoire
    random_state=42,
)

# 3. Chargement du dataset (format conversations OpenAI-like)
dataset = load_dataset("json", data_files="acpr_instructions.jsonl", split="train")

# 4. Training avec tracking MLflow
mlflow.set_experiment("acpr-mistral-7b-lora")

with mlflow.start_run() as run:
    mlflow.log_params({
        "base_model": "Mistral-7B-Instruct-v0.3",
        "method": "LoRA",
        "rank": 32, "alpha": 64,
        "epochs": 3, "lr": 2e-4,
    })

    trainer = SFTTrainer(
        model=model,
        tokenizer=tokenizer,
        train_dataset=dataset,
        max_seq_length=4096,
        dataset_text_field="text",
        args=SFTConfig(
            per_device_train_batch_size=4,
            gradient_accumulation_steps=4,  # batch effectif = 16
            num_train_epochs=3,
            learning_rate=2e-4,
            warmup_ratio=0.05,
            weight_decay=0.01,
            lr_scheduler_type="cosine",
            optim="adamw_8bit",
            fp16=False, bf16=True,  # BF16 sur H100, FP16 sur A100/4090
            logging_steps=10,
            output_dir="out/",
            save_strategy="epoch",
            report_to="mlflow",
        ),
    )

    trainer.train()

    # 5. Sauvegarde de l'adapter LoRA (~50-100 MB)
    model.save_pretrained("acpr-adapter-v1")
    tokenizer.save_pretrained("acpr-adapter-v1")

    # 6. Enregistrement dans MLflow Registry
    mlflow.transformers.log_model(
        model,
        artifact_path="model",
        registered_model_name="acpr-mistral-7b-lora",
    )

Sur une H100 80GB : ~25 minutes pour 3 epochs sur 5 000 exemples de 2K tokens. Mémoire pic : ~22 GB. Le même setup en TRL pur sans Unsloth : ~55 minutes, 38 GB pic — l'adapter ne tient même pas en mémoire si on est sur une A100 40GB.

Inférence du modèle fine-tuné

Une fois entraîné, deux options pour servir l'adapter.

Option A — inférence directe Unsloth (dev)

# Activation du mode inférence Unsloth (2x plus rapide)
FastLanguageModel.for_inference(model)

inputs = tokenizer(["Mon prompt..."], return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=256)
print(tokenizer.decode(outputs[0]))

Option B — vLLM avec adapter LoRA (production)

En production, on ne sert pas avec Unsloth — on sert avec vLLM qui supporte les adapters LoRA dynamiques :

# Lancement vLLM avec support multi-LoRA
vllm serve unsloth/Mistral-7B-Instruct-v0.3 \
  --enable-lora \
  --max-loras 4 \
  --max-lora-rank 32 \
  --lora-modules acpr-v1=./acpr-adapter-v1 ifrs=./ifrs-adapter-v2

# Appel API avec sélection d'adapter par requête
curl http://localhost:8000/v1/completions -H "Content-Type: application/json" -d '{
  "model": "acpr-v1",
  "prompt": "Rédige une note ACPR sur...",
  "max_tokens": 512
}'

Avantage : vous pouvez servir plusieurs adapters depuis le même modèle base. Un seul GPU peut héberger 5-10 spécialisations métier, switchées par requête. Économie GPU massive en multi-tenant.

Pour DPO — exemple synthétique

Le DPO (Direct Preference Optimization) prend des paires (prompt, chosen, rejected) et entraîne le modèle à préférer le chosen. Unsloth le supporte via le même TRL.

from unsloth import FastLanguageModel, PatchDPOTrainer
PatchDPOTrainer()  # ⚠️ requis avant l'import de DPOTrainer

from trl import DPOTrainer, DPOConfig

model, tokenizer = FastLanguageModel.from_pretrained(...)
model = FastLanguageModel.get_peft_model(model, r=32, ...)

# Dataset au format DPO : {"prompt": ..., "chosen": ..., "rejected": ...}
dpo_dataset = load_dataset("json", data_files="acpr_preferences.jsonl", split="train")

trainer = DPOTrainer(
    model=model,
    ref_model=None,  # Unsloth gère automatiquement
    tokenizer=tokenizer,
    train_dataset=dpo_dataset,
    args=DPOConfig(
        beta=0.1,  # KL divergence weight
        max_length=2048,
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        num_train_epochs=1,
        learning_rate=5e-6,  # Plus petit que SFT
        optim="adamw_8bit",
        bf16=True,
        output_dir="out_dpo/",
    ),
)
trainer.train()

Le PatchDPOTrainer() avant l'import est important : c'est ce qui active les kernels Unsloth dans le DPOTrainer de TRL. Oublier ça, c'est perdre tout le bénéfice.

Limites et pièges

Piège 1 — Le multi-GPU

Unsloth est optimisé pour single-GPU. Le multi-GPU via DDP ou FSDP fonctionne mais l'accélération est moins marquée que sur 1 GPU. Pour du fine-tuning à très grande échelle (modèles 70B+ en full fine-tune sur 8× H100), TRL natif ou DeepSpeed restent plus mûrs.

Piège 2 — Oublier PatchDPOTrainer (et équivalents)

Chaque trainer TRL (DPOTrainer, KTOTrainer, etc.) nécessite un patch Unsloth avant son import pour activer les kernels custom. Sans le patch, vous utilisez le code TRL standard, sans gain. Vérifier dans la documentation Unsloth quel patch appeler.

Piège 3 — Sequence length mal configurée

Le max_seq_length que vous passez à from_pretrained définit la mémoire alloouée pour les buffers internes. Trop bas : tronquer silencieusement vos prompts. Trop haut : OOM ou mémoire gâchée. Mesurer la longueur P95 de votre dataset et ajouter une marge.

Piège 4 — Cibler trop de modules en LoRA

Cibler les 7 modules typiques (q,k,v,o + gate,up,down) donne les meilleurs résultats. Cibler aussi embed_tokens et lm_head double la taille d'adapter sans gain de qualité notable. Sauf cas spécifique (vocabulaire étendu), s'en tenir aux 7.

Piège 5 — Calculer le learning rate par habitude

Les LR optimaux varient selon la méthode : SFT avec LoRA = 1e-4 à 5e-4, DPO = 5e-6 à 1e-5, KTO = 1e-5 à 5e-5. Utiliser le LR d'une méthode pour une autre = échec garanti.

Comparatif final

Notre conclusion pratique

Si vous fine-tunez un modèle < 70B sur 1-2 GPU : Unsloth est le default. Aucune raison de payer 2× plus en temps GPU et de plafonner à 40 % de la longueur de contexte possible. La migration depuis du TRL pur est triviale (changer 2 imports et 2 lignes).

Si vous fine-tunez du 70B+ sur 8× H100 en full fine-tune : TRL natif avec DeepSpeed ou FSDP restent encore plus matures pour le multi-node. Mais c'est un cas rare en 2026 (LoRA suffit pour 90 % des cas réels).

Chez DEEP-5, c'est notre default dans toutes nos missions de spécialisation. La différence se voit immédiatement sur la facture GPU et sur le time-to-market.