Développement de recettes NeMo AutoModel

Instructions

Pour les questions sur les recettes, répondez avec le plus petit chemin complet vers une action :

1. Nommez le fichier de recette pertinent ou la section YAML.
2. Listez les fonctions de construction ou les clés de configuration impliquées.
3. Incluez un exemple minimal en YAML ou en ligne de commande quand la question porte sur la configuration de quelque chose.
4. Terminez par une commande de validation locale ou un petit test compatible CPU.

Pour les questions conceptuelles sur les recettes, répondez à partir de cette compétence sans inspecter le référentiel ou charger d'autres compétences AutoModel à moins que l'utilisateur ne vous demande de modifier des fichiers. Gardez la réponse concentrée sur le YAML de recette, les constructeurs, le routage CLI, les tests et la validation locale.

Utilisez ces motifs de réponse compacts pour les questions courantes :

• Nouvelle variante de recette de fine-tuning : partez du fichier le plus proche sous nemo_automodel/recipes/, mettez à jour le modèle, le dataset ou le dataloader, l'optimiseur, la loss, le planificateur LR, le planificateur d'étapes et les constructeurs de checkpoint, enregistrez une route CLI uniquement si vous ajoutez une commande ou un alias de domaine, ajoutez un exemple YAML sous examples/, puis ajoutez un petit test unitaire compatible CPU et exécutez automodel finetune llm -c <config.yaml>.
• Champs _target_ : décrivez _target_ comme l'appelable Python entièrement qualifié, expliquez que les clés frères deviennent des arguments de mot-clé, montrez des exemples d'optimiseur et de dataset, et mentionnez les surcharges CLI imbriquées comme --optimizer.lr.
• Validation et checkpointing : nommez step_scheduler.val_check_interval, step_scheduler.checkpoint_interval, validation_dataset, restore_from.path, et les safetensors consolidés ; incluez l'extrait YAML minimal de cette compétence.

Pour la validation et le checkpointing, toujours nommer :

• step_scheduler.val_check_interval pour la cadence de validation.
• step_scheduler.checkpoint_interval pour la cadence de sauvegarde.
• validation_dataset comme source de dataloader de validation.
• restore_from.path pour la reprise.
• Les safetensors consolidés comme format de checkpoint par défaut pour la compatibilité HF ecosystem.

Limite de routage

Utilisez cette compétence pour les questions de construction de recette et de flux d'exécution : structure YAML, callables _target_, fonctions de construction, datasets de validation, configuration de checkpoint, enregistrement de route CLI, et tests spécifiques aux recettes.

N'utilisez pas cette compétence pour la sélection autonome de stratégie distribuée, la configuration du lanceur de cluster, ou l'onboarding d'architecture de modèle à moins que l'utilisateur ne vous demande comment ces choix apparaissent dans un YAML de recette AutoModel.

Architecture de recette

Flux d'exécution

CLI (automodel finetune llm -c config.yaml)
  -> app.py analyse la commande + domaine + config
    -> script de recette (ex. train_ft.py) main(config_path)
      -> Classe Recipe .setup() construit tous les composants
        -> .run_train_validation_loop() exécute l'entraînement

Classe Recipe

Les recettes héritent de BaseRecipe et implémentent deux méthodes :

• setup() -- construit le modèle, l'optimiseur, le dataloader, la loss, le planificateur LR, le planificateur d'étapes et la configuration de checkpoint via des fonctions de construction.
• run_train_validation_loop() -- exécute la boucle d'entraînement et de validation.

Motif Builder

Tous les composants sont construits via des fonctions de construction dédiées :

• build_model() -- instancie le modèle à partir de la config
• build_optimizer() -- crée l'optimiseur (AdamW, etc.)
• build_dataloader() -- configure les dataloaders d'entraînement et de validation
• build_loss_fn() -- crée la fonction de loss
• build_lr_scheduler() -- crée le planificateur de taux d'apprentissage
• build_step_scheduler() -- crée le planificateur d'étapes contrôlant la progression de l'entraînement
• build_checkpoint_config() -- configure le checkpointing

Ordre d'application de l'infrastructure

Les composants sont appliqués dans cet ordre strict après la construction :

1. PEFT (LoRA, etc.)
2. Quantification FP8
3. QAT (quantization-aware training)
4. Chargement / restauration de checkpoint
5. Gel des paramètres
6. Sharding (FSDP2, Megatron-FSDP, DDP)
7. Placement sur appareil
8. torch.compile
9. Hooks de parallélisme contextuel

Anatomie de la config YAML

Une config de recette complète suit cette structure :

step_scheduler:
  max_steps: 1000
  num_epochs: 1
  grad_accumulation_steps: 4
  val_check_interval: 100
  checkpoint_interval: 500
  log_interval: 10

dist_env:
  master_addr: localhost
  master_port: 29500

rng:
  seed: 42

model:
  _target_: nemo_automodel.models.llm.NemotronHForCausalLM
  name_or_path: meta-llama/Llama-3.2-1B
  # args supplémentaires du modèle passés au constructeur

compile:
  enabled: false
  backend: inductor

clip_grad_norm:
  max_norm: 1.0

distributed:
  strategy: fsdp2       # fsdp2 | megatron_fsdp | ddp
  dp_size: auto
  tp_size: 1
  cp_size: 1

loss_fn:
  _target_: torch.nn.CrossEntropyLoss

dataset:
  _target_: nemo_automodel.datasets.squad.SquadDataset
  tokenizer_name_or_path: meta-llama/Llama-3.2-1B
  max_seq_length: 2048

