tao-finetune-huggingface-model

Ajustement fin (fine-tuning) local sur GPU NVIDIA pour les modèles HuggingFace, basé sur une documentation récupérée en direct avec des références curatées comme filet de sécurité de repli. Un conteneur NGC, quelques scripts ciblés, une seule publication sur HF Hub. Suivez les règles de ce fichier ; n'improvisez pas.

Ordre d'autorité (du plus élevé au plus bas) :

1. Entrée utilisateur — model_id, dataset_id, training_method, et les overrides de config.yaml explicites.
2. Recherche en direct — fiche modèle, exemple de dépôt HF, script d'ajustement fin de l'auteur, documentation des tâches HF, article scientifique ; toujours récupéré (Étape 3 + references/research-priorities.md).
3. Références curatées (references/*.md) — repli lorsque la recherche en direct est silencieuse ou ambiguë.
4. Mémoire des données d'entraînement — dernier recours ; suspect, à croiser avec (2)/(3).

La résolution des conflits entre (2) et (3), ainsi que la note sur les écarts de ligne source, se trouvent dans references/research-priorities.md.

Entrées

Requis :

• model_id — ID du modèle HuggingFace, par ex. google/vit-base-patch16-224

Identifiants conditionnels (lus depuis l'environnement de session, exportés avant le lancement s'ils sont présents) :

• HF_TOKEN — uniquement lorsque le modèle/dataset est gated (lecture) ou que push_to_hub est activé (écriture) ; public + public + push_to_hub: false n'en nécessite aucun. La valeur n'est jamais lue — seule sa présence est vérifiée via [ -n "$HF_TOKEN" ].
• WANDB_API_KEY, WANDB_PROJECT — uniquement lorsque WandB est activé ; WANDB_MODE=disabled permet de s'exclure.

Dataset — exactement un :

• dataset_id — ID du dataset HuggingFace (source : hf)
• local_dataset_path — dossier ou fichier local (source : local) ; local_dataset_format optionnel ∈ {auto, imagefolder, coco, voc, jsonl, arrow, parquet, csv} (par défaut : détection automatique).
• (omission) — l'agent recommande des datasets populaires (source : recommend)

Facultatifs (avec valeurs par défaut) :

• task_type — détecté automatiquement à partir de la config + de la fiche modèle
• n_train=10000, n_eval=1000, n_epochs=3, lora_r=16
• output_dir=./output/<model_short_name></model_short_name>
• hf_model_repo — cible de publication ; si non défini et que HF_TOKEN a un accès en écriture, dérivé automatiquement comme <whoami>/<model_short_name>-finetuned</model_short_name></whoami>.
• push_to_hub=True — définir sur False pour ignorer
• skip_baseline=False — ignorer l'évaluation de la ligne de base zéro-shot

Livrables facultatifs (désactivés par défaut) :

emit_progress_log: false   # output_dir/PROGRESS.md (journal par étape)
emit_report:       false   # reports/report.{pdf,html} avec courbes et échantillons
emit_unit_tests:   false   # tests/ avec des tests de batch hétérogène sur fausses données

Toutes les valeurs résident dans output_dir/config.yaml. Ne jamais les coder en dur dans Python.

Plateforme d'exécution

Cette compétence orchestre ce qui doit être exécuté ; les compétences plateforme possèdent comment l'exécuter sur un hôte GPU — lisez-les d'abord.

Plateforme par défaut : local-docker — construire une image éphémère (run-<short>:latest</short>) et l'exécuter sur le daemon Docker local. Ne demander que si l'utilisateur a explicitement besoin d'un backend différent (GPU distant Brev, SLURM/Kubernetes) ; puis exécuter la Pré-vérification de cette plateforme d'abord et router les commandes docker run des Étapes 4–5 à travers elle. Les pré-vérifications de runtime GPU et de présence d'identifiants (valeurs jamais lues), l'ensemble canonique d'indicateurs docker run, la commande de sélection list_tao_platforms.py, et les indicateurs spécifiques au flux de travail (--entrypoint /bin/bash -lc, PYTORCH_CUDA_ALLOC_CONF, --name hft_train) se trouvent dans references/workflow-intake-preflight.md.

Références — filet de sécurité de repli

Consultées uniquement lorsque la recherche en direct est silencieuse, ambiguë ou indisponible ; les docs en direct l'emportent toujours pour le modèle spécifique et l'API actuelle. Chaque étape lie les références dont elle a besoin ; catalogue complet dans references/detailed-workflow.md.

Toujours activé : core-rules.md, error-playbook.md, compat-workarounds.md, model-discovery.md, dataset-recommendations.md, dataset-sources.md, dataset-patterns.md, hardware-container.md, research-priorities.md, cv-scripts.md, vlm-scripts.md, docker-runs.md, hub-push.md, pipeline-skill-template.md, deliverables.md. Activation optionnelle (lorsque leur indicateur/besoin s'applique) : progress-tracking.md, testing.md, reporting.md, workflow-intake-preflight.md, workflow-generate-train.md, workflow-push-rerun.md.

Règle : avant de se replier, consigner la source en direct essayée et pourquoi elle était insuffisante (config.yaml notes:, et PROGRESS.md si activé). Les marqueurs [FETCH LIVE] dans cv-scripts.md / vlm-scripts.md sont une liste de vérification de recherche, pas du code à inclure en ligne — re-récupérer l'URL listée si un bloc n'a pas de résultat Étape 3.

Règles fondamentales

Comportements non négociables. Version courte (énumération complète — liste des imports hallucinés, liste des éléments jamais sans approbation, tableaux complets de récupération d'erreurs et de dimensionnement matériel — dans references/core-rules.md, consulter avant toute décision au moment de l'entraînement) :

• Vos connaissances de la bibliothèque HF sont obsolètes. Récupérez les docs en direct (fiche modèle, exemple de dépôt HF, doc de tâche) avant d'écrire tout code ML — ne générez pas les args du formateur / collateur / transformations depuis la mémoire (Étape 3).
• Test de fumée sur de vraies données avec --max_steps 1 avant toute exécution complète ; aucune mise en lot sans test de fumée vérifié.
• Ne substituez jamais silencieusement model_id, dataset_id, ou training_method — si ce que l'utilisateur a demandé ne charge pas, arrêtez et demandez.
• La récupération d'erreur est à modification minimale. OOM → diviser le batch par deux, doubler grad_accum, activer le point de contrôle de gradient (pas de changement LoRA sans approbation) ; NaN → réduire LR de 10× ; perte plate → inspecter le collateur ; même erreur 3× → arrêter et demander. Ne bouclez pas.
• Les colonnes du dataset sont vérifiées AVANT le collateur — renommer dans prepare_data.py ; restructuration nécessaire → arrêter et demander.
• Règle empirique de dimensionnement matériel (bf16) : ≤3B → 24 GB, 7–13B → 80 GB, 30B+ → multi-GPU ou LoRA sur 1× 80 GB, 70B+ → 8× 80 GB ou LoRA. L'ajustement fin complet ne tiendra pas et aucun LoRA n'est demandé → demander avant de changer.

Flux de travail — 6 étapes

Passage unique, séquentiel ; chaque étape a une porte claire avant que la suivante ne commence.

Étape 1 — Inspecter & qualifier

Objectif : décider si l'on procède. Sonder le modèle + le dataset, appliquer acceptation/rejet, enregistrer les correctifs de compatibilité applicables, écrire le config.yaml initial.

Prérequis : MODEL_ID, DATASET_ID / local_dataset_path optionnels, HF_TOKEN optionnel, OUTPUT_DIR (par défaut ./output/<model_short_name></model_short_name>). Les sondages s'exécutent dans un conteneur Docker python:3.12-slim uniquement CPU (.probe/scratch monté en liaison) afin que l'hôte n'ait pas besoin de virtualenv — Docker doit exister d'abord. Garde de présence Docker, environnement du conteneur, invocation complète du sondage, et scripts de sondage modèle/dataset se trouvent dans references/workflow-intake-preflight.md, references/model-discovery.md et references/dataset-sources.md.

Exigences de sondage :

• Modèle : charger AutoConfig, lire les tags de la fiche modèle, détecter la tâche à partir de architectures + tags + exemples de carte (journalisation de repli dans model-discovery.md).
• Dataset : pour les datasets recommandés, présenter d'abord 3-5 choix de dataset-recommendations.md ; pour les données locales, monter en liaison en lecture seule et utiliser la détection de format de dataset-sources.md.
• Rejeter tôt si la config du modèle échoue, la tâche est hors périmètre, aucune source de recette n'existe, ou le dataset ne peut pas charger / correspondre au schéma de tâche.
• Évaluer compat-workarounds.md contre le modèle/la tâche ; reporter les règles dépendantes du matériel à l'Étape 2.

Écrire le config.yaml initial (model_id, task, dataset_id ou local_dataset_path, research_sources: [] rempli à l'Étape 3, applicable_workarounds: de l'Étape 1, notes: [] pour les replis de référence, push_to_hub: true par défaut — modèle annoté dans references/workflow-intake-preflight.md). Optionnellement rm -rf "$OUTPUT_DIR/.probe"une fois la porte franchie.

Porte : config.yaml existe avec modèle, dataset, tâche, applicable_workarounds ; ne pas procéder si un champ est manquant.

Étape 2 — Audit matériel & image NGC

Objectif : vérifier Docker + GPU + disque, choisir l'image PyTorch NGC en direct, finaliser les règles de compatibilité dépendantes du matériel.

2a. Audit (porte dure) — trois vérifications (commandes dans references/workflow-intake-preflight.md) :

1. Runtime hôte GPU — setup-nvidia-gpu-host.sh --backend docker --check-only de tao-setup-nvidia-gpu-host ; en cas d'échec, demander l'approbation puis relancer avec --install --yes.
2. Avertissement disque libre — override via MIN_DISK_GB (par défaut 100 GB) ; recommander ≥ 100 GB pour la base NGC (~20 GB) + cache HF + checkpoints + données.
3. Présence d'identifiants conditionnels (de l'environnement de session, valeurs jamais lues) — HF_TOKEN uniquement lorsque gated ou push_to_hub est activé ; WANDB_* uniquement lorsque WandB est activé.

Ne pas procéder à l'Étape 4 en cas d'échec dur — le docker build de l'Étape 4 tire une base NGC de 20+ GB, et un nvidia-container-toolkit manquant ne se manifeste que plus tard par could not select device driver "" with capabilities: [[gpu]]. Enregistrer gpu_count, gpu_name, driver_major, vram_gb_per_gpu dans config.yaml.

2b. Choisir l'image NGC (en direct) : depuis la matrice de support des frameworks de deep learning NVIDIA (https://docs.nvidia.com/deeplearning/frameworks/support-matrix/index.html), section conteneur PyTorch NGC, choisir l'image de version la plus élevée où Min driver ≤ detected driver_major et CUDA du conteneur ≤ CUDA Toolkit hôte (correspondre étroitement pour aligner cuDNN / TensorRT). Ne pas rejeter une image pour un tag PyTorch aN/bN/rcN — NGC valide l'image complète ; choisir celle la plus récente alignée sur CUDA et laisser compat-workarounds.md gérer les problèmes par version. Si la matrice est inaccessible, utiliser les replis dans references/hardware-container.md ; défaut nvcr.io/nvidia/pytorch:24.09-py3 (driver ≥ 545 ; bug SDPA+GQA — si num_key_value_heads , définirattn_implementation: "eager").Enregistrerngc_imagedansconfig.yaml.

2c. Réévaluer les règles de compatibilité dépendantes du matériel : relancer l'analyse de compat-workarounds.md pour les entrées dont le detect nécessite hw ; mettre à jour applicable_workarounds: sur place.

2d. Vérification d'ajustement du modèle : estimer param_bytes ≈ 2×param_count (bf16) ; si

60% de vram_gb_per_gpu × 1e9, recommander LoRA dans le résumé visible par l'utilisateur.

Porte : config.yaml contient ngc_image, gpu_count, gpu_name, driver_major, vram_gb_per_gpu ; correctifs de compatibilité dépendants du matériel enregistrés.

Étape 3 — Rechercher la recette

Objectif : récupérer la recette en direct — les connaissances sur les données d'entraînement de transformers/trl/peft sont suspectes, donc l'Étape 3 est non négociable. Parcourir references/research-priorities.md dans l'ordre de priorité (Priorité 1 → 6) ; s'arrêter une fois que vous avez, pour la tâche détectée :

• AutoModel / classe de processeur
• Transformations d'entraînement + évaluation
• Collateur
• compute_metrics
• Indices d'hyperparamètres (LR, taille de batch, époques, planificateur)

Enregistrer les résultats dans meta/recipe.md, ajouter les URL sources à config.yaml: research_sources:. Un emplacement sans résultat en direct se replie sur l'échafaudage correspondant (cv-scripts.md / vlm-scripts.md), consigné comme "repli vers échafaudage — aucune source en direct pour " sous notes:. Les règles de résolution de conflit sont dans references/research-priorities.md.

Porte : chaque emplacement requis rempli, avec une URL source ou une note de repli échafaudage.

Étape 4 — Générer le projet & test de fumée

Objectif : écrire tous les scripts, construire l'image, préparer les données, exécuter un test de fumée en 1 étape sur de vraies données (un docker build, deux docker runs).

4a. Générer les fichiers du projet dans output_dir/ : config.yaml, Dockerfile, requirements.txt, prepare_data.py, train.py, run_eval.py, infer.py, merge_lora.py optionnel, tests/ optionnel, .gitignore. La recherche en direct Étape 3 est l'autorité ; cv-scripts.md / vlm-scripts.md donnent uniquement la forme de l'échafaudage. Appliquer chaque entrée applicable_workarounds comme bloc Dockerfile, épingle de exigence, override de config, ou variable d'environnement d'exécution. Règles dures : run_eval.py conserve ce nom de fichier exact (évite les collisions avec le package HF evaluate) ; chaque .py généré commence par l'en-tête de copyright Apache-2.0 NVIDIA et tout émetteur échoue s'il est manquant ; emit_unit_tests: true génère et exécute des tests selon references/testing.md. Corps des scripts, forme du Dockerfile, et contrat d'émetteur se trouvent dans references/workflow-generate-train.md.

4b. Construire, préparer, fumer — docker build -t run-<short>:latest .</short>, puis prepare_data et l'exécution --smoke --max_steps 1 (references/docker-runs.md§1-3). Critères de passage du test de fumée (dans logs/smoke.log) :

• Aucune exception
• La perte est finie (pas 0.0, pas NaN)
• grad_norm > 0 à l'étape 1

Si emit_unit_tests: true, exécuter également pytest tests/ dans le conteneur. Tout échec → ARRÊTER.

4c. Résumé de pré-vérification — avant l'entraînement complet, imprimer et vérifier : URL de référence, colonnes du dataset, cible Hub, cible de surveillance, image NGC, matériel, perte/test de norm grad de fumée.

Porte : fichiers du projet écrits, image construite, test de fumée RÉUSSI, pré-vérification sans champs vides.

Étape 5 — Entraîner, évaluer, inférer

Objectif : évaluation de base, entraînement complet, évaluation post-entraînement, fusion LoRA optionnelle, 5 échantillons d'inférence (toutes les commandes : references/docker-runs.md §4-8).

Multi-GPU : préfixer torchrun --nproc_per_node=$gpu_count à python train.py.

Pendant que l'entraînement diffuse, surveiller docker logs -f hft_train : la perte devrait diminuer dans 10-20 étapes ; perte plate (bug collateur/masquage étiquette), NaN (LR trop élevé), et OOM arrêtent tous l'exécution — récupération dans references/core-rules.md. Si emit_report: true, exécuter report.py après l'Étape 5e selon references/reporting.md.

Porte : tout ce qui suit :

• checkpoints/final/ (ou checkpoints/merged/ pour LoRA) existe
• reports/eval_results.json contient une métrique principale numérique
• reports/baseline_results.json existe (sauf si ignoré)
• reports/inference_samples/ contient 5 échantillons
• l'URL wandb montre une perte descendante

Étape 6 — Publier & émettre la compétence de relance

Objectif : publier l'exécution et la rendre reproductible sans nouvelle recherche.

Publier selon references/hub-push.md (poids, fiche modèle, JSONs eval/baseline, config.yaml, Dockerfile, requirements.txt, échantillons d'inférence, rapports lorsqu'émis) sauf si push_to_hub: false est explicite. Émettre <output_dir>/skills/run-<short>/SKILL.md</short></output_dir> depuis references/pipeline-skill-template.md — substituer chaque espace réservé, inclure les métadonnées YAML complètes + le commentaire HTML de copyright NVIDIA, et faire échouer tout émetteur s'ils sont manquants.

Porte (critères de fin) : tout ce qui suit :

• Porte Étape 5 franchie
• Le dépôt HF Hub existe à l'URL résolue avec poids + carte + results/(sauf si push_to_hub: false)
• <output_dir>/skills/run-<short>/SKILL.md</short></output_dir> existe, aucun <placeholder></placeholder> laissé, avec métadonnées + commentaire HTML de copyright selon pipeline-skill-template.md

Message final : URL wandb, URL HF Hub, baseline -> métrique principale ajustée fin, reports/inference_samples/, et le chemin de la compétence de relance.

Jeu de gestion d'erreurs

En cas d'erreur d'exécution connue, consulter le tableau symptôme → correction minimale dans references/error-playbook.md (point d'entrée NGC, régressions PyTorch/Transformers, ABI numpy, bbox Albumentations, PEFT/checkpointing, largeur cible LoRA, lacunes d'augmentation CV, OOM à l'étape 0) avant de redessiner quoi que ce soit. Lorsqu'une ligne de ce tableau se déclenche deux fois sur plusieurs exécutions, la soulever dans compat-workarounds.md avec une règle detect — appliquée automatiquement à l'Étape 1 avant que l'erreur ne se produise.

Style de communication

• Concis. Pas de remplissage, pas de répétition de la demande ; réponses d'un mot lorsque approprié.
• Toujours inclure les URL directes du Hub et de wandb lors de la référence aux artefacts.
• En cas d'erreur : indiquer ce qui s'est mal passé, pourquoi, ce que vous avez changé — pas de menus.
• Ne présentez jamais "Option A/B/C" pour une demande ayant une réponse claire. Agissez.

Exemples de pipelines

• tao-rerun-convnext-cifar10
• tao-rerun-detr-cppe5
• tao-rerun-segformer-foodseg103
• tao-rerun-smolvlm-vqav2