Llama-Factory

Prérequis

Disposer d’un environnement GPU fonctionnel avec CUDA Toolkit pour une carte NVIDIA ou ROCm pour une carte AMD, voir cette page.
Distribution Ubuntu recommandée.

Installation

# apt update && apt upgrade
# apt install -y python3 python3-venv python3-pip

Créer un environnement virtuel dédié :

# mkdir -p /opt/llamafactory
# python3 -m venv /opt/llamafactory/venv
# source /opt/llamafactory/venv/bin/activate

Mettre à jour les outils Python :

# python -m pip install --upgrade pip setuptools wheel

Télécharger LLaMA-Factory :

# cd /opt/llamafactory
# git clone --depth 1 https://github.com/hiyouga/LlamaFactory.git
# cd LlamaFactory

Installation de PyTorch

Carte AMD

Installer PyTorch avec le support ROCm (exemple avec ROCm 7.2) :

# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2

Vérifier que PyTorch détecte le GPU :

# python -c "import torch; print(torch.__version__); print(torch.version.hip); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'GPU non détecté')"

Fix pour PyTorch sous Windows WSL

Sous WSL avec ROCDXG, certaines wheels PyTorch ROCm génériques peuvent échouer lors de l'initialisation du GPU, notamment à cause de composants liés à rocprofiler qui tentent d'utiliser la topologie KFD native (/dev/kfd et /sys/class/kfd), absente sous ROCDXG. Le profiling ROCm n'est actuellement pas pris en charge sous ROCDXG. Une solution consiste à utiliser les wheels PyTorch fournies et testées par AMD pour Radeon/WSL.

Supprimer l'environnement virtuel existant :

# deactivate 2>/dev/null || true
# rm -rf /opt/llamafactory/venv

Installer uv et Python 3.12 :

# curl -LsSf https://astral.sh/uv/install.sh | sh
# source ~/.bashrc
# uv python install 3.12

Recréer l'environnement virtuel :

# uv venv --python 3.12 /opt/llamafactory/venv
# uv pip install --python /opt/llamafactory/venv/bin/python pip setuptools wheel
# source /opt/llamafactory/venv/bin/activate

Créer les répertoires temporaires et de téléchargement :

# mkdir -p /opt/pip-tmp
# mkdir -p /opt/pytorch-rocm
# cd /opt/pytorch-rocm

Télécharger les wheels AMD compatibles ROCm 7.2 :

# wget 'https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/torch-2.9.1%2Brocm7.2.0.lw.git7e1940d4-cp312-cp312-linux_x86_64.whl'
# wget 'https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/torchvision-0.24.0%2Brocm7.2.0.gitb919bd0c-cp312-cp312-linux_x86_64.whl'
# wget 'https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/torchaudio-2.9.0%2Brocm7.2.0.gite3c6ee2b-cp312-cp312-linux_x86_64.whl'
# wget 'https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/triton-3.5.1%2Brocm7.2.0.gita272dfa8-cp312-cp312-linux_x86_64.whl'

Installer les wheels PyTorch AMD :

# TMPDIR=/opt/pip-tmp uv pip install \
  --python /opt/llamafactory/venv/bin/python \
  --no-cache \
  ./torch-2.9.1+rocm7.2.0.lw.git7e1940d4-cp312-cp312-linux_x86_64.whl \
  ./torchvision-0.24.0+rocm7.2.0.gitb919bd0c-cp312-cp312-linux_x86_64.whl \
  ./torchaudio-2.9.0+rocm7.2.0.gite3c6ee2b-cp312-cp312-linux_x86_64.whl \
  ./triton-3.5.1+rocm7.2.0.gita272dfa8-cp312-cp312-linux_x86_64.whl

Sous WSL avec ROCDXG, supprimer le runtime HSA inclus dans la wheel PyTorch afin d'utiliser le runtime HSA système compatible WSL :

# location=$(pip show torch | awk -F ': ' '/Location/{print $2}')
# rm -f "$location/torch/lib/libhsa-runtime64.so"*
# ldconfig

Vérifier que la variable ROCDXG est active :

# echo $HSA_ENABLE_DXG_DETECTION

La commande doit retourner :

