Nano-vLLM : une implémentation minimale de vLLM pour l’inférence locale

Nano-vLLM est une réimplémentation open source, écrite depuis zéro, du serveur d’inférence vLLM en environ 1 200 lignes de Python. Elle a été publiée au milieu de l’année 2025 par Xingkai Yu, ingénieur chez DeepSeek, sous licence MIT, sur github.com/GeeeekExplorer/nano-vllm. Il s’agit d’une base de code pédagogique et d’un outil performant pour l’inférence par lots — pas d’un remplacement direct du serveur vLLM complet.

Ce qu’est réellement Nano-vLLM

Le dépôt upstream vllm-project/vllm est un serveur d’inférence professionnel, volumineux, comptant des centaines de contributeurs, doté d’une API HTTP compatible OpenAI, de workers distribués, et prenant en charge des dizaines d’architectures de modèles et de schémas de quantification. Nano-vLLM en retire tout sauf la boucle centrale : le chargement du modèle, un gestionnaire de cache KV, un planificateur de traitement par lots et un échantillonneur.

Selon la page README du projet, nano-vllm conserve les optimisations clés qui font la rapidité de vLLM :

• Mise en cache de préfixe — réutilise les blocs du cache KV entre les requêtes partageant un même préfixe de prompt.
• Parallélisme tensoriel — répartit un modèle sur plusieurs GPU d’un même nœud.
• Compilation avec Torch — utilise torch.compile pour la fusion de noyaux.
• Graphes CUDA — réduit la surcharge de lancement à chaque étape pendant le décodage.

Ce qu’il omet délibérément : le serveur HTTP compatible OpenAI, les API de diffusion continue, la plupart des backends de quantification (AWQ, GPTQ, FP8), le décodage spéculatif, le changement à chaud de LoRA, le regroupement multi-nœuds et la vaste collection de modèles. Il est principalement testé avec des modèles denses de la classe Qwen3.

Installer Nano-vLLM

Nano-vLLM est un paquet Python. Aucun chemin natif de prise en charge CUDA sous Windows n’est prévu dans le dépôt upstream ; sous Windows, utilisez WSL2 avec un pilote NVIDIA. Linux et WSL2 sont les plateformes principales. macOS n’est pas pris en charge car les chemins de code supposent l’existence de CUDA.

Linux et WSL2

python -m venv .venv
source .venv/bin/activate
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install git+https://github.com/GeeeekExplorer/nano-vllm.git

Adaptez la version de la roue CUDA (cu121, cu124, etc.) au pilote NVIDIA installé. Vérifiez-le à l’aide de la commande nvidia-smi avant d’installer.

Windows (via WSL2)

Installez le pilote NVIDIA pour Windows, activez WSL2 avec une distribution Ubuntu (wsl --install -d Ubuntu), puis suivez les étapes Linux à l’intérieur de WSL. N’installez pas le kit d’outils CUDA dans WSL — le pilote Windows expose directement le GPU.

macOS

Non pris en charge. Nano-vLLM dépend de noyaux CUDA et de primitives d’attention paginée qui ne disposent pas de backend Metal. Sur Apple Silicon, utilisez plutôt Ollama ou LM Studio Ollama ou llama.cpp llama.cpp tous deux exécutant

Télécharger un modèle

Nano-vLLM charge les répertoires de modèles standard de Hugging Face — les mêmes config.json, tokenizer.json et safetensors structure utilisée par les bibliothèques transformers et vLLM. Récupérez un modèle à l’aide de la CLI officielle de Hugging Face Hub huggingface_hub Ligne de commande (CLI) :

pip install -U "huggingface_hub[cli]"
hf download Qwen/Qwen3-8B --local-dir ~/models/Qwen3-8B

Consultez le pour l’authentification et les modèles restreints. Notez que l’ancien point d’entrée est toujours fourni avec le paquet, mais Hugging Face recommande désormais la commande huggingface-cli entry point still ships with the package, but Hugging Face now recommends the hf hf.

