tiny-vllm : un moteur d'inférence LLM en C++ et CUDA, livré avec son cours

Un cours déguisé en dépôt de code

Le README annonce deux choses dans le même dépôt : le code source complet d'un serveur d'inférence, et un cours qui guide l'implémentation. La table des matières couvre une trentaine d'étapes, depuis la question de savoir ce qu'est physiquement un LLM jusqu'au kernel CUDA de PagedAttention. L'ordre n'est pas celui d'une documentation d'API : on commence par les nombres flottants et le bfloat16, puis la mémoire GPU et CPU, puis un seul token en inférence, et seulement ensuite la tokenisation, les embeddings, RMSNorm, RoPE, cublasGemmEx, la distinction prefill/decode, le KV cache, l'attention, GQA, SiLU, softmax, le masque causal, argmax, le feed forward network, la réutilisation de buffers, le batching statique puis continu, l'online softmax et enfin PagedAttention. Ce qui rend le dépôt intéressant n'est donc pas la surface d'API, c'est la progression pédagogique. Le public visé est nommé explicitement : quelqu'un qui apprend, ou un enseignant qui cherche un support de cours universitaire. Un ingénieur qui veut servir un modèle en production n'est pas le lecteur cible, et le README ne l'invite pas à le devenir.

Ce que le moteur prend réellement en charge

La liste des fonctionnalités cochées dans le README est le seul inventaire fiable dont on dispose. Elle indique : chargement d'un vrai modèle depuis Safetensors (Llama 3.2 1B Instruct), passe forward complète en prefill et en decode, toute la computation en kernels CUDA, KV cache, batching statique, continuous batching, online softmax de type FlashAttention, et PagedAttention. Aucune de ces lignes n'est accompagnée d'un chiffre : pas de tokens par seconde, pas de latence, pas de comparaison avec vLLM. Le README qualifie le projet de petit frère de vLLM, plus jeune et plus petit. C'est une description d'intention, pas un résultat mesuré. Un seul modèle est nommé, Llama 3.2 1B Instruct, ce qui suggère un chargeur écrit pour une architecture donnée plutôt qu'un chargeur générique. Le dépôt n'a pas de releases publiées, donc pas de version figée à épingler, et pas de page d'accueil séparée.

Le chemin d'un prompt dans le code

Le README décrit la chaîne de traitement en plusieurs endroits. Un prompt est d'abord tokenisé, puis converti en embeddings, et le cours consacre une section entière à l'écriture du kernel CUDA correspondant. Les poids sont chargés depuis un fichier Safetensors au démarrage du programme, pas à la compilation : le README insiste sur le fait que le fichier de poids n'est pas un exécutable et que l'architecture n'est qu'un plan. Vient ensuite la distinction prefill/decode, avec la question associée du KV cache. L'attention est implémentée avec un online softmax de type FlashAttention, ce qui évite de matérialiser toute la matrice d'attention en mémoire. PagedAttention et le KV cache paginé arrivent en fin de parcours, avec un kernel CUDA dédié. Le batching apparaît deux fois : d'abord statique, puis continu. La réutilisation de buffers est traitée comme une étape à part entière, ce qui est cohérent avec un moteur qui alloue peu et réutilise beaucoup. Le README mentionne aussi une astuce de transposition column-major vers row-major, typiquement pour faire coïncider la disposition attendue par cublasGemmEx avec celle des tenseurs.

Compiler et lancer : ce que le matériel ne dit pas

C'est la faiblesse la plus nette du README fourni. Il ne contient aucune commande de compilation, aucun CMakeLists visible, aucun nom de binaire, aucun exemple d'appel. Les seuls éléments concrets sont les dépendances implicites : CUDA pour les kernels, cublas pour les multiplications de matrices, un fichier Safetensors pour les poids. Le README donne un lien vers la documentation Safetensors sur Hugging Face et vers l'article PagedAttention, mais pas de commande du type cmake, make ou d'invocation du serveur. Impossible donc de dire ici comment on démarre le programme : cette information est absente du matériel. Un lecteur qui veut essayer doit ouvrir le dépôt et lire les fichiers de build lui-même. Le point positif est que le cours lui-même sert de documentation d'implémentation : si vous suivez les sections dans l'ordre, vous écrivez le code au fur et à mesure, et les commandes apparaissent dans le texte du cours plutôt que dans le README.

