Entraîner des modèles sur des Jobs

Cette page montre comment affiner et entraîner des modèles sur des Jobs, en utilisant le script d’une bibliothèque ou le vôtre. Chaque exemple est limité à une exécution courte qui se termine en quelques minutes sur une seule A10G, pour environ 0,10 $ de calcul. Le Job s’exécute sur les machines de Hugging Face, il continue donc de tourner même si vous fermez votre terminal ou votre ordinateur portable. Si vous n’avez jamais exécuté de Job auparavant, Quickstart couvre l’installation du CLI, la connexion et les crédits nécessaires à un Job.

Une première exécution

Cette commande ajuste finement un classifieur d’images sur 2 000 images Food-101 et le pousse dans votre espace de noms sur le Hub, en environ trois minutes :

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/transformers/main/examples/pytorch/image-classification/run_image_classification.py \
  --model_name_or_path google/vit-base-patch16-224-in21k \
  --dataset_name ethz/food101 \
  --do_train --do_eval \
  --remove_unused_columns False \
  --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 \
  --output_dir vit-food101 \
  --push_to_hub

La section Transformers couvre l'exécution complète ainsi que les autres scripts d'exemple.

Comment un Job d’entraînement est assemblé

La commande ci-dessus comporte cinq parties, et chaque commande de cette page en comporte les mêmes.

