Formation TRL sur Hugging Face Jobs

Vue d'ensemble

Entraînez des modèles de langage avec TRL (Transformer Reinforcement Learning) sur l'infrastructure Hugging Face entièrement gérée. Aucune configuration GPU locale requise — les modèles s'entraînent sur des GPUs cloud et les résultats sont automatiquement sauvegardés sur le Hub Hugging Face.

TRL propose plusieurs méthodes d'entraînement :

SFT (Supervised Fine-Tuning) - Tuning d'instructions standard
DPO (Direct Preference Optimization) - Alignement à partir de données de préférences
GRPO (Group Relative Policy Optimization) - Entraînement RL en ligne
Reward Modeling - Entraîner des modèles de récompense pour RLHF

Pour la documentation détaillée des méthodes TRL :

hf_doc_search("your query", product="trl")
hf_doc_fetch("https://huggingface.co/docs/trl/sft_trainer")  # SFT
hf_doc_fetch("https://huggingface.co/docs/trl/dpo_trainer")  # DPO
# etc.

Voir aussi : references/training_methods.md pour les aperçus des méthodes et des conseils de sélection

Quand utiliser cette compétence

Utilisez cette compétence quand les utilisateurs veulent :

Affiner des modèles de langage sur des GPUs cloud sans infrastructure locale
Entraîner avec les méthodes TRL (SFT, DPO, GRPO, etc.)
Exécuter des tâches d'entraînement sur l'infrastructure Hugging Face Jobs
Convertir les modèles entraînés en GGUF pour un déploiement local (Ollama, LM Studio, llama.cpp)
S'assurer que les modèles entraînés sont sauvegardés de manière permanente sur le Hub
Utiliser des workflows modernes avec des valeurs par défaut optimisées

Quand utiliser Unsloth

Utilisez Unsloth (references/unsloth.md) à la place de TRL standard quand :

Mémoire GPU limitée - Unsloth utilise ~60% moins de VRAM
La vitesse compte - Unsloth est ~2x plus rapide
Entraînement de grands modèles (>13B) - l'efficacité mémoire est critique
Entraînement de Vision-Language Models (VLMs) - Unsloth supporte FastVisionModel

Voir references/unsloth.md pour la documentation complète d'Unsloth et scripts/unsloth_sft_example.py pour un script d'entraînement prêt pour la production.

Directives clés

Quand vous aidez à des tâches d'entraînement :

TOUJOURS utiliser l'outil MCP hf_jobs() - Soumettez les tâches avec hf_jobs("uv", {...}), PAS les commandes bash trl-jobs. Le paramètre script accepte directement du code Python. Ne sauvegardez PAS sur des fichiers locaux sauf si l'utilisateur le demande explicitement. Transmettez le contenu du script sous forme de chaîne à hf_jobs(). Si l'utilisateur demande d'« entraîner un modèle », « affiner », ou des demandes similaires, vous DEVEZ créer le script d'entraînement ET soumettre la tâche immédiatement avec hf_jobs().
Toujours inclure Trackio - Chaque script d'entraînement doit inclure Trackio pour un suivi en temps réel. Utilisez les scripts d'exemple dans scripts/ comme modèles.
Fournir les détails de la tâche après la soumission - Après la soumission, fournissez l'ID de la tâche, l'URL de suivi, le temps estimé, et notez que l'utilisateur peut demander des vérifications de statut plus tard.
Utiliser les scripts d'exemple comme modèles - Référencez scripts/train_sft_example.py, scripts/train_dpo_example.py, etc. comme point de départ.

Exécution locale de scripts

Les scripts du dépôt utilisent les dépendances inline PEP 723. Exécutez-les avec uv run :

uv run scripts/estimate_cost.py --help
uv run scripts/dataset_inspector.py --help

Liste de vérification des prérequis

Avant de commencer toute tâche d'entraînement, vérifiez :

✅ Compte et authentification

Compte Hugging Face avec plan Pro, Team ou Enterprise (Jobs nécessite un plan payant)
Connexion authentifiée : Vérifiez avec hf_whoami()
HF_TOKEN pour la sauvegarde sur le Hub ⚠️ CRITIQUE - L'environnement d'entraînement est éphémère, doit être poussé sur le Hub sinon TOUS les résultats d'entraînement sont perdus
Le token doit avoir les permissions d'écriture
DOIT passer secrets={"HF_TOKEN": "$HF_TOKEN"} dans la config de la tâche pour rendre le token disponible (la syntaxe $HF_TOKEN référence votre valeur de token réelle)

