nndl/llm-beginner: ein Lehrbuch plus sechs Programmieraufgaben vom Transformer bis zum Coding-Agenten

Ein Lehrbuch, das nicht nur gelesen, sondern abgearbeitet werden soll

Das Repository versteht sich als Verbindung zweier Dinge, die sonst getrennt auftreten: ein Fließtext über große Sprachmodelle und Agenten, und eine Reihe von Übungen, in denen genau die Mechanismen nachgebaut werden, die der Text erklärt. Das PDF trägt den Titel 大模型与智能体, stammt von 邱锡鹏 und umfasst laut Beschreibung 17 Kapitel in vier Teilen: gemeinsame Grundlagen, große Modelle, Agenten, Grenzen und Zukunft. Die sechs Aufgaben folgen einer Linie: Transformer, mini-GPT, SFT und DPO, RAG, Tool-Calling-Agent, Coding-Agent.

Die Zielgruppe ist enger, als die Überschrift vermuten lässt. Das README sagt ausdrücklich, dass Buch und Übungen unabhängig voneinander lernbar sind, dass die Übungen aber Python- und Deep-Learning-Grundlagen voraussetzen. Wer noch nie eine Softmax-Ableitung von Hand geschrieben oder einen Trainingsloop mit PyTorch gebaut hat, wird bei Aufgabe eins hängen bleiben. Wer dagegen schon Modelle feinabgestimmt hat und die Interna nachholen will, findet hier den seltenen Fall, dass RoPE, KV-Cache und eine BPE-Implementierung nicht als Bibliotheksaufruf, sondern als eigene Arbeit verlangt werden.

Bemerkenswert ist der Hinweis, dass das Manuskript sich in der Phase der Verlagsvorbereitung befindet und sich mit den Revisionen ändert. Das ist kein Marketing, sondern eine Planungsgröße: Wer das PDF als Referenz für ein Semester nutzt, muss mit Verschiebungen rechnen.

Der Kontrakt zwischen src/ und eval/run.py

Das eigentliche Design dieses Repositories steckt nicht in den Aufgaben, sondern in der Verzahnung von Lernendem und Prüfskript. Alle sechs Aufgaben folgen derselben Verzeichnisstruktur: requirements.txt für die Abhängigkeiten, data/download.py zum Beschaffen von Daten und Modellen, eval/run.py als Selbstprüfung und eval/tutor_prompt.md als Prompt-Vorlage für eine Code-Review durch ein Sprachmodell. Die Implementierung selbst gehört in src/, und zwar nach den Klassen- und Funktionssignaturen, die die Tabelle 实现约定 im README der jeweiligen Aufgabe auflistet. Das Prüfskript importiert genau diese Namen. Wer eigene Bezeichner wählt, bekommt keine inhaltliche Bewertung, sondern gar keine.

Die Rückmeldung ist dreistufig. [通过] heißt, der Vertrag ist erfüllt. [跳过] heißt, eine Voraussetzung fehlt, etwa ein Modell, ein Checkpoint oder ein Datensatz; das ist ausdrücklich kein Fehler, sondern ein Zustand, der sich nach dem Nachladen auflöst. [失败] heißt, die Implementierung weicht von der Erwartung ab, und die Ausgabe enthält laut README ein error-Feld oder konkrete Metriken. Die Ergebnisse landen strukturiert in eval/result.json, immer UTF-8, und können einer Abgabe beigelegt werden.

Eine Einschränkung steht offen im Text: Die Selbstprüfung kontrolliert Schlüsselverträge wie die numerische Korrektheit der Attention, die Trefferquote beim Retrieval oder die Erfolgsrate bei der Aufgabenlösung. Sie ist, mit den Worten des README, eine untere Grenze dafür, ob etwas korrekt läuft, und ersetzt nicht die Vergleichs- und Ablationsläufe aus dem Abschnitt 实验 der einzelnen Aufgaben. Das ist eine ehrliche Formulierung, und sie markiert zugleich die Schwäche: Wer nur eval/run.py grün bekommt, hat die Aufgabe bestanden, aber nicht verstanden.

