how-to-train-your-gpt : écrire un Transformer décodeur ligne par ligne

Un cours, pas une bibliothèque

Le dépôt se présente comme un manuel interactif de 12 chapitres et plus de 7 500 lignes, complété par 28 fiches thématiques autonomes. Le README précise l'intention de l'auteur : apprendre ce qu'il ne comprenait pas entièrement, en particulier la partie attention. La licence MIT s'applique au contenu comme au code, ce qui autorise la réutilisation et la modification avec conservation du texte de licence, sans garantie d'aucune sorte.

Le public visé est explicite. Il faut savoir écrire des fonctions, des classes et des listes en Python, et savoir lancer un pip install. Le README affirme qu'aucune expérience en PyTorch, en calcul différentiel ou en algèbre linéaire n'est nécessaire, ces notions étant introduites au fil des chapitres. Un ingénieur qui évalue des architectures y trouvera aussi des comparaisons, par exemple RoPE contre encodage positionnel appris, ou RMSNorm contre LayerNorm.

Ce n'est pas un projet à installer comme dépendance. Le README indique une finalité d'apprentissage, et il n'existe aucune release publiée. Le dépôt est actif, la dernière poussée datant du 30 août 2026, mais rien n'indique une API stable à consommer.

Ce que les chapitres construisent réellement

La progression part du tokenizer et remonte jusqu'au moteur d'inférence. Le chapitre 2 déroule un BPE sur un mot comme unbelievably. Le chapitre 3 traite les embeddings et l'arithmétique vectorielle. Le chapitre 4 introduit RoPE, avec l'idée que LLaMA fait tourner des vecteurs au lieu d'additionner une position. Le chapitre 5 est annoncé comme le cœur du sujet : Q, K, V, la mise à l'échelle, le masque causal, et une démonstration en huit étapes.

Vient ensuite le bloc Transformer avec RMSNorm, SwiGLU, les connexions résiduelles et la comparaison pre-norm contre post-norm. Le chapitre 7 assemble un modèle de 151 millions de paramètres avec weight tying. Le chapitre 8 couvre l'entraînement : entropie croisée, rétropropagation, AdamW, warmup cosinus, précision mixte et accumulation de gradient. Le chapitre 9 traite l'inférence avec le KV cache, la température, top-k, top-p, la recherche par faisceau et la pénalité de répétition. Le chapitre 10 rassemble le tout dans un main.py exécutable.

Le README donne des ordres de grandeur de lignes par composant : environ 60 pour le tokenizer, 120 pour l'attention multi-têtes, 200 pour le modèle complet, 250 pour la boucle d'entraînement. Ces chiffres décrivent la taille du code pédagogique, pas une mesure de performance.

L'architecture enseignée et ses justifications

Le dépôt revendique une architecture décodeur-only de style LLaMA 3, avec un tableau qui associe chaque technique à un modèle public : RoPE chez LLaMA, Mistral et Qwen, RMSNorm chez LLaMA, Mistral et Gemma, SwiGLU chez PaLM, LLaMA et Gemini, pre-norm chez GPT-3. Le README note que GPT-4 et Claude sont propriétaires et non documentés, et que l'enseignement porte donc sur ce qui est publiquement confirmé.

Les justifications avancées sont parfois chiffrées. RMSNorm est présenté comme 15 pour cent plus rapide que LayerNorm à efficacité égale, la précision mixte comme deux fois plus rapide avec moitié moins de mémoire, le weight tying comme une économie de 30 pour cent de paramètres. Ces valeurs proviennent du README et ne sont accompagnées d'aucun protocole de mesure. Il faut les lire comme des ordres de grandeur couramment cités, pas comme des résultats reproduits dans ce dépôt.

Deux choix méritent l'attention. Le pre-norm est rattaché à la stabilité de l'entraînement au-delà de 100 couches, argument classique mais qui ne concerne pas un modèle de 151 millions de paramètres. Et le weight tying entre l'embedding et la projection de sortie réduit le nombre de paramètres, ce qui est un compromis assumé et non un gain gratuit.

Mise en route : Colab ou environnement local

Le README propose deux chemins. Le premier passe par un badge Colab pointant vers notebooks/colab_train.ipynb sur la branche master. C'est la voie la plus directe : aucune installation locale, l'environnement GPU étant fourni par le service.

Le second chemin est manuel. Le README donne les commandes de clonage :

git clone https://github.com/raiyanyahya/how-to-train-your-gpt.git cd how-to-tra

