Entraînement avec des Jobs

Hugging Face Jobs exécute votre entraînement sur des GPU Hugging Face. Vous choisissez le matériel pour chaque exécution et ne payez que pour les secondes d’exécution. Avec --push_to_hub, le modèle entraîné est téléversé sur le Hub à la fin.

Dans ce guide, vous apprendrez comment :

Lancer un script d'entraînement TRL avec une seule commande
Suivre une exécution et visualiser ses courbes de perte
Exécutez votre propre script, avec ses paramètres matériels dans le fichier
Conserver les points de contrôle et reprendre une exécution interrompue
Entraîner sur plusieurs GPU

Pour comprendre le fonctionnement général des Jobs, y compris le matériel et la tarification, consultez la documentation des Jobs.

Prérequis

Un compte Hugging Face avec un solde de crédits positif. Les jobs sont facturés à l’usage : vous ne payez que les secondes utilisées.
Connecté au Hugging Face Hub (hf auth login)

Une première exécution

Cette commande effectue un fine-tuning de Qwen2-0.5B-Instruct sur le jeu de données de chat Capybara à l'aide du script SFT de TRL, puis pousse le modèle vers votre compte :

bash

python

Cela prend quelques minutes et coûte bien moins de 1 $ sur a10g-small. Les options situées avant -- concernent les Jobs : le matériel, une limite de temps et le jeton utilisé pour pousser le modèle. --secrets HF_TOKEN envoie le jeton avec lequel vous vous êtes connecté. En Python, passez le jeton lui-même. Les arguments situés après l’URL du script sont transmis au script. hf jobs uv run exécute un script Python avec uv. sft.py liste ses dépendances dans un en-tête en haut du fichier, de sorte que Jobs installe TRL avant le démarrage du script. Le Job s’arrête lorsque le script se termine, et la facturation s’arrête avec lui.

--max_steps 100 limite cette première exécution. Supprimez-le pour l’exécution complète : trois époques, la valeur par défaut du script, prennent quelques heures sur a10g-small, il faut donc augmenter --timeout en conséquence, par exemple --timeout 3h. Jobs interrompt une exécution lorsqu’elle atteint son délai d’attente, qui est de 30 minutes par défaut. Un GPU plus puissant, comme a100-large, termine plus rapidement. Consultez Matériel pour les types de machines et leurs tarifs.

Suivre l'exécution

hf jobs uv run transmet les journaux en continu et maintient votre terminal ouvert jusqu’à la fin de l’exécution. Ctrl+C arrête uniquement le flux de journaux : le Job continue de s’exécuter. Ajoutez --detach pour récupérer immédiatement l’ID du Job, puis :

hf jobs logs -f <job_id>   # stream the logs
hf jobs ps                 # list your running Jobs
hf jobs inspect <job_id>   # status, and the error message if it failed
hf jobs cancel <job_id>    # stop it

Voir Gérer les tâches pour plus de détails.

Pour les courbes de perte, TRL journalise dans Trackio. Ajoutez --env TRACKIO_SPACE_ID=<your-username>/trackio avant -- pour nommer un Space pour le tableau de bord, et --report_to trackio après l'URL du script. Trackio crée le Space, ainsi qu'un bucket pour les métriques, s'ils n'existent pas. Les deux sont publics par défaut. Les autres traceurs pris en charge par Transformers fonctionnent également. Pour Weights & Biases, ajoutez --with wandb --secrets WANDB_API_KEY avant -- et --report_to wandb après l'URL du script. --secrets WANDB_API_KEY lit la valeur depuis WANDB_API_KEY dans votre environnement local. Consultez variables d'environnement et secrets pour d'autres méthodes de transmission.

Exécuter votre propre script

Écrivez votre code d’entraînement dans un fichier Python (par exemple, train.py). Énumérez ses dépendances en haut du fichier, dans un en-tête de script, de la même manière que le font les scripts TRL. Les jobs les installent avant le démarrage du script :

# /// script
# dependencies = [
#     "trl",
#     "peft",
# ]
# ///

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

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

