llm-beginner : six tâches pour écrire un Transformer, un mini-GPT et un agent de code

Six tâches au lieu d'un tutoriel unique

Le dépôt part d'un problème simple : la plupart des parcours sur les grands modèles de langue sautent directement à l'appel d'API ou au fine-tuning d'un modèle téléchargé, sans jamais faire écrire les composants de base. Ici, chaque tâche demande de coder d'abord le mécanisme à la main, puis de le comparer à ce que fait un framework. La progression annoncée va du Transformer (2 semaines estimées), au mini-GPT (3 semaines), à l'instruction tuning et au DPO (2 à 3 semaines), au RAG (2 semaines), à l'agent d'outils (2 semaines), puis au Mini Coding Agent (5 à 6 semaines). Le public visé est explicitement défini : le README précise que les exercices supposent des bases en Python et en apprentissage profond, et que le livre comme les tâches peuvent être suivis indépendamment. Ce n'est donc pas un parcours pour débutant complet, malgré le nom du dépôt.

La structure identique des six dossiers

Chaque répertoire task-* suit le même contrat. On y trouve requirements.txt pour les dépendances, data/download.py pour récupérer les données ou les modèles, eval/run.py pour l'auto-évaluation, et eval/tutor_prompt.md, un prompt prêt à copier dans Claude, Qwen ou DeepSeek avec votre code pour obtenir une revue organisée selon les critères de la tâche. L'implémentation se place dans src/, et le README de chaque tâche contient un tableau des signatures de classes et de fonctions attendues. C'est ce tableau qui compte le plus : eval/run.py importe votre code selon ces signatures pour le noter. Une implémentation correcte mais nommée différemment ne sera pas évaluée. Les scripts s'appuient aussi sur un fichier _eval_harness.py situé à la racine du dépôt, ce qui impose d'exécuter l'auto-évaluation depuis le dépôt lui-même : copier un dossier de tâche ailleurs casse l'import.

Du self-attention au mini-GPT avec RoPE et KV cache

La tâche 1 demande d'écrire scaled dot-product attention, multi-head attention, puis un bloc encodeur complet avec FFN, résidus et LayerNorm, avant de l'entraîner sur ChnSentiCorp, un jeu de classification de sentiment en chinois, et de tracer des cartes d'attention avec matplotlib. Deux masques sont travaillés : le padding mask pour la classification et le causal mask pour un modèle de langage jouet, qui sert de préparation à la tâche 2. Celle-ci reprend l'approche de nanoGPT mais va plus loin que le matériel du livre associé : le README indique que la tâche ajoute un tokenizer BPE écrit à la main, l'encodage positionnel rotatif RoPE et un KV cache, trois éléments que le texte de référence ne fait que décrire. Trois corpus sont proposés par ordre de taille : un fichier poetryFromTang.txt de 49 Ko pour valider la chaîne en cinq minutes, TinyStories autour de 100 Mo que le README annonce exécutable sur CPU, et un sous-ensemble de SkyPile-150B d'environ 1 Go et plus, pour lequel un GPU est conseillé. Les quatre stratégies de décodage à implémenter sont greedy, top-k, top-p et temperature.

Mise en route : commandes et variables d'environnement

L'environnement requis est Python 3.10 ou plus, avec 3.11 ou 3.12 recommandés. Les dépendances s'installent tâche par tâche, par exemple pip install -r task-1-transformer/requirements.txt, chaque dossier pouvant vivre dans son propre venv ou conda. Le flux standard tient en trois commandes, données dans le README pour la tâche 1 : cd task-1-transformer, puis python data/download.py, puis python eval/run.py. Les arguments de téléchargement varient : la tâche 2 accepte --dataset poetry, tinystories ou skypile, avec poetry par défaut ; la tâche 4 accepte --skip-models pour ne récupérer que le PDF NNDL et vérifier les données gold_qa ; la tâche 6 accepte --with-swebench pour ajouter un échantillon de métadonnées SWE-bench Lite. En cas d'accès instable à Hugging Face, le README propose export HF_ENDPOINT=https://hf-mirror.com, avec l'équivalent PowerShell, et signale que la plupart des ressources peuvent basculer vers ModelScope. Le résultat structuré de l'auto-évaluation est écrit dans eval/result.json, toujours en UTF-8, avec trois états par point de contrôle : [通过], [跳过] quand une dépendance manque, ce qui n'est pas une erreur, et [失败] avec un message d'erreur ou une métrique.

Ce que l'auto-évaluation ne vérifie pas

