tiny-llm : reconstruire un moteur d'inférence Qwen3 sur Apple Silicon, opérateur par opérateur

Ce que le cours demande d'écrire soi-même

tiny-llm s'adresse aux ingénieurs systèmes qui veulent comprendre l'inférence d'un grand modèle de langage de bout en bout, pas seulement l'appeler. Le README le formule ainsi : « a hands-on course for systems engineers who want to understand LLM inference end to end ». La contrainte centrale est explicite : quand un chapitre enseigne un opérateur, votre solution l'implémente en Python, en C++ ou en Metal au lieu d'appeler l'opération MLX optimisée correspondante. MLX reste l'oracle de correction et la référence de performance. Autrement dit, vous n'écrivez pas un wrapper autour de mlx.core.matmul, vous écrivez le matmul. Le projet se présente comme l'équivalent côté service LLM de Needle, le projet de la CMU où l'on construit un framework d'autodifférenciation. Le public visé est donc étroit : des gens à l'aise avec les tableaux, la mémoire et les noyaux, qui acceptent de relire plusieurs centaines de lignes pour relier une équation à une occupation de noyau.

Qwen3-4B et MLX : pourquoi ce couple précis

Le choix du matériel est justifié dans le README par une contrainte pratique : Apple silicon offre un espace mémoire partagé et un accès direct aux noyaux Metal, ce qui permet d'inspecter le chemin complet sur une seule machine sans dépendre d'un GPU CUDA coûteux. Le choix du modèle obéit à la même logique. Qwen3-4B est décrit comme assez grand pour exposer réellement les coûts de bande passante des poids, d'attention et de cache, mais assez petit pour itérer localement. Ses caractéristiques comptent pour la suite du cours : attention à requêtes groupées, normalisation QK, activations BF16 et poids 4 bits. Ces quatre détails ne sont pas décoratifs. La normalisation QK ajoute une étape que beaucoup de tutoriels d'attention omettent, et les poids 4 bits conditionnent le chapitre sur la quantification ainsi que le noyau de décodage matvec qui ouvre la semaine 2.

Quatre semaines, du matmul au batching paginé

La progression est découpée en quatre semaines. La semaine 1 construit un modèle Qwen3 directement à partir des opérations de tableau de mlx.core : attention, RoPE, GQA, RMSNorm, MLP, échantillonnage et boucle autorégressive. La semaine 2 ajoute le KV cache, établit une base MLX synchronisée, puis laisse des benchmarks appariés choisir chaque optimisation, en partant du matvec de décodage quantifié pour aller vers les noyaux de modèle fusionnés, le préremplissage tuilé et le split-K là où les formes mesurées de Qwen l'exigent. La semaine 3 introduit le batching continu et l'admission par morceaux, puis fait du KV paginé la disposition canonique du service : l'attention de décodage et FlashAttention apprennent à lire les pages directement, ce qui évite au planificateur de reconstruire un historique dense à chaque étape. La semaine 4 quitte le moteur pour construire un agent de codage, en commençant par une boucle bornée et validée. Cette bascule surprend dans un cours d'inférence, mais elle est cohérente : les chapitres 4.8 et 4.9 réutilisent un point de contrôle réel du tokenizer et du KV pour deux continuations isolées, puis stockent les résultats d'outils trop volumineux hors du prompt du modèle.

tiny_llm, tiny_llm_ref et la commande de vérification

Le dépôt sépare deux paquets. tiny_llm est l'endroit où l'étudiant écrit ses exercices. tiny_llm_ref contient la solution de référence utilisée par les tests et l'annexe de benchmarks. L'installation passe par pdm, et le README donne trois commandes : pdm install -v, puis pdm run check-installation, puis pdm run test-refsol -- -- -k week_1. Cette dernière exécute les tests contre la solution de référence en filtrant sur la première semaine. C'est le contrôle à faire en premier, parce qu'il valide l'environnement sans exiger que vous ayez écrit quoi que ce soit. Le fichier book/src/SUMMARY.md liste l'ordre des chapitres. La feuille de route du README suit quatre colonnes distinctes : Code, Test, Doc et Audit, cette dernière correspondant à la relecture éditoriale personnelle de Chi sur le contenu publié. Toutes les cases Code, Test et Doc sont cochées pour les chapitres listés, y compris les deux chapitres optionnels 3.6 sur le MoE et 3.7 sur le décodage spéculatif.

La colonne Audit et la publication au jour le jour

