<!-- Copyright (c) 2026, NVIDIA CORPORATION. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->

Skill d'intégration TAO-HF

Intégrer un modèle Computer Vision HuggingFace (HF) dans l'écosystème NVIDIA TAO Toolkit. Suivre les phases de manière itérative — non purement linéaire — en appliquant une boucle construire → tester → déboguer → corriger → retester à chaque étape.

Ce SKILL.md est le coordinateur de workflow. Chaque phase dispose d'un fichier de référence dédié sous references/ avec le contenu complet pas à pas, les blocs de code, les invocations Docker et les critères d'acceptance. Consulter la référence correspondante au début de chaque phase — les résumés ci-dessous ne suffisent pas en eux-mêmes.

Règle local uniquement

Tout le travail est strictement local. Vous ne pouvez que lire/cloner depuis les dépôts distants ; toutes les éditions de fichiers, les compilations Docker et les exécutions de tests restent sur la machine locale. Ne PAS faire de git commit/git push/créer de branches distantes (GitLab, GitHub, HuggingFace), créer de merge requests / pull requests / issues, ou uploader/publier/pousser des images Docker vers un registre ou un magasin d'artefacts. Ceci découle de la structure locale bind-mountée dans references/execution-and-debugging.md.

Priorité des submodules et plateforme d'exécution

local-docker est la plateforme par défaut. L'utilisateur clone les quatre dépôts TAO (tao-core, tao-pytorch, tao-deploy, tao-dataservices) indépendamment dans un répertoire de travail unique ; chaque dépôt porte aussi des submodules imbriqués tao-core/ (et tao-pytorch/) figés à leur commit original non modifié et obsolètes — les modifications résident uniquement dans le tao-core/ de haut niveau. Toujours installer depuis le tao-core/ de haut niveau, jamais depuis <repo>/tao-core/ (le submodule imbriqué supprime silencieusement toutes les modifications). L'override de la CI pip install tao-core/ suit trois règles : monter le répertoire de travail complet (-v $(pwd):/workspace) ; pip install /workspace/tao-core EN PREMIER pour que les schémas modifiés priment ; placer le tao-core de haut niveau en premier sur PYTHONPATH (-e PYTHONPATH=/workspace/tao-core:/workspace/tao-pytorch).

Chaque test, exécution de vérification et validation end-to-end s'exécute dans un conteneur TAO Toolkit préparé localement (tao-pytorch-base:latest, tao-deploy-base:latest, optionnellement tao-dataservices-base:latest, tous issus de la Phase 0), avec les clones locaux bind-montés à /workspace et installés via pip install /workspace/tao-core + setup.py develop. Tout travail Python s'exécute dans des conteneurs — pas de venvs hôte, pas d'installations pip install sur l'hôte. Les skills de plateforme maîtrisent le comment exécuter les conteneurs — GPU runtime hôte via tao-setup-nvidia-gpu-host ; drapeaux docker run / authentification NGC / mounts / passage d'env / --ipc=host/--shm-size / inspection / modes d'erreur via tao-run-on-docker et tao-run-on-local-docker. Ce workflow spécifie uniquement quoi exécuter à l'intérieur et n'enfreint jamais ces conventions. L'arborescence du répertoire de travail annoté, l'ensemble de drapeaux docker run canonical avec les additions -w/PYTHONPATH/install-shell spécifiques au workflow, trois contextes d'isolation, quatre règles d'isolation, la Boucle de développement et le tableau de la Playbook de débogage : references/execution-and-debugging.md.

Carte des phases

