tiny-vllm: ein Inferenzserver in C++ und CUDA als Lehrprojekt

Wofür tiny-vllm gedacht ist

Das Projekt richtet sich an zwei Gruppen. Die erste sind Entwickler, die verstehen wollen, was zwischen einem Safetensors-Container und einem fertigen Token passiert. Die zweite sind Dozierende, die Material für eine Vorlesung über GPU-Inferenz brauchen. Das README formuliert das selbst so: das Repository bestehe aus dem vollständigen Quelltext des Inferenzservers und aus einem Kurs, der durch die Implementierung führt. Der Autor schreibt, man werde unterwegs Fehler machen und die Ideen und die Mathematik von Grund auf herleiten. Wer eine Bibliothek sucht, die er in einen Dienst einbinden kann, liest dieses README falsch.

Das Problem, das hier bearbeitet wird, ist nicht der Durchsatz einer Produktionsflotte. Es ist die Lücke zwischen dem Wissen, dass vLLM PagedAttention verwendet, und der Fähigkeit, eine eigene Version dieser Idee zu schreiben. Der Kurs beginnt deshalb beim Modell als Datei voller Fließkommazahlen und endet beim Paged-Attention-CUDA-Kernel.

Der Pfad durch den Code: vom Safetensors bis zum Paged-Attention-Kernel

Die Reihenfolge im README ist die Architektur des Projekts. Am Anfang steht das Laden eines echten Modells aus dem Safetensors-Format, konkret Llama 3.2 1B Instruct. Danach folgt der vollständige Forward Pass, getrennt in Prefill und Decode. Die gesamte Berechnung läuft laut README in CUDA-Kernels, nicht über eine Host-Schleife.

Ein eigener Abschnitt erklärt, warum der KV-Cache überhaupt existiert, und ein weiterer trennt Prefill von Decode. Das sind die beiden Betriebsarten, die den Rest bestimmen: Prefill verarbeitet den Prompt, Decode erzeugt ein Token nach dem anderen. Die Aufmerksamkeit wird in mehreren Schritten aufgebaut: Attention, GQA (grouped-query attention), Softmax, kausale Maske, Argmax. Dazu kommen die Bausteine davor und danach: Tokenisierung, Embeddings, RMSNorm mit paralleler Reduktion in CUDA, RoPE, Residualverbindungen, SiLU und das Feed-Forward-Netz. Für die Matrixmultiplikationen nennt das README cublasGemmEx und einen eigenen Abschnitt zu einem Spalten-zu-Zeilen-Transpositionstrick, der offenbar nötig ist, um die Layouts von cuBLAS und dem eigenen Code zusammenzubringen.

Der interessante Teil liegt weiter unten. Online-Softmax in einer FlashAttention-artigen Form, PagedAttention, ein Paged KV-Cache und schließlich der Paged-Attention-CUDA-Kernel. Dazwischen stehen statisches Batching, Continuous Batching und Buffer-Reuse. Das ist die eigentliche Erzählung des Projekts: erst eine naive Schleife, dann das Batching, dann die Speicherverwaltung, dann der Kernel, der beides zusammenbringt.

Warum die Reihenfolge des Kurses selbst ein Argument ist

Viele Erklärungen zu vLLM springen direkt zu PagedAttention und lassen offen, welches Problem die Seitenverwaltung des KV-Cache löst. Hier ist die Reihenfolge umgekehrt aufgebaut. Zuerst kommt der KV-Cache, dann statisches Batching, dann Continuous Batching, dann Paged KV-Cache, dann der Kernel. Wer bis zum Ende liest, hat jede Stufe einmal ohne die nächste gesehen. Das ist der didaktische Kern und der Grund, warum das Material auch für eine Vorlesung taugt.

Der Preis dafür ist Redundanz im Repository. Ein Abschnitt zu GQA, einer zu Softmax, einer zur kausalen Maske. Wer nur den Kernel verstehen will, muss sich durch Themen arbeiten, die er schon kennt. Das README bietet keine Abkürzung an, keinen Schnellpfad für Leser mit CUDA-Erfahrung. Das ist eine bewusste Entscheidung für Vollständigkeit, aber sie kostet Zeit.

Was man zum Start braucht

Das README nennt einen Abschnitt Technical prerequisities, ohne dessen Inhalt im vorliegenden Material auszuführen. Konkrete Build-Kommandos, CMake-Ziele oder ein Beispielaufruf des Servers sind darin nicht enthalten. Wer das Projekt ausprobieren will, muss diese Angaben im Repository nachsehen; aus dem hier vorliegenden Text lassen sie sich nicht rekonstruieren.

