tiny-llm README

README проекта с github.com/skyzh/tiny-llm. Одним файлом markdown: README.md.

tiny-llm

CI (main)

tiny-llm is a hands-on course for systems engineers who want to understand LLM inference end to end. You can think of it as an LLM-serving counterpart to CMU's Needle project: build the path that loads a Qwen3 model, turns tokens into logits, and generates text.

The course begins with array and matrix operations, then introduces kernels and serving machinery as the running model needs them. Keeping the implementation small enough to read end to end makes it possible to connect the equations to memory traffic, kernel occupancy, KV-cache growth, batching, and request scheduling.

The course is built on MLX arrays and the MLX extension runtime, without using high-level neural-network layers. When a chapter teaches an operator, your solution implements that operator in Python, C++, or Metal rather than calling the corresponding optimized MLX operation. MLX remains the correctness oracle and performance baseline.

The Learning Path

The course follows a four-week learning path:

Why MLX and Qwen3?

Apple silicon provides a practical local environment with one shared memory space and direct access to Metal kernels. Students can inspect the complete path on one machine instead of depending on an expensive CUDA GPU setup.

Qwen3-4B is large enough to expose real weight-bandwidth, attention, and cache costs, but small enough to iterate on locally. Its grouped-query attention, QK normalization, BF16 activations, and 4-bit weights also keep the exercises close to current model-serving work.

Start Here

The book is published at skyzh.github.io/tiny-llm. Begin with the environment setup, or verify an existing checkout with:

pdm install -v
pdm run check-installation
pdm run test-refsol -- -- -k week_1

The tiny_llm package is where students implement the exercises. tiny_llm_ref contains the reference solution used by the tests and benchmark appendix. The book summary lists the chapter order; implementation, test, and publication readiness is tracked below.

Roadmap

The table tracks implementation (Code), tests (Test), rendered chapters (Doc), and Chi's review of learner-facing material (Audit). Week 4 is publishing one reviewed day at a time; Days 1 through 9 are currently available to learners. The Audit column reflects Chi's personal editorial pass on the published course content and is independent of code/test/doc readiness.

Day 3 can send file contents to the model, modify files after approval, and run one exact configured command. Use a disposable workspace without secrets and read the Week 4 overview before running the loop. Day 4 checkpoints a complete tool-observation boundary with the scripted model's fake cache metadata, then restores a fresh model without replaying the completed edit or command. Day 5 compacts older completed effects in the model-visible transcript while their exact receipts retain the full action, result, and changed artifacts. Day 6 inspects one complete-observation checkpoint, appends one visible operator instruction, and resumes a fresh model without replaying the completed effect. Day 7 evaluates one completed run from declared final, file, result, and receipt facts without grading hidden reasoning or exact transcript shape. Day 8 reuses one real tokenizer/KV checkpoint for two differently steered, effect-isolated continuations, evaluates both with Day 7's harness, and makes one explicit passing selection without pretending completed effects were rewound. Day 9 stores exact oversized tool-result bytes outside the model prompt, shows a bounded identity/digest/head-tail observation, and lets the model retrieve one explicit byte range through the existing loop.

Week + Chapter Topic Code Test Doc Audit
1.1 Attention ✅ ✅ ✅ ✅
1.2 RoPE ✅ ✅ ✅ ✅
1.3 Grouped Query Attention ✅ ✅ ✅ ✅
1.4 RMSNorm and MLP ✅ ✅ ✅ ✅
1.5 Load the Model ✅ ✅ ✅ ✅
1.6 Generate Responses (aka Decoding) ✅ ✅ ✅ ✅
1.7 Sampling ✅ ✅ ✅ ✅
2.1 KV Cache (kv-cache) 🚧 🚧 ✅ 🚧
2.2 Packed W4 Weights (packed-weights) 🚧 🚧 ✅ 🚧
2.3 Decode Matvec (quantized-matvec) 🚧 🚧 ✅ 🚧
2.4 SIMD Prefill (simd-matmul) 🚧 🚧 ✅ 🚧
2.5 Fused Kernels (rmsnorm, rope, swiglu) 🚧 🚧 ✅ 🚧
2.6 Tiled Attention (tiled-prefill, selected) 🚧 🚧 ✅ 🚧
3.1 Continuous Batching ✅ ✅ ✅ 🚧
3.2 Chunked Prefill ✅ ✅ ✅ 🚧
3.3 Paged KV Cache ✅ ✅ ✅ 🚧
3.4 Direct Paged Attention ✅ ✅ ✅ 🚧
3.5 Paged FlashAttention ✅ ✅ ✅ 🚧
3.6 (optional) MoE (Mixture of Experts) ✅ ✅ ✅ 🚧
3.7 (optional) Speculative Decoding ✅ ✅ ✅ 🚧
4.1 Validated Agent Loop ✅ ✅ ✅ 🚧
4.2 Inspect a Workspace ✅ ✅ ✅ 🚧
4.3 Edit, Validate, and Record ✅ ✅ ✅ 🚧
4.4 Checkpoint and Resume ✅ ✅ ✅ 🚧
4.5 Compact Completed Work ✅ ✅ ✅ 🚧
4.6 Inspect and Steer a Paused Agent ✅ ✅ ✅ 🚧
4.7 Evaluate Observable Outcomes ✅ ✅ ✅ 🚧
4.8 Fork, Steer, and Select ✅ ✅ ✅ 🚧
4.9 Bound Tool Evidence ✅ ✅ ✅ 🚧