trainer = SFTTrainer(
    model="Qwen/Qwen2.5-0.5B",
    train_dataset=dataset,
    peft_config=LoraConfig(),
    args=SFTConfig(output_dir="Qwen2.5-0.5B-SFT", max_steps=100),
)
trainer.train()
trainer.push_to_hub()

Lancez-le ensuite avec l'interface en ligne de commande hf jobs ou l'API Python :

bash

python

Pour un script sans en-tête, listez plutôt les dépendances au lancement à l’aide de --with, une fois par paquet : --with trl --with peft (dependencies=["trl", "peft"] en Python). Le script peut également être une URL, comme un lien raw GitHub, un Gist ou un fichier dans un dépôt public du Hub.

Les paramètres de lancement peuvent également être définis dans le script. Un tableau [tool.hf-jobs] dans l'en-tête définit le matériel, le délai d'expiration et les secrets :

# /// script
# dependencies = [
#     "trl",
#     "peft",
# ]
#
# [tool.hf-jobs]
# flavor = "a10g-small"
# timeout = "30m"
# secrets = ["HF_TOKEN"]
# ///

hf jobs uv run train.py n’a alors besoin d’aucune option, et une option que vous passez remplace toujours celle du script. Le script contient tout ce dont il a besoin pour s’exécuter, vous pouvez donc le partager, ou y revenir plus tard, sans avoir à vous souvenir de la GPU et du timeout requis. hf jobs uv run --dry-run train.py affiche les paramètres résolus et met en évidence les valeurs provenant du script. Le tableau est lu uniquement par le CLI hf : run_uv_job() l’ignore. Voir Définir la configuration de lancement dans le script.

Exécuter n'importe quel script TRL

Le même modèle s’applique à tous les scripts d’entraîneur TRL (SFT, DPO, GRPO, modélisation de récompense et autres) ainsi qu’aux exemples autonomes .py de l’Index des exemples. Chacun déclare ses dépendances dans l’en-tête du script. Un exemple qui lit d’autres fichiers situés à côté de lui nécessite que son dossier soit monté dans le Job. Voir Directories locaux. Les exemples réservés aux notebooks ne peuvent pas être soumis de cette manière. Les arguments du script sont les mêmes que lors de l’exécution locale du script.

Conserver les points de contrôle

Le disque d’un Job est supprimé lorsque le Job se termine, y compris en cas d’expiration du délai d’attente ou d’échec. Pour une exécution de longue durée, enregistrez les points de contrôle en dehors du Job afin qu’ils soient conservés.

La méthode la plus simple consiste à pousser chaque point de contrôle vers le dépôt du modèle de sortie au moment où il est enregistré :

bash

python

Avec --hub_strategy checkpoint, le checkpoint le plus récent, y compris l’état de l’optimiseur, est conservé dans un dossier last-checkpoint du dépôt. Pour reprendre une exécution interrompue, montez le dépôt dans un nouveau Job et repartez de ce dossier : lancez la même commande avec --volume hf://<your-username>/Qwen2-0.5B-SFT:/previous avant -- et --resume_from_checkpoint /previous/last-checkpoint après l’URL du script.

Pour conserver plusieurs points de contrôle en dehors du dépôt du modèle, écrivez-les plutôt dans un Storage Bucket. Créez-en un avec hf buckets create <your-username>/checkpoints --private, montez-le dans le Job et pointez --output_dir vers celui-ci :

bash

python

Pour reprendre une exécution interrompue, relancez la même commande avec --resume_from_checkpoint /checkpoints/Qwen2-0.5B-SFT/checkpoint-<step>. Consultez Écrire dans un bucket au fil de l'eau pour en savoir plus et Volumes pour les options de montage.

Chaque point de contrôle contient l’état du modèle et de l’optimiseur, soit plusieurs fois la taille du modèle. Ajoutez --save_total_limit 2 pour ne conserver que les plus récents. Si vous passez également --push_to_hub, définissez --hub_model_id, ou le dépôt sera nommé d’après la dernière partie du chemin de sortie.