Vérifier que PyTorch détecte le GPU :

# python -c "import torch; print(torch.__version__); print(torch.version.hip); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'GPU non détecté')"

Exemple de résultat attendu :

2.9.1+rocm7.2.0.git7e1940d4
7.2.x
True
AMD Radeon RX 9070 XT

Carte NVIDIA

# pip install torch torchvision torchaudio \
  --index-url https://download.pytorch.org/whl/cu128

Installation de LLaMA-Factory

# cd /opt/llamafactory/LlamaFactory/
# pip install -e .
# pip install -r requirements/metrics.txt

Vérification

# llamafactory-cli version
# llamafactory-cli env

Interface Web

# llamafactory-cli webui

Explication des paramètres d'entraînement

Les principaux paramètres influençant l'apprentissage sont les suivants :

num_train_epochs : nombre de passages complets sur le dataset pendant l'entraînement.
- 1 epoch signifie que chaque exemple est vu une seule fois.
- 3 epochs signifie que chaque exemple est présenté trois fois au modèle.
- Augmenter le nombre d'epochs peut aider un petit modèle à mieux apprendre une spécialisation, mais augmente le risque de surapprentissage.
- Pour un gros modèle déjà performant, 1 epoch est souvent suffisant. Pour un petit modèle spécialisé, 2 à 3 epochs peuvent être utiles.

learning_rate : vitesse d'adaptation du modèle pendant l'apprentissage.
- Une valeur élevée apprend plus rapidement mais augmente le risque de dégrader les capacités existantes du modèle.
- Une valeur faible apprend plus lentement mais permet une adaptation plus progressive.
- Valeurs courantes :
  - 5e-5 à 1e-4 : apprentissage prudent, gros dataset ou modèle sensible.
  - 1e-4 à 2e-4 : valeur classique pour du LoRA/QLoRA SFT.
  - 2e-4 et plus : adaptation plus agressive.

gradient_accumulation_steps : nombre de mini-batches accumulés avant une mise à jour des poids.
- Permet d'obtenir un batch effectif plus grand sans augmenter la consommation VRAM.
- Exemple :
  - per_device_train_batch_size: 1
  - 2 GPU
  - gradient_accumulation_steps: 4
  - donne un batch effectif de 1 × 2 × 4 = 8.
- Augmenter cette valeur réduit la fréquence des mises à jour mais augmente la stabilité.

per_device_train_batch_size : nombre d'exemples traités simultanément par GPU.
- Plus cette valeur est élevée, plus l'entraînement est rapide.
- Elle est principalement limitée par la VRAM.
- Avec des modèles volumineux, la valeur 1 est très courante.

cutoff_len : longueur maximale des séquences d'entraînement en tokens.
- Une valeur élevée permet au modèle de voir plus de contexte.
- Elle augmente fortement la consommation mémoire.
- Exemple :
  - 4096 : bon compromis pour la plupart des tâches longues.
  - 3072 : utile sur des GPU avec moins de VRAM.
  - 2048 : configuration plus légère.

lora_rank : capacité du module LoRA ajouté au modèle.
- Un rang élevé donne plus de paramètres entraînables et plus de capacité d'adaptation.
- Valeurs courantes :
  - 8-16 : adaptation légère.
  - 32-64 : spécialisation importante.
  - 128 et plus : tâches nécessitant beaucoup de changements.
- Un rang trop élevé augmente la taille du LoRA et peut favoriser le surapprentissage.

lora_alpha : facteur d'échelle du LoRA.
- Contrôle l'importance relative des poids LoRA ajoutés.
- Une règle courante est d'utiliser une valeur environ deux fois supérieure au lora_rank.
- Exemple : lora_rank: 64 avec lora_alpha: 128.

lora_dropout : régularisation appliquée au LoRA.
- Réduit le risque de mémorisation excessive.
- Valeurs courantes :
  - 0 : dataset très grand et propre.
  - 0.05 : valeur classique.
  - 0.1 : plus forte régularisation.

gradient_checkpointing : économise de la VRAM en recalculant certaines activations pendant le backward.
- Activé :
  - moins de mémoire utilisée ;
  - entraînement plus lent.
