从零读懂 nano-vLLM

No-GPU concept labs

Build a mental model in the browser before installing CUDA, a model, or a serving stack.

Source and trace anchors

Every major mechanism is connected to a concrete source path and a teaching trace for deliberate code reading.

Thirteen learning chapters

Follow the path from a generate request to scheduling, PagedAttention, cache reuse, decoding, parallelism, and CUDA Graphs.

Optional runtime validation

Move from the conceptual path to a real CUDA environment only when you are ready to validate the ideas.

What this guide is for

vLLM is easiest to use after its system mechanisms make sense. This guide begins with the questions that typically block a first reading of inference-engine code: How does one request become a batch? Why are KV blocks paged? Why are prefill and decode scheduled differently? Where does cache reuse stop?

The main teaching content is in Chinese. This English discovery page provides a map for international readers and contributors; the interactive labs and source anchors are the recommended way to explore the guide.

IMPORTANT

This is an independent community learning project, not official documentation for GeeeekExplorer/nano-vllm. Browser labs and teaching traces are conceptual learning artifacts, not real GPU traces or benchmark measurements. Use the upstream source code and documented runtime experiments as the final authority.

A three-layer learning path

Layer	What you do	What you gain
Concept path	Change state in a browser lab and predict what happens next.	A visual mental model for an otherwise abstract mechanism.
Source path	Follow the source map and read the smallest relevant code region.	A concrete link from an idea to the upstream implementation.
Runtime path	Run the optional CUDA setup and examine a real execution environment.	Evidence that distinguishes system behavior from a teaching simulation.

Layer

What you do

What you gain

Concept path

Change state in a browser lab and predict what happens next.

A visual mental model for an otherwise abstract mechanism.

Source path

Follow the source map and read the smallest relevant code region.

A concrete link from an idea to the upstream implementation.

Runtime path

Run the optional CUDA setup and examine a real execution environment.

Evidence that distinguishes system behavior from a teaching simulation.

Mechanisms covered

Area	Questions you can investigate
Scheduler and batching	When can a request enter, leave, or share a batch?
PagedAttention and KV Cache	How do block allocation and cache layout change memory behavior?
Prefix Cache	What may be reused, and what conditions end reuse?
Prefill and decode	Why do prompt processing and token-by-token decoding have different bottlenecks?
Sampling and parallelism	How do candidate selection and distributed execution alter the serving path?
CUDA Graph and benchmarking	What is stable enough to capture, and what evidence is required for a performance claim?

Area

Questions you can investigate

Scheduler and batching

When can a request enter, leave, or share a batch?

PagedAttention and KV Cache

How do block allocation and cache layout change memory behavior?

Prefix Cache

What may be reused, and what conditions end reuse?

Prefill and decode

Why do prompt processing and token-by-token decoding have different bottlenecks?

Sampling and parallelism

How do candidate selection and distributed execution alter the serving path?

CUDA Graph and benchmarking

What is stable enough to capture, and what evidence is required for a performance claim?

nano-vLLM Interactive GuideLearn vLLM internals before you need a GPU