> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-fr/entrainement/unsloth-finetune.md).

# Fine-tuning 2× 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)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-fr/entrainement/unsloth-finetune.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.