- Désactivé :
  - plus rapide ;
  - nécessite plus de VRAM.
- Pour les petits modèles avec suffisamment de mémoire, il est souvent préférable de le désactiver.

warmup_ratio : proportion du début de l'entraînement utilisée pour augmenter progressivement le learning rate.
- Évite des mises à jour trop brutales au démarrage.
- Valeurs courantes :
  - 0.03 à 0.05.

lr_scheduler_type : méthode utilisée pour faire évoluer le learning rate pendant l'entraînement.
- cosine : diminue progressivement le learning rate selon une courbe en cloche inversée.
- Souvent utilisé pour du fine-tuning.

bf16 : utilise le format numérique bfloat16.
- Réduit la mémoire utilisée et accélère les calculs sur les GPU récents.
- À privilégier sur les cartes compatibles.

flash_attn : optimisation du calcul de l'attention.
- Réduit la consommation mémoire et peut accélérer l'entraînement.
- sdpa utilise l'implémentation optimisée fournie par PyTorch.

Exemples

hy_mt2

Avec pour exemple le dataset paradox_sft_eu5.jsonl

# source /opt/llamafactory/venv/bin/activate
# cd /opt/llamafactory/LlamaFactory
# mkdir paradox_data

On place le fichier paradox_sft_eu5.jsonl dans /opt/llamafactory/LlamaFactory/paradox_data

# vi paradox_data/dataset_info.json

{
  "paradox_eu5": {
    "file_name": "paradox_sft_eu5.jsonl",
    "formatting": "sharegpt",
    "columns": {
      "messages": "messages"
    },
     "tags": {
     "role_tag": "role",
      "content_tag": "content",
      "user_tag": "user",
      "assistant_tag": "assistant",
      "system_tag": "system"
    }
  }
}

On installe bitsandbytes si nécessaire (indispensable pour QLoRA) :

# pip install -U bitsandbytes
# python -m bitsandbytes

Ensuite on récupère les 2 fichiers officiels Tencent encore nécessaires :

# mkdir -p hy_mt2_support hy_mt2_support_tmp

# hf download tencent/Hy-MT2-7B-GGUF \
  train/llama_factory_support/train_hy_dense.py \
  train/llama_factory_support/hy_v3_patches.py \
  --local-dir hy_mt2_support_tmp

# cp hy_mt2_support_tmp/train/llama_factory_support/train_hy_dense.py hy_mt2_support/
# cp hy_mt2_support_tmp/train/llama_factory_support/hy_v3_patches.py hy_mt2_support/

# rm -rf hy_mt2_support_tmp

Le fichier hy_dense_template.py étant déjà intégré à Llama-Factory on supprime son importation dans train_hy_dense.py :

# sed -i 's/^import hy_dense_template/# import hy_dense_template  # already built into LLaMA-Factory/' \
  hy_mt2_support/train_hy_dense.py

QLoRA (hy_mt2 7B)

GPU 16go

Ensuite on peut créer un fichier de test :

# vi hy_mt2_7b_eu5_qlora_smoke.yaml

### model
model_name_or_path: tencent/Hy-MT2-7B
trust_remote_code: true

# QLoRA 4-bit for 16 GB VRAM
quantization_method: bnb
quantization_bit: 4
quantization_type: nf4
double_quantization: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 64
lora_alpha: 128
lora_dropout: 0.05
lora_target: q_proj,k_proj,v_proj,o_proj

### dataset
dataset_dir: ./paradox_data
dataset: paradox_eu5
template: hy_dense_7b
cutoff_len: 4096
overwrite_cache: false
preprocessing_num_workers: 8

### output
logging_steps: 5
plot_loss: true
report_to: none
save_only_model: false

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 2.0e-4
lr_scheduler_type: cosine_with_min_lr
lr_scheduler_kwargs:
  min_lr_rate: 0.1
warmup_ratio: 0.05
bf16: true
gradient_checkpointing: true
gradient_checkpointing_kwargs:
  use_reentrant: true
flash_attn: sdpa
ddp_timeout: 180000000

output_dir: ./saves/hy_mt2_7b/eu5_qlora_smoke
overwrite_output_dir: true
save_steps: 100
max_steps: 200

Pour lancer ce test :