Gesichert ist dagegen der technische Rahmen: C++ als primäre Sprache, CUDA für die Kernel, cuBLAS über cublasGemmEx für die Matrixmultiplikation, Safetensors als Gewichtsformat. Als Modell ist Llama 3.2 1B Instruct benannt. Wer eine andere Architektur verwenden will, muss das Laden und den Forward Pass anpassen. Das Projekt ist auf genau ein Modell zugeschnitten, nicht auf einen Modellkatalog.

Wo tiny-vllm an seine Grenzen stößt

Der wichtigste Punkt ist die Modellbindung. Ein Inferenzserver, der auf Llama 3.2 1B Instruct ausgelegt ist, ist kein generischer Server. Andere Architekturen bedeuten andere Gewichtsnamen, andere Kopfzahlen, andere Dimensionen. Nichts im README deutet auf eine Abstraktion hin, die das auffängt.

Der zweite Punkt ist die Hardware. CUDA-Kernels laufen auf NVIDIA-GPUs. Wer auf anderen Beschleunigern oder auf CPU deployen will, kann mit diesem Code nichts anfangen. Das ist keine Einschränkung, die sich durch Konfiguration beheben lässt.

Der dritte Punkt betrifft die Betriebsreife. Das README verspricht keinen HTTP-Endpunkt, keine Authentifizierung, keine Metriken, keine Modellverwaltung, keine Quantisierung. Es verspricht einen Forward Pass, Batching und PagedAttention. Für einen Artikel über Produktionsinferenz ist das wenig. Für einen Kurs ist es genau richtig. Wer tiny-vllm in einen Dienst einbaut, muss alles oberhalb der Engine selbst schreiben.

Viertens: Es gibt keine abgerufenen Releases. Das Repository ist nicht archiviert, aber es gibt keinen versionierten Stand, an dem man sich festhalten könnte. Wer den Code einbettet, bindet sich an den jeweiligen Stand des main-Branches.

vLLM als Referenz und als Gegenentwurf

Das README bezeichnet tiny-vllm selbst als jüngeres und kleineres Geschwister von vLLM. Der Unterschied liegt nicht in der Idee, sondern im Umfang. vLLM ist ein Projekt, das viele Modelle, viele Hardware-Backends und eine OpenAI-kompatible Schnittstelle abdeckt. tiny-vllm deckt ein Modell ab und erklärt dabei jeden Schritt.

Wer die Idee hinter PagedAttention verstehen will, findet in tiny-vllm weniger Code, den er überfliegen muss. Wer sie einsetzen will, greift zu vLLM, weil dort die Arbeitsteilung zwischen Modell, Speicherverwaltung und Scheduler bereits gelöst ist. Der Vergleich ist also nicht besser gegen schlechter, sondern lesbar gegen belastbar. Ein weiterer Unterschied ist die Sprache: vLLM ist überwiegend Python mit CUDA-Kernels, tiny-vllm ist durchgehend C++ und CUDA. Wer den Kernel-Pfad ohne Python-Zwischenschicht sehen will, hat hier einen kürzeren Weg.

Lizenz und Pflegeaufwand

Das Projekt steht unter Apache-2.0. Diese Lizenz erlaubt Nutzung, Änderung und Weitergabe, auch in kommerziellen Zusammenhängen, und enthält eine Patentklausel. Wer den Code in ein eigenes Produkt übernimmt, muss die Bedingungen der Lizenz einhalten, insbesondere Hinweise auf Urheberrecht und Lizenz mitführen. Das ist eine allgemeine Einordnung, keine Rechtsberatung.

Zum Pflegeaufwand lässt sich aus dem Material nur wenig Sagen. Es gibt keine abgerufenen Releases, also auch keine Versionshistorie, an der man den Aufwand für ein Upgrade festmachen könnte. Der letzte Push datiert auf den 23. August 2026. Wer den Code forkt und weiterentwickelt, übernimmt die Pflege der CUDA-Kernel selbst; das ist der Teil, der bei Änderungen an der Modellarchitektur oder an der CUDA-Toolchain zuerst bricht. Ein Kursprojekt dieser Art hat typischerweise einen Autor. Ob und wie schnell Fehler behoben werden, lässt sich aus dem Repository-Zustand nicht ableiten.

Redaktionelles Fazit

Sinnvoll ist tiny-vllm für Lehre und Selbststudium: wer CUDA-Kernel, PagedAttention und Batching an einem vollständigen Beispiel nachvollziehen will, bekommt Code plus Kurs. Wer einen produktiven Endpunkt für mehrere Modelle, OpenAI-kompatible API oder Quantisierung braucht, ist hier falsch. Vor dem Einsatz ist zu prüfen, ob der Code auf der eigenen GPU-Generation baut, ob Safetensors-Layout und Tokenizer zu Llama 3.2 1B Instruct passen und ob das Repository nach dem letzten Push vom 23. August 2026 noch gepflegt wird.

Offizielle Quellen

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