Entraînement de modèles 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 GPUs gérés dans le cloud. Aucune configuration GPU locale requise — les résultats sont automatiquement sauvegardés sur le Hugging Face Hub.

Quand utiliser cette Skill

Utilisez cette skill quand les utilisateurs veulent :

• Affiner des modèles de détection d'objets (D-FINE, RT-DETR v2, DETR, YOLOS) sur des GPUs cloud ou localement
• Affiner des modèles de classification d'images (timm : MobileNetV3, MobileViT, ResNet, ViT/DINOv3, ou tout classificateur Transformers) sur des GPUs cloud ou localement
• 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 classificateurs d'images sur des datasets personnalisés
• Entraîner des modèles de segmentation sur des datasets masqués personnalisés avec des prompts
• Exécuter des jobs d'entraînement Vision sur l'infrastructure Hugging Face Jobs
• Assurer que les modèles Vision entraînés sont sauvegardés de façon permanente sur le Hub

Skills connexes

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

Exécution locale de scripts

Les scripts d'aide utilisent les dépendances inline PEP 723. Lancez-les avec uv run :

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

Checklist des prérequis

Avant de lancer un job 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() (outil) ou hf auth whoami (terminal)
• Token avec permissions write
• DOIT passer le token dans les secrets du job — voir la directive n°3 ci-dessous pour la syntaxe (outil MCP vs API Python)

Exigences du dataset — Détection d'objets

• Dataset doit exister sur le 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) — détection automatique et conversion
• Les catégories peuvent être des entiers ou des chaînes — les chaînes sont auto-mappées à des IDs entiers
• La colonne image_id est optionnelle — générée automatiquement si absente
• TOUJOURS valider les datasets inconnus avant l'entraînement GPU (voir section Validation du dataset)

Exigences du dataset — Classification d'images

• Dataset doit exister sur le 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 des entiers/chaînes simples — les chaînes sont auto-mappées
• Noms de colonne courants auto-détectés : label, labels, class, fine_label
• TOUJOURS valider les datasets inconnus avant l'entraînement GPU (voir section Validation du dataset)

Exigences du dataset — Segmentation SAM/SAM2

• Dataset doit exister sur le 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 des valeurs [x0,y0,x1,y1]
  • OU une colonne point dédiée avec des 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 du dataset)

Paramètres critiques

• Le timeout doit dépasser le temps d'entraînement attendu — Le default 30 min est TROP COURT. Voir la directive n°6 pour les valeurs recommandées.
• La sauvegarde Hub doit être activée — push_to_hub=True, hub_model_id="username/model-name", token dans secrets

Validation du dataset

Validez le format du dataset AVANT de lancer l'entraînement GPU pour éviter la cause n°1 d'é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é avant. Ignorer pour cppe-5 (le default dans le script d'entraînement).

Lancer l'inspecteur

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

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 l'outil MCP hf_jobs n'est pas 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,
)

Lire les résultats

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

Prétraitement automatique des 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), la sanification des bbox, la génération de image_id, le remapping catégorie chaîne→entier, et la troncature du dataset. Aucun prétraitement manuel nécessaire — assurez-vous simplement que le dataset a les colonnes objects.bbox et objects.category.

Workflow d'entraînement

Copiez cette checklist 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 Checklist des prérequis ci-dessus.

Étape 2 : Valider le dataset

Lancez l'inspecteur dataset AVANT de dépenser du temps GPU. Voir la section « Validation du dataset » ci-dessus.

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

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

