LLM Systems Course: nano-vLLM

这是一个从最小推理引擎走向真实 vLLM 和 MetaX C500 工程实践的教学仓库。

第一次进入仓库，先记住这些入口：

• docs/learning-path.md：先学什么、做到什么程度、下一步去哪。
• python scripts/course.py list：查看可运行的作业、实验和项目命令。
• homework/01_hello_vllm/：第一课 MetaX/vLLM 环境与基线任务。
• homework/02_nanovllm_engine/：第二课 nano-vLLM 引擎实现与实验任务。
• docs/nanovllm-source-reading.md：nano-vLLM 源码阅读笔记教程，按请求、调度、KV Cache、模型执行主线阅读。
• homework/03_operator_adaptation/：第三课沐曦 MACA/TileLang 算子开发任务。
• homework/04_inference_optimization/：第四课 PageAttention、vLLM 投机解码与性能优化任务。

环境准备

make setup                         # 安装课程包及开发/测试依赖

MetaX C500 环境测试：

make env-c500

课程结构

课程主线按 H01 → H04 顺序进行

准备环境与公共检查
        |
        v
H01  Hello vLLM
     MetaX / vLLM 环境采集、Qwen3-0.6B 离线推理与单卡基线
        |
        v
H02  nano-vLLM Engine
     Sequence、KV block、Scheduler、LLMEngine step（实现位于 src/nanovllm/）
        |
        v
H03  Operator Adaptation
     TileLang 算子、原生 MACA 算子及 nano-vLLM DSL backend 集成
        |
        v
H04  Inference Optimization
     PageAttention/GQA CPU 与 kernel 正确性、普通解码与投机解码速度体验

H01–H04 的任务入口统一位于 homework/。推荐顺序、各阶段出口条件和环境要求见 docs/learning-path.md。

目录结构

.
├── homework/                              # 四份课程实践，按 H01 → H04 学习
│   ├── 01_hello_vllm/                     # H01：MetaX/vLLM 环境与单卡基线
│   │   ├── run.py                          # 环境采集、推理、基线和验收入口
│   │   ├── check.py / test_check.py        # 结果验收及 checker 单测
│   │   └── prompts.json                   # 固定输入
│   ├── 02_nanovllm_engine/                 # H02：nano-vLLM Engine 实现
│   │   ├── 01_block_manager/              # KV block 练习
│   │   ├── 02_scheduler/                  # Scheduler 练习
│   │   ├── 03_llm_engine_step/            # Engine step 练习
│   │   ├── engine_labs.py                 # 三个练习的统一入口
│   │   └── run.py / check.py              # 推理实验和验收入口
│   ├── 03_operator_adaptation/             # H03：MACA / TileLang 算子开发
│   │   ├── intro_ops/                     # 算子源码、CMake 构建和测试
│   │   │   ├── ops/                       # vector_add 与融合算子实现
│   │   │   ├── python/                    # operator_runtime Python 接口
│   │   │   └── tests/                     # 算子正确性和 backend 测试
│   │   ├── run.py                         # assignment / maca / integration 入口
│   │   └── maca_gate.py                   # MACA 结果验收
│   └── 04_inference_optimization/          # H04：PageAttention + 投机解码
│       ├── page_attention/                # PageAttention reference、TileLang kernel、vLLM backend
│       │   ├── page_attention/            # reference 和 kernel Python 实现
│       │   ├── vllm_integration/          # GQA、metadata 和 backend 接入
│       │   ├── tests/                     # CPU、kernel 和 vLLM smoke 测试
│       │   └── bench.py / project_gate.py  # 性能测量和可选 gate
│       ├── vllm_speculative/              # draft-model 普通/投机速度体验
│       │   ├── experience.py               # 一条命令自动完成两种服务测速
│       │   ├── server.py / client.py      # 服务启动和 SSE 请求客户端
│       │   ├── benchmark.py                # 性能指标采集
│       │   ├── verify_identical.py         # 维护者可选的一致性回归校验
│       │   └── run_matrix.sh               # 维护者旧版矩阵回归入口
│       ├── cpu_labs.py                    # H04 CPU 练习入口
│       └── run.py                         # H04 全流程入口
├── src/nanovllm/                           # H02 使用的小型公共推理引擎
│   ├── engine/                             # Engine、Scheduler、KV block 和 ModelRunner
│   ├── layers/                             # Attention、Linear、Norm、Sampler 等层
│   ├── models/                             # Qwen3 模型实现
│   └── utils/                              # 上下文和权重加载工具
├── tests/                                  # 与具体作业无关的公共回归测试
├── scripts/                                # course CLI、环境探针、公共测试和清理工具
├── examples/                               # 最小推理示例
├── docs/                                   # 安装、学习路线、源码阅读和环境说明
├── Makefile                                # setup、test、环境检查和常用快捷命令
├── pyproject.toml                          # Python 包及基础/dev 依赖定义
├── run.sh                                  # nano-vLLM 命令行运行入口
└── README.md                               # 仓库总览

运行入口

完整安装、H01–H04 顺序和通用验收命令统一见 docs/getting-started.md。课程路线和前置知识见 docs/learning-path.md 与 docs/prerequisites.md。

MetaX/C500 环境检查使用 make env-c500；CPU、kernel 和 PageAttention smoke 命令见 homework/04_inference_optimization/page_attention/README.md。