Entraînement de modèles de vision sur Hugging Face Jobs

Entraînez des modèles de détection d'objets, de classification d'images et de segmentation SAM/SAM2 sur des GPU cloud gérés. Aucune configuration de GPU local requise — les résultats sont automatiquement sauvegardés sur le Hugging Face Hub.

Quand utiliser cette compétence

Utilisez cette compétence lorsque les utilisateurs souhaitent :

• Affiner des modèles de détection d'objets (D-FINE, RT-DETR v2, DETR, YOLOS) sur des GPU cloud ou locaux
• Affiner des modèles de classification d'images (timm: MobileNetV3, MobileViT, ResNet, ViT/DINOv3, ou tout classifier Transformers) sur des GPU cloud ou locaux
• Affiner des modèles SAM ou SAM2 pour la segmentation / matting d'images en utilisant des prompts bbox ou point
• Entraîner des détecteurs de boîtes englobantes sur des datasets personnalisés
• Entraîner des classifieurs d'images sur des datasets personnalisés
• Entraîner des modèles de segmentation sur des datasets de masques personnalisés avec prompts
• Exécuter des jobs d'entraînement de vision sur l'infrastructure Hugging Face Jobs
• S'assurer que les modèles de vision entraînés sont définitivement sauvegardés sur le Hub

Compétences associées

• hugging-face-jobs — Infrastructure générale HF Jobs : authentification par token, saveurs de matériel, gestion des timeouts, estimation des coûts, secrets, variables d'environnement, jobs planifiés et persistance des résultats. Consultez la compétence Jobs pour toute question non liée à l'entraînement (par exemple, « comment fonctionnent les secrets ? », « quel matériel est disponible ? », « comment passer les tokens ? »).
• hugging-face-model-trainer — Entraînement de modèles de langage basé sur TRL (SFT, DPO, GRPO). Utilisez cette compétence pour l'affinage de modèles de texte/langage.

Exécution locale de scripts

Les scripts auxiliaires utilisent les dépendances inline PEP 723. Exécutez-les avec uv run :

uv run scripts/dataset_inspector.py --dataset username/dataset-name --split train
uv run scripts/estimate_cost.py --help

Liste de contrôle des prérequis

Avant de commencer tout job d'entraînement, vérifiez :

Compte et authentification

• Compte Hugging Face avec plan Pro, Team ou Enterprise (Jobs nécessitent un plan payant)
• Connexion authentifiée : Vérifiez avec hf_whoami() (outil) ou hf auth whoami (terminal)
• Token avec permissions write
• DOIT passer le token dans les secrets du job — voir la directive #3 ci-dessous pour la syntaxe (outil MCP vs API Python)

Exigences de dataset — Détection d'objets

• Dataset doit exister sur Hub
• Les annotations doivent utiliser la colonne objects avec les sous-champs bbox, category (et optionnellement area)
• Les bboxes peuvent être au format xywh (COCO) ou xyxy (Pascal VOC) — auto-détection et conversion
• Les catégories peuvent être entiers ou chaînes — les chaînes sont automatiquement remappées aux IDs entiers
• La colonne image_id est optionnelle — générée automatiquement si manquante
• TOUJOURS valider les datasets inconnus avant l'entraînement GPU (voir section Validation de dataset)

Exigences de dataset — Classification d'images

• Dataset doit exister sur Hub
• Doit avoir une colonne image (images PIL) et une colonne label (IDs de classe entiers ou chaînes)
• La colonne label peut être de type ClassLabel (avec noms) ou entiers/chaînes simples — les chaînes sont automatiquement remappées
• Noms de colonnes courants auto-détectés : label, labels, class, fine_label
• TOUJOURS valider les datasets inconnus avant l'entraînement GPU (voir section Validation de dataset)

Exigences de dataset — Segmentation SAM/SAM2

• Dataset doit exister sur Hub
• Doit avoir une colonne image (images PIL) et une colonne mask (masque de segmentation binaire au sol)
• Doit avoir un prompt — soit :
  • Une colonne prompt avec JSON contenant {"bbox": [x0,y0,x1,y1]} ou {"point": [x,y]}
  • OU une colonne bbox dédiée avec les valeurs [x0,y0,x1,y1]
  • OU une colonne point dédiée avec les valeurs [x,y] ou [[x,y],...]