Plusieurs GPU

Une variante avec plusieurs GPU raccourcit la durée d’exécution. Pour cela, utilisez hf jobs run, qui exécute une commande dans une image Docker plutôt qu’un script, avec l’image huggingface/trl, sur laquelle TRL et Accelerate sont installés. Puis démarrez un processus par GPU. Cela fonctionne pour les scripts TRL ainsi que pour votre propre code d’entraînement.

Accélérer un script TRL

L’exécution SFT depuis le début de ce guide, sur quatre GPU :

bash

python

La trl CLI transmet --num_processes à accelerate launch. Définissez-le sur le nombre de GPU de la saveur, ici quatre L4. Chaque processus prend son propre lot, la taille de lot effective est donc quatre fois celle d'une exécution sur un seul GPU. Cette exécution prend quelques minutes. Sans --max_steps, les trois époques complètes prennent environ une heure, augmentez donc --timeout, par exemple à 2h.

Votre propre script

Vous n’êtes pas limité aux scripts TRL. Tout code d’entraînement qui s’exécute localement avec accelerate launch fonctionne de la même manière sur Jobs, à condition que l’image contienne les paquets nécessaires. Par exemple, enregistrez un script GRPO avec votre propre fonction de récompense sous le nom train_grpo.py dans un dossier, puis montez ce dossier dans le Job. Jobs télécharge le dossier dans un bucket privé et le monte en lecture seule :

bash

python

Le script s’exécute avec TRL installé dans l’image, il n’a donc pas besoin d’en-tête de script. GRPOTrainer génère des complétions avec transformers par défaut, ce qui s’exécute donc dans un seul Job sans serveur vLLM. Pour une génération plus rapide, voir vLLM Integration. La section suivante explique comment hf jobs run utilise l’image.

Images Docker

Jobs exécute votre script avec uv, qui installe les dépendances déclarées dans son en-tête # /// script dans un nouvel environnement. Le TRL importé par votre script provient donc de cet en-tête, et non de l’image, et les exemples hf jobs uv run ci-dessus n’ont pas besoin de --image du tout.

Une image Docker avec TRL préinstallée est disponible sur huggingface/trl. En la passant à hf jobs uv run, le job reçoit la couche système de l’image, comme sa chaîne d’outils CUDA, ce qui est important pour les dépendances qui se compilent à son encontre :

bash

python

Pour exécuter le TRL installé dans l’image, utilisez hf jobs run à la place. Cette commande exécute directement une commande dans l’image, sans en-tête de script à résoudre, de sorte que c’est le TRL de l’image lui-même qui s’exécute. Le -- sépare la commande des options de Jobs, ce qui est nécessaire chaque fois que la commande elle-même prend des options :

bash

python

L'image est publiée sous trois types de balises :

Tag	Sommaire
`X.Y.Z`	La version TRL de cette version, compilée lors de la publication de cette version
`latest`	La version la plus récente
`dev`	La branche `main`, reconstruite à chaque fusion

Utilisez dev pour exécuter la version de développement, ce qui est utile pour tester un correctif qui a été intégré dans main mais qui n'a pas encore été publié :

bash

python

Les tags ne sélectionnent que ce qui est installé dans l’image, ils n’ont donc d’importance que pour hf jobs run. Avec hf jobs uv run, la version provient à la place de l’en-tête du script, et le tag n’a aucune incidence sur la version de TRL importée.

Combiner les deux, de sorte que uv résolve l’en-tête du script tandis que certaines importations proviennent toujours de l’image, nécessite des drapeaux supplémentaires. Consultez Réutiliser les paquets de l’image et ajouter des dépendances avec UV pour cette forme et les chemins qu’elle requiert.

Les Jobs s'exécutent sur une image Docker issue de Hugging Face Spaces ou de Docker Hub, vous pouvez donc également spécifier une image personnalisée :

bash

python

Le wrapper TRL Jobs lance les scripts TRL sur Jobs avec des configurations prédéfinies pour certains modèles, par exemple trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara.

Update on GitHub