Aufbau und Ausführung: download, src, run

Der Ablauf ist für alle Aufgaben gleich und im README an Aufgabe eins durchexerziert. Zuerst die Abhängigkeiten der gewählten Aufgabe, nicht des gesamten Repositories:

pip install -r task-1-transformer/requirements.txt

Dann das Beschaffen der Daten, gefolgt von der eigenen Implementierung und der Prüfung:

cd task-1-transformer python data/download.py python eval/run.py

Die Download-Skripte unterscheiden sich je Aufgabe. Aufgabe eins holt ChnSentiCorp für chinesische Sentiment-Klassifikation. Aufgabe zwei akzeptiert einen Parameter: python data/download.py mit --dataset poetry, tinystories oder skypile, wobei poetry als Standard für den Schnelldurchlauf dient und rund 49 KB groß ist. Aufgabe drei lädt Qwen2.5-0.5B und verweist auf die Beschaffung der MOSS- und DPO-Daten. Aufgabe vier kennt --skip-models, um nur das NNDL-PDF zu laden und die gold_qa-Datei zu prüfen, ohne die BGE-Modelle zu ziehen. Aufgabe fünf erzeugt einen Aufgabensatz aus zehn Fragen samt Retrieval-Fixture und druckt einen Hinweis zur Modellbereitstellung. Aufgabe sechs baut ein lokales toy-repo und lädt mit --with-swebench zusätzlich eine Stichprobe der SWE-bench-Lite-Metadaten.

Für Umgebungen ohne stabilen Zugang zu Hugging Face nennt das README zwei Wege. Erstens die Spiegelung per Umgebungsvariable:

export HF_ENDPOINT=https://hf-mirror.com

In PowerShell lautet die Entsprechung $env:HF_ENDPOINT = "https://hf-mirror.com". Zweitens der Wechsel zu ModelScope, den die Download-Skripte am Ende erwähnen. Eine Falle ist explizit dokumentiert: eval/run.py muss innerhalb des Repositories laufen, weil es das Harness _eval_harness.py im Wurzelverzeichnis importiert. Wer ein Aufgabeverzeichnis isoliert kopiert, bricht die Prüfung.

Was in den sechs Aufgaben tatsächlich verlangt wird

Die Aufgaben sind nicht gleich schwer, und das README macht das über die Zeitangaben sichtbar. Aufgabe eins verlangt handgeschriebene scaled dot-product attention mit Skalierung, Softmax und Maske, daraus Multi-Head-Attention, einen vollständigen Encoder-Block aus Attention, Feed-Forward, Residual und LayerNorm, das Training auf ChnSentiCorp mit Padding-Maske, einen zweiten Durchlauf mit Causal-Maske als Vorbereitung auf Aufgabe zwei und eine Heatmap der Attention-Gewichte über matplotlib. Als Experimente sind Head-Anzahl, Schichtanzahl, das Entfernen von Residual und LayerNorm sowie die Interpretation der Heatmaps vorgesehen. Zwei Wochen sind dafür angesetzt.

Aufgabe zwei ist die technisch dichteste. Verlangt werden ein eigener vereinfachter BPE-Tokenizer ohne tiktoken oder sentencepiece, ein Decoder-only-Modell mit RoPE, ein KV-Cache und die Sampling-Strategien greedy, top-k, top-p sowie Temperatur. Das README markiert die Abgrenzung zur Vorlage deutlich: Gegenüber dem nanoGPT-Kapitel des Praxisbuchs kommen BPE, RoPE und KV-Cache hinzu. Damit ist die Aufgabe kein Nachbau, sondern eine Erweiterung. Drei Datensätze stehen bereit, von 49 KB über rund 100 MB bis über 1 GB für SkyPile-150B, wobei TinyStories laut Beschreibung auf der CPU lauffähig ist. Drei Wochen.

