Mettre à jour l'image de base PyTorch

Workflow complet pour migrer les CI GitHub et GitLab de Megatron-LM vers un conteneur nvcr.io/nvidia/pytorch:<YY.MM>-py3 plus récent. Le mode de défaillance le plus courant est d'oublier que les pins GitHub CI et GitLab CI sont indépendants — une mise à jour qui ne touche que le premier passe au vert, puis casse GitLab CI sur main et force une PR de suivi immédiate. Mettez toujours à jour les deux dans la même PR.

Inputs à recueillir auprès de l'utilisateur

Tag cible, par exemple 26.04-py3. Les conteneurs PyTorch NVIDIA NGC sont publiés sous nvcr.io/nvidia/pytorch:YY.MM-py3.
Scope — généralement dev uniquement. Le pin lts (docker/.ngc_version.lts, plus les lignes IMAGE_TYPE: lts dans GitLab) est mis à jour selon un calendrier différent ; ne le touchez que si l'utilisateur le demande explicitement.
Workflow run ID (optionnel mais typique) — après la première exécution de CI, l'utilisateur fournira un ID d'exécution GitHub Actions pour l'actualisation des valeurs de référence.

Workflow

- [ ] Étape 1 : Mettre à jour le pin GitHub CI (docker/.ngc_version.dev)
- [ ] Étape 2 : Mettre à jour le pin GitLab CI (.gitlab/stages/01.build.yml)
- [ ] Étape 3 : Ouvrir la PR avec le label `Run functional tests`
- [ ] Étape 4 : Relancer les tests défaillants via `/ok to test <commit-sha>`
- [ ] Étape 5 : Pour la dérive de valeurs de référence → actualiser avec la skill `update-golden-values`
- [ ] Étape 6 : Pour les blocages / régressions réelles → marquer les tests `mr-broken` et ouvrir des issues de suivi
- [ ] Étape 7 : Vérifier que les deux pins sont synchronisés avant de fusionner

Étape 1 — Pin GitHub CI

docker/.ngc_version.dev est un fichier d'une seule ligne consommé par docker/Dockerfile.ci.dev (via FROM_IMAGE_NAME=$(cat docker/.ngc_version.dev)). Écrasez-le :

echo 'nvcr.io/nvidia/pytorch:<YY.MM>-py3' > docker/.ngc_version.dev

Le fichier n'a historiquement pas de retour à la ligne finale ; le préserver ou en ajouter un est acceptable — les arguments de compilation traitent la valeur comme $(cat ...). Ne touchez pas à docker/.ngc_version.lts sauf si vous bumppez aussi LTS.

Étape 2 — Pin GitLab CI

GitLab CI ne lit pas docker/.ngc_version.dev. Il code en dur BASE_IMAGE dans un bloc parallel: matrix:. Mettez à jour les deux lignes IMAGE_TYPE: dev (une par plateforme) :

# .gitlab/stages/01.build.yml — sous test:pre_build_image -> parallel.matrix
- IMAGE: CI_MCORE_DEV_IMAGE
  FILE: Dockerfile.ci.dev
  IMAGE_TYPE: dev
  BASE_IMAGE: nvcr.io/nvidia/pytorch:<YY.MM>-py3   # ligne amd64
  PLATFORM: amd64
- IMAGE: CI_MCORE_DEV_IMAGE
  FILE: Dockerfile.ci.dev
  IMAGE_TYPE: dev
  BASE_IMAGE: nvcr.io/nvidia/pytorch:<YY.MM>-py3   # ligne arm64
  PLATFORM: arm64

Laissez les lignes IMAGE_TYPE: lts intactes. Vérification rapide avant commit :

rg -n '^\s*BASE_IMAGE: nvcr\.io/nvidia/pytorch:' .gitlab/stages/01.build.yml
# attendu : pin lts × 2 inchangé, pin dev × 2 == nouveau tag

Étape 3 — Ouvrir la PR