Le README est clair sur la portée de eval/run.py : il contrôle des contrats clés, comme la justesse numérique de l'attention, un taux de rappel ou un taux de réussite de tâche, et il est présenté comme un plancher, pas comme un substitut aux expériences et ablations décrites dans chaque README de tâche. Autrement dit, un résultat [通过] ne dit rien de la qualité de votre implémentation au-delà des points testés. Les expériences suggérées restent à votre charge : nombre de têtes et de couches contre exactitude en classification, suppression des résidus ou du LayerNorm pour voir si l'entraînement converge encore, lecture des cartes d'attention pour vérifier que le modèle regarde les bons mots. Sur le plan matériel, le README renvoie aux README de tâche pour les besoins en ressources et rappelle que l'occupation mémoire varie avec le modèle, la précision, la longueur de séquence et la taille de lot, en conseillant de commencer petit. Aucun chiffre de performance n'est avancé pour les implémentations attendues, et le dépôt ne fournit pas de modèle entraîné à réutiliser.

Le choix de Qwen et la question du chinois

Le dépôt impose une cohérence d'écosystème : la famille Qwen traverse l'ensemble des tâches, la tâche 3 télécharge Qwen2.5-0.5B et la tâche 4 s'appuie sur des modèles BGE pour le volet recherche documentaire. La langue de travail est le chinois, avec passage à l'anglais uniquement quand les données sont nettement meilleures, ce qui est assumé pour certains corpus de pré-entraînement de petits modèles. Ce choix a une conséquence pratique : une partie du matériel d'accompagnement, notamment les jeux ChnSentiCorp et TinyStoriesChinese, est en chinois, et le dépôt ne propose pas de variante francophone. Pour un lecteur francophone, l'intérêt reste dans le code et les mécanismes, mais les expériences de classification et de génération se feront sur des corpus chinois, sauf à remplacer soi-même les données et à adapter les scripts de vérification.

Le coût réel : six tâches, six maintenances

Le dépôt est publié sous licence MIT, ce qui autorise la réutilisation et la modification du code et de la documentation, sous réserve de conserver l'avis de licence ; les modalités exactes relèvent du texte de la licence et non d'une interprétation. Le coût de maintenance ne se lit pas dans un compteur d'étoiles mais dans la structure : six dossiers de tâches, chacun avec ses requirements.txt, son script de téléchargement et son auto-évaluation, plus un harnais commun _eval_harness.py à la racine. Toute évolution d'une API PyTorch, d'un dépôt Hugging Face ou d'un jeu de données se répercute sur plusieurs tâches à la fois. Le dépôt est actif, la dernière poussée datant du 6 septembre 2026, et une release book-pdf fournit le manuscrit complet en PDF, avec la mention que le texte est en préparation éditoriale et évolue au fil des révisions. Les mises à jour du livre et celles du code ne sont donc pas nécessairement synchronisées, et un lecteur qui suit une version imprimée plus ancienne peut rencontrer des écarts.

Face à nanoGPT et aux dépôts de cours classiques

nanoGPT de Karpathy, cité en référence par la tâche 2, va à l'essentiel : un modèle decoder-only compact, entraîné sur un corpus de texte, avec un code court à lire d'un bout à l'autre. llm-beginner adopte la même philosophie de départ mais élargit le périmètre : tokenizer BPE écrit à la main plutôt qu'emprunté, RoPE en plus de l'encodage positionnel absolu, KV cache effectivement implémenté, puis quatre tâches supplémentaires qui sortent du pré-entraînement pour aller vers l'alignement, la recherche documentaire et l'outillage d'un agent. La différence n'est pas seulement quantitative. Un dépôt comme nanoGPT se parcourt en une session ; ici, la progression est découpée en semaines et suppose de respecter des signatures imposées par un harnais d'évaluation. Le revers est une liberté moindre : vous n'écrivez pas le code que vous voulez, vous écrivez celui que eval/run.py saura importer.

Conclusion éditoriale

llm-beginner convient à qui veut écrire lui-même un Transformer, un mini-GPT, une boucle DPO ou un agent ReAct et dispose de plusieurs mois devant lui. À éviter si vous cherchez un modèle pré-entraîné à réutiliser en production : le dépôt ne fournit aucun poids. Vérifiez d'abord que PyTorch s'installe sur votre machine et que data/download.py récupère bien le jeu de la tâche 1 avant de vous engager sur les cinq autres.

Sources officielles

1. License: MIT
2. nndl/llm-beginner on GitHub
3. Project website
4. README
5. Releases