Les sept phases (objectifs complets + critères d'acceptance ci-dessous ; références par phase) :

• Phase 0 — Prérequis + images TAO Toolkit + étiquettes d'images locales : phase-0-prereqs.md
• Phase 1 — Environnement d'inspection HF, valider modèle HF + dataset : phase-1-inspection.md, hf-inspection.md
• Phase 2 — Modèle de référence TAO le plus proche : phase-2-codebase.md, task-type-guide.md
• Phase 3 — Config tao-core + trainer tao-pytorch / évaluation native / inference : phase-3-implementation.md, tao-patterns.md, repo-structure.md
• Phase 4 — Export ONNX + moteur TensorRT tao-deploy, inference, évaluation : phase-4-deploy.md
• Phase 5 — Packaging (setup.py console_scripts) + tests L0 : phase-5-packaging.md
• Phase 6 — Tests basés conteneur + validation de pipeline end-to-end : phase-6-container-tests.md, docker-patterns.md
• Phase 7 — (conditionnel) Tuning de précision / latence / taille : phase-7-optimization.md

IMPORTANT — Exécution continue jusqu'à la Phase 6 : Ne PAS s'arrêter après l'implémentation (Phases 3–5) pour attendre l'utilisateur lancent les tests ; procéder immédiatement à la Phase 6 obligatoire. L'implémentation n'est complète que lorsque les tests passent dans les conteneurs TAO Toolkit et que le pipeline end-to-end est validé. Appliquer la boucle construire-tester-déboguer à chaque étape — écrire, tester immédiatement, corriger en cas d'échec, ne jamais accumuler de code non testé.

Phase 0 — Vérification des prérequis

Objectif : vérifier Python 3.10+ et git ; déléguer la vérification hôte du driver NVIDIA / CUDA / Docker / NVIDIA Container Toolkit à tao-setup-nvidia-gpu-host ; vérifier la connexion NGC docker login pour nvcr.io. Ensuite, demander à l'utilisateur les références des images TAO Toolkit (tao-pytorch, tao-deploy, optionnellement tao-dataservices), les récupérer et préparer les étiquettes d'images locales tao-pytorch-base:latest, tao-deploy-base:latest, tao-dataservices-base:latest pour les Phases 3–6. La préparation supprime les packages TAO déjà présents dans ces images pour que les clones locaux de l'utilisateur (montés à /workspace/...) s'installent et soient détectés au moment de l'exécution. Arrêt définitif si une vérification échoue. Commandes complètes, formulation des demandes utilisateur et snippets Dockerfile de préparation par image : phase-0-prereqs.md.

Critère : tous les prérequis passent ; l'utilisateur a fourni les références d'images requises ; tao-pytorch-base:latest et tao-deploy-base:latest existent localement ; tao-dataservices-base:latest existe si du travail avec dataservices est attendu.

Phase 1 — Collecte d'informations et validation

Objectif : décider s'il faut continuer. Collecter les identifiants, localiser (ou cloner) les quatre dépôts TAO et créer une branche de travail cohérente localement, lancer le conteneur long-lived tao-hf-inspect (contexte d'isolation A), valider que le modèle HF est un modèle CV avec un pipeline_tag supporté, extraire le schéma config + state-dict, faire une vérification de santé de l'export ONNX, et nettoyer. Étapes complètes (1.1–1.7) : phase-1-inspection.md ; patterns génériques : hf-inspection.md.

Rejeter si pipeline_tag est NLP / audio / LLM (hors du scope CV), AutoConfig lève une exception, ou l'export ONNX ne peut fondamentalement pas fonctionner et n'a pas de chemin de réécriture.

