skyzh/tiny-llm: Ein LLM-Inferenzstack zum Selbernachbauen auf Apple Silicon

Für wen der Kurs gebaut ist und welche Frage er beantwortet

Das README benennt die Zielgruppe selbst: Systems Engineers, die LLM-Inferenz end to end verstehen wollen. Der Vergleich mit CMUs Needle-Projekt ist bewusst gewählt. Needle lehrt, wie ein Autograd-Framework von innen aussieht. tiny-llm nimmt dieselbe Haltung und richtet sie auf die Serving-Seite: Wie kommt ein Qwen3-Modell von Gewichten zu Logits, und wie wird daraus Text, der unter Last noch vertretbar läuft. Wer schon einmal einen vLLM-Stack deployt hat, aber nicht erklären kann, warum der Scheduler Blöcke statt Sequenzen verwaltet, ist die richtige Leserschaft. Wer vortrainierte Checkpoints fine-tunen will, ist es nicht. Der Kurs behandelt Inferenz, nicht Training, und das README führt kein Fine-Tuning-Kapitel. Auch Modellarchitektur-Forschung ist kein Thema: Qwen3-4B ist fest gesetzt, nicht als Vorschlag, sondern weil seine grouped-query attention, QK-Normalisierung, BF16-Aktivierungen und 4-Bit-Gewichte laut README genau die Kosten sichtbar machen, um die es im Kurs geht. Wer ein anderes Modell einsetzen will, verlässt den Pfad an der Stelle, an der die Referenztests auf Qwen-Formen kalibriert sind.

Der Mechanismus: MLX als Laufzeit, aber nicht als Bequemlichkeitsschicht

Die zentrale Designentscheidung steht im README und ist der Grund, warum der Kurs überhaupt funktioniert: gebaut wird auf MLX-Arrays und der MLX-Extension-Runtime, ohne die hochstufigen neuronalen Schichten der Bibliothek. Wenn ein Kapitel einen Operator lehrt, implementiert die Lösung diesen Operator in Python, C++ oder Metal, statt die entsprechende optimierte MLX-Operation aufzurufen. MLX bleibt dabei zwei Dinge gleichzeitig: Korrektheitsorakel und Performance-Baseline. Das ist ein sauberer Trick. Der Lernende bekommt eine Referenz, gegen die er testen kann, ohne dass ihm die Referenz die Arbeit abnimmt. Der Preis ist, dass jede Übung gegen genau diese Baseline gemessen wird. Wer auf einer anderen Laufzeit implementiert, hat kein Orakel mehr. Der Stoff folgt dann der Reihenfolge, in der ein Serving-Stack tatsächlich entsteht. Woche 1 baut Attention, RoPE, GQA, RMSNorm, das MLP, Sampling und die autoregressive Schleife direkt aus mlx.core-Operationen. Woche 2 setzt den KV-Cache voraus und lässt jeden Optimierungsschritt durch gematchte Benchmarks entscheiden: quantisierte Decode-Matvec, fusionierte Modell-Kernel, getiletes Prefill, Split-K dort, wo die gemessenen Qwen-Formen es verlangen. Woche 3 macht daraus Serving-Mechanik mit kontinuierlichem Batching, Chunked Admission und Paged KV als kanonischem Layout. Decode-Attention und FlashAttention lernen, Seiten direkt zu lesen, damit der Scheduler nicht bei jedem Schritt die dichte Historie neu aufbaut.

Woche 4: ein Agent, der seine eigenen Effekte bucht

