Nano-vLLM: Eine Minimal-Implementierung von vLLM für lokale Inferenz

Nano-vLLM ist eine quelloffene, von Grund auf neu implementierte Inferenz-Server-Software in rund 1.200 Zeilen Python. Sie wurde Mitte 2025 von Xingkai Yu, einem DeepSeek-Ingenieur, unter der MIT-Lizenz auf vLLM Inferenz-Server, geschrieben in rund 1.200 Zeilen Python. Sie wurde Mitte 2025 von Xingkai Yu, einem DeepSeek-Ingenieur, unter der MIT-Lizenz auf github.com/GeeeekExplorer/nano-vllmveröffentlicht. Es handelt sich um eine Lehr-Codebasis und ein Werkzeug für schnelle Batch-Inferenz – nicht um einen direkten Ersatz für den vollständigen vLLM-Server.

Was Nano-vLLM tatsächlich ist

Das ursprüngliche Repository vllm-project/vllm ist ein großer, produktionsreifer Inferenzserver mit Hunderten von Mitwirkenden, einer OpenAI-kompatiblen HTTP-API, verteilten Workern sowie Unterstützung für Dutzende von Modellarchitekturen und Quantisierungsschemata. Nano-vLLM reduziert dies auf die Kernkomponenten: Modell-Loading, einen KV-Cache-Manager, einen Batch-Scheduler und einen Sampler.

Laut der Projekt-README behält nano-vllm die zentralen Optimierungen bei, die vLLM so schnell machen:

• Prefix Caching – wiederverwendet KV-Cache-Blöcke zwischen Anfragen mit identischem Prompt-Präfix.
• Tensor-Parallelisierung – verteilt ein Modell über mehrere GPUs auf einem Knoten.
• Torch-Kompilierung – nutzt torch.compile zur Kernel-Fusion.
• CUDA Graphs – reduziert den Overhead pro Schritt beim Decodieren.

Was bewusst weggelassen wird: Der OpenAI-kompatible HTTP-Server, kontinuierliche Streaming-APIs, die meisten Quantisierungs-Backends (AWQ, GPTQ, FP8), spekulative Decodierung, LoRA-Hot-Swapping, Multi-Node-Clustering sowie der breite Modell-Zoo. Die primäre Testabdeckung umfasst dichte Modelle der Qwen3-Klasse.

Nano-vLLM installieren

Nano-vLLM ist ein Python-Paket. Der offizielle Repository-Pfad bietet keine native Windows-CUDA-Unterstützung; unter Windows verwenden Sie stattdessen WSL2 mit einem NVIDIA-Treiber. Linux und WSL2 sind die primären Plattformen. macOS wird nicht unterstützt, da der Code CUDA-spezifische Pfade voraussetzt.

Linux und 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

Passen Sie das CUDA-Wheel (cu121, cu124, usw.) an Ihren installierten NVIDIA-Treiber an. Überprüfen Sie dies mit nvidia-smi vor der Installation.

Windows (über WSL2)

Installieren Sie den NVIDIA-Windows-Treiber, aktivieren Sie WSL2 mit einer Ubuntu-Distribution (wsl --install -d Ubuntu) und folgen Sie anschließend den Linux-Anweisungen innerhalb von WSL. Installieren Sie das CUDA-Toolkit nicht innerhalb von WSL – der Windows-Treiber stellt die GPU bereit.

macOS

Nicht unterstützt. Nano-vLLM setzt CUDA-Kernel und paged-attention-Primitive voraus, für die es keine Metal-Backend-Implementierung gibt. Auf Apple Silicon verwenden Sie stattdessen Ollama oder LM Studio Ollama oder LM Studio llama.cpp beide führen intern

Ein Modell herunterladen

Nano-vLLM lädt Standard-Hugging-Face-Modellverzeichnisse – dieselben config.json, tokenizer.json und safetensors Verzeichnisstruktur, die auch von transformers und vLLM genutzt wird. Laden Sie ein Modell mit der offiziellen huggingface_hub CLI:

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

Weitere Details finden Sie im Hugging-Face-Hub-CLI-Dokumentation zur Authentifizierung und für eingeschränkte Modelle herunter. Beachten Sie, dass der ältere huggingface-cli Einstiegspunkt weiterhin im Paket enthalten ist, Hugging Face empfiehlt jedoch nun ausdrücklich den hf Befehl.