Le dépôt ne publie aucune release, donc pas de version épinglée à installer. Le chapitre 1 est consacré à la configuration : installation des outils, choix entre GPU et CPU, création d'un environnement virtuel, bases de PyTorch. Le chapitre 10 fournit un main.py unique qui regroupe tokenizer, modèle, entraînement et inférence dans un seul fichier, ce qui évite d'avoir à recoller des morceaux éparpillés.

Un point pratique : l'ordre de lecture n'est pas indifférent. Le README insiste pour commencer au chapitre 0 et avancer séquentiellement, chaque chapitre s'appuyant sur le précédent. Sauter directement au chapitre 5 sur l'attention sans avoir vu les embeddings et RoPE revient à lire du code dont les entrées n'ont pas été définies.

Ce que le dépôt n'est pas

Le README porte lui-même la mention learning only. C'est la limite principale et elle est honnête. Un modèle de 151 millions de paramètres entraîné sur un corpus de démonstration ne produit pas un assistant utilisable. Le chapitre 7 annonce ce nombre de paramètres, ce qui situe l'exercice très en dessous des modèles déployés aujourd'hui.

La forme du dépôt impose une seconde contrainte : l'essentiel du contenu est en Jupyter Notebook et en fichiers Markdown. Il n'y a pas de package installable, pas de tests, pas de versionnement sémantique. Réutiliser le code d'attention dans un projet réel demande de l'extraire à la main et de le confronter à du code non commenté, donc plus difficile à auditer.

Le coût d'entraînement n'est pas chiffré dans les éléments fournis. La précision mixte et l'accumulation de gradient sont présentées comme des techniques du chapitre 8, mais aucune durée, aucun matériel de référence, aucun volume de données ne sont indiqués. Si votre objectif est de reproduire un résultat mesurable, ce dépôt ne fournit pas de point de comparaison. Il fournit une explication.

nanoGPT comme point de comparaison

L'alternative la plus proche est nanoGPT d'Andrej Karpathy. La différence tient à la densité du commentaire et au choix d'architecture. nanoGPT vise un code court et lisible, proche de GPT-2, avec peu de commentaires et l'hypothèse que le lecteur connaît déjà les Transformers. how-to-train-your-gpt revendique 100 pour cent de code commenté et une architecture LLaMA 3 style, donc RoPE, RMSNorm et SwiGLU plutôt que des encodages positionnels appris et du LayerNorm.

L'écart de pédagogie est réel. Le dépôt ajoute 28 fiches thématiques, deux parcours narratifs qui suivent une phrase à travers tout le modèle, et des analogies destinées à un lecteur sans bagage en apprentissage automatique. nanoGPT suppose une familiarité avec PyTorch et la lecture d'articles de recherche.

Le choix dépend donc de votre point de départ. Si vous lisez déjà du code PyTorch sans difficulté et voulez un modèle de référence minimal, la concision de nanoGPT est un avantage. Si vous avez besoin qu'on vous explique pourquoi le facteur 1 sur racine de d_k existe, la densité de commentaires de ce dépôt est l'argument principal. Aucun des deux n'est un framework de production.

Maintenance et propriété intellectuelle

Le dépôt est sous licence MIT, ce qui autorise l'usage, la copie, la modification et la redistribution, y compris commerciale, à condition de conserver l'avis de copyright et le texte de licence. La licence exclut toute garantie. Ce paragraphe décrit le texte de la licence, il ne constitue pas un conseil juridique.

Côté maintenance, le rythme est celui d'un projet personnel : la dernière poussée date du 30 août 2026, il n'y a aucune release publiée et aucun mécanisme de version. Une mise à jour de PyTorch peut donc casser un notebook sans qu'une version corrigée soit identifiée. La contrepartie est que le contenu est majoritairement du Markdown et du code autonome, peu exposé aux ruptures d'API des bibliothèques.

Le coût de mise à niveau se concentre sur les chapitres 8 et 9, entraînement et inférence, qui dépendent le plus de PyTorch et des API de précision mixte. Les chapitres sur les embeddings, RoPE et l'attention reposent sur des tenseurs et des opérations de base, beaucoup plus stables dans le temps. Si vous cherchez un support durable, c'est de ce côté qu'il faut regarder en premier.

Conclusion éditoriale

À adopter si vous voulez écrire vous-même un tokenizer BPE, une attention multi-têtes et une boucle d'entraînement pour comprendre ce qui se passe à l'intérieur. À éviter si vous cherchez un modèle à affiner sur vos données ou un composant à importer dans une application. Avant de vous lancer, ouvrez le notebook Colab et vérifiez que le chapitre 5 sur l'attention correspond bien à votre niveau, puis lisez le chapitre 10 pour voir si le script unique tient sur votre machine.

Sources officielles

1. Issues
2. License: MIT
3. raiyanyahya/how-to-train-your-gpt on GitHub
4. README