Les limites que le dépôt ne masque pas

Le README prend soin de dire que le projet va faire des erreurs en chemin. C'est honnête, mais cela signifie aussi que le code n'est pas présenté comme un produit fini. Plusieurs signaux vont dans ce sens. Un seul modèle est supporté, ce qui exclut de servir une autre architecture sans écrire un nouveau chargeur. Il n'y a aucune release, donc aucun point de version stable. Aucune mesure de performance n'est publiée, alors que le nom du projet et la présence de PagedAttention suggèrent une ambition de performance : sans chiffres, cette ambition reste une intention. Le dépôt se décrit comme une version plus petite de vLLM, ce qui implique des fonctionnalités manquantes par rapport à vLLM, sans que le README précise lesquelles. Enfin, un moteur d'inférence en C++ et CUDA implique une compilation spécifique au matériel : le README ne dit rien sur les versions de CUDA ou de GPU compatibles. C'est un choix pédagogique assumé, pas un oubli, mais cela déplace le coût de vérification vers le lecteur.

vLLM comme point de comparaison, et ce qui change vraiment

Le README nomme lui-même la référence : vLLM, dont tiny-vllm serait le petit frère. La différence d'approche est structurelle. vLLM est un moteur destiné à être déployé, avec une API de serveur, un support multi-modèles et une communauté de contributeurs. tiny-vllm est un code source unique accompagné d'un cours, écrit pour être lu et reconstruit. Là où vLLM cache ses kernels derrière une API stable, tiny-vllm expose chaque étape : le kernel d'embeddings, RMSNorm avec réduction parallèle, RoPE, le masque causal, l'argmax. Là où vLLM doit gérer une matrice de configurations et de formats de modèles, tiny-vllm se limite à Llama 3.2 1B Instruct. Là où vLLM publie des benchmarks, tiny-vllm publie une table des matières. Ce sont deux objets différents : l'un s'installe, l'autre s'étudie. Un lecteur qui cherche à servir un modèle n'a aucune raison de choisir tiny-vllm, et le README ne l'y encourage pas.

Licence, maintenance et coût de mise à jour

Le dépôt est publié sous Apache-2.0, ce qui autorise l'usage, la modification et la redistribution, y compris dans un contexte commercial, sous réserve de conserver les mentions de licence et d'état des modifications. Ce n'est pas un avis juridique : pour un usage en entreprise, faites relire les termes par qui de droit. Le dépôt n'est pas archivé, et le dernier push date du 23 août 2026. Aucune release n'a été récupérée, donc il n'existe pas de version taguée sur laquelle s'appuyer : suivre le dépôt signifie suivre la branche main. Pour un support de cours, c'est un avantage, puisque le contenu évolue avec le code. Pour un usage en production, c'est un problème, puisqu'aucun point de retour stable n'est défini. Le coût de mise à jour est faible en apparence : le projet ne dépend que de CUDA, cublas et d'un fichier Safetensors. Mais il dépend aussi de l'architecture d'un modèle précis, et un changement de modèle implique de retoucher le chargeur. C'est le principal poste de maintenance à prévoir.

Conclusion éditoriale

tiny-vllm s'adresse à un lecteur précis : quelqu'un qui veut écrire lui-même les kernels d'un moteur d'inférence et comprendre pourquoi le KV cache, le continuous batching et PagedAttention existent. Ce n'est pas un moteur à déployer en production, et le README ne prétend pas le contraire. Avant de vous engager, vérifiez trois choses dans le dépôt : la commande de compilation réellement fournie, le nom exact du modèle attendu par le chargeur Safetensors, et la présence d'un fichier de licence Apache-2.0 à la racine. Si ces trois points sont clairs, le cours est utilisable tel quel comme support.

Sources officielles

1. Issues
2. jmaczan/tiny-vllm on GitHub
3. License: Apache-2.0
4. README