AskUserQuestion({
    "questions": [
        {
            "question": "Voulez-vous d'abord faire un test rapide avec un sous-ensemble des données ?",
            "header": "Taille du dataset",
            "options": [
                {"label": "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": "Split des 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": "Flavor matériel",
            "options": [
                {"label": "t4-small ($0.40/hr)", "description": "1x T4, 16 GB VRAM — suffisant pour tous les modèles OD sous 100M params"},
                {"label": "l4x1 ($0.80/hr)", "description": "1x L4, 24 GB VRAM — plus d'espace pour les grandes images ou batch sizes"},
                {"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 tailles d'image"}
            ],
            "multiSelect": false
        }
    ]
})

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

Pour la détection d'objets, utilisez scripts/object_detection_training.py comme template en production. 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 passe par les arguments CLI dans script_args, JAMAIS 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 de l'espace de travail (créer si nécessaire) avec un nom descriptif comme training_<dataset>_<YYYYMMDD_HHMMSS>.py. Indiquez le chemin à l'utilisateur.
2. Soumettre en utilisant l'outil MCP hf_jobs (préféré) ou HfApi().run_uv_job() — voir la directive n°1 pour les deux méthodes. Passer toute la config via script_args.
3. Signaler l'ID du job (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 les demandes de vérification de statut — ne pas faire de polling automatique. Les jobs d'entraînement s'exécutent de façon asynchrone et peuvent prendre des heures.

Directives critiques

Ces règles évitent les défaillances courantes. Suivez-les exactement.

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

hf_jobs() est un outil MCP, PAS une fonction Python. Ne TENTEZ PAS de l'importer depuis huggingface_hub. Appelez-le 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, utilisez 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 de fichier, PAS le 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 (ils appartiennent à run_job(), pas à run_uv_job())

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

Config du job DOIT inclure le token dans les 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 appelle create_repo(token=self.args.hub_token) lors de __init__() quand push_to_hub=True. Le script d'entraînement DOIT injecter HF_TOKEN dans training_args.hub_token APRÈS le parsing des args mais AVANT la création du Trainer. Le template 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 DEVEZ inclure cette injection de token avant l'appel Trainer(...).

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

3. Attribut JobInfo

Accédez à l'identifiant du job en utilisant .id (PAS .job_id ou .name — 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. Flags d'entraînement requis et syntaxe booléenne HfArgumentParser

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

• Champs bool (p. ex., push_to_hub, do_train) : Utilisez comme bare flags (--push_to_hub) ou niez avec le préfixe --no_ (--no_remove_unused_columns)
• Champs Optional[bool] (p. ex., greater_is_better) : DOIT passer une valeur explicite (--greater_is_better True). Le bare --greater_is_better cause error: expected one argument

Flags 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 des nombres différents 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

Flags 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

Flags 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 le collator personnalisé

5. Gestion du timeout

Le default 30 min est TROP COURT pour la détection d'objets. Définissez le minimum 2-4 heures. Ajoutez un buffer de 30% pour le chargement du modèle, le prétraitement, et la sauvegarde Hub.

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. Pas besoin de passer --report_to trackio. Le nom du projet est tiré de --output_dir et le nom de la run de --run_name. Pour la classification d'images, passer --report_to trackio dans TrainingArguments.

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

Sélection du modèle et du matériel

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

Commencez avec ustc-community/dfine-small-coco pour l'itération rapide. Passez à 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.

Commencez avec timm/mobilenetv3_small_100.lamb_in1k pour l'itération rapide. Passez à timm/resnet50.a1_in1k ou timm/vit_base_patch16_dinov3.lvd1689m pour une meilleure précision.

Modèles de segmentation SAM/SAM2 recommandés

Commencez avec facebook/sam2.1-hiera-small pour l'itération rapide. Les modèles SAM2 sont généralement plus efficaces que SAM v1 à qualité similaire. Par défaut, seul le mask decoder est entraîné (les encodeurs vision et prompt sont gelés).

Recommandation matériel

Tous les modèles OD et IC recommandés sont sous 100M params — 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 confortablement même ViT-Base. Pour les modèles SAM2 jusqu'à hiera-base-plus, t4-small est suffisant puisque seul le mask decoder est entraîné. Pour sam2.1-hiera-large ou les modèles SAM v1, utilisez l4x1 ou a10g-large. Mettez à niveau seulement si vous rencontrez OOM à cause de grandes batch sizes — réduisez d'abord la batch size avant de changer le matériel. Chemin de mise à niveau courant : t4-small → l4x1 ($0.80/hr, 24 GB) → a10g-large ($1.50/hr, 24 GB).

Pour la liste complète des flavors matériel : consultez la skill hugging-face-jobs. Pour l'estimation des coûts : lancez scripts/estimate_cost.py.

Démarrage rapide — Détection d'objets

Les script_args ci-dessous sont identiques pour les deux méthodes de soumission. Voir la directive n°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}")

Key OD script_args

• --model_name_or_path — recommandé : "ustc-community/dfine-small-coco" (voir le tableau des 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 Hub
• --num_train_epochs — 30 typique pour la convergence
• --train_val_split — fraction pour le split de validation (default 0.15), définir si le dataset manque un split de validation
• --max_train_samples — tronquer l'ensemble d'entraînement (utile pour les runs de test rapides, p. ex. "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,
    flavor="t4-small",
    timeout=7200,
    env={"PYTHONUNBUFFERED": "1"},
    secrets={"HF_TOKEN": get_token()},
)
print(f"Job ID: {job_info.id}")

Key IC script_args

• --model_name_or_path — tout modèle timm/ ou modèle de classification Transformers (voir le tableau des modèles ci-dessus)
• --dataset_name — l'ID du dataset Hub
• --image_column_name — colonne contenant les images PIL (default : "image")
• --label_column_name — colonne contenant les labels de classe (default : "label")
• --hub_model_id — "username/model-name" pour la persistance Hub
• --num_train_epochs — 3-5 typique pour la classification (moins que OD)
• --per_device_train_batch_size — 16-64 (les modèles de classification utilisent moins de mémoire que OD)
• --train_val_split — fraction pour le split de validation (default 0.15), définir si le dataset manque un split de validation
• --max_train_samples / --max_eval_samples — tronquer pour les tests rapides

Démarrage rapide — Segmentation SAM/SAM2

SAM_SCRIPT_ARGS = [
    "--model_name_or_path", "facebook/sam2.1-hiera-small",
    "--dataset_name", "merve/MicroMat-mini",
    "--prompt_type", "bbox",
    "--prompt_column_name", "prompt",
    "--output_dir", "sam2-finetuned",
    "--num_train_epochs", "30",
    "--per_device_train_batch_size", "4",
    "--learning_rate", "1e-5",
    "--logging_steps", "1",
    "--save_strategy", "epoch",
    "--save_total_limit", "2",
    "--remove_unused_columns", "False",
    "--dataloader_pin_memory", "False",
    "--push_to_hub",
    "--hub_model_id", "username/sam2-finetuned",
    "--do_train",
    "--report_to", "trackio",
]

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

Key SAM script_args

• --model_name_or_path — modèle SAM ou SAM2 (voir le tableau des modèles ci-dessus); détection automatique SAM vs SAM2
• --dataset_name — l'ID du dataset Hub (p. ex., "merve/MicroMat-mini")
• --prompt_type — "bbox" ou "point" — type de prompt dans le dataset
• --prompt_column_name — colonne avec les prompts encodés JSON (default : "prompt")
• --bbox_column_name — colonne bbox dédiée (alternative à la colonne de prompt JSON)
• --point_column_name — colonne point dédiée (alternative à la colonne de prompt JSON)
• --mask_column_name — colonne avec les masques ground-truth (default : "mask")
• --hub_model_id — "username/model-name" pour la persistance Hub
• --num_train_epochs — 20-30 typique pour l'affinage SAM
• --per_device_train_batch_size — 2-4 (les modèles SAM utilisent une mémoire significative)
• --freeze_vision_encoder / --freeze_prompt_encoder — geler les poids des encodeurs (default : les deux gelés, seul le mask decoder s'entraîne)
• --train_val_split — fraction pour le split de validation (default 0.1)

Vérifier le statut du job

Outil MCP (s'il est disponible) :

hf_jobs("ps")                                   # Lister tous les jobs
hf_jobs("logs", {"job_id": "your-job-id"})      # Voir les logs
hf_jobs("inspect", {"job_id": "your-job-id"})   # Détails du job

Fallback API Python :

from huggingface_hub import HfApi
api = HfApi()
api.list_jobs()                                  # Lister tous les jobs
api.get_job_logs(job_id="your-job-id")           # Voir les logs
api.get_job(job_id="your-job-id")                # Détails du job

Modes d'échec courants

OOM (CUDA out of memory)

Réduisez per_device_train_batch_size (essayez 4, puis 2), réduisez IMAGE_SIZE, ou mettez à niveau le matériel.

Erreurs de format du dataset

Lancez d'abord scripts/dataset_inspector.py. Le script d'entraînement auto-détecte xyxy vs xywh, convertit les catégories chaîne en IDs entiers, et ajoute image_id s'il manque. Assurez-vous que objects.bbox contient des listes de 4 valeurs de coordonnées en pixels absolus et objects.category contient soit des IDs entiers soit des labels chaîne.

Échecs de sauvegarde Hub (401)

Vérifiez : (1) les secrets du job incluent le token (voir la directive n°2), (2) le script définit training_args.hub_token AVANT de créer le Trainer, (3) push_to_hub=True est défini, (4) hub_model_id correct, (5) le token a les permissions write.

Timeout du job

Augmentez le timeout (voir le tableau de la directive n°5), réduisez les epochs/dataset, ou utilisez la stratégie checkpoint avec hub_strategy="every_save".

KeyError: 'test' (split test manquant)

Le script d'entraînement de détection d'objets gère ceci gracieusement — il revient au split validation. Assurez-vous d'utiliser le dernier scripts/object_detection_training.py.

Dataset single-class : "iteration over a 0-d tensor"

torchmetrics.MeanAveragePrecision retourne des tenseurs scalaires (0-d) pour les métriques par-classe quand il n'y a qu'une classe. Le template scripts/object_detection_training.py gère ceci en appelant .unsqueeze(0) sur ces tenseurs. Assurez-vous d'utiliser le dernier template.

Mauvaise performance de détection (mAP < 0.15)

Augmentez les epochs (30-50), assurez-vous 500+ images, vérifiez mAP par-classe pour les classes déséquilibrées, essayez différents learning rates (1e-5 à 1e-4), augmentez la taille d'image.

Pour le dépannage complet : voir references/reliability_principles.md

Fichiers de référence

• scripts/object_detection_training.py — Script d'entraînement détection d'objets prêt pour la production
• scripts/image_classification_training.py — Script d'entraînement classification d'images prêt pour la production (support des modèles timm)
• scripts/sam_segmentation_training.py — Script d'entraînement segmentation SAM/SAM2 prêt pour la production (prompts bbox & point)
• scripts/dataset_inspector.py — Valider le format du dataset pour OD, classification, et segmentation SAM
• scripts/estimate_cost.py — Estimer les coûts d'entraînement pour tout modèle vision (inclut SAM/SAM2)
• references/object_detection_training_notebook.md — Workflow entraînement détection d'objets, stratégies augmentation, et patterns d'entraînement
• references/image_classification_training_notebook.md — Workflow classification d'images avec ViT, prétraitement, et évaluation
• references/finetune_sam2_trainer.md — Walkthrough affinage SAM2 avec dataset MicroMat, perte DiceCE, et intégration Trainer
• references/timm_trainer.md — Utiliser les modèles timm avec HF Trainer (TimmWrapper, transforms, exemple complet)
• references/hub_saving.md — Guide détaillé persistance Hub et checklist de vérification
• references/reliability_principles.md — Principes de prévention d'échecs issus de l'expérience production

Liens externes

• Transformers Object Detection Guide
• Transformers Image Classification Guide
• DETR Model Documentation
• ViT Model Documentation
• HF Jobs Guide — Documentation principale Jobs
• HF Jobs Configuration — Matériel, secrets, timeouts, namespaces
• HF Jobs CLI Reference — Interface ligne de commande
• Object Detection Models
• Image Classification Models
• SAM2 Model Documentation
• SAM Model Documentation
• Object Detection Datasets
• Image Classification Datasets