Die weiteren Aufgaben verschieben den Schwerpunkt von der Mechanik zur Systemintegration. In Aufgabe drei wird LoRA von Hand implementiert und SFT sowie DPO werden verglichen. Aufgabe vier verlangt eine Kette aus Retrieval, Reranking und Generierung samt Bewertung der Antwortqualität. Aufgabe fünf baut die ReAct-Schleife mit Werkzeugaufrufen und Fehlerbehandlung. Aufgabe sechs, mit 5 bis 6 Wochen die längste, zielt auf einen Agenten, der Code ändert, Tests ausführt und iteriert. Wer nur an einer Stelle einsteigen will, kann das laut README tun, sofern die im jeweiligen README genannten Voraussetzungen erfüllt sind.

Die Selbstprüfung als Untergrenze, nicht als Note

Der wichtigste Vorbehalt betrifft die Aussagekraft von eval/run.py. Das Skript prüft Verträge, nicht Verständnis. Eine Attention-Implementierung, die numerisch korrekt rechnet, aber den Sinn der Skalierung nicht durchdrungen hat, passiert. Ein RAG-Aufbau, der die geforderte Trefferquote erreicht, aber bei der Reranking-Reihenfolge zufällig richtig liegt, passiert ebenfalls. Die Aufgaben-READMEs enthalten deshalb eigene Experimentabschnitte mit Vergleichen und Ablationen, und das Haupt-README sagt selbst, dass die Prüfung diese nicht ersetzt. Wer die Aufgaben als Portfolio nutzt, sollte die Ablationsergebnisse mitliefern, sonst bleibt vom Nachweis nur ein Häkchen.

Ein zweiter Punkt betrifft die Reproduzierbarkeit. Der Status [跳过] tritt auf, wenn Modelle, Checkpoints oder Daten fehlen. In einer Umgebung ohne Hugging-Face-Zugang kann das dazu führen, dass eine Aufgabe überwiegend übersprungen wird und die Ausgabe grün aussieht, ohne dass etwas geprüft wurde. Das ist kein Fehler des Skripts, aber ein Missverständnis, das leicht entsteht. Wer die Ergebnisse weitergibt, sollte die result.json auf übersprungene Einträge durchsehen, nicht nur auf Fehler.

Drittens die Datenabhängigkeit. Aufgabe drei verweist für die Präferenzdaten auf externe Beschaffungswege, Aufgabe zwei bietet drei Korpora mit stark unterschiedlichem Umfang, Aufgabe sechs lädt SWE-bench Lite nur auf ausdrücklichen Wunsch. Diese Wahlfreiheit ist praktisch, verschiebt aber die Vergleichbarkeit: Zwei Lernende, die dieselbe Aufgabe mit poetry und mit skypile durchlaufen, haben unterschiedliche Erfahrungen gemacht.

Abgrenzung zu nanoGPT und zum Praxisbuch

Die naheliegende Alternative für Aufgabe zwei ist nanoGPT von Karpathy. Der Unterschied liegt nicht im Umfang, sondern im Anspruch. nanoGPT ist ein lesbares, vollständiges Trainingsskript, das man klont und laufen lässt; die Architektur ist fertig, der Lernende passt Konfigurationen an. llm-beginner dreht das um: Das Modell ist gerade nicht vorhanden. Der Lernende schreibt BPE, RoPE und KV-Cache selbst, und das Harness prüft anschließend, ob die Signaturen stimmen. Wer schnell ein Sprachmodell trainieren will, ist bei nanoGPT besser aufgehoben. Wer verstehen will, warum ein KV-Cache Speicher gegen Rechenzeit tauscht, muss den Weg über die eigene Implementierung gehen.

