stas00/ml-engineering : le carnet de terrain du training à grande échelle
Machine Learning Engineering Open Book
En bref
- De quoi s’agit-il ?
- Un recueil de procédures et de scripts pour entraîner et servir des LLM/VLM sur plusieurs nœuds, écrit par l'ingénieur qui a piloté BLOOM-176B et IDEFICS-80B. Sa valeur tient à ses scripts de diagnostic, pas à ses chapitres explicatifs.
- À qui s’adresse-t-il ?
- À adopter si vous exploitez déjà un cluster multi-nœuds et cherchez des commandes prêtes à coller pour diagnostiquer un entraînement qui bloque : commencez par all_reduce_bench.py et torch-distributed-gpu-test.py, qui sont les deux outils les plus directement réutilisables du dépôt. À éviter si vous cherchez un tutoriel progressif sur PyTorch ou une bibliothèque installable : il n'y a ni code publié sur PyPI ni parcours pédagogique, seulement des notes et des scripts.
- Puis-je l’utiliser commercialement ?
- Oui, en citant les auteurs. CC-BY-SA-4.0 autorise l’usage commercial à condition de créditer les auteurs et d’indiquer vos modifications. Elle est conçue pour les contenus créatifs : vérifiez comment elle s’applique au code.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 4 jours.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Ce que le dépôt contient réellement
Le README annonce la couleur : il s'agit d'un « ongoing brain dump » issu du training de BLOOM-176B en 2022, d'IDEFICS-80B en 2023 et de modèles RAG chez Contextual.AI en 2024. L'auteur précise viser les « LLM/VLM training engineers and operators », et que le contenu comporte « lots of scripts and copy-n-paste commands ». C'est la promesse exacte du dépôt : des commandes à coller, pas un manuel progressif.
La table des matières couvre sept parties. Insights (choix de fournisseur cloud, décision de changer de génération de GPU), Hardware (compute, storage, network), Orchestration (conteneurs, SLURM), Training, Inference, Development (debugging, testing), Miscellaneous (resources). Le README liste aussi des tableaux comparatifs de TFLOPS théoriques, de taille et vitesse de mémoire accélérateur, et de débits réseau inter-nœuds et intra-nœuds.
Le public réel est étroit. Un ingénieur qui entraîne un modèle sur un seul GPU n'y trouvera presque rien d'actionnable. Le contenu suppose un cluster, un ordonnanceur, et des problèmes qui n'apparaissent qu'à partir du moment où la communication entre nœuds devient le facteur limitant.
Les scripts qui justifient le détour
Le README met en avant trois outils dans une section « Shortcuts ». Le premier, all_reduce_bench.py, est présenté comme « a much easier way to benchmark network throughput than nccl-tests ». La formulation est un argument de positionnement : l'auteur considère nccl-tests comme la référence établie et propose une alternative plus simple à mettre en œuvre. Le deuxième, torch-distributed-gpu-test.py, sert à « quickly test your inter-node connectivity ». Le troisième, mamf-finder.py, répond à la question du TFLOPS réellement atteignable sur un accélérateur donné.
Ces trois scripts ciblent le même angle mort : l'écart entre les chiffres théoriques des tableaux comparatifs et ce que la machine produit vraiment. Un cluster qui affiche de bons débits réseau sur le papier peut s'effondrer dès que la topologie réelle entre en jeu. Le dépôt ne prétend pas résoudre ce problème par l'analyse, il fournit l'instrument de mesure.
C'est là que se trouve la valeur la plus défendable du projet. Les chapitres explicatifs vieillissent avec le matériel ; un script de benchmark reste exécutable tant que l'API sous-jacente ne change pas.
Mettre les outils en route
Le README donne les chemins exacts, ce qui suffit à localiser chaque outil dans l'arborescence : network/benchmarks/all_reduce_bench.py, debug/torch-distributed-gpu-test.py et compute/accelerator/benchmarks/mamf-finder.py. Le dépôt ne publie pas de paquet installable ni de release : le README indique explicitement « Recent releases: (none retrieved) » côté métadonnées, et aucune commande d'installation n'apparaît dans le texte fourni.
La procédure implicite est donc le clone du dépôt puis l'exécution directe des scripts avec l'interpréteur Python et les dépendances que chaque fichier suppose. Le README ne détaille pas ces dépendances, pas plus qu'il ne fournit de fichier de configuration unique. Les scripts sont conçus pour être lus et adaptés, pas invoqués avec des options standardisées.
Pour le volet ordonnancement, le dépôt renvoie à orchestration/slurm/users.md, décrit comme « a slurm cheatsheet and tricks ». Pour PyTorch, debug/pytorch.md est présenté comme une source de « quick copy-n-paste solutions to resolve hanging or breaking pytorch applications ». Ce sont les deux points d'entrée les plus opérationnels après les scripts de benchmark.
Je n'ai pas exécuté ces scripts et je ne peux donc pas confirmer leur compatibilité avec une version donnée de PyTorch ou de CUDA. Le matériel fourni ne permet pas de trancher ce point.
Le SKILL.md et les formats ebook
Deux éléments sortent du cadre habituel d'un dépôt de documentation. D'abord un fichier SKILL.md, que l'auteur décrit comme servant à « teach your AI agent to train and operate large-scale ML models better », avec deux compagnons externes : The Art of Debugging et Stas' Python Cookbook, chacun avec son propre SKILL.md. Ensuite des versions ebook, PDF et EPUB, hébergées sur le Hugging Face Hub, avec des instructions de build dans le dossier build et une reconstruction annoncée « once in a few weeks or so ».
La reconstruction périodique des ebooks est un point de friction à connaître. Si vous dépendez du PDF, vous travaillez sur un instantané qui peut avoir plusieurs semaines de retard sur la branche master. Le dépôt signale d'ailleurs que les instructions de build sont disponibles pour qui veut la version la plus récente.
Le SKILL.md mérite une réserve. Un fichier destiné à un agent IA dépend étroitement du modèle et de l'outillage employés. Le README ne documente ni le format attendu ni les résultats observés, et je n'ai aucun élément pour évaluer son efficacité. À traiter comme une piste à tester, pas comme une fonctionnalité acquise.
Ce que le dépôt ne fera pas pour vous
La licence CC-BY-SA-4.0 est une licence de contenu, pas une licence logicielle. Elle impose l'attribution et le partage dans les mêmes conditions pour les adaptations. Concrètement, si vous reprenez des passages dans de la documentation interne diffusée, la clause de partage à l'identique s'applique à l'œuvre dérivée. Pour un usage strictement interne et non diffusé, la question se pose différemment, mais je ne donne pas d'avis juridique : faites trancher ce point avant de réutiliser le contenu à grande échelle.
Le vrai angle mort est la maintenance. Le README ne décrit aucune politique de compatibilité, aucun test automatisé des scripts, aucun calendrier de mise à jour au-delà de la reconstruction des ebooks. Les commandes de debug PyTorch et les scripts de benchmark dépendent d'API qui bougent, et rien dans le matériel fourni n'indique qu'elles sont vérifiées à chaque changement. Le dépôt n'est pas archivé et le dernier push est daté du 8 septembre 2026, ce qui suggère une activité récente, mais l'absence de releases rend le suivi des changements difficile : vous suivez master, avec tout ce que cela implique.
Autre limite : le contenu est un « brain dump » revendiqué comme tel. Il n'y a pas de relecture éditoriale homogène, pas de garantie que chaque chapitre ait le même niveau de détail, et pas de parcours ordonné. Un lecteur qui cherche une progression du débutant vers l'expert sera mal servi.
Face à quoi le comparer
L'alternative la plus directe est nccl-tests, que le README cite lui-même comme la référence que all_reduce_bench.py cherche à remplacer. La différence d'approche est nette : nccl-tests fournit une suite de benchmarks compilés, avec des primitives de communication variées et une couverture systématique des opérations collectives. all_reduce_bench.py se concentre sur l'all_reduce, l'opération qui domine en entraînement distribué, et l'auteur le présente comme plus simple à lancer. Vous gagnez en rapidité de mise en œuvre, vous perdez en couverture.
Une autre comparaison utile concerne le contenu rédactionnel. Les livres et cours consacrés au ML engineering à grande échelle proposent en général un chemin structuré, avec des exercices et une progression. Ici, le dossier courses/lesson-learned est décrit comme offrant « a very different way of reading my open books, by going over the terse learned insights », ce qui reste une lecture d'insights condensés, pas un cursus. La différence n'est pas qualitative mais de nature : d'un côté un matériau de référence à consulter quand un problème précis survient, de l'autre une formation à suivre dans l'ordre.
Le choix dépend donc de votre situation. Si vous êtes bloqué sur un entraînement qui hang, un cheatsheet SLURM et un script de test de connectivité valent plus qu'un chapitre théorique. Si vous cherchez à comprendre les fondamentaux, ce dépôt n'est pas le bon point d'entrée.
Le calcul de rentabilité d'un changement de GPU
Le chapitre Insights intitulé « When Is It Worth Upgrading GPUs? » est présenté comme « a practical framework for deciding whether a GPU generation upgrade is worth its cost, worked through on a real H200 → B200 benchmark ». C'est le seul endroit du README où une méthodologie de décision chiffrée est explicitement annoncée, avec un cas concret nommé.
L'intérêt de ce chapitre tient à ce qu'il relie deux parties du dépôt : les tableaux de TFLOPS théoriques et de taille mémoire d'un côté, les scripts de mesure réelle de l'autre. Un changement de génération ne se justifie pas par les chiffres constructeur, mais par le gain effectif sur votre charge de travail, qui dépend de la mémoire disponible, de la bande passante et du débit réseau. Le dépôt fournit les instruments pour mesurer ces trois dimensions et un cadre pour interpréter le résultat.
Je ne peux pas évaluer la solidité du benchmark H200 vers B200, n'ayant pas accès au contenu du chapitre. Le README indique seulement qu'il est « worked through », ce qui laisse penser à un raisonnement complet plutôt qu'à un tableau de chiffres. À vérifier avant de vous en servir comme argument budgétaire.
Conclusion éditoriale
À adopter si vous exploitez déjà un cluster multi-nœuds et cherchez des commandes prêtes à coller pour diagnostiquer un entraînement qui bloque : commencez par all_reduce_bench.py et torch-distributed-gpu-test.py, qui sont les deux outils les plus directement réutilisables du dépôt. À éviter si vous cherchez un tutoriel progressif sur PyTorch ou une bibliothèque installable : il n'y a ni code publié sur PyPI ni parcours pédagogique, seulement des notes et des scripts. Avant de vous engager, vérifiez que le fichier SKILL.md et le dossier courses répondent au format que vous attendez, car ce sont les deux points d'entrée qui s'écartent le plus d'un dépôt classique.
Notes de la communauté