• Les bboxes doivent être au format xyxy (coordonnées absolues en pixels)
• Exemple de dataset : merve/MicroMat-mini (matting d'image avec prompts bbox)
• TOUJOURS valider les datasets inconnus avant l'entraînement GPU (voir section Validation de dataset)

Paramètres critiques

• Timeout doit dépasser le temps d'entraînement attendu — La valeur par défaut de 30 min est TROP COURTE. Voir la directive #6 pour les valeurs recommandées.
• Hub push doit être activé — push_to_hub=True, hub_model_id="username/model-name", token dans secrets

Validation de dataset

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

TOUJOURS valider pour les datasets inconnus/personnalisés ou tout dataset avec lequel vous n'avez pas entraîné auparavant. Ignorer pour cppe-5 (la valeur par défaut dans le script d'entraînement).

Exécution de l'inspecteur

Option 1 : Via HF Jobs (recommandé — évite les problèmes locaux de SSL/dépendances) :

hf_jobs("uv", {
    "script": "path/to/dataset_inspector.py",
    "script_args": ["--dataset", "username/dataset-name", "--split", "train"]
})

Option 2 : Localement :

uv run scripts/dataset_inspector.py --dataset username/dataset-name --split train

Option 3 : Via HfApi().run_uv_job() (si hf_jobs MCP non disponible) :

from huggingface_hub import HfApi
api = HfApi()
api.run_uv_job(
    script="scripts/dataset_inspector.py",
    script_args=["--dataset", "username/dataset-name", "--split", "train"],
    flavor="cpu-basic",
    timeout=300,
)

Lecture des résultats

• ✓ READY — Dataset est compatible, utilisez directement
• ✗ NEEDS FORMATTING — Nécessite un prétraitement (code de mapping fourni dans la sortie)

Prétraitement automatique de bbox

Le script d'entraînement de détection d'objets (scripts/object_detection_training.py) gère automatiquement la détection du format bbox (conversion xyxy→xywh), l'assainissement bbox, la génération image_id, le remapping catégorie chaîne→entier, et la troncature de dataset. Aucun prétraitement manuel requis — assurez-vous simplement que le dataset a les colonnes objects.bbox et objects.category.

Flux de travail d'entraînement

Copiez cette liste de contrôle et suivez la progression :

Progression d'entraînement :
- [ ] Étape 1 : Vérifier les prérequis (compte, token, dataset)
- [ ] Étape 2 : Valider le format du dataset (exécuter dataset_inspector.py)
- [ ] Étape 3 : Demander à l'utilisateur la taille du dataset et le split de validation
- [ ] Étape 4 : Préparer le script d'entraînement (OD : scripts/object_detection_training.py, IC : scripts/image_classification_training.py, SAM : scripts/sam_segmentation_training.py)
- [ ] Étape 5 : Sauvegarder le script localement, soumettre le job et signaler les détails

Étape 1 : Vérifier les prérequis

Suivez la liste de contrôle des prérequis ci-dessus.

Étape 2 : Valider le dataset

Exécutez l'inspecteur de dataset AVANT de dépenser du temps GPU. Voir la section "Validation de dataset" ci-dessus.

Étape 3 : Demander les préférences de l'utilisateur

TOUJOURS utiliser l'outil AskUserQuestion avec un format de style options :

AskUserQuestion({
    "questions": [
        {
            "question": "Voulez-vous exécuter un test rapide avec un sous-ensemble des données d'abord ?",
            "header": "Taille du dataset",
            "options": [
                {"label": "Exécution de test rapide (10% des données)", "description": "Plus rapide, moins cher (~30-60 min, ~$2-5) pour valider la configuration"},
                {"label": "Dataset complet (Recommandé)", "description": "Entraînement complet pour la meilleure qualité de modèle"}
            ],
            "multiSelect": false
        },
        {
            "question": "Voulez-vous créer un split de validation à partir des données d'entraînement ?",
            "header": "Diviser les données",
            "options": [
                {"label": "Oui (Recommandé)", "description": "Diviser automatiquement 15% des données d'entraînement pour la validation"},
                {"label": "Non", "description": "Utiliser le split de validation existant du dataset"}
            ],
            "multiSelect": false
        },
        {
            "question": "Quel matériel GPU voulez-vous utiliser ?",
            "header": "Saveur de matériel",
            "options": [
                {"label": "t4-small ($0.40/hr)", "description": "1x T4, 16 GB VRAM — suffisant pour tous les modèles OD de moins de 100M paramètres"},
                {"label": "l4x1 ($0.80/hr)", "description": "1x L4, 24 GB VRAM — plus d'espace pour les grandes images ou tailles de batch"},
                {"label": "a10g-large ($1.50/hr)", "description": "1x A10G, 24 GB VRAM — entraînement plus rapide, plus de CPU/RAM"},
                {"label": "a100-large ($2.50/hr)", "description": "1x A100, 80 GB VRAM — plus rapide, pour les très grands datasets ou images"}
            ],
            "multiSelect": false
        }
    ]
})

