# Affinage 2x plus rapide avec Unsloth

Unsloth réécrit les parties critiques pour la performance de HuggingFace Transformers avec des noyaux Triton optimisés à la main, offrant **2x la vitesse d'entraînement** et **réduction de 70 % de la VRAM** sans perte d'exactitude. C'est un remplacement plug-and-play — vos scripts TRL/PEFT existants fonctionnent sans modification après avoir changé l'importation.

{% hint style="success" %}
Tous les exemples s'exécutent sur des serveurs GPU loués via le [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Principales caractéristiques

* **Entraînement 2x plus rapide** — noyaux Triton personnalisés pour l'attention, RoPE, l'entropie croisée et la normalisation RMS
* **70 % de VRAM en moins** — checkpointing de gradient intelligent et poids mappés en mémoire
* **Remplacement HuggingFace plug-and-play** — un seul changement d'importation, rien d'autre
* **QLoRA / LoRA / entraînement complet** — tous les modes pris en charge dès la sortie de la boîte
* **Export natif** — sauvegardez directement en GGUF (tous types de quantification), adaptateurs LoRA, ou fusionné en 16 bits
* **Large couverture de modèles** — Llama 3.x, Mistral, Qwen 2.5, Gemma 2, DeepSeek-R1, Phi-4, et plus
* **Gratuit et open source** (Apache 2.0)

## Exigences

| Composant | Minimum        | Recommandé     |
| --------- | -------------- | -------------- |
| GPU       | RTX 3060 12 Go | RTX 4090 24 Go |
| VRAM      | 10 Go          | 24 Go          |
| RAM       | 16 Go          | 32 Go          |
| Disque    | 40 Go          | 80 Go          |
| CUDA      | 11.8           | 12.1+          |
| Python    | 3.10           | 3.11           |

**Tarifs Clore.ai :** RTX 4090 ≈ 0,5–2 $/jour · RTX 3090 ≈ 0,3–1 $/jour · RTX 3060 ≈ 0,15–0,3 $/jour

Un modèle 7B avec QLoRA 4 bits tient dans **\~10 Go de VRAM**, rendant même une RTX 3060 viable.

## Démarrage rapide

### 1. Installer Unsloth

```bash
# Créez un venv (recommandé)
python -m venv /workspace/unsloth-env
source /workspace/unsloth-env/bin/activate

pip install --upgrade pip
pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
pip install --no-deps trl peft accelerate bitsandbytes xformers
```

### 2. Charger un modèle avec quantification 4 bits

```python
from unsloth import FastLanguageModel
import torch

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit",
    max_seq_length=2048,
    dtype=None,            # détection automatique (float16 sur Ampere, bfloat16 sur Ada)
    load_in_4bit=True,
)
```

### 3. Appliquer les adaptateurs LoRA

```python
model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                     "gate_proj", "up_proj", "down_proj"],
    lora_alpha=16,
    lora_dropout=0,
    bias="none",
    use_gradient_checkpointing="unsloth",   # réduction de 70 % de la VRAM
    random_state=42,
    use_rslora=False,
    loftq_config=None,
)
```

### 4. Préparer les données et entraîner

```python
from datasets import load_dataset
from trl import SFTTrainer
from transformers import TrainingArguments

dataset = load_dataset("yahma/alpaca-cleaned", split="train")

trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    dataset_text_field="text",
    max_seq_length=2048,
    dataset_num_proc=2,
    packing=True,
    args=TrainingArguments(
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        warmup_steps=10,
        num_train_epochs=1,
        learning_rate=2e-4,
        fp16=not torch.cuda.is_bf16_supported(),
        bf16=torch.cuda.is_bf16_supported(),
        logging_steps=10,
        optim="adamw_8bit",
        weight_decay=0.01,
        lr_scheduler_type="linear",
        seed=42,
        output_dir="/workspace/outputs",
    ),
)

stats = trainer.train()
print(f"Training loss: {stats.training_loss:.4f}")
```

## Exportation du modèle

### Sauvegarder uniquement l'adaptateur LoRA

```python
model.save_pretrained("/workspace/lora-adapter")
tokenizer.save_pretrained("/workspace/lora-adapter")
```

### Fusionner et sauvegarder le modèle complet (float16)

```python
model.save_pretrained_merged(
    "/workspace/merged-model",
    tokenizer,
    save_method="merged_16bit",
)
```

### Exporter en GGUF pour Ollama / llama.cpp