Inferenz ausführen

Die API orientiert sich eng an vLLMs offline-Batch-Schnittstelle. Ein minimales Skript:

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 = ["Erklären Sie paged attention in einem Absatz."]
outputs = llm.generate(prompts, sp)
print(outputs[0]["text"])

Die genauen Klassennamen und die Form der Rückgabewerte können sich zwischen Commits ändern – prüfen Sie daher example.py im Repository-Stammverzeichnis, das als maßgebliche Referenz für die Nutzung dient.

Hardwareanforderungen nach Modell

Da nano-vLLM derzeit Modelle ausschließlich in bf16/fp16 ausführt (zum Zeitpunkt der Erstellung dieses Artikels ist keine integrierte 4-Bit-Quantisierung verfügbar), betragen die VRAM-Anforderungen etwa das Doppelte der nachfolgenden 4-Bit-Werte. Nutzen Sie die VRAM-Rechner für eine schätzwertbasierte Abschätzung pro Genauigkeit. Die folgenden Zahlen stellen 4-Bit-Referenzwerte aus dem Convly Modelldatenbank dar – für nano-vLLM in bf16 sollten Sie ungefähr das Zweifache dieser Werte plus zusätzlichen Spielraum für den KV-Cache einplanen.

Modell	Kontext	VRAM (4-Bit-Referenz)	Realistische nano-vLLM-GPU-Konfiguration
Qwen3 8B	128 K	~5 GB	Einzelne RTX 4090 (24 GB) in bf16
Qwen3 14B	128 K	~9 GB	Einzelne RTX 4090 in bf16 mit moderatem Kontext
Qwen3 32B	128 K	~20 GB	2× RTX 4090 mit tensor_parallel_size=2
Llama 3.1 8B	128 K	~5 GB	Einzelne RTX 4090
Llama 3.3 70B	128 K	~40 GB	2× A100 80 GB oder 4× RTX 4090

Für einen umfassenderen Überblick darüber, welche Modelle auf welcher GPU laufen, siehe beste GPUs für lokale LLMs und das VRAM-Anforderungstabelle.

Nano-vLLM vs. vLLM vs. Ollama

Funktion	Nano-vLLM	vLLM	Ollama
Zeilenanzahl	~1.200 Python-Zeilen	~100.000+ Python/C++/CUDA-Zeilen	Go-Wrapper über llama.cpp
OpenAI-kompatibler Server	Nein	Ja	Ja (über /v1)
Backend	PyTorch + CUDA	PyTorch + benutzerdefinierte Kernel	llama.cpp (GGUF)
Quantisierung	Minimal	AWQ, GPTQ, FP8, INT4	Q2–Q8 GGUF
Multi-GPU	Tensor-Parallelisierung	Tensor- + Pipeline- + Expert-Parallelisierung	Begrenzt
Hauptanwendungsfall	Lernen, Embeddings	Produktionsserving	Desktop / Entwicklung

Wenn Ihr Ziel darin besteht, einen kundenorientierten Endpunkt bereitzustellen, verwenden Sie vLLM in voller Ausprägung. Wenn Sie eine Batch-Inferenzschleife nahtlos in ein größeres Python-Programm mit minimalen Abhängigkeiten integrieren möchten, ist nano-vLLM durchaus geeignet. Für einen lokalen Chatbot per Einzelbefehl nutzen Sie am besten Ollama.

Wann Nano-vLLM sinnvoll ist

• Verständnis der internen Funktionsweise. Der Scheduler und der Block-Manager passen auf einen Bildschirm. Das Lesen des nano-vLLM-Quellcodes ist der schnellste Weg, paged attention anhand realen Codes zu verstehen.
• Forschungs-Forks. Die Modifikation eines 1.200-Zeilen-Codebases zum Testen eines neuen Samplers oder einer neuen Cache-Policy ist gut handhabbar; ein Fork des upstream-vLLM-Projekts hingegen nicht.
• Batch-offline-Inferenz. Bewertung, Generierung synthetischer Daten, Evaluationsläufe über eine feste Prompt-Menge.