Étape 4 : Préparer le script d'entraînement

Pour la détection d'objets, utilisez scripts/object_detection_training.py comme modèle production-ready. Pour la classification d'images, utilisez scripts/image_classification_training.py. Pour la segmentation SAM/SAM2, utilisez scripts/sam_segmentation_training.py. Tous les scripts utilisent HfArgumentParser — toute la configuration est passée via les arguments CLI en script_args, PAS en éditant les variables Python. Pour les détails du modèle timm, voir references/timm_trainer.md. Pour les détails de l'entraînement SAM2, voir references/finetune_sam2_trainer.md.

Étape 5 : Sauvegarder le script, soumettre le job et signaler

1. Sauvegarder le script localement dans submitted_jobs/ à la racine du workspace (créer si nécessaire) avec un nom descriptif comme training_<dataset>_<YYYYMMDD_HHMMSS>.py. Indiquer le chemin à l'utilisateur.
2. Soumettre en utilisant l'outil MCP hf_jobs (préféré) ou HfApi().run_uv_job() — voir directive #1 pour les deux méthodes. Passer toute la config via script_args.
3. Signaler l'ID du job (à partir de l'attribut .id), l'URL de monitoring, le dashboard Trackio (https://huggingface.co/spaces/{username}/trackio), le temps attendu et le coût estimé.
4. Attendre l'utilisateur pour demander les vérifications de statut — ne pas faire de polling automatique. Les jobs d'entraînement s'exécutent de manière asynchrone et peuvent prendre des heures.

Directives critiques

Ces règles préviennent les défaillances courantes. Les suivre exactement.

1. Soumission de job : outil MCP hf_jobs vs API Python

hf_jobs() est un outil MCP, PAS une fonction Python. Ne PAS essayer de l'importer depuis huggingface_hub. L'appeler comme un outil :

hf_jobs("uv", {"script": training_script_content, "flavor": "a10g-large", "timeout": "4h", "secrets": {"HF_TOKEN": "$HF_TOKEN"}})

Si l'outil MCP hf_jobs n'est pas disponible, utiliser l'API Python directement :

from huggingface_hub import HfApi, get_token
api = HfApi()
job_info = api.run_uv_job(
    script="path/to/training_script.py",  # chemin FICHIER, PAS contenu
    script_args=["--dataset_name", "cppe-5", ...],
    flavor="a10g-large",
    timeout=14400,  # secondes (4 heures)
    env={"PYTHONUNBUFFERED": "1"},
    secrets={"HF_TOKEN": get_token()},  # DOIT utiliser get_token(), PAS "$HF_TOKEN"
)
print(f"Job ID: {job_info.id}")

Différences critiques entre les deux méthodes :

Règles pour les deux méthodes :

• Le script d'entraînement DOIT inclure les métadonnées inline PEP 723 avec les dépendances
• NE PAS utiliser les paramètres image ou command (ceux-ci appartiennent à run_job(), pas run_uv_job())

2. Authentification via secrets du job + injection explicite du hub_token

Configuration du job DOIT inclure le token dans secrets — la syntaxe dépend de la méthode de soumission (voir le tableau ci-dessus).

Exigence du script d'entraînement : L'appel Trainer de Transformers exécute create_repo(token=self.args.hub_token) pendant __init__() quand push_to_hub=True. Le script d'entraînement DOIT injecter HF_TOKEN dans training_args.hub_token APRÈS l'analyse des arguments mais AVANT la création du Trainer. Le modèle scripts/object_detection_training.py inclut déjà ceci :

