DINOv3

Installation autonome ? Si cette session n'a pas été initialisée par le plugin du skill bank TAO, exécutez d'abord le skill tao-setup.

Utilisez ce skill pour poursuivre l'entraînement auto-supervisé d'un backbone DINOv3 sur des images non étiquetées, puis convertir, exporter ou lancer l'inférence avec un checkpoint teacher entraîné.

Démarrage rapide (docker run)

Lancement natif Docker — sans TAO SDK et sans Python sur l'hôte. Utilisez le skill Docker/platform local quand il fournit une commande plus stricte spécifique à l'environnement (mappage UID non-root, redirections de cache, daemons distants).

TAO_PYT_IMAGE_DEFAULT=nvcr.io/nvidia/tao/tao-toolkit:7.2.0-pyt  # versions-key: images.tao_toolkit.pyt
TAO_PYT_IMAGE="${TAO_PYT_IMAGE:-$TAO_PYT_IMAGE_DEFAULT}"
RUN_ROOT="${RUN_ROOT:-$PWD}"
DOCKER_COMMON=(
  --rm --gpus all --shm-size=8g
  --shm-size=8g
  --ulimit memlock=-1
  --ulimit stack=67108864
  -v "$RUN_ROOT/data:/data:ro"
  -v "$RUN_ROOT/specs:/specs:ro"
  -v "$RUN_ROOT/results:/results"
)

Entraînement :

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  dinov3 train -e /specs/train.yaml

Inférence :

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  dinov3 inference -e /specs/inference.yaml

Export :

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  dinov3 export -e /specs/export.yaml

Conversion :

docker run "${DOCKER_COMMON[@]}" "$TAO_PYT_IMAGE" \
  dinov3 convert -e /specs/convert.yaml

Chaque action prend sa spec avec -e ; results_dir est défini dans la spec ou surchargé en ligne de commande. Montez tout répertoire de poids pré-entraînés que la spec référence, et gardez chaque chemin dans le conteneur cohérent entre les actions.

Configuration

Utilisez schemas/<action>.schema.json pour les champs supportés, les valeurs par défaut, les plages et les options. Commencez par le template correspondant references/spec_template_<action>.yaml.

L'entraînement est activé par AutoML. Lisez references/skill_info.yaml et résolvez une automl_policy explicite ou une demande utilisateur avant l'entraînement. Par défaut, automl_policy: on ; les demandes telles que « désactiver AutoML », « pas de HPO » ou « entraînement simple » signifient off pour cette exécution. Quand c'est activé et que la schema et template d'entraînement sont packagés, routez l'entraînement via tao-skill-bank:tao-run-automl. Utilisez l'entraînement direct uniquement quand la politique est off ou ces fichiers manquent, et signalez la limitation de fichiers manquants. Les actions non-entraînement restent dans ce skill.

Traitez train_loss comme un signal d'optimisation ; utilisez l'évaluation aval lors de la sélection d'un checkpoint pour le déploiement.

Pour le contexte méthodologique ou des idées de tuning, lisez optionnellement :

• references/dinov3-method.md
• references/dinov3-recipes.md

Workflow principal

1. Obtenez un checkpoint DINOv3 compatible au format timm ou TAO.
2. Pointez dataset.train_dataset.images_dir vers un répertoire d'images non étiquetées.
3. Configurez le backbone, l'échelle d'entraînement et l'emplacement de sortie.
4. Exécutez l'entraînement et évaluez les checkpoints teacher utiles sur des données représentatives de la tâche aval.
5. Utilisez le checkpoint teacher sélectionné avec convert, export ou inference.

Fournissez soit train.pretrained_model_path pour une nouvelle exécution, soit train.resume_training_checkpoint_path pour reprendre une exécution existante.

Champs essentiels

Exemple de paramètres d'entraînement :

model:
  backbone:
    teacher_type: vit_b
    student_type: vit_b
    rope_theta: 100.0
dataset:
  train_dataset:
    images_dir: /path/to/unlabeled/images
  batch_size: 16
train:
  pretrained_model_path: /path/to/dinov3/weights
  num_epochs: 10
  num_gpus: 1

Les extensions d'image supportées incluent jpg, jpeg, png, ppm, bmp, pgm, tif, tiff et webp. Gardez les données d'évaluation séparées des données d'entraînement lors de la mesure de la qualité aval.