# torchrun --nproc_per_node=1 hy_mt2_support/train_hy_dense.py hy_mt2_7b_eu5_qlora_smoke.yaml

Pour l'apprentissage :

# vi hy_mt2_7b_eu5_qlora_1epoch.yaml

### model
model_name_or_path: tencent/Hy-MT2-7B
trust_remote_code: true

# QLoRA 4-bit for 16 GB VRAM
quantization_method: bnb
quantization_bit: 4
quantization_type: nf4
double_quantization: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 64
lora_alpha: 128
lora_dropout: 0.05
lora_target: q_proj,k_proj,v_proj,o_proj

### dataset
dataset_dir: ./paradox_data
dataset: paradox_eu5
template: hy_dense_7b
cutoff_len: 4096
overwrite_cache: false
preprocessing_num_workers: 8

### output
logging_steps: 5
plot_loss: true
report_to: none
save_only_model: false

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 2.0e-4
lr_scheduler_type: cosine_with_min_lr
lr_scheduler_kwargs:
  min_lr_rate: 0.1
warmup_ratio: 0.05
bf16: true
gradient_checkpointing: true
gradient_checkpointing_kwargs:
  use_reentrant: true
flash_attn: sdpa
ddp_timeout: 180000000

output_dir: ./saves/hy_mt2_7b/eu5_qlora_1epoch
overwrite_output_dir: true
save_steps: 2000
num_train_epochs: 1.0

Puis lancer avec :

# torchrun --nproc_per_node=1 hy_mt2_support/train_hy_dense.py hy_mt2_7b_eu5_qlora_1epoch.yaml

Multi-GPU 2x12go

Ensuite on peut créer un fichier de test :

# vi hy_mt2_7b_eu5_qlora_smoke.yaml

### model
model_name_or_path: tencent/Hy-MT2-7B
trust_remote_code: true

# QLoRA 4-bit for 2x12 GB VRAM
quantization_method: bnb
quantization_bit: 4
quantization_type: nf4
double_quantization: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 64
lora_alpha: 128
lora_dropout: 0.05
lora_target: q_proj,k_proj,v_proj,o_proj

### dataset
dataset_dir: ./paradox_data
dataset: paradox_eu5
template: hy_dense_7b
cutoff_len: 3072
overwrite_cache: false
preprocessing_num_workers: 8

### output
logging_steps: 5
plot_loss: true
report_to: none
save_only_model: false

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 4
learning_rate: 2.0e-4
lr_scheduler_type: cosine_with_min_lr
lr_scheduler_kwargs:
  min_lr_rate: 0.1
warmup_ratio: 0.05
bf16: true
gradient_checkpointing: true
gradient_checkpointing_kwargs:
  use_reentrant: true
flash_attn: sdpa
ddp_timeout: 180000000

output_dir: ./saves/hy_mt2_7b/eu5_qlora_smoke
overwrite_output_dir: true
save_steps: 100
max_steps: 200

Avec deux RTX 3060 12 Go, cutoff_len: 4096 peut dépasser la VRAM disponible sur les exemples les plus longs. Une valeur de 3072 offre davantage de marge tout en conservant un contexte relativement important.

En multi-GPU, gradient_accumulation_steps passe de 8 à 4 afin de conserver le même batch effectif : 1 × 1 GPU × 8 = 8 et 1 × 2 GPU × 4 = 8. Chaque GPU possède sa propre copie du modèle ; deux cartes de 12 Go ne constituent donc pas un espace mémoire unique de 24 Go.

Pour lancer ce test :

# torchrun --nproc_per_node=2 hy_mt2_support/train_hy_dense.py hy_mt2_7b_eu5_qlora_smoke.yaml

Pour l'apprentissage :

# vi hy_mt2_7b_eu5_qlora_1epoch.yaml

### model
model_name_or_path: tencent/Hy-MT2-7B
trust_remote_code: true

# QLoRA 4-bit for 2x12 GB VRAM
quantization_method: bnb
quantization_bit: 4
quantization_type: nf4
double_quantization: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 64
lora_alpha: 128
lora_dropout: 0.05
lora_target: q_proj,k_proj,v_proj,o_proj