✅ Exigences du dataset

Le dataset doit exister sur le Hub ou être chargeable via datasets.load_dataset()
Le format doit correspondre à la méthode d'entraînement (SFT : "messages"/text/prompt-completion; DPO : chosen/rejected; GRPO : prompt-only)
TOUJOURS valider les datasets inconnus avant l'entraînement GPU pour éviter les échecs de format (voir la section Validation du dataset ci-dessous)
Taille appropriée au matériel (Démo : 50-100 exemples sur t4-small; Production : 1K-10K+ sur a10g-large/a100-large)

⚠️ Paramètres critiques

Le timeout doit dépasser le temps d'entraînement estimé - Par défaut 30min est TROP COURT pour la plupart des entraînements. Minimum recommandé : 1-2 heures. La tâche échoue et perd toute progression si le timeout est dépassé.
La sauvegarde sur le Hub doit être activée - Config : push_to_hub=True, hub_model_id="username/model-name"; Tâche : secrets={"HF_TOKEN": "$HF_TOKEN"}

Directives pour les tâches asynchrones

⚠️ IMPORTANT : Les tâches d'entraînement s'exécutent de manière asynchrone et peuvent prendre des heures

Action requise

Quand l'utilisateur demande un entraînement :

Créer le script d'entraînement avec Trackio inclus (utilisez scripts/train_sft_example.py comme modèle)
Soumettre immédiatement avec l'outil MCP hf_jobs() avec le contenu du script en ligne - ne sauvegardez pas en fichier sauf si l'utilisateur le demande
Rapporter la soumission avec l'ID de la tâche, l'URL de suivi et le temps estimé
Attendre l'utilisateur pour demander les vérifications de statut - ne faites pas de scrutation automatique

Règles de base

Les tâches s'exécutent en arrière-plan - La soumission retourne immédiatement; l'entraînement continue indépendamment
Logs initiaux retardés - Peut prendre 30-60 secondes pour que les logs apparaissent
L'utilisateur vérifie le statut - Attendez que l'utilisateur demande les mises à jour de statut
Éviter la scrutation - Vérifiez les logs uniquement sur demande de l'utilisateur; fournissez plutôt des liens de suivi

Après la soumission

Fournir à l'utilisateur :

✅ ID de la tâche et URL de suivi
✅ Temps de completion estimé
✅ URL du tableau de bord Trackio
✅ Note que l'utilisateur peut demander des vérifications de statut plus tard

Exemple de réponse :

✅ Tâche soumise avec succès !

ID de la tâche : abc123xyz
Suivi : https://huggingface.co/jobs/username/abc123xyz

Temps estimé : ~2 heures
Coût estimé : ~$10

La tâche s'exécute en arrière-plan. Demandez-moi de vérifier le statut/logs quand vous êtes prêt !

Démarrage rapide : Trois approches

💡 Conseil pour les démos : Pour les démos rapides sur des GPUs plus petits (t4-small), omettez eval_dataset et eval_strategy pour économiser ~40% de mémoire. Vous verrez toujours la perte d'entraînement et la progression de l'apprentissage.

Configuration de la longueur de séquence

Les classes de config TRL utilisent max_length (pas max_seq_length) pour contrôler la longueur de séquence tokenisée :

# ✅ CORRECT - Si vous devez définir la longueur de séquence
SFTConfig(max_length=512)   # Tronquer les séquences à 512 tokens
DPOConfig(max_length=2048)  # Contexte plus long (2048 tokens)

# ❌ WRONG - Ce paramètre n'existe pas
SFTConfig(max_seq_length=512)  # TypeError!

Comportement par défaut : max_length=1024 (tronque à partir de la droite). Cela fonctionne bien pour la plupart des entraînements.

Quand l'écraser :

