Configuration de l'environnement Spark

DGX Spark embarque une puce GB10 Grace Blackwell : CPU aarch64, GPU SM121, 128 GB de mémoire unifiée, CUDA 13. Il s'agit d'une plateforme plus étroite et plus récente qu'une boîte x86 CUDA 12 standard, donc la sélection des paquets et la correspondance ABI sont plus critiques que d'habitude — l'écosystème des wheels pour aarch64 + CUDA 13 se remplit encore.

Quand utiliser cette compétence

• Configurer une nouvelle boîte Spark pour l'entraînement ou l'inférence.
• Rencontrer une erreur d'import mentionnant libcudart, un symbole manquant, ou une wheel qui « s'installe bien mais ne se charge pas ».
• L'installation d'un framework (PyTorch, Unsloth, TRL, vLLM, xformers) échoue, se bloque, ou bascule silencieusement vers le CPU.
• Décider s'il faut utiliser un conteneur NGC ou pip nu.
• Restaurer une configuration fonctionnelle après une réinstallation du système d'exploitation ou une mise à jour de l'image de base, nécessitant de revérifier depuis le début.

Chacun de ces cas accepte le même correctif général : faire correspondre la combinaison conteneur/wheel à CUDA 13 et SM121, ne pas combattre l'ABI.

Règle du conteneur en premier

Décision rapide, avant les détails ci-dessous :

• Travail d'entraînement/inférence standard → conteneur NGC PyTorch.
• Fine-tuning centré sur Unsloth → conteneur Unsloth (il embarque déjà la combinaison Triton/xformers/transformers épinglée et validée pour ce chemin).
• Aucun ne s'adapte (paquet système personnalisé, interprète IDE local) → pip nu, en suivant la séquence exacte ci-dessous.

Préférez un conteneur par défaut. Utilisez nvcr.io/nvidia/pytorch:25.09-py3 comme base pour le travail général — le tag le plus récent confirmé fonctionnel sur ce matériel ; tirez un tag bénit plus récent s'il est disponible localement plutôt que de bloquer fortement sur 25.11-py3. Le tag NGC étant daté, l'exécuter directement est acceptable :

docker run --runtime=nvidia --gpus all -it --rm \
  nvcr.io/nvidia/pytorch:25.09-py3

unsloth/unsloth:dgxspark-latest est par contraste un tag mobile — résolvez et épinglez son digest avant de l'exécuter pour quoi que ce soit de reproductible ; le tag nu est une étape de découverte seulement, pas l'invocation par défaut. Séquence complète pull-inspect-pin et justification des flags/montages de volumes pour les répertoires finetuning/ : references/container-workflow.md. Traitez pip nu comme l'exception.

La raison de cette position en faveur du conteneur est l'épinglage, pas la commodité. Les versions de Triton, xformers et transformers interagissent étroitement avec la cible SM121 de GB10 et CUDA 13 ; un conteneur les verrouille tous ensemble face à une combinaison déjà validée sur ce matériel. Pip nu laisse cette résolution à vos soins, une import cassée à la fois.

Quand pip nu est justifié, suivez verbatim et dans l'ordre la séquence d'installation du playbook NVIDIA :

pip install "transformers==5.13.1" "peft==0.19.1" "hf_transfer==0.1.9" "datasets==4.3.0" "trl==1.8.0"
pip install --no-deps "unsloth==2026.7.2" "unsloth_zoo==2026.7.2" "bitsandbytes==0.49.2"
pip install -U "torchao==0.17.0"

Le flag --no-deps de la deuxième commande n'est pas optionnel — laisser pip ré-résoudre l'arborescence des dépendances d'Unsloth sur aarch64 est un moyen courant de tirer une build torch ou triton incompatible. La troisième ligne n'est pas optionnelle non plus : le torchao bundlé de l'image de base NGC est trop ancien pour le chemin LoRA-attach actuel de peft (ImportError: ... torchao ... seules les versions au-dessus de 0.16.0 sont supportées) — un bloqueur dur, pas un avertissement. Chaque épinglage == ci-dessus est structurel, provenant de la matrice de versions connues et bonnes dans references/stack-matrix.md (sa date Last verified gouverne la peremption) — une installation non épinglée résout les versions actuelles de PyPI bien en dehors de ce que cette version d'Unsloth supporte.