Wann es nicht sinnvoll ist: Produktions-APIs, Multi-Tenant-Serving, strikte Quantisierungsbudgets oder jegliche Hardware außer NVIDIA-GPUs.

Self-Hosting vs. API

Der lokale Betrieb von nano-vLLM verursacht echte Kosten – Investitionen in GPUs, Stromkosten sowie Engineering-Zeit. Cloud-basierte Frontiers-Modelle sind bei geringem Volumen oft kostengünstiger pro Token als die amortisierten lokalen Inferenzkosten. Vergleichen Sie dies mit der Selbsthosting vs. API-Rechner und das API-Kostenrechner. Als Referenz kosten Qwen3 8B auf einem gehosteten Endpunkt $0,04 ein- bzw. $0,14 aus pro 1 Mio. Tokens gemäß der Convly Modelldatenbank, während eine 24-GB-GPU, die lokal dafür geeignet ist, deutlich über 1.500 US-Dollar kostet.

Häufig gestellte Fragen

Wer hat nano-vllm geschrieben?

Das Repository wird von Xingkai Yu (GitHub-Benutzername GeeeekExplorer), einem Ingenieur bei DeepSeek, gepflegt. Es handelt sich um ein persönliches Projekt und nicht um eine offizielle DeepSeek-Veröffentlichung. Der Quellcode steht unter der MIT-Lizenz und ist verfügbar unter github.com/GeeeekExplorer/nano-vllm.

Ist nano-vllm schneller als vLLM?

Die README berichtet über eine Durchsatzleistung, die bei kleinen dichten Modellen wie Qwen3-0,6B auf einer einzelnen RTX-4070-ähnlichen GPU nahe an der von vLLM liegt; in einigen Kurz-Benchmark-Konfigurationen ist sie sogar leicht schneller, da weniger Scheduler-Overhead anfällt. Bei größeren Modellen, längeren Kontexten oder beim Serving mehrerer Anfragen ziehen die Optimierungen des upstream-vLLM-Projekts deutlich vor. Verstehen Sie die Leistungsparität daher als „im selben Bereich für Offline-Batch“, nicht als „strikten Ersatz“.

Kann nano-vllm eine OpenAI-kompatible API bereitstellen?

Nicht out-of-the-box. Das Projekt stellt eine Python LLM.generate() Methode für die Offline-Batch-Verwendung. Falls Sie einen HTTP-Server mit /v1/chat/completions, umschließen Sie ihn selbst mit FastAPI oder verwenden Sie den OpenAI-kompatiblen Server von vLLM oder Ollama.

Unterstützt nano-vllm quantisierte Modelle wie GGUF oder AWQ?

Nein. Der Code lädt standardmäßig bf16-/fp16-gewichtete Hugging-Face-safetensors-Modelle. Für GGUF-Formate (z. B. Q4_K_M) verwenden Sie llama.cpp-basierte Tools; für AWQ- oder GPTQ-Modelle nutzen Sie den upstream vLLM. Dies ist einer der Gründe dafür, dass der VRAM-Verbrauch von nano-vllm pro Parameter höher ist als der von Ollama für dasselbe Modell.

Welche Modelle sind bekanntermaßen kompatibel?

Dichte Qwen3-Modelle sind das primäre Ziel der Referenzimplementierung. Andere Modelle mit Llama-Architektur funktionieren oft mit geringfügigen Anpassungen des Modell-Loaders, exotische Architekturen (z. B. Mixture-of-Experts oder hybride State-Space-Modelle) hingegen in der Regel nicht. Eine aktuelle Liste der unterstützten Modelle finden Sie im Verzeichnis nanovllm/models/ des Repositorys.

Kann ich nano-vllm auf AMD- oder Apple-Silicon-Hardware ausführen?

Derzeit nicht. Die Kernel setzen CUDA voraus. ROCm könnte mit einem benutzerdefinierten PyTorch-Build funktionieren, wurde jedoch upstream nicht getestet. Auf Apple Silicon gibt es keine Unterstützung – verwenden Sie stattdessen MLX-basierte Tools oder llama.cpp. Für einen Überblick über Alternativen siehe die LLM-Leaderboard und wählen Sie ein Modell, das zu Ihrem Hardware-Profil passt.