C'est ici que la prudence s'impose. La colonne Audit n'est cochée que pour les sept chapitres de la semaine 1. Tous les chapitres des semaines 2 et 3 sont marqués d'un symbole de chantier, et la semaine 4 est publiée un jour relu à la fois : les jours 1 à 9 sont disponibles, ce qui correspond aux chapitres 4.1 à 4.9 du tableau. Le README précise que l'audit est indépendant de l'état du code, des tests et de la documentation. Concrètement, cela signifie que le code d'un chapitre peut être complet et testé alors que le texte que vous lisez n'a pas encore reçu sa passe éditoriale. Pour un apprenant autonome, la différence est réelle : les premiers chapitres sont ceux sur lesquels le moins de surprises sont à attendre côté explications. Le dépôt ne publie aucune release, ce qui est cohérent avec un cours dont l'unité de livraison est le chapitre et non la version.

La semaine 4 manipule des fichiers : lisez l'avertissement

Le README est direct sur ce point. Le jour 3 peut envoyer le contenu de fichiers au modèle, modifier des fichiers après approbation et exécuter une commande configurée exacte. La consigne est de travailler dans un espace jetable sans secrets et de lire book/src/week4-overview.md avant de lancer la boucle. Ce n'est pas une clause de style. Une boucle d'agent qui édite des fichiers et exécute une commande, même bornée et validée, reste un composant qui agit sur votre système de fichiers. Les jours suivants ajoutent des mécanismes de contrôle plutôt que de les retirer : le jour 4 enregistre un point de contrôle complet avec les fausses métadonnées de cache du modèle scripté et restaure un modèle neuf sans rejouer l'édition ni la commande déjà effectuées ; le jour 5 compacte les effets terminés dans la transcription visible tout en conservant leurs reçus exacts, action, résultat et artefacts modifiés ; le jour 9 sort les octets volumineux du prompt et n'expose qu'une observation bornée avec identité, empreinte et début-fin, que le modèle peut ensuite récupérer par plage d'octets explicite. Ce sont des garde-fous documentés, pas des garanties d'isolation.

Le cas où tiny-llm n'est pas le bon outil

Si votre objectif est de servir Qwen3 en production sur un Mac, ce dépôt n'est pas la réponse. Aucune release n'est publiée, le projet est un cours et non un moteur maintenu, et les implémentations que vous écrivez sont destinées à être lues et comparées à MLX, pas déployées. Le README indique d'ailleurs que d'autres sujets ne sont pas couverts, sans que la liste complète apparaisse dans l'extrait fourni. La comparaison utile se fait avec NanoGPT, qui suit la même philosophie d'implémentation minimale mais reste centré sur l'entraînement et l'architecture du modèle, ou avec llm.c, qui écrit l'entraînement et l'inférence en C mais vise d'abord la performance sur GPU CUDA. tiny-llm se distingue par trois choix simultanés : la cible Apple silicon via MLX, l'accent mis sur le service (batching continu, admission par morceaux, KV paginé) plutôt que sur l'entraînement, et l'obligation d'écrire les noyaux vous-même au lieu d'appeler la couche haut niveau. Un tutoriel qui vous ferait appeler l'opération MLX optimisée irait plus vite, mais supprimerait précisément ce que ce cours cherche à enseigner.

Coût de maintenance et licence

Le coût de suivi se lit dans la structure du dépôt plutôt que dans un fichier de version. Chaque chapitre existe en quatre états indépendants, et la semaine 4 avance à raison d'un jour relu à la fois, ce qui implique que la couverture complète du parcours n'est pas encore atteinte. Un apprenant qui commence aujourd'hui doit donc vérifier chapitre par chapitre ce qui est publié, et non se fier à la seule liste de la semaine 4. Le projet est sous licence Apache-2.0, une licence permissive qui autorise la réutilisation et la modification avec conservation des mentions et des brevets, mais ce texte n'est pas un avis juridique : si vous réutilisez du code du cours dans un produit, faites vérifier les obligations de notice par vos propres moyens. Le dépôt n'étant pas archivé et son dernier push datant du 9 septembre 2026, le projet est actif au moment de cette lecture.

Conclusion éditoriale

À adopter si vous êtes ingénieur systèmes et voulez écrire vous-même les noyaux d'inférence Qwen3 sur un Mac, en acceptant que les semaines 2 à 4 ne soient pas encore auditées. À éviter si vous cherchez un moteur de service en production : le dépôt ne publie aucune release et la semaine 4 demande explicitement un espace de travail jetable sans secrets. Avant de vous engager, lancez pdm run test-refsol -- -- -k week_1 et vérifiez que la colonne Audit de la feuille de route couvre bien les chapitres qui vous intéressent.

Sources officielles

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. skyzh/tiny-llm on GitHub