Formation TRL sur les Jobs Hugging Face

Vue d'ensemble

Entraînez des modèles de langage en utilisant 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 GPU cloud et les résultats sont automatiquement sauvegardés sur le Hugging Face Hub.

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

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

Pour une documentation détaillée sur les 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 les conseils de sélection

Quand utiliser cette compétence

Utilisez cette compétence quand les utilisateurs veulent :

• Affiner les modèles de langage sur des GPU 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 définitivement sur le Hub
• Utiliser des workflows modernes avec des valeurs par défaut optimisées

Quand utiliser Unsloth

Utilisez Unsloth (references/unsloth.md) au lieu de TRL standard quand :

• Mémoire GPU limitée - Unsloth utilise ~60% moins de VRAM
• La vitesse est importante - Unsloth est ~2x plus rapide
• Entraînement de modèles larges (>13B) - l'efficacité mémoire est critique
• Entraînement de modèles Vision-Language (VLMs) - Unsloth a le support 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

Lors de l'assistance avec des tâches d'entraînement :

1. UTILISEZ TOUJOURS l'outil MCP hf_jobs() - Soumettez les tâches en utilisant hf_jobs("uv", {...}), PAS les commandes bash trl-jobs. Le paramètre script accepte le code Python directement. Ne sauvegarder sur des fichiers locaux QUE si l'utilisateur le demande explicitement. Passez le contenu du script en tant que 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 en utilisant hf_jobs().

2. Incluez toujours Trackio - Chaque script d'entraînement doit inclure Trackio pour la surveillance en temps réel. Utilisez les scripts d'exemple dans scripts/ comme modèles.

3. Fournissez les détails de la tâche après la soumission - Après la soumission, fournissez l'ID de tâche, l'URL de surveillance, le temps estimé, et notez que l'utilisateur peut demander des vérifications de statut ultérieurement.

4. Utilisez les scripts d'exemple comme modèles - Référencez scripts/train_sft_example.py, scripts/train_dpo_example.py, etc. comme points de départ.

Exécution de scripts locaux

Les scripts du référentiel utilisent les dépendances en ligne PEP 723. Exécutez-les avec uv run :

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

Liste de contrôle des prérequis

Avant de lancer une 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)
• Authentification : Vérifiez avec hf_whoami()
• HF_TOKEN pour Hub Push ⚠️ CRITIQUE - L'environnement d'entraînement est éphémère, doit être envoyé au Hub ou TOUS les résultats d'entraînement sont perdus
• Le jeton doit avoir les permissions d'écriture
• DOIT passer secrets={"HF_TOKEN": "$HF_TOKEN"} dans la configuration de tâche pour rendre le jeton disponible (la syntaxe $HF_TOKEN fait référence à votre valeur de jeton réelle)

✅ Exigences de dataset

• Le dataset doit exister sur 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 uniquement)
• VALIDEZ TOUJOURS les datasets inconnus avant l'entraînement GPU pour éviter les défaillances de format (voir la section Validation du dataset ci-dessous)
• Taille appropriée pour le 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 attendu - La valeur par défaut de 30 min est TROP COURTE pour la plupart des entraînements. Minimum recommandé : 1-2 heures. La tâche échoue et perd tout progrès si le timeout est dépassé.
• Le push vers Hub doit être activé - Config : push_to_hub=True, hub_model_id="username/model-name" ; Tâche : secrets={"HF_TOKEN": "$HF_TOKEN"}

Directives sur 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 :

1. Créer le script d'entraînement avec Trackio inclus (utilisez scripts/train_sft_example.py comme modèle)
2. Soumettre immédiatement en utilisant l'outil MCP hf_jobs() avec le contenu du script en ligne - ne sauvegarder en fichier que si l'utilisateur le demande
3. Signaler la soumission avec l'ID de tâche, l'URL de surveillance et le temps estimé
4. Attendre l'utilisateur pour demander des vérifications de statut - ne pas sonder automatiquement

Règles de base

• Les tâches s'exécutent en arrière-plan - La soumission revient immédiatement ; l'entraînement continue indépendamment
• Délai des journaux initiaux - Peut prendre 30-60 secondes pour que les journaux apparaissent
• L'utilisateur vérifie le statut - Attendre que l'utilisateur demande des mises à jour de statut
• Évitez le sondage - Vérifiez les journaux uniquement sur demande de l'utilisateur ; fournissez des liens de surveillance à la place

Après la soumission

Fournissez à l'utilisateur :

• ✅ ID de tâche et URL de surveillance
• ✅ Temps d'exécution estimé
• ✅ URL du tableau de bord Trackio
• ✅ Remarque indiquant que l'utilisateur peut demander des vérifications de statut ultérieurement

Exemple de réponse :

✅ Tâche soumise avec succès !

Job ID: abc123xyz
Monitor: 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/les journaux quand vous êtes prêt !

Démarrage rapide : trois approches

💡 Conseil pour les démos : Pour les démos rapides sur des GPU 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 configuration 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)

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

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

Quand remplacer :