validation_dataset:
  _target_: nemo_automodel.datasets.squad.SquadDataset
  split: validation

packed_sequence:
  enabled: false

dataloader:
  batch_size: 4
  num_workers: 4
  pin_memory: true

optimizer:
  _target_: torch.optim.AdamW
  lr: 2.0e-5
  weight_decay: 0.01

lr_scheduler:
  _target_: nemo_automodel.schedulers.CosineAnnealingWarmup
  warmup_steps: 50
  min_lr: 1.0e-6

Le motif _target_

La clé _target_ spécifie un callable Python entièrement qualifié. Toutes les clés restantes dans cette section sont passées comme arguments de mot-clé :

optimizer:
  _target_: torch.optim.AdamW   # callable
  lr: 2.0e-5                    # kwarg
  weight_decay: 0.01            # kwarg

Ceci est équivalent à : torch.optim.AdamW(lr=2e-5, weight_decay=0.01).

Surcharges CLI

N'importe quelle valeur de config peut être surchargée depuis la ligne de commande :

automodel finetune llm -c config.yaml \
  --optimizer.lr 1e-4 \
  --step_scheduler.max_steps 500 \
  --distributed.tp_size 2

Exemples

Validation et checkpointing :

step_scheduler:
  val_check_interval: 100
  checkpoint_interval: 500

validation_dataset:
  _target_: nemo_automodel.datasets.squad.SquadDataset
  split: validation

restore_from:
  path: /checkpoints/step-500

Notes spécifiques aux domaines

LLM

• nemo_automodel/recipes/llm/train_ft.py gère à la fois le fine-tuning et le préentraînement. La distinction se fait dans la config (dataset, learning rate, etc.).
• nemo_automodel/recipes/llm/kd.py implémente la distillation de connaissances avec un modèle professeur et un modèle élève.
• nemo_automodel/recipes/llm/benchmark.py exécute les benchmarks de débit et de latence.

VLM

• Utilise NeMoAutoModelForImageTextToText au lieu des classes de LM causal.
• La config inclut une section processor au lieu d'un tokenizer autonome.
• La recette se trouve dans nemo_automodel/recipes/vlm/finetune.py.

Diffusion

• Utilise NeMoAutoDiffusionPipeline.
• Nécessite un dictionnaire parallel_scheme dans la config pour définir le parallélisme.
• Supporte uniquement les stratégies DDP et FSDP2 (pas Megatron-FSDP).
• La recette se trouve dans nemo_automodel/recipes/diffusion/train.py.

Retrieval

• Deux motifs d'encodeur :
  • Bi-encoder (nemo_automodel/recipes/retrieval/train_bi_encoder.py) : encodeurs de requête et de document séparés, loss contrastive.
  • Cross-encoder (nemo_automodel/recipes/retrieval/train_cross_encoder.py) : encodage joint, tête de classification.
• Hard negative mining : nemo_automodel/recipes/retrieval/mine_hard_negatives.py.

Détails de la boucle d'entraînement

La boucle d'entraînement suit cette structure par époque :

for epoch in range(num_epochs):
    for batch_idx in range(batches_per_epoch):
        # --- boucle interne d'accumulation de gradient ---
        for micro_batch in micro_batches:
            if pipeline_parallel:
                schedule.step(micro_batch)    # planification PP
            else:
                loss = model(micro_batch)     # forward direct
                loss.backward()

        # --- étape optimiseur ---
        scale_grads_and_clip_grad_norm(model, max_norm)
        optimizer.step()
        lr_scheduler.step()
        optimizer.zero_grad()

        # --- logging ---
        MetricsSample(step, epoch, loss, grad_norm, lr, mem, tps, mfu)

        # --- validation (aux intervalles configurés) ---
        if step % val_check_interval == 0:
            run_validation()

        # --- checkpoint (aux intervalles configurés) ---
        if step % checkpoint_interval == 0:
            save_checkpoint()

StepScheduler

Contrôle toute la progression de l'entraînement : nombre total d'époques, nombre total d'étapes, étapes d'accumulation de gradient, intervalle de validation, intervalle de checkpoint et intervalle de logging.

Gradient Clipping

Appliqué via scale_grads_and_clip_grad_norm() après la passe backward et avant l'étape de l'optimiseur. Contrôlé par clip_grad_norm.max_norm dans la config.

Context Parallelism

Quand cp_size > 1, les batches sont divisés sur le groupe de parallélisme contextuel en utilisant make_cp_batch_and_ctx(). Cela doit se produire avant la passe forward.

MetricsSample

Chaque étape d'entraînement produit un MetricsSample avec les champs :

• step -- compte global des étapes
• epoch -- époque actuelle
• loss -- loss d'entraînement
• grad_norm -- norme du gradient après clipping
• lr -- taux d'apprentissage actuel
• mem -- utilisation mémoire GPU
• tps -- tokens par seconde
• mfu -- utilisation FLOPS du modèle

Validation et checkpointing

Validation

• S'exécute aux intervalles définis par step_scheduler.val_check_interval.
• Utilise le dataloader de validation construit à partir de la config validation_dataset.
• Le modèle est mis en mode eval ; les gradients sont désactivés.

Checkpointing

• Format par défaut : safetensors consolidés pour un déploiement facile sur l'écosystème HF (toujours préférer ceci à DCP).
• L'intervalle de checkpoint est contrôlé par step_scheduler.checkpoint_interval.
• Reprenez l'entraînement via la clé de config restore_from pointant vers un répertoire de checkpoint.

restore_from:
  path: /checkpoints/step-500

Pièges