hf_token = os.environ.get("HF_TOKEN")
if training_args.push_to_hub and not training_args.hub_token:
    if hf_token:
        training_args.hub_token = hf_token

Si vous écrivez un script personnalisé, vous DOIT inclure cette injection de token avant l'appel Trainer(...).

• NE PAS appeler login() dans les scripts personnalisés sauf en répliquant le modèle complet de scripts/object_detection_training.py
• NE PAS compter sur la résolution implicite du token (hub_token=None) — peu fiable dans Jobs
• Voir la compétence hugging-face-jobs → Token Usage Guide pour les détails complets

3. Attribut JobInfo

Accéder à l'identifiant du job en utilisant .id (PAS .job_id ou .name — ceux-ci n'existent pas) :

job_info = api.run_uv_job(...)  # ou hf_jobs("uv", {...})
job_id = job_info.id  # Correct -- retourne une chaîne comme "687fb701029421ae5549d998"

4. Drapeaux d'entraînement requis et syntaxe booléenne HfArgumentParser

scripts/object_detection_training.py utilise HfArgumentParser — toute la config est passée via script_args. Les arguments booléens ont deux syntaxes :

• Champs bool (par exemple push_to_hub, do_train) : Utiliser comme drapeaux simples (--push_to_hub) ou nier avec le préfixe --no_ (--no_remove_unused_columns)
• Champs Optional[bool] (par exemple greater_is_better) : DOIT passer la valeur explicite (--greater_is_better True). Le simple --greater_is_better provoque error: expected one argument

Drapeaux requis pour la détection d'objets :

--no_remove_unused_columns          # DOIT : préserve la colonne image pour pixel_values
--no_eval_do_concat_batches         # DOIT : les images ont différents nombres de boîtes cibles
--push_to_hub                       # DOIT : l'environnement est éphémère
--hub_model_id username/model-name
--metric_for_best_model eval_map
--greater_is_better True            # DOIT passer "True" explicitement (Optional[bool])
--do_train
--do_eval

Drapeaux requis pour la classification d'images :

--no_remove_unused_columns          # DOIT : préserve la colonne image pour pixel_values
--push_to_hub                       # DOIT : l'environnement est éphémère
--hub_model_id username/model-name
--metric_for_best_model eval_accuracy
--greater_is_better True            # DOIT passer "True" explicitement (Optional[bool])
--do_train
--do_eval

Drapeaux requis pour la segmentation SAM/SAM2 :

--remove_unused_columns False       # DOIT : préserve input_boxes/input_points
--push_to_hub                       # DOIT : l'environnement est éphémère
--hub_model_id username/model-name
--do_train
--prompt_type bbox                  # ou "point"
--dataloader_pin_memory False       # DOIT : évite les problèmes pin_memory avec collator personnalisé

5. Gestion des timeouts

La valeur par défaut de 30 min est TROP COURTE pour la détection d'objets. Définir minimum 2-4 heures. Ajouter 30% de buffer pour le chargement du modèle, prétraitement et Hub push.

6. Monitoring Trackio

Trackio est toujours activé dans le script d'entraînement de détection d'objets — il appelle trackio.init() et trackio.finish() automatiquement. Aucun besoin de passer --report_to trackio. Le nom du projet est pris de --output_dir et le nom de run de --run_name. Pour la classification d'images, passer --report_to trackio dans TrainingArguments.

Dashboard à : https://huggingface.co/spaces/{username}/trackio

Sélection de modèle et matériel

Modèles de détection d'objets recommandés

Commencer avec ustc-community/dfine-small-coco pour une itération rapide. Passer à D-FINE Large ou RT-DETR v2 R50 pour une meilleure précision.

Modèles de classification d'images recommandés

Tous les modèles timm/ fonctionnent directement via AutoModelForImageClassification (chargés comme TimmWrapperForImageClassification). Voir references/timm_trainer.md pour les détails.

Commencer avec timm/mobilenetv3_small_100.lamb_in1k pour une itération rapide. Passer à timm/resnet50.a1_in1k ou timm/vit_base_patch16_dinov3.lvd1689m pour une meilleure précision.

Modèles de segmentation SAM/SAM2 recommandés

Commencer avec facebook/sam2.1-hiera-small pour une itération rapide. Les modèles SAM2 sont généralement plus efficaces que SAM v1 à qualité similaire. Seul le décodeur de masque est entraîné par défaut (encodeurs de vision et de prompts gelés).