Critère : les 4 dépôts TAO localisés/clonés avec une branche de travail cohérente ; pipeline_tag confirmé comme CV ; model_type, image_size, hidden_size, num_labels extraits ; clés state-dict documentées et le plan de remappage HF→TAO rédigé ; vérification de santé ONNX passée (ou mode d'échec compris) ; utilisateur a confirmé model_short_name et le type de tâche. Présenter les résultats et confirmer avant de continuer.

Phase 2 — Exploration de la base de code

Objectif : trouver le modèle de référence TAO le plus proche pour le pipeline_tag détecté (classification → classification_pyt, détection → dino/rtdetr, segmentation → segformer, instance → mask2former, panoptique → oneformer, zero-shot → grounding_dino, profondeur → mono_depth), lire son implémentation complète à travers tao-core, tao-pytorch et tao-deploy, et décider si le backbone existe déjà dans backbone_v2/. Le modèle de référence choisi pilote tout ce qui suit — structure config, architecture, loss, forme ONNX, builder TRT, déployeur/loader d'inférence, métriques, format dataset. La liste complète de référence (12 fichiers par modèle), la vérification de couverture backbone_v2/ (elle fournit déjà vit, swin, resnet, dino_v2 et autres), et la vérification de couverture tao-dataservices : phase-2-codebase.md ; détails par tâche : task-type-guide.md.

Si un nouveau backbone est nécessaire, décider la stratégie (wrap timm > ré-implémenter de zéro > wrap black-box HF) avant la Phase 3 — cela change le chargement de poids, l'export ONNX et le pipeline de déploiement. Ne jamais hériter doublement de transformers.PreTrainedModel et BackboneBase (conflit de métaclasse).

Critère : modèle TAO de référence identifié et les 12 emplacements lus ; implications du type de tâche comprises (architecture, loss, sorties ONNX, classes de déploiement, métriques, dataset) ; couverture du backbone décidée (réutilisation / wrap timm / nouveau) ; couverture de dataservices vérifiée.

Phase 3 — Configuration TAO Core et implémentation native

Objectif : rédiger le schéma config tao-core et le trainer tao-pytorch + inférence native + évaluation native, en testant de vérification entre les deux. Utiliser <model_name> (snake_case de la Phase 1) et <ModelName> (PascalCase). Sept étapes : (1) config tao-core sous config/<model_name>/ — ExperimentConfig(CommonExperimentConfig) DOIT contenir model, dataset, train, evaluate, inference, export, gen_trt_engine, quantize ; (2) trainer tao-pytorch sous cv/<model_name>/ (build_model(), <ModelName>PlModel(TAOLightningModule), train.py, entrypoint, experiment_spec.yaml ; nouveau backbone → ajouter+enregistrer cv/backbone_v2/<backbone_name>.py) ; (3) multi-GPU/multi-nœud via launch() de l'entrypoint ; (4) inférence native → result.csv ; (5) évaluation native → results.json ; (6–7) câblage MLOps (@monitor_status → status.json). Les règles de cohérence (y compris export.onnx_file vs gen_trt_engine.onnx_file et ??? = obligatoire MISSING) sont appliquées par la checklist cross-phase ci-dessous.

Code complet par étape et experiment_spec.yaml canonical : phase-3-implementation.md (avec snippets tao-patterns.md, layout repo-structure.md, par tâche task-type-guide.md).

Critères : Étape 1 — ExperimentConfig s'importe proprement dans le conteneur ; Étape 2 — build_model(cfg) s'exécute et la PLModel s'instancie ; global — les 7 étapes complètes, tests de vérification passent, aucun __init__.py manquant.

Phase 4 — Export, déploiement et intégration TensorRT

Objectif : livrer l'export ONNX de tao-pytorch, puis un builder de moteur TRT + inférence TRT + évaluation TRT dans tao-deploy qui réutilisent ExperimentConfig de tao-core. Quatre étapes (8–11) : export ONNX (scripts/export.py, noms d'entrée/sortie par tâche, batch_size=-1 ⇒ batch dynamique) ; builder moteur TRT (gen_trt_engine.py, sous-classe EngineBuilder ou réutilise ClassificationEngineBuilder, écrit specs/{gen_trt_engine,inference,evaluate}.yaml) ; inférence TRT (NumPy-only ClassificationLoader → result.csv) ; évaluation TRT (sklearn/pycocotools → results.json). Code complet et critère Phase 3+4 : phase-4-deploy.md.

Écueil module : tao-pytorch et tao-deploy ont des implémentations séparées de hydra_runner et monitor_status — utiliser les versions de déploiement dans les scripts de déploiement ; ExperimentConfig s'importe depuis nvidia_tao_core dans les deux dépôts (même schéma, mêmes chemins de champs).

Critère Phase 3+4 : les trois vérifications en conteneur passent — imports + modèle + export ONNX tao-pytorch, et imports tao-deploy.

Phase 5 — Packaging et tests L0

