> 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/llama-factory.md).

# LLaMA-Factory

LLaMA-Factory est le cadre de fine-tuning open-source le plus complet, prenant en charge plus de 100 modèles de langue, y compris toutes les variantes de LLaMA, Qwen, Mistral, Phi, Falcon, ChatGLM, et plus encore. Il propose LoRA, QLoRA, fine-tuning complet, RLHF, DPO et PPO — le tout via une interface web intuitive (LLaMA Board) ou une CLI. Les serveurs GPU à la demande de CLORE.AI en font la plateforme idéale pour lancer des tâches de fine-tuning à une fraction du coût des fournisseurs cloud.

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

## Exigences serveur

| Paramètre | Minimum          | Recommandé     |
| --------- | ---------------- | -------------- |
| RAM       | 16 Go            | 32 Go+         |
| VRAM      | 8 Go (QLoRA)     | 24 Go+         |
| Disque    | 50 Go            | 200 Go+        |
| GPU       | NVIDIA RTX 2080+ | A100, RTX 4090 |

{% hint style="info" %}
**La méthode d'entraînement détermine les exigences GPU :**

* **QLoRA (4 bits)**: 8 Go de VRAM pour les modèles 7B, 16 Go pour les 13B
* **LoRA (float16)**: 16 Go de VRAM pour les modèles 7B, 40 Go pour les 13B
* **Fine-tuning complet**: \~14 Go de VRAM par paramètre 7B (+ états de l'optimiseur)
* Multi-GPU (DeepSpeed/FSDP) s'étend sur n'importe quel nombre de GPU
  {% endhint %}

## Déploiement rapide sur CLORE.AI

**Image Docker :** `hiyouga/llamafactory:latest`

**Ports :** `22/tcp`, `7860/http`

**Variables d’environnement :**

| Variable               | Exemple     | Description                                    |
| ---------------------- | ----------- | ---------------------------------------------- |
| `HF_TOKEN`             | `hf_xxx...` | Jeton HuggingFace pour les modèles protégés    |
| `WANDB_API_KEY`        | `xxx...`    | Weights & Biases pour le suivi des expériences |
| `CUDA_VISIBLE_DEVICES` | `0,1`       | GPUs à utiliser                                |

## Configuration étape par étape

### 1. Louez un serveur GPU sur CLORE.AI

Visitez [CLORE.AI Marketplace](https://clore.ai/marketplace) et sélectionnez en fonction de votre tâche :

| Tâche         | VRAM     | GPU recommandé          |
| ------------- | -------- | ----------------------- |
| QLoRA 7B      | 8 Go     | RTX 3070/2080           |
| QLoRA 13B     | 16 Go    | RTX 3090/A4000          |
| LoRA 7B       | 16 Go    | RTX 3090/A4000          |
| LoRA 13B      | 40 Go    | A6000/A100 40GB         |
| FT complet 7B | 80 Go    | A100 80GB               |
| Multi-GPU     | Variable | 2-8× n'importe quel GPU |

### 2. SSH sur votre serveur

```bash
ssh -p <PORT> root@<SERVER_IP>
```

### 3. Créer les répertoires de travail

```bash
mkdir -p /root/llamafactory/{data,models,output,saves}
```

### 4. Récupérer l'image Docker

```bash
docker pull hiyouga/llamafactory:latest
```

### 5. Lancer LLaMA-Factory

**Lancer avec l'interface Web (LLaMA Board) :**

```bash
docker run -d \
  --name llamafactory \
  --gpus all \
  -p 7860:7860 \
  -v /root/llamafactory/data:/app/LLaMA-Factory/data \
  -v /root/llamafactory/models:/root/.cache/huggingface \
  -v /root/llamafactory/output:/app/LLaMA-Factory/output \
  -v /root/llamafactory/saves:/app/LLaMA-Factory/saves \
  -e HF_TOKEN=hf_your_token_here \
  hiyouga/llamafactory:latest \
  llamafactory-cli webui
```

**Avec le suivi Weights & Biases :**

```bash
docker run -d \
  --name llamafactory \
  --gpus all \
  -p 7860:7860 \
  -v /root/llamafactory/data:/app/LLaMA-Factory/data \
  -v /root/llamafactory/models:/root/.cache/huggingface \
  -v /root/llamafactory/output:/app/LLaMA-Factory/output \
  -v /root/llamafactory/saves:/app/LLaMA-Factory/saves \
  -e HF_TOKEN=hf_your_token_here \
  -e WANDB_API_KEY=your_wandb_key \
  hiyouga/llamafactory:latest \
  llamafactory-cli webui
```

**Multi-GPU avec DeepSpeed (4 GPUs) :**

```bash
docker run -d \
  --name llamafactory \
  --gpus all \
  --shm-size 16g \
  --ipc host \
  -p 7860:7860 \
  -v /root/llamafactory/data:/app/LLaMA-Factory/data \
  -v /root/llamafactory/models:/root/.cache/huggingface \
  -v /root/llamafactory/output:/app/LLaMA-Factory/output \
  -e CUDA_VISIBLE_DEVICES=0,1,2,3 \
  hiyouga/llamafactory:latest \
  bash -c "llamafactory-cli webui"
```

### 6. Accéder à l'interface Web

Vérifiez les logs et obtenez l'URL :

```bash
docker logs -f llamafactory
```

Votre URL http\_pub CLORE.AI pour le port 7860 :

```
https://<order-id>-7860.clore.ai/
```

***

## Exemples d’utilisation

### Exemple 1 : Fine-tuning LoRA via l'interface Web (LLaMA Board)

1. Ouvrez LLaMA Board à votre URL CLORE.AI
2. Allez à l'onglet **Train** onglet
3. Configurer :
   * **Nom du modèle**: `LLaMA-3` → `Meta-Llama-3-8B-Instruct`
   * **Phase d'entraînement**: `Fine-tuning supervisé`
   * **Jeu de données**: Sélectionnez votre jeu de données (ou téléchargez un personnalisé)
   * **Méthode de fine-tuning**: `lora`
   * **Rang LoRA**: `8` (plus élevé = plus de paramètres entraînés)
   * **Taux d'apprentissage**: `1e-4`
   * **Époques**: `3`
   * **Répertoire de sortie**: `llama3-finetuned`
4. Cliquez **Démarrer** pour commencer l'entraînement
5. Surveillez les courbes de perte dans le **Loss** graphique

### Exemple 2 : Fine-tuning QLoRA via la CLI

Préparez un fichier de configuration YAML d'entraînement :

```bash
docker exec -it llamafactory bash

cat > /app/LLaMA-Factory/configs/qlora_mistral.yaml << 'EOF'
### Modèle
model_name_or_path: mistralai/Mistral-7B-Instruct-v0.3

### Méthode
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
lora_rank: 16
lora_alpha: 32
lora_dropout: 0.05

### Jeu de données
dataset: alpaca_en
template: mistral
cutoff_len: 2048
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16

### Sortie
output_dir: saves/mistral-qlora
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true

### Entraînement
per_device_train_batch_size: 2
gradient_accumulation_steps: 8
learning_rate: 0.0001
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
fp16: true

### Quantification
quantization_method: bitsandbytes
quantization_bit: 4
EOF

# Lancer l'entraînement
llamafactory-cli train /app/LLaMA-Factory/configs/qlora_mistral.yaml
```

### Exemple 3 : Téléverser un jeu de données personnalisé

Créez un jeu de données personnalisé au format Alpaca :

```bash
# Créer le fichier du jeu de données
cat > /root/llamafactory/data/my_dataset.json << 'EOF'
[
  {
    "instruction": "Vous êtes un agent du service client pour une entreprise technologique. Répondez de manière utile.",
    "input": "Mon ordinateur portable ne s'allume plus après la mise à jour. Que dois-je faire ?",
    "output": "Je comprends à quel point cela peut être frustrant. Résolvons cela étape par étape :\n\n1. **Maintenez le bouton d'alimentation pendant 10 secondes** pour forcer l'arrêt\n2. **Retirez le câble d'alimentation** et la batterie si elle est amovible, attendez 30 secondes\n3. **Reconnectez l'alimentation** et essayez de rallumer\n4. Si toujours aucune réponse, appuyez sur **F8/F11** pendant le démarrage pour accéder au mode de récupération\n\nSouhaitez-vous que je vous guide en détail pour l'une de ces étapes ?"
  },
  {
    "instruction": "Vous êtes un agent du service client pour une entreprise technologique.",
    "input": "Comment réinitialiser mon mot de passe ?",
    "output": "Réinitialiser votre mot de passe est facile ! Voici comment :\n\n1. Allez sur la page de connexion et cliquez sur **'Mot de passe oublié'**\n2. Saisissez votre **adresse e-mail enregistrée**\n3. Vérifiez votre e-mail pour un lien de réinitialisation (vérifiez aussi les spams)\n4. Cliquez sur le lien et **créez un nouveau mot de passe**\n\nLe lien de réinitialisation expire au bout de 24 heures. Si vous ne recevez pas l'e-mail sous 5 minutes, contactez notre équipe de support."
  }
]
EOF

# Enregistrer le jeu de données dans dataset_info.json
docker exec -it llamafactory bash -c "
cat >> /app/LLaMA-Factory/data/dataset_info.json << 'EOF2'
,
\"my_dataset\": {
  \"file_name\": \"/root/llamafactory/data/my_dataset.json\"
}
EOF2
"
```

Puis sélectionnez `my_dataset` dans le menu déroulant Dataset de LLaMA Board.

### Exemple 4 : DPO (Direct Preference Optimization)

```yaml
### configs/dpo_llama.yaml

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct

### Méthode - DPO
stage: dpo
do_train: true
finetuning_type: lora
lora_rank: 8

### Spécifique à DPO
pref_beta: 0.1
pref_loss: sigmoid  # sigmoid, hinge, ipo

### Jeu de données (doit être au format préférence)
dataset: dpo_en_demo
template: llama3
cutoff_len: 2048

### Sortie
output_dir: saves/llama3-dpo
logging_steps: 10
save_steps: 100

### Entraînement
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 5e-5
num_train_epochs: 1.0
fp16: true
```

```bash
docker exec -it llamafactory bash -c "llamafactory-cli train /configs/dpo_llama.yaml"
```

### Exemple 5 : Inférence avec un modèle fine-tuné

Après l'entraînement, testez votre modèle :

```bash
docker exec -it llamafactory bash

# Chat interactif
llamafactory-cli chat \
  --model_name_or_path mistralai/Mistral-7B-Instruct-v0.3 \
  --adapter_name_or_path /app/LLaMA-Factory/saves/mistral-qlora \
  --template mistral \
  --finetuning_type lora
```

Ou exportez le modèle fusionné :

```bash
llamafactory-cli export \
  --model_name_or_path mistralai/Mistral-7B-Instruct-v0.3 \
  --adapter_name_or_path /app/LLaMA-Factory/saves/mistral-qlora \
  --template mistral \
  --finetuning_type lora \
  --export_dir /app/LLaMA-Factory/output/mistral-merged \
  --export_size 4 \
  --export_legacy_format false
```

***

## Configuration

### Paramètres clés d'entraînement

| Paramètre                     | Valeur typique | Description                             |
| ----------------------------- | -------------- | --------------------------------------- |
| `lora_rank`                   | 8–64           | Rang LoRA (plus élevé = plus expressif) |
| `lora_alpha`                  | 2× rang        | Mise à l'échelle alpha LoRA             |
| `lora_dropout`                | 0.0–0.1        | Dropout pour les couches LoRA           |
| `lora_target`                 | `all`          | Quelles couches appliquer LoRA          |
| `learning_rate`               | `1e-4`         | Taux d'apprentissage de départ          |
| `num_train_epochs`            | 1–5            | Époques d'entraînement                  |
| `per_device_train_batch_size` | 1–4            | Taille de batch par GPU                 |
| `gradient_accumulation_steps` | 4–16           | Multiplicateur effectif de batch        |
| `cutoff_len`                  | 1024–4096      | Longueur maximale de séquence           |
| `quantization_bit`            | 4 ou 8         | Bits de quantification QLoRA            |
| `warmup_ratio`                | 0.05–0.1       | Fraction d'échauffement du LR           |
| `lr_scheduler_type`           | `cosine`       | Planning du LR                          |

### Méthodes de fine-tuning prises en charge

| Méthode              | Utilisation de la mémoire | Qualité    | Quand l'utiliser          |
| -------------------- | ------------------------- | ---------- | ------------------------- |
| `full`               | Très élevé                | Meilleur   | VRAM illimitée            |
| `freeze`             | Moyen                     | Bonne      | Geler les couches de base |
| `lora`               | Faible                    | Très bonne | Choix par défaut          |
| `qlora` (lora+quant) | Le plus bas               | Bonne      | VRAM limitée              |

### Entraînement Multi-GPU DeepSpeed

Pour l'entraînement sur plusieurs GPU, lancez avec `torchrun`:

```bash
docker exec -it llamafactory bash -c "
FORCE_TORCHRUN=1 NNODES=1 RANK=0 MASTER_ADDR=127.0.0.1 MASTER_PORT=29500 \
llamafactory-cli train configs/qlora_mistral.yaml \
  --deepspeed examples/deepspeed/ds_z3_config.json
"
```

***

## Conseils de performance

### 1. Paramètres QLoRA optimaux par GPU

**8 Go VRAM (RTX 3070) :**

```yaml
quantization_bit: 4
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
cutoff_len: 1024
```

**24 Go VRAM (RTX 3090/4090) :**

```yaml
quantization_bit: 4  # Utiliser toujours QLoRA pour une taille de batch plus grande
per_device_train_batch_size: 4
gradient_accumulation_steps: 4
cutoff_len: 2048
```

**80 Go VRAM (A100) :**

```yaml
# Aucune quantification nécessaire — utiliser LoRA directement
finetuning_type: lora
per_device_train_batch_size: 8
gradient_accumulation_steps: 2
cutoff_len: 4096
fp16: true
```

### 2. Flash Attention 2 pour des contextes plus longs

```yaml
flash_attn: fa2  # Nécessite un GPU Ampere+
```

Cela permet d'entraîner avec des séquences 2× plus longues sur la même VRAM.

### 3. Gradient Checkpointing

Économise de la VRAM au prix d'un entraînement \~20% plus lent :

```yaml
gradient_checkpointing: true
```

### 4. Choisir la bonne cible LoRA

```yaml
lora_target: all  # Toutes les couches linéaires (par défaut, meilleure qualité)
# ou
lora_target: q_proj,v_proj  # Minimal, le plus rapide, moins de qualité
```

### 5. Geler les couches supérieures pour une adaptation rapide

```yaml
finetuning_type: freeze
freeze_trainable_layers: 2   # Entraîner seulement les 2 couches supérieures
freeze_trainable_modules: all
```

Beaucoup plus rapide que LoRA complet pour l'adaptation à des tâches simples.

### 6. Surveiller avec TensorBoard

```bash
# Dans un terminal séparé
docker exec -it llamafactory bash -c "
tensorboard --logdir /app/LLaMA-Factory/saves --host 0.0.0.0 --port 6006
"
```

Ajoutez le port 6006 à votre commande CLORE.AI pour accéder à TensorBoard.

***

## Dépannage

### Problème : "CUDA out of memory" pendant l'entraînement

1. Réduire la taille du batch : `per_device_train_batch_size: 1`
2. Activer le gradient checkpointing : `gradient_checkpointing: true`
3. Réduire la longueur de contexte : `cutoff_len: 512`
4. Utiliser QLoRA (4 bits) : `quantization_bit: 4`
5. Réduire le rang LoRA : `lora_rank: 4`

### Problème : La perte d'entraînement ne diminue pas

* Vérifiez le taux d'apprentissage — essayez `5e-5` ou `2e-4`
* Vérifiez que le format du jeu de données correspond au template
* Augmenter `lora_rank` (8→16→32)
* Vérifiez que `lora_target: all` est défini

### Problème : Vitesse d'entraînement lente

```bash
# Vérifiez l'utilisation du GPU à l'intérieur du conteneur
docker exec -it llamafactory bash -c "watch -n 1 nvidia-smi"
```

Si le GPU est utilisé à < 80% :

* Augmentez la taille du batch
* Utilisez Flash Attention : `flash_attn: fa2`
* Supprimez `gradient_checkpointing` si la VRAM le permet

### Problème : Modèle introuvable dans l'interface Web

```bash
# Pré-téléchargez dans le volume cache
docker exec -it llamafactory bash -c "
huggingface-cli download mistralai/Mistral-7B-Instruct-v0.3
"
```

Puis actualisez la liste des modèles dans LLaMA Board.

### Problème : Erreurs de format du jeu de données

Tous les formats de jeu de données doivent correspondre `dataset_info.json` spécification :

```bash
# Valider le jeu de données
docker exec -it llamafactory python3 -c "
import json
with open('/app/LLaMA-Factory/data/my_dataset.json') as f:
    data = json.load(f)
print(f'Dataset has {len(data)} samples')
print('First sample keys:', list(data[0].keys()))
"
```

### Problème : Port WebUI inaccessible

Assurez-vous que LLaMA-Factory a démarré le serveur Gradio :

```bash
docker logs llamafactory 2>&1 | grep -E "Running on|Error|Traceback"
```

Ajouter `--share` option pour une URL Gradio publique en alternative.

***

## Liens

* [GitHub](https://github.com/hiyouga/LLaMA-Factory)
* [Documentation](https://llamafactory.readthedocs.io)
* [Docker Hub (hiyouga)](https://hub.docker.com/r/hiyouga/llamafactory)
* [Modèles pris en charge](https://github.com/hiyouga/LLaMA-Factory?tab=readme-ov-file#supported-models)
* [Format du jeu de données](https://github.com/hiyouga/LLaMA-Factory/blob/main/data/README.md)
* [CLORE.AI Marketplace](https://clore.ai/marketplace)

***

## Recommandations GPU Clore.ai

| Cas d’utilisation      | GPU recommandé  | Coût estimé sur Clore.ai |
| ---------------------- | --------------- | ------------------------ |
| Développement/Test     | RTX 3090 (24GB) | \~$0.12/gpu/hr           |
| Fine-tuning (7B–13B)   | RTX 4090 (24GB) | \~$0.70/gpu/hr           |
| Grands modèles (70B+)  | A100 80GB       | \~$1.20/gpu/hr           |
| Entraînement Multi-GPU | 2-4x A100 80GB  | \~2,40–4,80 $/heure      |

> 💡 Tous les exemples de ce guide peuvent être déployés sur [Clore.ai](https://clore.ai/marketplace) serveurs GPU. Parcourez les GPU disponibles et louez à l’heure — sans engagement, avec accès root complet.


---

# 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/llama-factory.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.