reasoning-from-scratch : construire un modèle de raisonnement à partir d'un Qwen3 pré-entraîné
Implement a reasoning LLM in PyTorch from scratch, step by step
En bref
- De quoi s’agit-il ?
- Le dépôt officiel du livre Build a Reasoning Model (From Scratch) de Sebastian Raschka. Huit chapitres de notebooks PyTorch qui ajoutent, une technique à la fois, des capacités de raisonnement à un LLM de base, plus un appendice final consacré à une interface de chat.
- À qui s’adresse-t-il ?
- À adopter si vous voulez coder vous-même le passage d'un modèle de base à un modèle de raisonnement et que vous acceptez la contrainte des notebooks. À éviter si vous cherchez un composant de production ou une bibliothèque installable.
- Puis-je l’utiliser commercialement ?
- Oui. Apache-2.0 est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 10 jours.
- En quel langage est-il écrit ?
- Principalement Jupyter Notebook, 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 couvre, et ce qu'il laisse de côté
Le point de départ est explicite dans le README : on ne repart pas d'un tokenizer et de matrices aléatoires. Le livre travaille sur un LLM de base open source déjà pré-entraîné, Qwen3, et empile par-dessus les méthodes de raisonnement. Le README précise que le dépôt contient aussi du code pour charger les poids de modèles pré-entraînés existants. Autrement dit, la partie « comment fonctionne un transformer » n'est pas ici : elle appartient au livre précédent de l'auteur, Build a Large Language Model (From Scratch), que la section Companion Book désigne comme le complément naturel.
Le périmètre réel tient en trois familles de techniques, résumées par le README : le scaling à l'inférence, l'apprentissage par renforcement et la distillation. Les chapitres 4 et 5 traitent le scaling à l'inférence, d'abord par échantillonnage multiple, ensuite par auto-raffinement. Les chapitres 6 et 7 passent à l'entraînement par renforcement, avec GRPO puis une version améliorée de GRPO. Le chapitre 8 ferme la boucle avec la distillation. Le public visé est donc précis : quelqu'un qui sait déjà lire du PyTorch et qui veut comprendre pourquoi une chaîne de pensée améliore un score, pas seulement qu'elle l'améliore.
Le trajet d'un notebook à l'autre
Le dépôt n'est pas une bibliothèque mais une suite de notebooks numérotés. Chaque chapitre possède un dossier 01_main-chapter-code contenant deux fichiers : un notebook principal, par exemple ch04_main.ipynb, et un notebook de solutions d'exercices, ch04_exercise-solutions.ipynb. Ce découpage est cohérent avec la nature pédagogique du projet : le code du chapitre est le support de lecture, et les exercices forcent à modifier ce code plutôt qu'à le consommer.
La progression est cumulative. Le chapitre 2 charge un LLM pré-entraîné et génère du texte. Le chapitre 3 construit l'évaluation, ce qui est une décision structurante : sans mesure, les chapitres suivants seraient invérifiables. Le chapitre 4 ajoute le scaling à l'inférence, le chapitre 5 l'auto-raffinement, puis viennent le RL et la distillation. Le README ajoute trois appendices qui sortent du chemin principal : l'appendice C reproduit le code source de Qwen3, l'appendice D montre comment utiliser des LLM plus grands, et l'appendice E traite le batching et l'exécution orientée débit. Ce dernier point mérite l'attention : un notebook qui traite un exemple à la fois et un notebook qui traite des lots ne se comportent pas de la même façon, et l'auteur a jugé nécessaire d'en faire un appendice séparé.
Installation et premiers pas
Le README donne une commande de clonage allégée :
git clone --depth 1 https://github.com/rasbt/reasoning-from-scratch.git
git clone --depth 1 https://github.com/rasbt/reasoning-from-scratch.git
Le --depth 1 évite de télécharger tout l'historique, ce qui a du sens pour un dépôt de notebooks pédagogiques. Le README renvoie aussi vers un bouton Download ZIP pour ceux qui préfèrent cette voie.
Sur l'environnement, le dépôt reste volontairement discret. Le README indique que le chapitre 2 fournit des conseils supplémentaires sur l'installation de Python, la gestion des paquets et la configuration de l'environnement de développement. Il n'y a donc pas de commande pip install unique dans le README lui-même, et il faut ouvrir le notebook du chapitre 2 pour connaître la liste exacte des dépendances. C'est une limite pratique : on ne peut pas évaluer la surface de dépendances sans lire le notebook. Un fichier troubleshooting.md est présent à la racine, ce qui suggère que les problèmes d'installation sont suffisamment fréquents pour justifier un document dédié.
Matériel : la promesse et sa portée exacte
Le README est clair sur l'intention : le code des chapitres principaux est conçu pour tourner majoritairement sur du matériel grand public, dans un délai raisonnable, sans serveur spécialisé. Il ajoute que le code utilise automatiquement les GPU lorsqu'ils sont disponibles. La phrase s'arrête là dans le matériel fourni, sur un « That being said » qui n'est pas suivi de sa justification.
C'est un point à ne pas surinterpréter. La promesse porte sur les chapitres principaux, pas sur les appendices. L'appendice D, consacré aux LLM plus grands, et l'appendice E, consacré au débit, sont précisément les endroits où la contrainte matérielle change de nature. Un lecteur qui veut reproduire les résultats des chapitres 6 et 7 (entraînement par renforcement) doit s'attendre à une charge différente de celle du chapitre 2, qui se contente de charger un modèle et de générer du texte. Le README ne chiffre ni la VRAM requise ni la durée d'exécution, et rien dans le matériel fourni ne permet de l'affirmer.
Ce que le projet n'est pas
Le dépôt est le code officiel d'un livre, et cela impose des contraintes. Il n'y a pas de package publié, pas d'API stable, pas de versionnement sémantique au sens habituel. La seule release listée est v1.0, datée du 18 mai 2026, et elle correspond à la publication de l'ouvrage plutôt qu'à un cycle de maintenance logicielle. Le README porte d'ailleurs la mention « Table of Contents (In Progress) », ce qui indique que le contenu était encore en cours de finalisation au moment de la rédaction du fichier.
Conséquence directe : si votre objectif est d'intégrer du raisonnement dans un service, ce dépôt ne vous fournit pas de brique réutilisable. Vous y trouverez des implémentations lisibles de GRPO et de distillation, utiles pour comprendre ou pour porter ailleurs, mais pas un composant à importer. La licence Apache-2.0 est permissive et autorise la réutilisation, y compris dans un contexte commercial, à condition de conserver les mentions de copyright et de licence et de signaler les modifications. Cela dit, le code est indissociable d'un livre payant : la licence couvre le code du dépôt, pas le texte de l'ouvrage, et rien dans le matériel fourni ne permet de dire ce que la licence du livre autorise en matière de reproduction.
Alternative : rester sur le modèle de base
L'alternative la plus directe n'est pas un autre dépôt de raisonnement, c'est le dépôt précédent de l'auteur, LLMs-from-scratch. La différence d'approche est nette. LLMs-from-scratch construit l'architecture d'un transformer de base, l'entraînement et l'échantillonnage : on part de zéro et on obtient un modèle qui prédit du texte. reasoning-from-scratch prend ce modèle comme une boîte déjà entraînée et travaille uniquement sur ce qu'on ajoute après le pré-entraînement.
Le choix a une conséquence pratique. Dans LLMs-from-scratch, le coût principal est l'entraînement depuis l'initialisation, ce qui limite fortement la taille atteignable. Ici, le coût principal se déplace vers l'inférence et vers les boucles de RL sur un modèle existant. Vous héritez d'un modèle qui sait déjà écrire, et vous payez pour lui apprendre à raisonner. Pour quelqu'un qui veut comprendre la chaîne complète, les deux dépôts sont complémentaires. Pour quelqu'un qui veut seulement voir l'effet d'une méthode de raisonnement, reasoning-from-scratch est le point d'entrée le plus court, à condition d'accepter de ne pas savoir ce qui se passe dans les poids de Qwen3.
Ce qu'il faut vérifier avant de s'engager
Trois choses sont vérifiables dans le dépôt lui-même. D'abord les tests : le README affiche des badges d'intégration continue pour Linux, macOS et Windows, ce qui indique que les notebooks sont exécutés sur les trois plateformes. C'est un signal de sérieux pour un dépôt pédagogique, où les chemins de fichiers et les dépendances cassent souvent selon l'OS. Ensuite le troubleshooting.md, qui documente les problèmes connus. Enfin le notebook du chapitre 2, qui contient les instructions d'installation absentes du README.
Ce qui reste non vérifiable à partir du matériel fourni : la durée réelle d'exécution des chapitres d'entraînement, la quantité de mémoire GPU nécessaire, et le niveau de performance atteint par le modèle final. Le README annonce un modèle « small-but-functional » à but éducatif, sans avancer de chiffre. Il faut prendre cette absence au sérieux plutôt que de la combler par hypothèse : le projet ne prétend pas rivaliser avec DeepSeek R1 ou GPT-5 Thinking, il prétend refléter leurs approches. La différence entre les deux formulations est l'écart entre un support d'apprentissage et un résultat de recherche.
Conclusion éditoriale
À adopter si vous voulez coder vous-même le passage d'un modèle de base à un modèle de raisonnement et que vous acceptez la contrainte des notebooks. À éviter si vous cherchez un composant de production ou une bibliothèque installable. Avant de vous engager, ouvrez ch02/01_main-chapter-code/ch02_main.ipynb et lisez le troubleshooting.md : c'est là que vous verrez si votre environnement tient la charge.
Notes de la communauté