Convention de titre : chore: Update Docker image version to <YY.MM>-py3 (voir #4611).
Appliquez le label Run functional tests avant le premier push. Cela déverrouille la matrice fonctionnelle complète sur la PR ; sans lui, la mise à jour ne lance que les vérifications GH PR standard et vous manquerez la dérive.
Poussez en brouillon d'abord si vous itérez encore ; le bot se mettra en brouillon automatiquement sinon.

Étape 4 — Relancer CI sur un nouveau commit

Pour les PR des forks (le cas classique du contributeur), chaque nouveau commit a besoin d'un commentaire PR explicite /ok to test <commit-sha> pour autoriser les runners NVIDIA (voir le flux copy-pr-bot dans #4611). Un commentaire par commit. Si copy-pr-bot signale « had a problem deploying to test », poussez simplement un autre commit (ou réémettez le commentaire après le prochain push) ; le déploiement est par commit, pas par commentaire.

Étape 5 — Dérive de valeurs de référence

Les bumps de conteneur décalent CUDA / cuBLAS / cuDNN / l'autotuning du kernel, ce qui déplace lm loss, num-zeros, iteration-time, et les métriques mem-* sur une grande fraction des tests fonctionnels. C'est attendu et n'est pas une régression de correction — actualisez les valeurs de référence plutôt que de chasser chaque test.

Passez à la skill update-golden-values avec :

--source github
--pipeline-id <WORKFLOW_RUN_ID> de la run CI défaillante
--only-failing (actualiser uniquement les trajectoires qui ont dévié)

La PR #4611 a actualisé 78 fichiers de valeurs de référence sur dev_dgx_h100 et dev_dgx_gb200 pour les suites GPT / MoE / MIMO / hybrid en une seule passe via ce flux exact. Le résumé de différence relative par métrique que la skill produit est le blurb de description PR recommandé — les relecteurs s'attendent à le voir.

Étape 6 — Régressions réelles : marquer comme cassé, ne bloquez pas la mise à jour

Un petit nombre de tests cassera véritablement (blocages, OOM, régressions numériques réelles). Ne bloquez pas la mise à jour de l'image de base sur leur correction — cela mélange deux changements. À la place :

Ouvrez une issue GitHub décrivant le mode de défaillance et liant la run CI défaillante.
Changez le scope du test à la variante -broken dans le YAML de recette sous tests/test_utils/recipes/<arch>/, avec un commentaire inline qui référence l'issue. Motif :
```
- test_case: [hybrid_dynamic_inference_tp1_ep8_nanov3_chunked_prefill]
  products:
    - environment: [dev]
      # Broken: hangs on repeat iter 3, exceeds 1h job limit — see issue #<N>.
      scope: [mr-broken, mr-github-broken]      # was: [mr, mr-github]
      platforms: [dgx_h100]
```
Correspondance des scopes (remplacer, ne pas ajouter) :

Avant Après

mr mr-broken

mr-github mr-github-broken

nightly nightly-broken

La recette s'exécute toujours dans le scope -broken, mais les défaillances ne bloquent plus les fusions de PR.

Avant	Après
`mr`	`mr-broken`
`mr-github`	`mr-github-broken`
`nightly`	`nightly-broken`

Étape 7 — Vérification de synchronisation avant fusion

Le plus gros mode de défaillance de ce workflow est de livrer #4611 sans #4688. Avant de demander la fusion, confirmez que les deux pins se résolvent sur le même tag :

echo -n "ngc_version.dev: " && cat docker/.ngc_version.dev
echo
echo "gitlab dev rows:"
rg -n '^\s*BASE_IMAGE: nvcr\.io/nvidia/pytorch:' .gitlab/stages/01.build.yml \
  | rg -B1 'IMAGE_TYPE: dev' \
  | rg 'BASE_IMAGE'

Les trois lignes doivent afficher nvcr.io/nvidia/pytorch:<YY.MM>-py3. Si ce n'est pas le cas, corrigez avant fusion — sinon GitLab CI continue de compiler sur l'ancien conteneur et la prochaine personne tombe dans le même piège.

Pense-bête des fichiers à toucher

Chemin	Modification
`docker/.ngc_version.dev`	Écraser avec le nouveau `nvcr.io/nvidia/pytorch:<YY.MM>-py3`
`.gitlab/stages/01.build.yml`	Mettre à jour les deux lignes `IMAGE_TYPE: dev` `BASE_IMAGE:` (amd64 + arm64)
`tests/functional_tests/test_cases/**/golden_values_dev_dgx_{h100,gb200}.json`	Actualiser via la skill `update-golden-values`
`tests/test_utils/recipes/<arch>/<suite>.yaml`	Basculer les cas dérives / bloqués vers `mr-broken` / `mr-github-broken` avec lien issue
`docker/.ngc_version.lts`, `.gitlab/stages/01.build.yml` lignes `IMAGE_TYPE: lts`	Ignorer sauf si vous bumpez explicitement LTS. LTS a son propre calendrier de sortie.

Pièges

Les pins GitHub et GitLab sont indépendants. docker/.ngc_version.dev ne pilote que la compilation locale du conteneur GitHub CI via Dockerfile.ci.dev. GitLab CI a sa propre matrice BASE_IMAGE: codée en dur dans .gitlab/stages/01.build.yml. La PR #4688 n'existait que parce que #4611 a oublié la deuxième — ne répétez pas.
Ne bumpez pas LTS avec dev. Les lignes IMAGE_TYPE: lts et docker/.ngc_version.lts sont épinglées à la stabilité pour le chemin du label container::lts. Bumpez-les dans une PR dédiée avec sa propre validation LTS.
Ne corrigez pas la dérive de valeurs de référence à la main. Utilisez tests/test_utils/python_scripts/download_golden_values.py via la skill update-golden-values. Éditer manuellement les JSONs invite le bruit de diff et les régressions de différence relative sur les bumps suivants.
mr-broken est un vrai scope, pas un marqueur de commentaire. Il garde la recette câblée dans la matrice (pour qu'elle reste découvrable et exécutable à la demande) sans bloquer les fusions. Ne supprimez pas le cas de test de la recette.
/ok to test est par commit. Un nouveau force-push ou commit de correction a besoin d'un commentaire /ok to test <sha> frais pour relancer la CI des runners NVIDIA sur une PR fork.
Ne fusionnez pas tant que le pin GitLab ne correspond pas. Utilisez le grep de l'étape 7 avant de demander la revue.

Skills associées

update-golden-values — appelez ceci dès que la première run CI post-bump termine et que vous avez un workflow run ID avec des vérifications golden défaillantes. Produit le résumé de différence relative par métrique que vous collez dans la description PR.
build-and-dependency — pour vérifier que la nouvelle image compile localement avant d'ouvrir la PR (docker build --target main --build-arg FROM_IMAGE_NAME=$(cat docker/.ngc_version.dev) ...).
cicd — pour les sémantiques du label de scope PR (Run functional tests, complexity::*) et le flux copy-pr-bot.

bump-base-image