Earlier Week 2 chapter URLs not reused by the active six days still serve their historical pages, which are hidden from the book's sidebar. The five-day Day 3 to 5 addresses redirect to their renumbered chapters.

Other topics not covered include quantized or compressed KV caches, cross-request prefix caching, fine-tuning, and long-context techniques.

Community

Join skyzh's Discord server to study with the tiny-llm community.

Join skyzh's Discord Server

Community port: amagilabs/tiny-llm-cuda is an unofficial CUDA (NVIDIA GPU) backend for the reference solution kernels, via MLX's CUDA backend.

tiny-llm (skyzh/tiny-llm)

Ищем в базе…

Что это такое?tiny-llm — практический курс, который учит инженеров-системщиков тому, как работает инференс LLM от начала до конца: они собирают небольшую модель Qwen3 и мини-стек обслуживания в стиле vLLM на Apple Silicon с использованием MLX.
Это библиотека, которую я импортирую, или курс, который я прохожу?Это опубликованный курс в формате книги (skyzh.github.io/tiny-llm). В пакете students под названием tinyllm вы реализуете упражнение каждой главы, а пакет tinyllmref содержит эталонное решение, которое используют тесты.
С чего начать прохождение курса?Начните с настройки окружения, описанной в опубликованной книге, или проверьте уже имеющуюся копию с помощью команды из материалов курса перед началом первой недели.
Нужна ли видеокарта CUDA, чтобы пройти этот курс?Нет, весь курс работает на Mac с Apple Silicon с использованием MLX и ядер Metal вместо CUDA.
Четырёхнедельный курс уже полностью готов?Первая и третья недели полностью реализованы, протестированы и задокументированы. Несколько глав второй недели пока помечены как находящиеся в работе, а материалы четвёртой недели про агента для написания кода выходят по одному проверенному дню за раз, сейчас доступно до девятого дня включительно.
Нужен ли Apple Silicon, или подойдёт Mac на Intel?Курс построен на архитектуре Apple Silicon с общей памятью и прямом доступе к ядрам Metal, поэтому он рассчитан на Mac с Apple Silicon, а не на Mac с Intel или машины с Linux и CUDA.
Вокруг какой модели строится курс?Qwen3-4B. Её выбрали, потому что она достаточно большая, чтобы показать реальные издержки пропускной способности весов, внимания и кэша, и при этом достаточно маленькая, чтобы экспериментировать локально. Её grouped-query attention, QK-нормализация, активации BF16 и 4-битные веса делают упражнения близкими к современной практике обслуживания моделей.
Почему MLX, а не PyTorch или настройка с CUDA?MLX даёт Apple Silicon среду с общей памятью и прямым доступом к ядрам Metal. Студенты видят весь путь инференса на одной машине, без дорогой видеокарты CUDA. Кроме того, MLX служит эталоном правильности и базовым уровнем производительности для каждого упражнения.
Что добавляет четвёртая неделя?Четвёртая неделя строит ограниченный и проверяемый цикл агента для написания кода, подключённого к небольшому рабочему пространству. Постепенно добавляются сохранение и возобновление с контрольных точек, сжатие контекста, управление с паузой и корректировкой, а также оценка, опирающаяся на доказательства, — по всем опубликованным дням.
Есть ли сообщество, с которым можно проходить курс?Да, автор ведёт Discord-сервер, где ученики вместе проходят tiny-llm.
Какие есть похожие проекты?llm-inference-engineering, lectures, jeeves, dflash, BigMoeOnEdge, vllm, v100-skinny, NeoHorse
Автор
skyzh
Размер
7.9 MB
Звёзды
5.8K
Обновлён
КоммитNov 16
Возраст
1 г
Коммиты · 90 дней