Der vierte Teil weicht vom Inferenzpfad ab und baut einen Coding-Agenten. Interessant ist weniger das Agentenmuster als die Buchhaltung dahinter. Das README beschreibt einen begrenzten, validierten Agent-Loop, der an einen kleinen Workspace angebunden wird. Ab Tag 3 darf der Loop Dateiinhalte an das Modell senden, Dateien nach Freigabe ändern und genau einen konfigurierten Befehl ausführen. Tag 4 setzt einen Checkpoint an einer vollständigen Tool-Observation und stellt ein frisches Modell wieder her, ohne die abgeschlossene Bearbeitung oder den Befehl erneut abzuspielen. Tag 5 kompaktiert ältere abgeschlossene Effekte im modell-sichtbaren Transkript, während die zugehörigen Receipts Aktion, Ergebnis und geänderte Artefakte vollständig behalten. Tag 8 verwendet einen echten Tokenizer- und KV-Checkpoint für zwei unterschiedlich gesteuerte, effekt-isolierte Fortsetzungen, bewertet beide mit der Auswertung aus Tag 7 und trifft eine ausdrückliche Auswahl, ohne zu behaupten, abgeschlossene Effekte seien zurückgespult worden. Diese Formulierung ist bemerkenswert ehrlich für ein Lehrprojekt: Sie gibt zu, dass ein KV-Prefix-Reuse keine Transaktion ist. Für Lernende, die Agenten bisher als Prompt-Schleife gebaut haben, ist das der eigentlich lehrreiche Teil von Woche 4.

Installation und der erste echte Test

Der Einstieg ist knapp dokumentiert. Das Buch liegt unter skyzh.github.io/tiny-llm, das Setup-Kapitel unter /setup.html. Für eine vorhandene Arbeitskopie nennt das README drei Befehle: pdm install -v, dann pdm run check-installation, dann pdm run test-refsol -- -- -k week_1. Die ersten beiden prüfen die Umgebung, der dritte lässt die Referenzlösung gegen die Tests der ersten Woche laufen. Wer hier einen Fehler bekommt, hat ein Umgebungsproblem, kein Verständnisproblem, und sollte das vor Kapitel 1.1 klären. Die Paketaufteilung ist ebenfalls im README benannt: tiny_llm ist das Paket, in dem die Übungen implementiert werden, tiny_llm_ref enthält die Referenzlösung, die Tests und Benchmark-Anhang verwenden. Die Kapitelreihenfolge steht in book/src/SUMMARY.md. Wichtig für die Erwartungssteuerung: Es gibt keine Releases. Die Fortschrittstabelle im README führt pro Kapitel vier Spalten, Code, Test, Doc und Audit, und die Audit-Spalte ist ausdrücklich als persönlicher redaktioneller Durchgang von Chi beschrieben, unabhängig von Code-, Test- und Doku-Bereitschaft. In Woche 1 sind alle vier Spalten gesetzt. Ab Kapitel 2.1 stehen Code, Test und Doc auf erledigt, Audit auf in Arbeit.

Wo der Kurs an seine Grenzen kommt

Die Bindung an Apple Silicon ist keine Fußnote, sondern die Voraussetzung. Das README begründet sie mit einem gemeinsamen Speicherraum und direktem Zugriff auf Metal-Kernel, sodass der komplette Pfad auf einer Maschine inspizierbar ist, statt von einem teuren CUDA-Setup abzuhängen. Der Satz gilt in beide Richtungen. Wer die Übungen auf einer NVIDIA-Karte nachbauen will, muss Metal durch etwas anderes ersetzen und verliert damit die Kernel-Kapitel, in denen Woche 2 und 3 messen. Die zweite Grenze ist der Reifegrad von Woche 4. Das README formuliert es selbst: Der Kurs veröffentlicht jeweils einen geprüften Checkpoint nach dem anderen, Tage 1 bis 9 sind derzeit für Lernende verfügbar. Die Tabelle endet bei Kapitel 4.9, und alle Woche-4-Zeilen stehen im Audit auf in Arbeit. Wer den Agententeil als abgeschlossenes Curriculum erwartet, wird enttäuscht. Drittens: Kapitel 3.6 (MoE) und 3.7 (Speculative Decoding) sind im README als optional markiert. Das ist eine sinnvolle Priorisierung, aber es heißt auch, dass zwei Themen, die in aktuellen Serving-Stacks viel Aufmerksamkeit bekommen, hier nur am Rand liegen. Und schließlich der Warnhinweis zu Woche 4, der wörtlich im README steht: ein Wegwerf-Workspace ohne Secrets, und vor dem Ausführen des Loops die Week-4-Übersicht lesen. Ein Agent, der Dateien ändern und einen konfigurierten Befehl ausführen darf, ist genau das, was diese Warnung nötig macht.

