train-llm-from-scratch : préentraînement et post-entraînement en PyTorch nu

Un tutoriel qui va jusqu'au modèle aligné

Le README résume la promesse en une phrase : partir du texte brut et arriver à un modèle de style raisonnement aligné, chaque algorithme étant écrit à la main en PyTorch, sans trl, sans peft et sans transformers. Le projet a commencé comme un tutoriel de préentraînement et couvre désormais l'ensemble de la chaîne. Le public visé est explicitement divisé en trois : l'étudiant qui lit de haut en bas, le développeur qui copie les commandes, le chercheur intéressé par la seconde moitié, celle du post-entraînement. Cette dernière partie est présentée comme le cœur du dépôt : SFT, modèle de récompense Bradley-Terry, PPO avec GAE, DPO, ORPO, KTO et GRPO, tous appliqués au même petit Transformer. Le README précise aussi que l'auteur cherche un poste de doctorat en IA, ce qui donne une indication sur le rythme de maintenance à attendre.

Du texte brut au prochain token, puis à la récompense

Le pipeline est donné sous forme de flèches dans le README : raw text vers tokens, vers un Transformer, vers la perte de prochain token, vers un modèle de base. Ensuite le modèle de base passe par SFT, un Reward Model, un choix entre PPO et DPO, puis GRPO, et enfin l'évaluation et le chat. Le README insiste sur l'idée unique qui traverse tout : transformer le texte en nombres, prédire le token suivant, puis modifier les données et la perte jusqu'à obtenir le comportement voulu. Les diagrammes suivent un code couleur documenté : vert pour les données brutes, turquoise pour les données tokenisées stockées sur disque, bleu pour une étape de traitement, jaune pour le modèle ou une étape d'entraînement, orange pour le RL et les récompenses, rouge pour une perte, gris pour un checkpoint sauvegardé, violet pour la sortie finale ou l'évaluation. Ce code couleur n'est pas décoratif : il sert de légende commune à tous les schémas, ce qui aide à suivre un pipeline long sans se perdre.

Le Transformer décomposé en blocs lisibles

La table des matières détaille la construction du modèle dans un ordre précis : MLP, attention à une tête, attention multi-têtes, bloc Transformer, Transformer complet. Le README affirme que le code suit le papier Attention is All You Need, et que chaque bloc de code est précédé d'une explication en langage courant, souvent suivie de la sortie attendue. C'est la partie la plus pédagogique du dépôt. Elle a une contrepartie : en écrivant tout à la main, on renonce aux optimisations des bibliothèques établies. Le README ne revendique d'ailleurs aucune performance particulière, seulement la possibilité d'entraîner un modèle de taille million ou milliard de paramètres sur un seul GPU. La preuve donnée est une sortie de modèle de 13 millions de paramètres, citée telle quelle dans le README, avec un texte grammaticalement instable. C'est honnête : à cette échelle, le résultat ressemble à ce qu'on attend d'un petit modèle de langage, pas à un assistant.

Installation en mode éditable et extras optionnels

Les commandes d'installation sont explicites. On clone le dépôt, on entre dans le dossier, puis on lance pip install -e . Le README justifie ce choix : l'installation éditable place config, src, data_loader et ui sur le chemin d'import, ce qui évite de définir PYTHONPATH à la main. Deux extras sont documentés : pip install -e ".[train]" pour datasets et wandb, utile au téléchargement des données et à la journalisation, et pip install -e ".[ui]" pour streamlit, pandas et altair, qui alimentent le panneau de contrôle. Le README mentionne aussi une documentation hébergée sur fareedkhan-dev.github.io et une interface Streamlit décrite comme un control panel. Le texte fourni s'arrête au milieu de la phrase décrivant l'extra ui, donc je ne peux pas confirmer la liste complète des dépendances ni le contenu exact de pyproject.toml au-delà de ce qui est cité.

Le tableau GPU comme contrat de lecture

Le README impose une condition matérielle claire : il faut un GPU. Un Colab ou un Kaggle T4 gratuit suffit pour le modèle de 13 millions de paramètres, mais pas pour un modèle d'un milliard. Le tableau fourni est le document le plus utile du dépôt, parce qu'il chiffre les limites. Un Tesla T4 avec 16 Go peut entraîner le 13M et viser environ 1,5 à 2 milliards de paramètres au maximum. Une RTX 4060 avec 8 Go reste sur le 13M et plafonne autour d'1 milliard. Une A100 40 Go monte à environ 6 à 8 milliards. Une RTX 5090 32 Go est annotée 13M vérifié, configs plus grandes à déterminer, ce qui signale que les chiffres ne sont pas tous mesurés. Le README indique aussi que le script de préentraînement possède des drapeaux optionnels, --amp, --grad-checkpointing et --grad-accum, pour réduire la consommation mémoire. Ces options sont présentées comme un moyen de faire passer une grosse configuration, pas comme une garantie.