```python
# Quantifier en Q4_K_M (bon équilibre entre taille et qualité)
model.save_pretrained_gguf(
    "/workspace/gguf-output",
    tokenizer,
    quantization_method="q4_k_m",
)

# Autres options : q5_k_m, q8_0, f16
```

Après l'exportation, servez avec Ollama :

```bash
# Créer un Modelfile pour Ollama
cat > Modelfile <<EOF
FROM /workspace/gguf-output/unsloth.Q4_K_M.gguf
TEMPLATE "{{ .System }}\n{{ .Prompt }}"
PARAMETER temperature 0.7
EOF

ollama create my-finetuned -f Modelfile
ollama run my-finetuned "Résumez les points clés de l'architecture des transformers"
```

## Exemples d'utilisation

### Fine-tuning sur un jeu de données de chat personnalisé

```python
from unsloth.chat_templates import get_chat_template

tokenizer = get_chat_template(tokenizer, chat_template="llama-3.1")

def format_chat(example):
    messages = [
        {"role": "system", "content": "Vous êtes un assistant serviable."},
        {"role": "user", "content": example["instruction"]},
        {"role": "assistant", "content": example["output"]},
    ]
    return {"text": tokenizer.apply_chat_template(messages, tokenize=False)}

dataset = dataset.map(format_chat)
```

### Entraînement d'alignement DPO / ORPO

```python
from trl import DPOTrainer, DPOConfig

dpo_trainer = DPOTrainer(
    model=model,
    ref_model=None,          # Unsloth gère le modèle de référence en interne
    args=DPOConfig(
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,
        learning_rate=5e-6,
        num_train_epochs=1,
        beta=0.1,
        output_dir="/workspace/dpo-output",
    ),
    train_dataset=dpo_dataset,
    tokenizer=tokenizer,
)
dpo_trainer.train()
```

## Référence d'utilisation de la VRAM

| Modèle         | Quant   | Méthode | VRAM    | GPU         |
| -------------- | ------- | ------- | ------- | ----------- |
| Llama 3.1 8B   | 4 bits  | QLoRA   | \~10 Go | RTX 3060    |
| Llama 3.1 8B   | 16 bits | LoRA    | \~18 Go | RTX 3090    |
| Qwen 2.5 14B   | 4 bits  | QLoRA   | \~14 Go | RTX 3090    |
| Mistral 7B     | 4 bits  | QLoRA   | \~9 Go  | RTX 3060    |
| DeepSeek-R1 7B | 4 bits  | QLoRA   | \~10 Go | RTX 3060    |
| Llama 3.3 70B  | 4 bits  | QLoRA   | \~44 Go | 2× RTX 3090 |

## Conseils

* **Toujours utiliser `use_gradient_checkpointing="unsloth"`** — c'est le plus grand économiseur de VRAM unique à Unsloth
* **Définir `lora_dropout=0`** — les noyaux Triton d'Unsloth sont optimisés pour une absence de dropout et s'exécutent plus rapidement
* **Utilisez `packing=True`** dans SFTTrainer pour éviter le gaspillage dû au padding sur les exemples courts
* **Commencez avec `r=16`** pour le rang LoRA — augmentez à 32 ou 64 seulement si la perte de validation stagne
* **Surveillez avec wandb** — ajoutez `report_to="wandb"` dans TrainingArguments pour le suivi de la perte
* **Ajustement de la taille de lot** — augmentez `per_device_train_batch_size` jusqu'à approcher la limite de VRAM, puis compensez avec `gradient_accumulation_steps`

## Dépannage

| Problème                                  | Solution                                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `OutOfMemoryError` pendant l'entraînement | Réduisez la taille de lot à 1, diminuez `max_seq_length`, ou utilisez la quantification 4 bits          |
| Erreurs de compilation des noyaux Triton  | Exécutez `pip install triton --upgrade` et assurez-vous que le toolkit CUDA correspond                  |
| Première étape lente (compilation)        | Normal — Triton compile les noyaux au premier lancement, mis en cache ensuite                           |
| `bitsandbytes` Erreur de version CUDA     | Installez la version correspondante : `pip install bitsandbytes --upgrade`                              |
| Pics de perte pendant l'entraînement      | Diminuez le taux d'apprentissage à 1e-4, ajoutez des étapes de warmup                                   |
| Les exportations GGUF plantent            | Assurez-vous d'avoir suffisamment de RAM (2× la taille du modèle) et d'espace disque pour la conversion |

## Ressources

* [Unsloth GitHub](https://github.com/unslothai/unsloth)
* [Wiki Unsloth — Tous les notebooks](https://github.com/unslothai/unsloth/wiki)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)