Was tiny-llm nicht ist: der Unterschied zu vLLM

Der Titel des Projekts nennt vLLM, und der README beschreibt Woche 3 als Bau eines Mini vLLM. Der Unterschied liegt nicht im Umfang, sondern in der Richtung der Abstraktion. vLLM ist eine Laufzeit: Man übergibt ein Modell und bekommt einen Server mit Paged Attention, kontinuierlichem Batching und einem Scheduler, der auf Durchsatz über viele gleichzeitige Anfragen optimiert ist. tiny-llm liefert dieselben Konzepte als Übung, in der jede Optimierung durch eine gemessene Entscheidung begründet wird. In Woche 2 wählt laut README ein gematchter Benchmark jede Optimierung aus, und Split-K kommt nur dort zum Einsatz, wo die gemessenen Qwen-Formen es verlangen. Das ist der lehrreiche Teil und gleichzeitig der Grund, warum niemand tiny-llm als Serving-Backend einsetzen sollte. Es gibt keine Releases, keinen Stabilitätsvertrag, keine Zusagen zur Modellabdeckung über Qwen3-4B hinaus. Wer eine API mit mehreren Modellen, Autoscaling und Fehlertoleranz braucht, nimmt vLLM. Wer wissen will, warum vLLM so aussieht, wie es aussieht, nimmt tiny-llm und geht danach zurück zu vLLM mit anderen Augen.

Wartung, Mitverfolgen und Lizenz

Das Repository ist nicht archiviert, der letzte Push datiert auf den 9. September 2026, und die CI läuft über GitHub Actions mit einem Badge für den main-Branch. Releases gibt es laut den vorliegenden Angaben keine, was für einen Kurs konsequent ist: Man klont oder installiert aus dem Repo, nicht aus einem Paketindex. Der Aufwand beim Mitverfolgen liegt in Woche 4. Solange dort Tage einzeln veröffentlicht werden, ändert sich der Lernstoff an der Spitze des Pfads, während Wochen 1 bis 3 stehen. Wer den Kurs in einem Durchgang absolvieren will, wartet entweder, bis Woche 4 vollständig ist, oder akzeptiert, dass der letzte Teil weiterläuft. Die Lizenz ist Apache-2.0. Das erlaubt die Nutzung, Veränderung und Weitergabe des Materials einschließlich der Referenzlösungen unter den Bedingungen dieser Lizenz, üblicherweise mit Beibehaltung der Copyright- und Lizenzhinweise sowie Angabe von Änderungen. Was das für die eigenen Lösungen bedeutet, hängt davon ab, ob man sie als abgeleitetes Werk des Referenzcodes betrachtet, und diese Einordnung ist eine Rechtsfrage, keine technische. Wer die Übungen nur lokal zum Lernen durcharbeitet, berührt sie ohnehin nicht. Wer Teile des Referenzcodes in ein eigenes Produkt übernehmen will, sollte die Apache-2.0-Bedingungen im Wortlaut lesen, statt sich auf eine Zusammenfassung zu verlassen.

Redaktionelles Fazit

Wer verstehen will, warum Paged KV Cache und kontinuierliches Batching die Serving-Architektur bestimmen, findet hier einen Pfad, der vom Matmul bis zum Scheduler durchgeht, und zwar auf einer Maschine ohne CUDA. Wer dagegen einen Produktionsserver sucht, ist falsch: tiny-llm ist ein Kurs, kein Runtime. Vor dem Start ist zu prüfen, ob die eigene Hardware MLX trägt, ob pdm install -v und pdm run check-installation durchlaufen und ob der eigene Lernstand zu Woche 1 passt, denn die späteren Wochen setzen die Referenzlösungen der früheren voraus.

Offizielle Quellen

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