Ce que le dépôt ne fournit pas

Aucune release n'apparaît dans les métadonnées, et le dépôt n'est pas archivé. Le README ne décrit ni tests automatisés, ni intégration continue, ni politique de compatibilité entre versions. Pour un projet qui sert à apprendre, ce n'est pas rédhibitoire. Pour un usage en production, c'est un obstacle : une mise à jour de PyTorch peut casser un script sans préavis, et rien dans le matériel fourni n'indique un engagement de maintenance au-delà des pushes récents. Il faut aussi noter que le projet n'est pas un outil de prétraitement de données à grande échelle. Le README ne mentionne ni streaming distribué, ni déduplication, ni filtrage de qualité de corpus. Si votre problème est de préparer des téraoctets de texte, ce dépôt n'est pas le bon outil : il vous montrera comment tokeniser et entraîner, pas comment industrialiser la collecte. Enfin, l'absence de trl et peft est un choix pédagogique assumé, mais elle signifie que vous réimplémentez des mécanismes déjà éprouvés ailleurs, avec les risques de bug que cela comporte.

Face à Hugging Face Transformers et TRL

L'alternative la plus directe est la pile Hugging Face : transformers pour le modèle, trl pour le SFT, le DPO et le PPO, peft pour les adaptateurs. Le README nomme lui-même ces trois bibliothèques comme ce qu'il évite. La différence d'approche est nette. Avec TRL, vous configurez un Trainer et vous laissez la bibliothèque gérer la boucle, le masking des labels, la gestion du gradient et l'intégration des adaptateurs. Avec train-llm-from-scratch, vous lisez et modifiez chaque étape, ce qui est précieux pour comprendre pourquoi une perte de DPO se comporte d'une certaine façon, mais coûteux si vous voulez seulement obtenir un modèle aligné. Autre différence : l'écosystème Hugging Face donne accès à des modèles préentraînés, donc vous pouvez partir d'un checkpoint existant. Ici, le pipeline commence par le texte brut, et le README ne décrit pas d'import de poids externes. Si votre objectif est un assistant fonctionnel en quelques jours, TRL et peft sont plus courts. Si votre objectif est de savoir ce qui se passe dans le gradient, ce dépôt est plus direct.

Licence MIT et coût de suivi

La licence est MIT, ce qui autorise la réutilisation, la modification et la redistribution, y compris dans un contexte commercial, à condition de conserver l'avis de copyright et la licence. Je ne donne pas de conseil juridique : les dépendances elles-mêmes, comme PyTorch, datasets, wandb, streamlit, pandas et altair, ont leurs propres licences, qu'il faut vérifier séparément si vous redistribuez un produit dérivé. Le coût de maintenance se lit dans la structure du dépôt : pas de release, donc pas de version épinglée à suivre. Vous dépendez de la branche main. Les extras [train] et [ui] ajoutent des dépendances lourdes, et les commandes d'installation en mode éditable supposent que vous restez dans l'arborescence du dépôt. Le README ne documente pas de procédure de migration ni de journal de changements. Pour un projet pédagogique, ce coût est acceptable : vous lisez le code, vous l'exécutez, vous l'adaptez. Pour un service en production, il faut prévoir de figer vos propres dépendances et de maintenir votre fork.

Conclusion éditoriale

À adopter si vous voulez lire et exécuter un pipeline complet sans trl, peft ni transformers, et si vous disposez d'un GPU d'au moins 16 Go pour le modèle de 13 millions de paramètres. À éviter si vous cherchez un entraînement distribué multi-nœuds ou une API stable : aucune release n'est publiée et le dépôt indique lui-même que les gros configs restent à vérifier. Vérifiez d'abord le tableau de mémoire GPU du README, puis le contenu réel de pyproject.toml pour les extras [train] et [ui].

Sources officielles

1. FareedKhan-dev/train-llm-from-scratch on GitHub
2. Issues
3. License: MIT
4. Project website
5. README