Chaque valeur dataset.*.images_dir doit être un dossier d'images extrait. Les sources gérées basées sur archive utilisent runtime: extracted_folder, qui déplie la source avant d'injecter le répertoire dans la spec. Pour les exécutions Docker ou TAO CLI directs, extrayez les entrées .tar, .tar.gz, .tgz ou .zip avant le lancement.

Checkpoints

Pour l'export, privilégiez un teacher_epoch_*_step_*.pth strippé sélectionné. L'export accepte aussi un model_epoch_*_step_*.pth complet sélectionné et sélectionne et enregistre teacher.backbone de manière déterministe. L'inférence requiert un checkpoint teacher strippé. Ne substituez pas dinov3_model_latest.pth sans évaluer ce jalon.

La loss d'entraînement ne mesure pas directement la qualité de la représentation aval. Quand c'est possible, comparez les checkpoints teacher candidats en utilisant des métriques pertinentes pour la tâche cible.

Pour convert, export et inference, copiez la configuration du backbone du temps d'entraînement dans la spec d'action, y compris rope_theta. Les checkpoints strippés ne restaurent pas la base de fréquence RoPE, donc revenir à la valeur par défaut peut changer le comportement du modèle entraîné.

Options clés

• model.backbone.teacher_type et student_type supportent vit_s, vit_s_plus, vit_b, vit_l, vit_h_plus et vit_7b.
• Quand model.distill.enable: false, les types de backbone teacher et student doivent correspondre.
• model.backbone.rope_theta contrôle la base de fréquence rotatoire. Il a pour défaut 100.0 et est ajustable ; le modifier altère l'encodage positionnel, donc évaluez le checkpoint résultant pour la tâche envisagée.
• model.centering_method supporte sinkhorn et softmax.
• model.gram.* contrôle l'ancrage Gram optionnel.
• model.lora.* active l'entraînement continu pré-pré-entraînement efficace en paramètres. La défaut cible les projections attention qkv et proj ; num_last_blocks: 0 adapte chaque bloc transformer.
• model.preservation.* ajoute les losses MSE et cosinus du token CLS contre le teacher anchor gelé. C'est recommandé avec LoRA quand la qualité de l'embedding global compte.
• train.log_every_n_steps contrôle la visibilité de la loss au niveau des étapes et a pour défaut 1, donc les courtes exécutions de smoke émettent les losses de composant et preservation.
• train.precision a pour défaut 16-mixed ; choisissez la précision basée sur le matériel et la qualité mesurée.
• train.use_custom_attention: false utilise l'attention native quand l'attention personnalisée est indisponible.
• Les dimensions crop et export doivent être divisibles par model.backbone.patch_size.

Entraînement distribué

Utilisez train.num_gpus, train.gpu_ids, train.num_nodes et train.distributed_strategy. Commencez par auto ; utilisez ddp ou fsdp le cas échéant pour le backbone sélectionné, la résolution et la mémoire disponible.

Problèmes courants

• Échec du chargement de checkpoint : vérifiez que le checkpoint est DINOv3 et que son backbone correspond aux types de teacher et student configurés.
• Aucune image trouvée ou archive rejetée : passez un dossier d'images extrait à dataset.*.images_dir, pas un fichier archive.
• Dépassement mémoire : réduisez la taille du batch ou la résolution de l'image, ou utilisez une stratégie distribuée shardée.
• Échec de l'attention personnalisée : réglez train.use_custom_attention: false.
• Échec backward déterministe : l'attention mémoire-efficace xformers ne fournit pas de kernel backward déterministe ; utilisez train.cudnn.deterministic: false.
• Erreur de grid-size : choisissez les dimensions crop et export divisibles par la taille du patch.
• Clés d'inférence inattendues : utilisez un checkpoint teacher_epoch_*_step_*.pth strippé.
• Export de checkpoint complet : un model_epoch_*_step_*.pth sélectionné est supporté ; l'export sélectionne et enregistre son teacher.backbone EMA.
• Mismatch de reprise : le dataloader SSL n'est pas resumable au niveau des étapes, donc reprenez à partir d'une limite d'époque/checkpoint quand la reproductibilité compte.