Objectif : enregistrer le modèle comme script de console '<model_name>=...entrypoint.<model_name>:main' dans tao-pytorch/setup.py et tao-deploy/setup.py (l'entrypoint de déploiement utilise nvidia_tao_deploy.cv.common.entrypoint.entrypoint_hydra), et ajouter des tests L0 — tests de déploiement (tao-deploy/tests/<model_name>/, subprocess + --buildOnly trtexec) et tests de trainer (tao-pytorch/tests/cv_unit_test/<model_name>/, Trainer(..., fast_dev_run=True), marqueurs @pytest.mark.cv_unit @pytest.mark.<model_name>). Code complet et layout de test : phase-5-packaging.md.

Critère : entrypoints enregistrés ; fichiers pytest existent et suivent la convention de marqueur. Ne PAS s'arrêter ici — procéder directement à la Phase 6.

Flux de données cross-phase et vérification de cohérence

Avant les tests Docker, vérifier la chaîne d'artefacts — train produit <results_dir>/train/<model_name>_model_latest.pth → export.checkpoint → <results_dir>/export/<model_name>.onnx → gen_trt_engine → <results_dir>/trt/<model_name>.engine → inference.trt_engine / evaluate.trt_engine. Ensuite confirmer la checklist de cohérence : le nom *_latest.pth ; augmentation.mean/std correspondant à travers le spec d'entraînement, inference.yaml, evaluate.yaml et preprocess_mode du builder ; noms ONNX input_names/output_names ; export.input_width/input_height vs dataset.img_size ; model.head.in_channels vs model_params_mapping.py ; classes.txt partagé ; et un __init__.py dans chaque répertoire de package (y compris scripts/__init__.py pour la découverte pkgutil de get_subtasks()). Chemins d'interpolation complets, checklist détaillée et chemins de champs config : workflow-consistency.md.

Phase 6 — Tests en conteneur et validation end-to-end

Obligatoire — commencer immédiatement après la Phase 5. Tous les modèles TAO se livrent sous forme d'images Docker ; le code qui ne fonctionne que hors conteneur est incomplet. Les tests s'exécutent directement à l'intérieur du conteneur TAO Toolkit (aucune compilation d'image Docker dans la boucle de test) : monter la source locale dans les étiquettes d'images de la Phase 0, installer via setup.py develop, et invoquer pytest / pylint / pydocstyle / flake8 directement — utiliser des binaires vanille pytest + lint, PAS de wrappers ci/run_functional_tests.py / ci/run_static_tests.py (ceux-ci n'existent que dans les miroirs internes NVIDIA ; les miroirs github.com/NVIDIA-TAO/ publics n'ont pas de répertoire ci/).

Étapes 16–25, dans l'ordre : vérifier les étiquettes d'images locales (16) ; pytest conteneur pour tao-core (17), tao-pytorch (18, -m cv_unit, --shm-size=16G), tao-deploy (19) ; tests statiques/lint (20, pylint --errors-only + optionnel pydocstyle/flake8) ; builds de roue (21) ; le pipeline end-to-end (22 — dry-run d'entraînement + export dans une session tao-pytorch, puis gen_trt_engine + inference + evaluate dans une session tao-deploy, car --rm supprime les packages installés) ; vérification native-vs-TRT (23 — FP32 ≈ exact, FP16 ≈ petit delta, divergence ⇒ problème ONNX/TRT) ; shells de débogage interactif (24) ; build optionnel d'image Docker de release (25, distribution-only). Commandes complètes par étape et boucle correction-retesting : phase-6-container-tests.md ; scripts de construction, patterns de runner, requirements, conventions CI : docker-patterns.md.

Critère Phase 6 (Critères "Done") : les tests unitaires tao-core / tao-pytorch / tao-deploy passent dans leurs conteneurs TAO Toolkit ; tests statiques passent (ou avertissements lint legacy uniquement) ; roues se compilent ; end-to-end <model_name>_model_latest.pth → model.onnx → model.engine → result.csv et results.json non-vides ; prédictions native vs TRT concordent dans la tolérance.

Phase 7 — Optimisation et tuning (conditionnel)

Entrer uniquement si la Phase 6 passe mais que la précision / latence / taille du modèle a besoin d'amélioration. Demander d'abord à l'utilisateur les métriques cibles. Diagnostiquer (Étape 26) à travers quatre catégories — précision trop basse, écart TRT-vs-native, entraînement trop lent, inférence trop lente — puis appliquer la technique pertinente : tuning d'hyperparamètres (27), quantification INT8 (28), élagage de canaux + ré-entraînement (29), distillation de connaissance (30) ou tuning de résolution (31). Diagnostics complets, blocs config, overrides YAML et arbre de décision : phase-7-optimization.md.

Argument

$ARGUMENTS

S'il est fourni, interpréter $ARGUMENTS comme l'ID ou l'URL du modèle HuggingFace à utiliser comme point de départ pour la Phase 1. Si les identifiants ou le nom court du modèle ne sont pas inclus, demander à l'utilisateur avant de continuer.