Exécuter une inférence

L’API reproduit étroitement l’interface hors ligne par lots de vLLM. Un script minimal :

from nanovllm import LLM, SamplingParams

llm = LLM("/home/user/models/Qwen3-8B", enforce_eager=False, tensor_parallel_size=1)
sp = SamplingParams(temperature=0.7, max_tokens=256)

prompts = ["Expliquez l’attention paginée en un seul paragraphe."]
outputs = llm.generate(prompts, sp)
print(outputs[0]["text"])

Les noms exacts des classes et la forme des valeurs renvoyées peuvent évoluer entre deux commits — consultez example.py à la racine du dépôt, qui constitue la référence officielle d’utilisation.

Exigences matérielles selon le modèle

Comme nano-vLLM exécute actuellement les modèles en bf16/fp16 (sans quantification intégrée en 4 bits au moment de la rédaction), les besoins en VRAM sont approximativement le double des valeurs indiquées ci-dessous pour la précision 4 bits. Utilisez le Calculateur de VRAM pour une estimation précise selon la précision utilisée. Les valeurs suivantes correspondent aux références en 4 bits fournies par Convly Base de données de modèles — pour nano-vLLM en bf16, prévoyez environ deux fois ces valeurs, plus une marge pour le cache KV.

Modèle	Contexte	VRAM (référence en 4 bits)	GPU NVIDIA adapté à nano-vLLM
Qwen3 8B	128 K	~5 Go	RTX 4090 unique (24 Go) en bf16
Qwen3 14B	128 K	~9 Go	RTX 4090 unique en bf16 avec un contexte modéré
Qwen3 32B	128 K	~20 Go	2× RTX 4090 avec tensor_parallel_size=2
Llama 3.1 8B	128 K	~5 Go	RTX 4090 unique
Llama 3.3 70B	128 K	~40 Go	2× A100 80 Go ou 4× RTX 4090

Pour une vue d’ensemble plus large des modèles pouvant tenir sur chaque carte, consultez le meilleures GPU pour les LLM locaux et le tableau des besoins en VRAM.

Nano-vLLM contre vLLM contre Ollama

Fonctionnalité	Nano-vLLM	vLLM	Ollama
Nombre de lignes	~1 200 lignes Python	~100 000+ lignes Python/C++/CUDA	Wrapper Go sur llama.cpp
Serveur compatible OpenAI	Non	Oui	Oui (via /v1)
Backend	PyTorch + CUDA	PyTorch + noyaux personnalisés	llama.cpp (GGUF)
Quantification	Minimale	AWQ, GPTQ, FP8, INT4	GGUF Q2–Q8
Multi-GPU	Parallélisme tensoriel	Tensoriel + pipeline + expert	Limité
Utilisation principale	Apprentissage, intégration	Production (mise en service)	Poste de travail / développement

Si votre objectif est de déployer un point de terminaison accessible aux clients, utilisez vLLM complet. Si vous souhaitez intégrer une boucle d’inférence par lots dans un programme Python plus vaste, avec un minimum de dépendances, nano-vLLM est une solution raisonnable. Si vous recherchez un chatbot local lancé en une seule commande, utilisez Ollama.

Quand utiliser Nano-vLLM est pertinent

• Apprendre les mécanismes internes. Le planificateur et le gestionnaire de blocs tiennent sur un seul écran. Lire le code de nano-vLLM est la méthode la plus rapide pour comprendre concrètement le fonctionnement de l’attention paginée.
• Forks destinés à la recherche. Modifier une base de code de 1 200 lignes afin de tester un nouvel échantillonneur ou une nouvelle politique de cache est tout à fait faisable ; en revanche, forker vLLM upstream ne l’est pas.
• Inférence hors ligne par lots. Évaluation, génération de données synthétiques, boucles d’évaluation sur un ensemble fixe de prompts.