Tirez un tag frais quand une nouvelle version bénite est annoncée. Reconstruisez localement à partir d'une des deux bases seulement quand un projet a besoin d'un paquet système supplémentaire empiléé — non pour « mettre à niveau » un composant que l'image épingle déjà. Détails sur les deux chemins : references/container-workflow.md.

Un dernier contrôle de préparation : les playbooks DGX Spark officiels ont expédié cassé auparavant. Vérifiez les problèmes récents sur github.com/NVIDIA/dgx-spark-playbooks (et les autres ressources dans references/stack-matrix.md) avant de faire confiance à une recette verbatim pour une longue exécution.

La règle ABI

L'échec le plus courant sur Spark est un décalage ABI CUDA 12/13 : une wheel construite contre libcudart.so.12 chargée sur un système qui n'a que libcudart.so.13. L'installation réussit généralement ; l'échec apparaît plus tard sous forme d'erreur de symbole manquant ou d'un segfault qui ne pointe pas évidemment vers CUDA.

Correctif : tirez les wheels depuis download.pytorch.org/whl/cu130 (les builds aarch64 taggées cu130), ou utilisez l'un des conteneurs ci-dessus, qui embarquent déjà une build assorti. Avant de chasser une trace de pile mentionnant un symbole CUDA, vérifiez contre quel tag CUDA la wheel installée a été construite :

python3 -c "import torch; print(torch.version.cuda)"

Si ce résultat ne commence pas par 13, le décalage ABI est la première chose à corriger. Les builds de conteneur NGC (ex. nvcr.io/nvidia/pytorch:25.09-py3) construisent torch en interne contre CUDA 13 sans tag de wheel +cu130 — pip show torch ne mentionnera pas cu130 là, et cette absence seule n'est pas un échec.

Symptômes typiques :

• ImportError: undefined symbol référençant une fonction du runtime CUDA.
• Un segfault au premier appel .cuda(), pas de trace utile.
• Une wheel qui s'installe proprement, puis échoue à l'import — le solveur de pip ne vérifie pas l'ABI CUDA, seulement les contraintes de version.
• Deux environnements « identiques » se comportant différemment — généralement l'un a une wheel cu130, l'autre un reste cu121/cu124.

Le correctif est le même quel que soit le symptôme : faire correspondre le tag CUDA de la wheel au système, ou utiliser un conteneur qui le fait déjà.

Tableau récapitulatif des composants

État condensé pour les composants les plus susceptibles de poser problème. Tableau complet avec URLs de wheels, flags de build, distinction sm_121 vs sm_121a, et matrice de versions connues et bonnes datée : references/stack-matrix.md.

Tout le reste — Unsloth, Axolotl, TRL, PEFT — s'installe proprement via le chemin conteneur-en-premier ci-dessus. LLaMA-Factory et NeMo sont fragiles sur Spark ; vérifiez d'abord les problèmes en amont.

Commandes de vérification

Confirmer que l'environnement peut réellement voir le GPU avant d'exécuter quelque chose de coûteux :

import torch
print(torch.cuda.is_available(), torch.version.cuda)

Cet appel retourne deux valeurs ; le format de sortie exact est une ligne, <bool> <cuda-version> :

True 13.0

S'il imprime False à la place, ne sautez pas directement à une réinstallation de wheel — le décalage ABI est une cause parmi plusieurs :

Vérifiez d'abord nvidia-smi — s'il ne montre pas le GPU, c'est l'un des trois premiers, pas ABI. Réinstallez une wheel seulement une fois l'ABI confirmé. Détail par hypothèse : references/stack-matrix.md. Exécutez juste après le démarrage du conteneur, avant d'installer les paquets spécifiques au projet.

Une vérification de plus : si la compilation du kernel Triton échoue une fois l'entraînement lancé, réglez TRITON_PTXAS_PATH=/usr/local/cuda/bin/ptxas et réessayez — voir references/stack-matrix.md pour la liste complète des solutions.

Étapes suivantes

Un environnement vérifié n'est que le point de départ. Voir aussi : spark-training-gotchas pour les vérifications de préparation aux défaillances avant une exécution d'entraînement, et spark-memory-thermal-ops pour les OOM de mémoire unifiée et l'étranglement thermique pendant les longues exécutions.