### dataset
dataset_dir: ./paradox_data
dataset: paradox_eu5
template: hy_dense_7b
cutoff_len: 3072
overwrite_cache: false
preprocessing_num_workers: 8

### output
logging_steps: 5
plot_loss: true
report_to: none
save_only_model: false

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 4
learning_rate: 2.0e-4
lr_scheduler_type: cosine_with_min_lr
lr_scheduler_kwargs:
  min_lr_rate: 0.1
warmup_ratio: 0.05
bf16: true
gradient_checkpointing: true
gradient_checkpointing_kwargs:
  use_reentrant: true
flash_attn: sdpa
ddp_timeout: 180000000

output_dir: ./saves/hy_mt2_7b/eu5_qlora_1epoch
overwrite_output_dir: true
save_steps: 2000
num_train_epochs: 1.0

Puis lancer avec :

# torchrun --nproc_per_node=2 hy_mt2_support/train_hy_dense.py hy_mt2_7b_eu5_qlora_1epoch.yaml

LoRA standard (hy_mt2 1.8B)

Multi-GPU 2x12 go

Contrairement au Hy-MT2-7B, le modèle Hy-MT2-1.8B est suffisamment léger pour utiliser un entraînement LoRA classique en BF16 sans quantification 4-bit.

On peut réutiliser le même dataset et les mêmes fichiers de support Tencent que pour le 7B.

Pour un test rapide :

# vi hy_mt2_1_8b_eu5_lora_smoke.yaml

### model
model_name_or_path: tencent/Hy-MT2-1.8B
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 64
lora_alpha: 128
lora_dropout: 0.05
lora_target: q_proj,k_proj,v_proj,o_proj

### dataset
dataset_dir: ./paradox_data
dataset: paradox_eu5
template: hy_dense_1_8b
cutoff_len: 4096
overwrite_cache: false
preprocessing_num_workers: 8

### output
logging_steps: 5
plot_loss: true
report_to: none
save_only_model: false

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 4
learning_rate: 1.0e-4
lr_scheduler_type: cosine_with_min_lr
lr_scheduler_kwargs:
  min_lr_rate: 0.1
warmup_ratio: 0.05
bf16: true
gradient_checkpointing: false
gradient_checkpointing_kwargs:
  use_reentrant: true
flash_attn: sdpa
ddp_timeout: 180000000

output_dir: ./saves/hy_mt2_1_8b/eu5_lora_smoke
overwrite_output_dir: true
save_steps: 100
max_steps: 200

Pour lancer le test sur deux GPU :

# torchrun --nproc_per_node=2 hy_mt2_support/train_hy_dense.py hy_mt2_1_8b_eu5_lora_smoke.yaml

Avec per_device_train_batch_size: 1, deux GPU et gradient_accumulation_steps: 4, le batch effectif est de 8 : 1 × 2 × 4 = 8.

Pour l'apprentissage complet (2 epochs) :

# vi hy_mt2_1_8b_eu5_lora_2epoch.yaml

### model
model_name_or_path: tencent/Hy-MT2-1.8B
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 64
lora_alpha: 128
lora_dropout: 0.05
lora_target: q_proj,k_proj,v_proj,o_proj

### dataset
dataset_dir: ./paradox_data
dataset: paradox_eu5
template: hy_dense_1_8b
cutoff_len: 4096
overwrite_cache: false
preprocessing_num_workers: 8

### output
logging_steps: 5
plot_loss: true
report_to: none
save_only_model: false

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 4
learning_rate: 1.0e-4
lr_scheduler_type: cosine_with_min_lr
lr_scheduler_kwargs:
  min_lr_rate: 0.1
warmup_ratio: 0.05
bf16: true
gradient_checkpointing: false
gradient_checkpointing_kwargs:
  use_reentrant: true
flash_attn: sdpa
ddp_timeout: 180000000

output_dir: ./saves/hy_mt2_1_8b/eu5_lora_3epoch
overwrite_output_dir: true
save_steps: 2000
num_train_epochs: 2.0

Puis lancer avec :

# torchrun --nproc_per_node=2 hy_mt2_support/train_hy_dense.py hy_mt2_1_8b_eu5_lora_2epoch.yaml