• Contexte plus long : Définissez à une valeur supérieure (p. ex., max_length=2048)
• Contraintes de mémoire : Définissez à une valeur inférieure (p. ex., max_length=512)
• Modèles Vision : Définissez 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 en ligne 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")

# Créer une division train/eval pour la surveillance
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", # nom du projet pour le nom d'entraînement (trackio)
        run_name="meaningful_run_name",   # nom descriptif pour la série d'entraînement spécifique (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 total 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 des 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 :

• Code en ligne (recommandé pour l'entraînement personnalisé)
• URL publiques
• URL de repo privé (avec HF_TOKEN)

Erreurs courantes :

# ❌ Celles-ci échoueront toutes
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>"})

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

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

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

Pour utiliser des scripts locaux : Chargez d'abord sur HF Hub :

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

Approche 2 : Scripts maintenus par TRL (exemples officiels)

TRL fournit des scripts testés en production pour toutes les méthodes. Peuvent être exécutés à partir d'URL :

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é Disponibles : Les scripts sont disponibles depuis https://github.com/huggingface/trl/tree/main/examples/scripts

Trouver plus de scripts UV sur Hub

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

# 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 de terminal direct)

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

⚠️ CRITIQUE : Règles de syntaxe CLI

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

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

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

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

Règles clés de syntaxe :

1. L'ordre des commandes est hf jobs uv run (PAS hf jobs run uv)
2. Tous les drapeaux (--flavor, --timeout, --secrets) doivent venir AVANT l'URL du script
3. Utilisez --secrets (pluriel), pas --secret
4. 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 journaux
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 valeurs par défaut optimisées 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, push Hub automatique, commandes d'une ligne Quand utiliser : Utilisateur travaillant directement en terminal (pas dans le contexte Claude Code), expérimentation locale rapide Référentiel : https://github.com/huggingface/trl-jobs

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

Sélection du matériel

Flavors 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 géré automatiquement par TRL/Accelerate
• Commencez avec un matériel plus petit pour les tests

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

Critique : sauvegarder les résultats sur Hub

⚠️ ENVIRONNEMENT ÉPHÉMÈRE—DOIT ENVOYER À 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 envoyé à 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 : envoyer les points de contrôle
)

Dans la soumission de tâche :

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

Liste de vérification de 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 repo 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éfinition des timeouts

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

Directives sur les timeouts

Toujours ajouter une marge de 20-30% pour le chargement du modèle/dataset, la sauvegarde des points de contrôle, les opérations d'envoi à Hub et les délais réseau.

Au timeout : Tâche tuée immédiatement, tout progrès non sauvegardé perdu, doit redémarrer au début

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

Identifier les modèles à entraîner basés sur le type de tâche ou les résultats de benchmark.

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 respectant les contraintes de taille et de matériel.

# Obtenir de 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

Proposez une estimation des coûts lors de la planification de 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 marge) et les suggestions d'optimisation.

Quand proposer : Utilisateur planifiant une tâche, demande de coût/temps, choix de matériel, tâche durera >1 heure ou coûtera >$5

Scripts d'entraînement d'exemple

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

Chargez ces scripts pour correctement :

• scripts/train_sft_example.py - Entraînement SFT complet avec Trackio, LoRA, points de contrôle
• scripts/train_dpo_example.py - Entraînement DPO pour apprentissage par préférence
• scripts/train_grpo_example.py - Entraînement GRPO pour RL en ligne

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

Surveillance et suivi

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" et run_name="meaningful_name"

Paramètres par défaut de la configuration Trackio

Utilisez des valeurs par défaut sensées sauf si l'utilisateur spécifie autrement. Lors de la génération de 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, nommez la série de manière à ce que l'utilisateur la reconnaisse (p. ex., descriptive de la tâche, du modèle ou de l'objectif)
• Configuration : Garder minimal - inclure uniquement les hyperparamètres et l'info de modèle/dataset
• Nom du projet : Utiliser un nom de projet pour associer les exécutions à un projet particulier

Remplacements de l'utilisateur : Si l'utilisateur demande une configuration trackio spécifique (espace personnalisé, nommage des exécutions, regroupement ou configuration supplémentaire), appliquer plutôt ses préférences que les valeurs par défaut.

C'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 regroupement 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 journaux
hf_jobs("logs", {"job_id": "your-job-id"})

Rappelez-vous : Attendre que l'utilisateur demande des vérifications de statut. Évitez de sonder répétitivement.

Validation du dataset

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

Pourquoi valider

• 50%+ des défaillances d'entraînement sont dues à des problèmes de format de dataset
• DPO est particulièrement strict : nécessite des noms de colonnes 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

VALIDEZ TOUJOURS pour :

• Datasets inconnus ou personnalisés
• Entraînement DPO (CRITIQUE - 90% des datasets ont besoin d'un mappage)
• Tout dataset ne pas explicitement compatible avec TRL

Ignorez la validation pour les datasets TRL connus :

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

Utilisation

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 termine généralement de manière synchrone.