Contexte plus long : Définir plus haut (ex. max_length=2048)
Contraintes mémoire : Définir plus bas (ex. max_length=512)
Modèles vision : Définir max_length=None (empêche de couper les tokens d'image)

Généralement vous n'avez pas besoin de définir ce paramètre du tout - les exemples ci-dessous utilisent la valeur par défaut sensée.

Approche 1 : Scripts UV (Recommandé — choix par défaut)

Les scripts UV utilisent les dépendances inline PEP 723 pour un entraînement propre et autonome. C'est l'approche principale pour Claude Code.

hf_jobs("uv", {
    "script": """
# /// script
# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio"]
# ///

from datasets import load_dataset
from peft import LoraConfig
from trl import SFTTrainer, SFTConfig
import trackio

dataset = load_dataset("trl-lib/Capybara", split="train")

# Create train/eval split for monitoring
dataset_split = dataset.train_test_split(test_size=0.1, seed=42)

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B",
    train_dataset=dataset_split["train"],
    eval_dataset=dataset_split["test"],
    peft_config=LoraConfig(r=16, lora_alpha=32),
    args=SFTConfig(
        output_dir="my-model",
        push_to_hub=True,
        hub_model_id="username/my-model",
        num_train_epochs=3,
        eval_strategy="steps",
        eval_steps=50,
        report_to="trackio",
        project="meaningful_prject_name", # project name for the training name (trackio)
        run_name="meaningful_run_name",   # descriptive name for the specific training run (trackio)
    )
)

trainer.train()
trainer.push_to_hub()
""",
    "flavor": "a10g-large",
    "timeout": "2h",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
})

Avantages : Utilisation directe de l'outil MCP, code propre, dépendances déclarées en ligne (PEP 723), aucune sauvegarde de fichier requise, contrôle complet Quand utiliser : Choix par défaut pour toutes les tâches d'entraînement dans Claude Code, logique d'entraînement personnalisée, tout scénario nécessitant hf_jobs()

Travailler avec les scripts

⚠️ Important : Le paramètre script accepte soit du code en ligne (comme montré ci-dessus) SOIT une URL. Les chemins de fichiers locaux NE FONCTIONNENT PAS.

Pourquoi les chemins locaux ne fonctionnent pas : Les tâches s'exécutent dans des conteneurs Docker isolés sans accès à votre système de fichiers local. Les scripts doivent être :

Du code en ligne (recommandé pour l'entraînement personnalisé)
Des URLs accessible publiquement
Des URLs de dépôt privé (avec HF_TOKEN)

Erreurs courantes :

# ❌ Tous ces cas échoueront
hf_jobs("uv", {"script": "train.py"})
hf_jobs("uv", {"script": "./scripts/train.py"})
hf_jobs("uv", {"script": "/path/to/train.py"})

Approches correctes :

# ✅ Code en ligne (recommandé)
hf_jobs("uv", {"script": "# /// script\n# dependencies = [...]\n# ///\n\n<your code>"})

# ✅ Du Hub Hugging Face
hf_jobs("uv", {"script": "https://huggingface.co/user/repo/resolve/main/train.py"})

# ✅ De GitHub
hf_jobs("uv", {"script": "https://raw.githubusercontent.com/user/repo/main/train.py"})

# ✅ De Gist
hf_jobs("uv", {"script": "https://gist.githubusercontent.com/user/id/raw/train.py"})

Pour utiliser des scripts locaux : Téléchargez d'abord sur le Hub HF :

hf repos create my-training-scripts --type model
hf upload my-training-scripts ./train.py train.py
# Utiliser : https://huggingface.co/USERNAME/my-training-scripts/resolve/main/train.py

Approche 2 : Scripts maintenus par TRL (exemples officiels)

TRL fournit des scripts battle-tested pour toutes les méthodes. Peuvent être exécutés à partir d'URLs :

hf_jobs("uv", {
    "script": "https://github.com/huggingface/trl/blob/main/trl/scripts/sft.py",
    "script_args": [
        "--model_name_or_path", "Qwen/Qwen2.5-0.5B",
        "--dataset_name", "trl-lib/Capybara",
        "--output_dir", "my-model",
        "--push_to_hub",
        "--hub_model_id", "username/my-model"
    ],
    "flavor": "a10g-large",
    "timeout": "2h",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}
})

Avantages : Aucun code à écrire, maintenu par l'équipe TRL, testé en production Quand utiliser : Entraînement TRL standard, expériences rapides, n'avez pas besoin de code personnalisé Disponible : Les scripts sont disponibles à https://github.com/huggingface/trl/tree/main/examples/scripts

Recherche de plus de scripts UV sur le Hub

L'organisation uv-scripts fournit des scripts UV prêts à l'emploi stockés comme datasets sur le Hub Hugging Face :

# Découvrir les collections de scripts UV disponibles
dataset_search({"author": "uv-scripts", "sort": "downloads", "limit": 20})

# Explorer une collection spécifique
hub_repo_details(["uv-scripts/classification"], repo_type="dataset", include_readme=True)

Collections populaires : ocr, classification, synthetic-data, vllm, dataset-creation

Approche 3 : CLI HF Jobs (commandes directes du terminal)

Quand l'outil MCP hf_jobs() n'est pas disponible, utilisez le CLI hf jobs directement.

⚠️ CRITIQUE : Règles de syntaxe du CLI

# ✅ Syntaxe CORRECT - les flags AVANT l'URL du script
hf jobs uv run --flavor a10g-large --timeout 2h --secrets HF_TOKEN "https://example.com/train.py"

# ❌ WRONG - "run uv" au lieu de "uv run"
hf jobs run uv "https://example.com/train.py" --flavor a10g-large

# ❌ WRONG - les flags APRÈS l'URL du script (seront ignorés!)
hf jobs uv run "https://example.com/train.py" --flavor a10g-large

# ❌ WRONG - "--secret" au lieu de "--secrets" (pluriel)
hf jobs uv run --secret HF_TOKEN "https://example.com/train.py"

Règles de syntaxe clés :

L'ordre des commandes est hf jobs uv run (PAS hf jobs run uv)
Tous les flags (--flavor, --timeout, --secrets) doivent venir AVANT l'URL du script
Utilisez --secrets (pluriel), pas --secret
L'URL du script doit être le dernier argument positionnel

Exemple CLI complet :

hf jobs uv run \
  --flavor a10g-large \
  --timeout 2h \
  --secrets HF_TOKEN \
  "https://huggingface.co/user/repo/resolve/main/train.py"

Vérifier le statut de la tâche via CLI :

hf jobs ps                        # Lister toutes les tâches
hf jobs logs <job-id>             # Afficher les logs
hf jobs inspect <job-id>          # Détails de la tâche
hf jobs cancel <job-id>           # Annuler une tâche

Approche 4 : Package TRL Jobs (entraînement simplifié)

Le package trl-jobs fournit des paramètres par défaut optimisés et un entraînement en une ligne.

uvx trl-jobs sft \
  --model_name Qwen/Qwen2.5-0.5B \
  --dataset_name trl-lib/Capybara

Avantages : Paramètres pré-configurés, intégration Trackio automatique, sauvegarde Hub automatique, commandes en une ligne Quand utiliser : Utilisateur travaillant directement dans le terminal (pas dans le contexte Claude Code), expérimentation locale rapide Dépôt : https://github.com/huggingface/trl-jobs

⚠️ Dans le contexte Claude Code, préférez utiliser l'outil MCP hf_jobs() (Approche 1) quand disponible.

Sélection du matériel

Taille du modèle	Matériel recommandé	Coût (approx/hr)	Cas d'usage
<1B params	`t4-small`	~$0.75	Démos, tests rapides seulement sans étapes d'eval
1-3B params	`t4-medium`, `l4x1`	~$1.50-2.50	Développement
3-7B params	`a10g-small`, `a10g-large`	~$3.50-5.00	Entraînement production
7-13B params	`a10g-large`, `a100-large`	~$5-10	Grands modèles (utilisez LoRA)
13B+ params	`a100-large`, `a10g-largex2`	~$10-20	Très grands (utilisez LoRA)

Saveurs GPU : cpu-basic/upgrade/performance/xl, t4-small/medium, l4x1/x4, a10g-small/large/largex2/largex4, a100-large, h100/h100x8

Directives :

Utilisez LoRA/PEFT pour les modèles >7B pour réduire la mémoire
Multi-GPU automatiquement géré par TRL/Accelerate
Commencez avec un matériel plus petit pour tester

Voir : references/hardware_guide.md pour les spécifications détaillées

Critique : Sauvegarder les résultats sur le Hub

⚠️ ENVIRONNEMENT ÉPHÉMÈRE — DOIT ÊTRE POUSSÉ SUR LE HUB

L'environnement Jobs est temporaire. Tous les fichiers sont supprimés quand la tâche se termine. Si le modèle n'est pas poussé sur le Hub, TOUT L'ENTRAÎNEMENT EST PERDU.

Configuration requise

Dans le script/config d'entraînement :

SFTConfig(
    push_to_hub=True,
    hub_model_id="username/model-name",  # DOIT être spécifié
    hub_strategy="every_save",  # Optionnel : pousser les checkpoints
)

Dans la soumission de la tâche :

{
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # Active l'authentification
}

Liste de vérification de la vérification

Avant de soumettre :

[ ] push_to_hub=True défini dans la config
[ ] hub_model_id inclut username/repo-name
[ ] Le paramètre secrets inclut HF_TOKEN
[ ] L'utilisateur a accès en écriture au dépôt cible

Voir : references/hub_saving.md pour le dépannage détaillé

Gestion du timeout

⚠️ PAR DÉFAUT : 30 MINUTES — TROP COURT POUR L'ENTRAÎNEMENT

Définir les timeouts

{
    "timeout": "2h"   # 2 heures (formats : "90m", "2h", "1.5h", ou secondes comme entier)
}

Directives de timeout

Scénario	Recommandé	Notes
Démo rapide (50-100 exemples)	10-30 min	Vérifier la configuration
Entraînement de développement	1-2 heures	Petits datasets
Production (3-7B model)	4-6 heures	Datasets complets
Grand modèle avec LoRA	3-6 heures	Dépend du dataset

Toujours ajouter un buffer de 20-30% pour le chargement du modèle/dataset, la sauvegarde des checkpoints, les opérations de sauvegarde sur le Hub, et les délais réseau.

En cas de timeout : Tâche tuée immédiatement, toute progression non sauvegardée est perdue, doit redémarrer depuis le début

Choisir un modèle de base (sélection du modèle)

Identifier les modèles à entraîner en fonction du type de tâche ou des résultats des benchmarks.

Utilisez scripts/hf_benchmarks.py pour identifier les modèles les plus performants pour des tâches spécifiques. Cela aide l'utilisateur à sélectionner un modèle comme base pour l'entraînement, tout en gardant à l'esprit les contraintes de taille et de matériel.

# Obtenir l'aide sur la commande benchmarks :
uv run scripts/hf_benchmarks.py --help

Exemple -- choisir un modèle de base OCR

# Rechercher des benchmarks dont le nom contient le texte `ocr`
uv run scripts/hf_benchmarks.py search --query ocr

# Obtenir le classement pour le benchmark allenai/olmOCR-bench
uv run scripts/hf_benchmarks.py leaderboard allenai/olmOCR-bench

Estimation des coûts

Offrez d'estimer le coût quand vous planifiez des tâches avec des paramètres connus. Utilisez scripts/estimate_cost.py :

uv run scripts/estimate_cost.py \
  --model meta-llama/Llama-2-7b-hf \
  --dataset trl-lib/Capybara \
  --hardware a10g-large \
  --dataset-size 16000 \
  --epochs 3

La sortie inclut le temps estimé, le coût, le timeout recommandé (avec buffer), et les suggestions d'optimisation.

Quand offrir : Utilisateur planifiant une tâche, demande de coût/temps, choisit un matériel, la tâche s'exécutera >1 heure ou coûtera >$5

Scripts d'entraînement d'exemple

Modèles prêts pour la production avec toutes les meilleures pratiques :

Charger ces scripts pour correctement :

scripts/train_sft_example.py - Entraînement SFT complet avec Trackio, LoRA, checkpoints
scripts/train_dpo_example.py - Entraînement DPO pour l'apprentissage de préférences
scripts/train_grpo_example.py - Entraînement GRPO pour RL en ligne

Ces scripts démontrent la sauvegarde appropriée sur le Hub, l'intégration Trackio, la gestion des checkpoints et les paramètres optimisés. Transmettez leur contenu en ligne à hf_jobs() ou utilisez-les comme modèles pour des scripts personnalisés.

Suivi et traçage

Trackio fournit la visualisation des métriques en temps réel. Voir references/trackio_guide.md pour le guide de configuration complet.

Points clés :

Ajouter trackio aux dépendances
Configurer le trainer avec report_to="trackio" and run_name="meaningful_name"

Valeurs par défaut de la configuration Trackio

Utilisez les valeurs par défaut sensées sauf si l'utilisateur spécifie autrement. Quand générer des scripts d'entraînement avec Trackio :

Configuration par défaut :

Space ID : {username}/trackio (utiliser "trackio" comme nom d'espace par défaut)
Nommage des exécutions : Sauf indication contraire, nommer l'exécution d'une manière que l'utilisateur reconnaîtra (ex. descriptif de la tâche, du modèle ou du but)
Config : Garder minimal - inclure uniquement les hyperparamètres et les infos de modèle/dataset
Nom du projet : Utiliser un nom de projet pour associer les exécutions à un projet particulier

Paramètres de l'utilisateur : Si l'utilisateur demande une configuration trackio spécifique (espace personnalisé, nommage d'exécution, groupement ou config additionnelle), appliquer ses préférences à la place des valeurs par défaut.

Cela est utile pour gérer plusieurs tâches avec la même configuration ou garder les scripts d'entraînement portables.

Voir references/trackio_guide.md pour la documentation complète incluant le groupement des exécutions pour les expériences.

Vérifier le statut de la tâche

# Lister toutes les tâches
hf_jobs("ps")

# Inspecter une tâche spécifique
hf_jobs("inspect", {"job_id": "your-job-id"})

# Afficher les logs
hf_jobs("logs", {"job_id": "your-job-id"})

Souvenez-vous : Attendez que l'utilisateur demande les vérifications de statut. Évitez de scruter à répétition.

Validation du dataset

Valider le format du dataset AVANT de lancer l'entraînement GPU pour éviter la #1 cause d'échecs d'entraînement : les incompatibilités de format.

Pourquoi valider

50%+ des échecs d'entraînement sont dus aux problèmes de format de dataset
DPO est particulièrement strict : requiert les noms de colonne exacts (prompt, chosen, rejected)
Les tâches GPU échouées gaspillent $1-10 et 30-60 minutes
La validation sur CPU coûte ~$0.01 et prend <1 minute

Quand valider

TOUJOURS valider pour :

Datasets inconnus ou personnalisés
Entraînement DPO (CRITIQUE - 90% des datasets ont besoin de mapping)
Tout dataset qui n'est pas explicitement TRL-compatible

Ignorer la validation pour les datasets TRL connus :

trl-lib/ultrachat_200k, trl-lib/Capybara, HuggingFaceH4/ultrachat_200k, etc.

Usage

hf_jobs("uv", {
    "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",
    "script_args": ["--dataset", "username/dataset-name", "--split", "train"]
})

Le script est rapide, et se complète généralement de manière synchrone.

Lire les résultats

La sortie montre la compatibilité pour chaque méthode d'entraînement :

✓ READY - Le dataset est compatible, l'utiliser directement
✗ NEEDS MAPPING - Compatible mais a besoin de prétraitement (code de mapping fourni)
✗ INCOMPATIBLE - Ne peut pas être utilisé pour cette méthode

Quand un mapping est nécessaire, la sortie inclut une section "MAPPING CODE" avec du code Python prêt à copier-coller.

Exemple de workflow

# 1. Inspecter le dataset (coûte ~$0.01, <1 min sur CPU)
hf_jobs("uv", {
    "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",
    "script_args": ["--dataset", "argilla/distilabel-math-preference-dpo", "--split", "train"]
})

# 2. Vérifier les marqueurs de sortie :
#    ✓ READY → procéder avec l'entraînement
#    ✗ NEEDS MAPPING → appliquer le code de mapping ci-dessous
#    ✗ INCOMPATIBLE → choisir une autre méthode/dataset

# 3. Si mapping nécessaire, appliquer avant l'entraînement :
def format_for_dpo(example):
    return {
        'prompt': example['instruction'],
        'chosen': example['chosen_response'],
        'rejected': example['rejected_response'],
    }
dataset = dataset.map(format_for_dpo, remove_columns=dataset.column_names)

# 4. Lancer la tâche d'entraînement en confiance

Scénario courant : Incompatibilité de format DPO

La plupart des datasets DPO utilisent des noms de colonne non-standard. Exemple :

Le dataset a : instruction, chosen_response, rejected_response
DPO attend : prompt, chosen, rejected

Le validateur détecte cela et fournit le code de mapping exact pour le corriger.

Conversion de modèles en GGUF

Après l'entraînement, convertissez les modèles en format GGUF pour utilisation avec llama.cpp, Ollama, LM Studio et d'autres outils d'inférence locale.

Qu'est-ce que GGUF :

Optimisé pour l'inférence CPU/GPU avec llama.cpp
Supporte la quantification (4-bit, 5-bit, 8-bit) pour réduire la taille du modèle
Compatible avec Ollama, LM Studio, Jan, GPT4All, llama.cpp
Typiquement 2-8GB pour les modèles 7B (vs 14GB non-quantifié)

Quand convertir :

Exécuter des modèles localement avec Ollama ou LM Studio
Réduire la taille du modèle avec la quantification
Déployer sur des appareils en périphérie
Partager les modèles pour une utilisation locale en priorité

Voir : references/gguf_conversion.md pour le guide de conversion complet, incluant le script de conversion prêt pour la production, les options de quantification, les exigences matériel, les exemples d'usage et le dépannage.

Conversion rapide :

hf_jobs("uv", {
    "script": "<voir references/gguf_conversion.md pour le script complet>",
    "flavor": "a10g-large",
    "timeout": "45m",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
    "env": {
        "ADAPTER_MODEL": "username/my-finetuned-model",
        "BASE_MODEL": "Qwen/Qwen2.5-0.5B",
        "OUTPUT_REPO": "username/my-model-gguf"
    }
})

Modèles d'entraînement courants

Voir references/training_patterns.md pour des exemples détaillés incluant :

Démo rapide (5-10 minutes)
Production avec checkpoints
Entraînement multi-GPU
Entraînement DPO (apprentissage de préférences)
Entraînement GRPO (RL en ligne)

Modes de défaillance courants

Mémoire dépassée (OOM)

Corriger (essayer dans l'ordre) :

Réduire la taille du batch : per_device_train_batch_size=1, augmenter gradient_accumulation_steps=8. La taille de batch effective est per_device_train_batch_size x gradient_accumulation_steps. Pour les meilleures performances, garder la taille de batch effective proche de 128.
Activer : gradient_checkpointing=True
Upgrader le matériel : t4-small → l4x1, a10g-small → a10g-large etc.

Dataset mal formaté

Corriger :

Valider en premier avec l'inspecteur de dataset :

uv run https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py \
  --dataset name --split train

Vérifier la sortie pour les marqueurs de compatibilité (✓ READY, ✗ NEEDS MAPPING, ✗ INCOMPATIBLE)
Appliquer le code de mapping de la sortie de l'inspecteur si nécessaire

Timeout de la tâche

Corriger :

Vérifier les logs pour le temps réel d'exécution : hf_jobs("logs", {"job_id": "..."})
Augmenter le timeout avec buffer : "timeout": "3h" (ajouter 30% au temps estimé)
Ou réduire l'entraînement : baisser num_train_epochs, utiliser un dataset plus petit, activer max_steps
Sauvegarder les checkpoints : save_strategy="steps", save_steps=500, hub_strategy="every_save"

Note : Par défaut 30min est insuffisant pour un vrai entraînement. Minimum 1-2 heures.

Échecs de sauvegarde sur le Hub

Corriger :

Ajouter à la tâche : secrets={"HF_TOKEN": "$HF_TOKEN"}
Ajouter à la config : push_to_hub=True, hub_model_id="username/model-name"
Vérifier l'auth : mcp__huggingface__hf_whoami()
Vérifier que le token a les permissions d'écriture et que le dépôt existe (ou définir hub_private_repo=True)

Dépendances manquantes

Corriger : Ajouter à l'en-tête PEP 723 :

# /// script
# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio", "missing-package"]
# ///

Dépannage

Problèmes courants :

La tâche expire → Augmenter le timeout, réduire les epochs/dataset, utiliser un modèle plus petit/LoRA
Le modèle n'est pas sauvegardé sur le Hub → Vérifier push_to_hub=True, hub_model_id, secrets=HF_TOKEN
Mémoire dépassée (OOM) → Réduire la taille du batch, augmenter l'accumulation de gradient, activer LoRA, utiliser un GPU plus grand
Erreur de format de dataset → Valider avec l'inspecteur de dataset (voir section Validation du dataset)
Erreurs d'import/module → Ajouter l'en-tête PEP 723 avec les dépendances, vérifier le format
Erreurs d'authentification → Vérifier mcp__huggingface__hf_whoami(), les permissions du token, le paramètre secrets

Voir : references/troubleshooting.md pour le guide de dépannage complet

Ressources

Références (dans cette compétence)

references/training_methods.md - Aperçu de SFT, DPO, GRPO, KTO, PPO, Reward Modeling
references/training_patterns.md - Modèles d'entraînement courants et exemples
references/unsloth.md - Unsloth pour l'entraînement VLM rapide (~2x vitesse, 60% moins VRAM)
references/gguf_conversion.md - Guide de conversion GGUF complet
references/trackio_guide.md - Configuration du suivi Trackio
references/hardware_guide.md - Spécifications et sélection du matériel
references/hub_saving.md - Dépannage de l'authentification du Hub
references/troubleshooting.md - Problèmes courants et solutions
references/local_training_macos.md - Entraînement local sur macOS

Scripts (dans cette compétence)

scripts/train_sft_example.py - Modèle SFT production
scripts/train_dpo_example.py - Modèle DPO production
scripts/train_grpo_example.py - Modèle GRPO production
scripts/unsloth_sft_example.py - Modèle Unsloth text LLM (plus rapide, moins VRAM)
scripts/estimate_cost.py - Estimer le temps et le coût (offrir le cas échéant)
scripts/convert_to_gguf.py - Script de conversion GGUF complet
scripts/hf_benchmarks.py - Rechercher les résultats de benchmarks et les classements par tâche, alias ou texte libre.

Scripts externes

Dataset Inspector - Valider le format du dataset avant l'entraînement (utiliser via uv run ou hf_jobs)

Liens externes

Points clés à retenir

Soumettre les scripts en ligne - Le paramètre script accepte directement du code Python ; aucune sauvegarde de fichier requise sauf si l'utilisateur demande
Les tâches sont asynchrones - Ne pas attendre/scruter ; laisser l'utilisateur vérifier quand prêt
Toujours définir le timeout - Par défaut 30 min est insuffisant ; minimum 1-2 heures recommandé
Toujours activer la sauvegarde sur le Hub - L'environnement est éphémère ; sans sauvegarde, tous les résultats sont perdus
Inclure Trackio - Utiliser les scripts d'exemple comme modèles pour un suivi en temps réel
Offrir l'estimation des coûts - Quand les paramètres sont connus, utiliser scripts/estimate_cost.py
Utiliser les scripts UV (Approche 1) - Par défaut utiliser hf_jobs("uv", {...}) avec scripts en ligne ; les scripts maintenus par TRL pour l'entraînement standard ; éviter les commandes bash trl-jobs dans Claude Code
Utiliser hf_doc_fetch/hf_doc_search pour la documentation TRL la plus récente
Valider le format du dataset avant l'entraînement avec l'inspecteur de dataset (voir section Validation du dataset)
Choisir le matériel approprié pour la taille du modèle ; utiliser LoRA pour les modèles >7B

Formation TRL sur Hugging Face Jobs

Vue d'ensemble

Quand utiliser cette compétence

Quand utiliser Unsloth

Directives clés

Exécution locale de scripts

Liste de vérification des prérequis

✅ Compte et authentification

✅ Exigences du dataset

⚠️ Paramètres critiques

Directives pour les tâches asynchrones

Action requise

Règles de base

Après la soumission

Démarrage rapide : Trois approches

Configuration de la longueur de séquence

Approche 1 : Scripts UV (Recommandé — choix par défaut)

Travailler avec les scripts

Approche 2 : Scripts maintenus par TRL (exemples officiels)

Recherche de plus de scripts UV sur le Hub

Approche 3 : CLI HF Jobs (commandes directes du terminal)

Approche 4 : Package TRL Jobs (entraînement simplifié)

Sélection du matériel

Critique : Sauvegarder les résultats sur le Hub

Configuration requise

Liste de vérification de la vérification

Gestion du timeout

Définir les timeouts

Directives de timeout

Choisir un modèle de base (sélection du modèle)

Exemple -- choisir un modèle de base OCR

Estimation des coûts

Scripts d'entraînement d'exemple

Suivi et traçage

Valeurs par défaut de la configuration Trackio

Vérifier le statut de la tâche

Validation du dataset

Pourquoi valider

Quand valider

Usage

Lire les résultats

Exemple de workflow

Scénario courant : Incompatibilité de format DPO

Conversion de modèles en GGUF

Modèles d'entraînement courants

Modes de défaillance courants

Mémoire dépassée (OOM)

Dataset mal formaté

Timeout de la tâche

Échecs de sauvegarde sur le Hub

Dépendances manquantes

Dépannage

Ressources

Références (dans cette compétence)

Scripts (dans cette compétence)

Scripts externes

Liens externes

Points clés à retenir

Skills similaires