Recommandation de matériel

Tous les modèles OD et IC recommandés contiennent moins de 100M paramètres — t4-small (16 GB VRAM, $0.40/hr) est suffisant pour tous. Les modèles de classification d'images sont généralement plus petits et plus rapides que les modèles de détection d'objets — t4-small gère même ViT-Base confortablement. Pour les modèles SAM2 jusqu'à hiera-base-plus, t4-small est suffisant puisque seul le décodeur de masque est entraîné. Pour sam2.1-hiera-large ou les modèles SAM v1, utiliser l4x1 ou a10g-large. Upgrade uniquement si vous atteignez OOM à partir de grandes tailles de batch — réduire d'abord la taille de batch avant de changer le matériel. Chemin d'upgrade courant : t4-small → l4x1 ($0.80/hr, 24 GB) → a10g-large ($1.50/hr, 24 GB).

Pour la liste complète des saveurs de matériel : consulter la compétence hugging-face-jobs. Pour l'estimation des coûts : exécuter scripts/estimate_cost.py.

Démarrage rapide — Détection d'objets

Le script_args ci-dessous est le même pour les deux méthodes de soumission. Voir la directive #1 pour les différences critiques entre elles.

OD_SCRIPT_ARGS = [
    "--model_name_or_path", "ustc-community/dfine-small-coco",
    "--dataset_name", "cppe-5",
    "--image_square_size", "640",
    "--output_dir", "dfine_finetuned",
    "--num_train_epochs", "30",
    "--per_device_train_batch_size", "8",
    "--learning_rate", "5e-5",
    "--eval_strategy", "epoch",
    "--save_strategy", "epoch",
    "--save_total_limit", "2",
    "--load_best_model_at_end",
    "--metric_for_best_model", "eval_map",
    "--greater_is_better", "True",
    "--no_remove_unused_columns",
    "--no_eval_do_concat_batches",
    "--push_to_hub",
    "--hub_model_id", "username/model-name",
    "--do_train",
    "--do_eval",
]

from huggingface_hub import HfApi, get_token
api = HfApi()
job_info = api.run_uv_job(
    script="scripts/object_detection_training.py",
    script_args=OD_SCRIPT_ARGS,
    flavor="t4-small",
    timeout=14400,
    env={"PYTHONUNBUFFERED": "1"},
    secrets={"HF_TOKEN": get_token()},
)
print(f"Job ID: {job_info.id}")

Principaux script_args OD

• --model_name_or_path — recommandé : "ustc-community/dfine-small-coco" (voir tableau de modèles ci-dessus)
• --dataset_name — l'ID du dataset Hub
• --image_square_size — 480 (itération rapide) ou 800 (meilleure précision)
• --hub_model_id — "username/model-name" pour la persistance sur Hub
• --num_train_epochs — 30 typique pour la convergence
• --train_val_split — fraction à diviser pour la validation (défaut 0.15), définir si le dataset manque de split de validation
• --max_train_samples — tronquer l'ensemble d'entraînement (utile pour les exécutions de test rapides, par exemple "785" pour ~10% d'un dataset de 7.8K)
• --max_eval_samples — tronquer l'ensemble d'évaluation

Démarrage rapide — Classification d'images

IC_SCRIPT_ARGS = [
    "--model_name_or_path", "timm/mobilenetv3_small_100.lamb_in1k",
    "--dataset_name", "ethz/food101",
    "--output_dir", "food101_classifier",
    "--num_train_epochs", "5",
    "--per_device_train_batch_size", "32",
    "--per_device_eval_batch_size", "32",
    "--learning_rate", "5e-5",
    "--eval_strategy", "epoch",
    "--save_strategy", "epoch",
    "--save_total_limit", "2",
    "--load_best_model_at_end",
    "--metric_for_best_model", "eval_accuracy",
    "--greater_is_better", "True",
    "--no_remove_unused_columns",
    "--push_to_hub",
    "--hub_model_id", "username/food101-classifier",
    "--do_train",
    "--do_eval",
]

from huggingface_hub import HfApi, get_token
api = HfApi()
job_info = api.run_uv_job(
    script="scripts/image_classification_training.py",
    script_args=IC_SCRIPT_ARGS