Quand cela n’a pas de sens : API de production, mise en service multi-locataire, contraintes strictes de quantification ou utilisation sur du matériel autre que NVIDIA.

Auto-hébergement contre API

Exécuter nano-vLLM localement implique des coûts réels — investissement matériel GPU, consommation électrique et temps ingénierie. Les modèles hébergés sur des plateformes de pointe sont souvent moins chers par jeton que l’inférence locale amortie, notamment à faible volume. Comparez avec le calculateur auto-hébergement vs API et le Calculateur de coûts d’APItableau des coûts. Qwen3 8B sur un point de terminaison hébergé coûte 0,04 $ en entrée / 0,14 $ en sortie par million de jetons selon Convly Base de données de modèles, tandis qu’un GPU de 24 Go capable de l’exécuter localement coûte largement plus de 1 500 $.

Questions fréquemment posées

Qui a écrit nano-vllm ?

Le dépôt est maintenu par Xingkai Yu (identifiant GitHub GeeeekExplorer), ingénieur chez DeepSeek. Il s’agit d’un projet personnel, non d’une publication officielle de DeepSeek. Le code est publié sous licence MIT et hébergé à l’adresse github.com/GeeeekExplorer/nano-vllm.

Nano-vllm est-il plus rapide que vLLM ?

Le fichier README indique un débit proche de celui de vLLM sur de petits modèles denses comme Qwen3-0.6B, sur un GPU de classe RTX 4070, et dans certaines configurations de benchmarcs courts, légèrement supérieur grâce à une surcharge moindre du planificateur. Sur des modèles plus volumineux, des contextes plus longs ou lors de la prise en charge de plusieurs requêtes simultanées, les optimisations de vLLM upstream prennent nettement l’avantage. Considérez la parité comme « comparable dans le cadre de l’inférence hors ligne par lots », et non comme « remplacement strict ».

Nano-vllm peut-il exposer une API compatible OpenAI ?

Pas nativement. Le projet expose une interface Python LLM.generate() méthode destinée à une utilisation hors ligne par lots. Si vous avez besoin d’un serveur HTTP avec /v1/chat/completions, enveloppez-le vous-même avec FastAPI ou utilisez le serveur compatible OpenAI de vLLM ou Ollama.

Nano-vllm prend-il en charge les modèles quantifiés comme GGUF ou AWQ ?

Non. La base de code charge les poids standard au format safetensors de Hugging Face en bf16/fp16. Pour les formats GGUF (Q4_K_M, etc.), utilisez des outils basés sur llama.cpp; pour AWQ ou GPTQ, utilisez vLLM upstream. C’est l’une des raisons pour lesquelles l’empreinte mémoire VRAM de nano-vllm est plus élevée par paramètre que celle d’Ollama pour un même modèle.

Quels modèles sont connus pour fonctionner ?

Les modèles denses Qwen3 constituent la cible principale de l’implémentation de référence. D’autres modèles reposant sur l’architecture Llama fonctionnent souvent avec de légères adaptations du chargeur de modèles, mais les architectures exotiques (mélange d’experts, espaces d’état hybrides) ne sont généralement pas prises en charge. Consultez le répertoire nanovllm/models/ du dépôt pour obtenir la liste actuelle des modèles pris en charge.

Puis-je exécuter nano-vllm sur du matériel AMD ou Apple Silicon ?

Pas pour le moment. Les noyaux supposent l’utilisation de CUDA. ROCm pourrait fonctionner avec une version personnalisée de PyTorch, mais n’a pas été testé upstream. Sur les puces Apple Silicon, aucune solution n’est disponible — privilégiez plutôt des outils basés sur MLX ou llama.cpp. Pour un aperçu des alternatives disponibles, consultez le Classement des grands modèles linguistiques (LLM) et choisissez un modèle adapté à votre configuration matérielle.