• Ce qui s’exécute. Soit un script uv, lancé avec hf jobs uv run : un script Python qui déclare ses dépendances dans un bloc de commentaires en haut du fichier (# /// script, au format PEP 723), que uv installe dans un environnement vierge. La section TRL en présente un. Soit l’image Docker d’une bibliothèque, lancée avec hf jobs run, qui utilise la bibliothèque déjà installée dans l’image. Commencez par un script uv lorsque la bibliothèque s’installe avec pip. Utilisez l’image lorsque la bibliothèque en fournit une avec des dépendances compilées, ou lorsque sa documentation le recommande. Consultez Utilisation des images Docker pour le compromis.
• Un jeton. Les tâches ne reçoivent pas de jeton Hugging Face par défaut. -s HF_TOKEN transmet le vôtre en tant que secret, permettant ainsi à l’exécution de pousser son modèle et de lire des entrées restreintes ou privées. D’autres secrets sont transmis de la même manière, par exemple -s WANDB_API_KEY.
• Matériel et durée. --flavor sélectionne le GPU. --timeout définit la limite de temps, qui est de 30 minutes par défaut. Une exécution qui atteint le délai est arrêtée, il est donc recommandé de définir --timeout au-dessus de la durée d'exécution prévue. Consultez Hardware flavor et Timeout.
• Un -- entre les drapeaux hf et le script. Les drapeaux placés avant -- sont destinés à hf jobs. Après ce séparateur figurent le chemin du script et ses propres arguments. Sans ce séparateur, un argument du script qui porte le même nom qu’un drapeau hf, comme --timeout ou --token, est interprété par hf. Dans le cas de l’image, ce qui suit -- est la commande à exécuter dans le conteneur.
• Lieu de destination de la sortie. Chaque bibliothèque ci-dessous peut pousser le modèle final vers un dépôt du Hub, et chaque exemple montre l’option correspondante. Pour Transformers et TRL, le dépôt prend le nom de --output_dir. Une exécution peut également écrire dans un bucket monté au fur et à mesure, en utilisant -v pour en monter un dans le conteneur. Voir Après la fin.

Votre propre code d’entraînement. Utilisez la forme la plus simple qui convient :

• Un seul fichier. Déclarez ses dépendances dans l’en-tête du script et exécutez hf jobs uv run train.py. La section TRL en présente un.

• Un dossier de projet avec des imports locaux, un fichier pyproject.toml ou des fichiers de configuration. hf jobs uv run ne téléverse que le fichier script, il faut donc monter le dossier. Le montage est en lecture seule, la commande copie donc le projet dans un dossier accessible en écriture et l’exécute là, comme vous le feriez localement :

  Copié

  hf jobs run --flavor a10g-small --timeout 30m -s HF_TOKEN \
    -v ./my-project:/code ghcr.io/astral-sh/uv:python3.12-bookworm -- \
    bash -c "cp -r /code /tmp/project && cd /tmp/project && uv run train.py --config configs/run.yaml"

  uv run installe les dépendances depuis pyproject.toml ou l’en-tête du script, et les imports locaux ainsi que les chemins relatifs fonctionnent sans modification. Voir Local directories.

• Code nécessitant des paquets système ou un kit CUDA. Construisez une image une seule fois et exécutez-la avec hf jobs run. Consultez Construire votre propre image avec un Space Docker.

Un script peut également contenir sa propre configuration de lancement dans un tableau [tool.hf-jobs] dans l’en-tête du script, comme le montre la section TRL. Consultez Définir la configuration de lancement dans le script. Les mêmes commandes sont disponibles depuis Python sous la forme de run_uv_job() et run_job(), décrites dans Configuration.

Vérifications avant une longue exécution

Avant de retirer les caps, quelques vérifications permettent d'éviter une exécution inutile.

• Commencez par un test de fumée. Exécutez la commande avec une limite de pas sur une petite variante, comme le font les exemples de cette page. Cela permet de vérifier que les dépendances s’installent, que les données se chargent, que le modèle s’adapte et que la publication fonctionne. Retirez ensuite la limite et lancez l’exécution complète.
• Vérifiez que les données tiennent. Chaque variante dispose d'un disque fixe, indiqué dans la colonne Ephemeral Storage sur Pricing and Billing. Les poids, le jeu de données et les points de contrôle enregistrés le partagent. Un jeu de données trop volumineux pour le disque peut être diffusé en continu ou monté au lieu d'être téléchargé. Consultez Process Large Datasets.
• Estimez la durée d’exécution. Les métriques finales train_* du test de fumée incluent train_steps_per_second, et l’entraîneur affiche le nombre total d’étapes au démarrage. Ensemble, ils donnent le temps d’entraînement de l’exécution complète. Définissez --timeout avec une marge confortable au-dessus de cette valeur, car le Job consacre également du temps à l’installation des dépendances et au téléchargement du modèle. Les tarifs par saveur sont disponibles sur Pricing and Billing.
• Sur une instance multi-GPU, démarrez un processus par GPU. Les instances se terminant par x2, x4 ou x8 offrent plusieurs GPU sur une seule machine. Assurez-vous que votre méthode de lancement les exploite. Transformers et TRL nécessitent accelerate launch, comme le montre la section TRL. Axolotl le fait de lui-même. Un simple python train.py n’utilise qu’un seul GPU, et un Trainer bascule sur DataParallel, ce qui est plus lent qu’un processus par GPU.
• Épingler si vous réexécutez. Épinglez l’URL d’un script à un commit plutôt qu’à main, et une image à un tag spécifique plutôt qu’à latest. Une réexécution obtient alors le même logiciel. Les URL de scripts ci-dessous suivent main, donc épinglez le commit avant d’en réexécuter un.
• Enregistrer les points de contrôle des longues exécutions dans un bucket monté, afin qu’un dépassement de délai ou un plantage ne fasse pas perdre l’exécution. Voir Après la fin.

Pendant son exécution

Les commandes hf jobs run et hf jobs uv run diffusent les journaux et bloquent votre terminal jusqu’à la fin de l’exécution. Ctrl+C arrête uniquement le flux de journaux. Le Job continue de s’exécuter jusqu’à son terme ou jusqu’à ce que vous l’arrêtiez avec hf jobs cancel <job_id>.

Pour les exécutions plus longues, passez -d (detach) pour obtenir immédiatement l’identifiant du Job, puis suivez l’exécution avec hf jobs logs -f <job_id> et vérifiez que le GPU est occupé avec hf jobs stats <job_id>. Après une exécution détachée, hf jobs wait <job_id> bloque jusqu’à la fin du Job et renvoie un code de sortie non nul en cas d’échec, ce dont a besoin un script ou une boucle d’agent. Une exécution non détachée le fait déjà. Voir Gérer les Jobs.

Les journaux de travail affichent les valeurs de perte sous forme de texte. Pour les courbes, orientez l’entraîneur vers un traceur d’expériences tel que trackio et, pour un traceur hébergé tel que Weights & Biases, passez sa clé en tant que second secret.

Après sa fin

Le disque d’un Job est supprimé lorsque le Job se termine, qu’il ait réussi, échoué ou expiré. Tout ce que vous souhaitez conserver doit quitter le conteneur avant cela.

Poussez le modèle vers un dépôt du Hub. Chaque bibliothèque de cette page propose une option à cet effet : --push_to_hub pour Transformers, TRL et Diffusers, --output-repo pour les scripts Unsloth, hub_model_id dans un fichier YAML Axolotl. À la fin de l'exécution, la bibliothèque téléverse les poids, le tokenizer et une carte de modèle générée qui enregistre le modèle de base et les arguments d'entraînement. Le dépôt est créé s'il n'existe pas. Pour le rendre privé, créez-le d'abord avec hf repos create <name> --private. Un jeton à granularité fine nécessite les accès en écriture et en création sur le dépôt du modèle. Sans cela, l'exécution entraîne le modèle jusqu'au bout puis échoue lors du téléversement.

Écrivez dans un bucket au fil de l’eau. Pour une exécution qui dure des heures, montez un Storage Bucket existant en lecture-écriture (créez-en un avec hf buckets create) et orientez le répertoire de sortie de la bibliothèque vers celui-ci. Les points de contrôle sont déposés dans le bucket au moment où ils sont enregistrés, de sorte qu’un dépassement de délai ou un plantage ne fait pas perdre l’exécution, et que le Job suivant peut reprendre à partir d’eux. Le même chemin fonctionne pour les sorties d’évaluation, les journaux et tout autre élément qui n’est pas un modèle.

hf jobs uv run --flavor a10g-large --timeout 8h -s HF_TOKEN \
  -v hf://buckets/your-username/checkpoints:/ckpt -- \
  train.py --output_dir /ckpt/run-01

Les scripts de Transformers, TRL et Diffusers acceptent --output_dir. Axolotl utilise output_dir dans le fichier YAML. Si vous passez également --push_to_hub, définissez aussi --hub_model_id, sinon le dépôt sera nommé d’après la dernière partie du chemin de sortie (run-01). Pour reprendre une exécution interrompue, montez à nouveau le même bucket et passez l’option de reprise de la bibliothèque, par exemple --resume_from_checkpoint pour un Trainer de Transformers. Consultez Volumes pour les options de montage.

Lire les journaux d’une exécution échouée. Un Job qui échoue conserve ses journaux : hf jobs logs <job_id> fonctionne après sa fin, et hf jobs inspect <job_id> fournit l’état final et le message d’erreur. hf jobs logs -f se termine lorsque le flux de journaux s’arrête, que l’exécution ait réussi ou non ; vérifiez donc inspect avant de supposer qu’elle a fonctionné.

Transformers

Les scripts d’exemple du dépôt Transformers déclarent leurs dépendances dans l’en-tête du script, ce qui permet de les exécuter sur Jobs directement depuis leur URL GitHub. Les arguments placés après l’URL sont transmis au script. Une première exécution utilise le script de classification d’images.

Pour l’exécution complète, supprimez --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 de cette commande : trois époques sur les 75 000 images d’entraînement de Food-101 prennent environ une heure sur a10g-small, soit environ 1 $ au tarif de cette instance, et atteignent 90 % de précision. Augmentez --timeout à 2h avant de lancer l’exécution. --push_to_hub télécharge le modèle sous votre espace de noms en utilisant le nom du répertoire de sortie. Des scripts existent pour la classification de texte, la résumés, la traduction, la classification de jetons, la reconnaissance vocale et plus encore.

TRL

TRL propose un script prêt à l’emploi pour chaque formateur (SFT, DPO, GRPO et autres), chacun déclarant ses propres dépendances, de sorte qu’ils s’exécutent directement sur Jobs depuis leur URL, à l’instar des scripts Transformers. Cette commande effectue un fine-tuning d’un petit modèle sur un jeu de données de chat :

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py \
  --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
  --dataset_name trl-lib/Capybara \
  --max_steps 100 \
  --output_dir Qwen2-0.5B-SFT \
  --push_to_hub

Cela prend environ six minutes. Supprimez --max_steps pour une exécution complète : trois époques sur Capybara, la valeur par défaut du script, prennent environ 2 h 20 min sur a10g-small, il faut donc augmenter --timeout en conséquence. La documentation de TRL utilise a100-large, qui est plus rapide.

Le guide complet, y compris la rédaction de votre propre script TRL et l’exécution de l’image huggingface/trl, est Training with Jobs dans la documentation TRL.

Pour plusieurs GPU, passez à l’image TRL, qui inclut accelerate, et laissez-la démarrer un processus par GPU :

hf jobs run --flavor a10g-largex2 --timeout 30m -s HF_TOKEN huggingface/trl -- \
  accelerate launch --num_processes 2 -m trl.scripts.sft \
  --model_name_or_path Qwen/Qwen2-0.5B-Instruct \
  --dataset_name trl-lib/Capybara \
  --max_steps 100 \
  --output_dir Qwen2-0.5B-SFT \
  --push_to_hub

Sans --max_steps, l’exécution complète (trois époques de Capybara, la valeur par défaut du script) prend environ 1 h 35 min sur deux A10G.

Lorsque vous écrivez votre propre script TRL, la configuration de lancement peut voyager avec lui. Un tableau [tool.hf-jobs] dans l'en-tête définit le type, le délai d'expiration et les secrets :

# /// script
# dependencies = ["trl"]
#
# [tool.hf-jobs]
# flavor  = "a10g-small"
# timeout = "1h"
# secrets = ["HF_TOKEN"]
# ///
from trl import SFTConfig, SFTTrainer
...

hf jobs uv run train.py n’a alors besoin d’aucun drapeau, et un drapeau que vous passez l’emporte toujours. Voir Définir la configuration de lancement dans le script.

Unsloth

Unsloth fournit des scripts prêts à l’emploi dans le jeu de données unsloth/jobs, un par famille de modèles. Ils installent Unsloth depuis l’en-tête de leur script et prennent le jeu de données et le dépôt de sortie en arguments :

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://huggingface.co/datasets/unsloth/jobs/resolve/main/sft-lfm2.5.py \
  --dataset mlabonne/FineTome-100k \
  --max-steps 50 \
  --output-repo your-username/lfm-finetuned

Cette opération s’achève en environ cinq minutes et pousse un adaptateur LoRA. Pour une époque complète, remplacez --max-steps 50 par --num-epochs 1 et augmentez --timeout. Le tutoriel est Fine-tune with Unsloth on Jobs sur le blog Hugging Face.

Axolotl

Axolotl prend une configuration YAML et s’exécute depuis son propre image Docker, cette section utilise donc hf jobs run avec un tag épinglé et synchronise la configuration depuis un répertoire local avec -v. Enregistrez une configuration des exemples Axolotl sous ./configs/lora.yml et ajoutez les clés indiquées après la commande. Cet exemple utilise examples/phi/lora-3.5.yaml, un fine-tuning LoRA de Phi-3.5-mini, sans autre modification. L’image contient déjà la commande axolotl.

hf jobs run --flavor a10g-small --timeout 30m -s HF_TOKEN \
  -v ./configs:/configs \
  axolotlai/axolotl:0.19.0-py3.12-cu130-2.13.0 -- \
  axolotl train /configs/lora.yml

-v ./configs:/configs téléverse le répertoire local configs vers votre bucket privé jobs-artifacts (créé pour vous lors de la première utilisation) et le monte en lecture seule dans le conteneur, de sorte que le YAML sur votre disque est le YAML utilisé par l’exécution. La sortie est définie dans le YAML. Ces clés poussent le modèle à la fin de l’exécution, et max_steps limite cette exécution d’essai :

hub_model_id: your-username/my-adapter
hub_strategy: end
max_steps: 20

Cette opération prend environ sept minutes et pousse l’adaptateur vers hub_model_id, en tant que dépôt privé. Supprimez max_steps pour une exécution complète. Les formats de balises d’image sont décrits dans le guide Docker d’Axolotl.

Pour plus de GPU, changez simplement le flavor, rien d’autre : sur a10g-largex4, axolotl train lance un processus par GPU tout seul. DeepSpeed et FSDP ne sont alors qu’une question de clés YAML, traitées dans le guide multi-GPU d’Axolotl.

Pour plus de détails, consultez le guide Hugging Face Jobs dans la documentation Axolotl.

Diffusers

La plupart des scripts DreamBooth LoRA du dépôt Diffusers déclarent leurs dépendances dans l’en-tête du script, ce qui permet de les exécuter directement sur Jobs depuis leur URL GitHub, tout comme les scripts Transformers. Cette commande entraîne un LoRA pour FLUX.2 [klein] 4B sur cinq photos d’un chien :

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/diffusers/main/examples/dreambooth/train_dreambooth_lora_flux2_klein.py \
  --pretrained_model_name_or_path black-forest-labs/FLUX.2-klein-4B \
  --dataset_name diffusers/dog-example \
  --instance_prompt "a photo of sks dog" \
  --resolution 512 --mixed_precision bf16 --guidance_scale 1 \
  --gradient_checkpointing --cache_latents \
  --optimizer adamW --use_8bit_adam --learning_rate 1e-4 \
  --max_train_steps 20 --seed 0 \
  --output_dir /tmp/out \
  --push_to_hub --hub_model_id your-username/klein-dog-lora

Cela prend environ cinq minutes et pousse le LoRA. Augmentez --max_train_steps pour une exécution réelle ; le README de FLUX.2 utilise 500. Les autres README de ce dossier couvrent les modèles restants et leurs options de mémoire. Vérifiez le début d’un script pour un bloc # /// script : les scripts sans ce bloc, comme le script SDXL, nécessitent que leurs dépendances soient passées avec --with.

Aller plus loin

• Serve Models permet de placer le modèle que vous avez entraîné derrière un point de terminaison temporaire, pour une exécution d’évaluation ou une démonstration. Inference Endpoints en exécute un qui reste actif.
• Configuration des secrets, des variables d’environnement, des volumes et du tableau [tool.hf-jobs] qui permet à un script de définir sa propre saveur et son délai d’expiration.
• Gérer les Jobs pour lister, inspecter, déboguer et annuler des Jobs.
• Travailler avec de grands jeux de données pour le streaming et le montage de données qui ne tiennent pas sur le disque.
• Planifier des tâches pour exécuter une commande d'entraînement selon un minutage.
• Exemples et tutoriels pour les contributions de la communauté, incluant l’ajustement fin de modèles vision-langage et le streaming de grands jeux de données dans une session d’entraînement.
• Utiliser des Jobs depuis un agent de codage : la compétence hf de la CLI permet à Claude Code, Codex et Cursor de lancer et de surveiller ces exécutions pour vous.