Eine zweite Referenz ist das eigene Praxisbuch 案例与实践 in der zweiten Auflage, auf das die Aufgaben mehrfach verweisen. Das Verhältnis ist komplementär und wird im README offengelegt. Aufgabe eins überschneidet sich bewusst mit dem Kapitel zur Attention-Mechanik, um Lesern ohne Vorgeschichte einen Einstieg zu geben. Aufgabe zwei geht über das nanoGPT-Kapitel hinaus, weil der KV-Cache dort nur erklärt und nicht implementiert wird. Diese Offenheit über die Doppelung ist angenehm, macht aber auch klar, dass das Repository für Leser des Praxisbuchs teilweise Wiederholung bedeutet. Wer beide nutzt, sollte die Reihenfolge bewusst wählen, statt parallel zu arbeiten.

Pflege, Lizenz und der Aufwand über die Erstbearbeitung hinaus

Das Repository steht unter MIT-Lizenz. Für Lernende und für Lehrende, die Materialien anpassen oder in eigene Kurse einbetten wollen, ist das die unkomplizierteste Variante: Weitergabe und Bearbeitung sind erlaubt, sofern der Urheberrechtsvermerk und der Lizenztext erhalten bleiben. Für das E-Book selbst sagt das Repository nichts über eine abweichende Regelung; das PDF wird als Release book-pdf mit dem Hinweis 出版前电子稿 verteilt, also als Vorabfassung vor der Veröffentlichung. Wer das PDF weiterverbreitet oder in eigene Unterlagen einbindet, sollte diesen Status und die Verlagsphase klären, bevor er sich darauf verlässt. Eine rechtliche Einschätzung ist hier nicht möglich und auch nicht beabsichtigt.

Der Pflegeaufwand für Nutzer entsteht an zwei Stellen. Erstens durch die Aktualisierung des Manuskripts: Das README sagt, dass die Inhalte mit den Revisionen fortgeschrieben werden. Wer auf bestimmte Kapitelnummern verweist, muss mit Verschiebungen rechnen. Zweitens durch die Aufgabenabhängigkeiten. Jede Aufgabe hat eine eigene requirements.txt, und die Aufgaben sind laut README unabhängig installierbar, entweder in einer gemeinsamen Umgebung oder in getrennten venv- beziehungsweise conda-Umgebungen. Das ist flexibel, bedeutet aber, dass ein Upgrade der PyTorch-Version in einer Aufgabe nicht automatisch die anderen erfasst. Wer alle sechs Aufgaben über Monate bearbeitet, sollte die Umgebungen getrennt halten, statt eine gemeinsame Installation zu erweitern.

Ein Punkt zur Modellbeschaffung: Aufgabe drei lädt Qwen2.5-0.5B, und die Aufgaben verweisen für weitere Modelle auf die Download-Skripte. Diese Skripte sind der einzige Ort, an dem sich Modellquellen ändern können, ohne dass sich die Aufgabe selbst ändert. Wer den Kurs über einen längeren Zeitraum plant, prüft daher zu Beginn jedes Blocks, ob data/download.py noch durchläuft, bevor er Stunden in eine Implementierung investiert, die anschließend an fehlenden Gewichten scheitert.

Redaktionelles Fazit

Wer die Kette aus Attention, mini-GPT, LoRA und DPO, RAG, ReAct und Coding-Agent einmal vollständig selbst implementieren will, findet hier einen durchgängigen, MIT-lizenzierten Pfad mit klaren Signaturen und einem Harness, der die Untergrenze prüft. Wer ein Framework für den Produktivbetrieb sucht oder in zwei Wochen Ergebnisse braucht, ist falsch: Der vorgeschlagene Rhythmus reicht von 2 bis 6 Wochen pro Aufgabe. Vor dem Start sollte man data/download.py der gewählten Aufgabe ausführen und prüfen, ob der Datensatz durchläuft, sowie im README der Aufgabe die Tabelle der Klassensignaturen lesen, denn eval/run.py importiert genau diese Namen aus src/.

Offizielle Quellen

1. License: MIT
2. nndl/llm-beginner on GitHub
3. Project website
4. README
5. Releases