从零读懂 nano-vLLM

面向开发者与初学者的交互式源码教程

通过 13 个纯 HTML 互动实验 + 13 章中文教程 + 每章课后习题， 从一次 generate() 请求出发，逐步理解 nano-vLLM 的完整推理引擎。

🚀 开始学习 · 📖 查看源码地图 · 🔧 上游项目

English | 中文

---

🌟 项目亮点

🧪 13 个 HTML 互动实验 无需 GPU，直接在浏览器体验调度队列、KV Cache、采样概率等核心机制

📚 13 章源码级教程 从第一次 generate() 调用出发，逐步拆解 Scheduler、PagedAttention、CUDA Graph

🎯 即时反馈习题 每章配套选择题与动手任务，从”看懂”走到”能改”

🤖 自动部署 GitHub Actions 构建 + GitHub Pages 发布，提交代码即上线

---

📖 教程大纲

第一部分 · 建立全局认识

章节	标题	核心概念
00	学习路线与运行环境	概念轨 / 源码轨 / 运行轨
01	从 Prompt 到第一个 Token	generate() → step() → 五阶段流程
02	读懂整体架构	7 大模块数据流全景图
03	Sequence 状态机	WAITING / RUNNING / FINISHED 生命周期

第二部分 · 调度与内存

章节	标题	核心概念
04	Scheduler 与连续批处理	连续批处理 vs 静态批处理
05	分页 KV Cache	PagedAttention 块分配策略
06	Prefix Cache	前缀命中率与缓存失效边界
07	Prefill 与 Decode 分离	两阶段执行模型

第三部分 · GPU 执行与扩展

章节	标题	核心概念
08	Attention 与缓存写入	FlashAttention 融合内核
09	Sampling 采样	Greedy / Temperature / Top-K / Top-P
10	Tensor Parallel	矩阵切分与 All-Reduce 通信
11	CUDA Graph	捕获 Kernel 启动消除 CPU 开销
12	综合项目与 Benchmark	可验证的推理引擎改造

---

🚀 快速开始

方式一：互动实验（无需 GPU）

直接在浏览器体验 13 个交互式场景，理解调度、KV Cache、Prefix Cache 等核心概念。

👉 打开教程网站

方式二：源码阅读（需要 Python 环境）

# 1. 克隆仓库
git clone https://github.com/lora-sys/nano-vllm-interactive-guide.git
cd nano-vllm-interactive-guide

# 2. 安装依赖
npm install

# 3. 本地开发
npm run docs:dev

# 4. 质量检查
npm run check

方式三：真实运行（需要 CUDA 环境）

# 创建虚拟环境
python3.11 -m venv .venv
source .venv/bin/activate
pip install -U pip

# 安装 nano-vLLM
pip install git+https://github.com/GeeeekExplorer/nano-vllm.git

# 下载示例模型
pip install -U huggingface_hub
hf download Qwen/Qwen3-0.6B --local-dir ~/huggingface/Qwen3-0.6B

# 运行自检
python examples/check_runtime.py

---

📊 项目统计

指标	数据
📝 教程章节	13 章
🧪 互动实验	13 个
🎨 SVG 插图	13 张
💻 代码仓库	GeeeekExplorer/nano-vllm
📄 许可证	MIT
🏗️ 构建工具	VitePress v1.6
⚡ 框架	Vue 3.5 + Node.js 22

---

🎯 核心机制图解

graph LR
    A[Prompt] --> B[Tokenizer]
    B --> C[Sequence]
    C --> D[Scheduler]
    D --> E{Phase}
    E -->|Prefill| F[ModelRunner]
    E -->|Decode| F
    F --> G[Attention]
    G --> H[KV Cache]
    H --> I[Sampler]
    I --> J{Finished?}
    J -->|No| D
    J -->|Yes| K[Output]

    style A fill:#7c5cff
    style K fill:#40e0d0
    style H fill:#ffd166

Loading

---

📁 项目结构

nano-vllm-interactive-guide/
├── docs/
│   ├── guide/                 # 13 个教程章节
│   ├── public/
│   │   ├── labs/              # 13 个独立 HTML 互动实验
│   │   ├── illustrations/     # 13 张抽象 SVG 教学插图
│   │   └── favicon.svg
│   └── .vitepress/            # VitePress 配置
├── scripts/                   # 质量检查脚本
├── examples/                  # nano-vLLM 运行环境自检
├── .github/workflows/         # GitHub Actions 自动部署
├── package.json
└── README.md

---

🎨 为什么选择这个教程？

传统教程的痛点

• ❌ 直接从 scheduler.py 或 block_manager.py 开始，缺乏心智模型
• ❌ 需要 GPU 才能实践，门槛过高
• ❌ 代码片段过长，难以快速理解关键状态变化
• ❌ 抽象概念难以可视化

本教程的优势

• ✅ 先建立直觉：13 个纯 HTML 实验，不依赖 GPU
• ✅ 再读源码：每章都链接到具体文件，强调关键状态变化
• ✅ 即时验证：选择题 + 动手任务，学完就能用
• ✅ 分层学习：概念轨 / 源码轨 / 运行轨，适配不同硬件条件

---

🔧 内容更新原则

1. 先确认上游源码变化，再修改教程
2. 所有机制说明都链接到具体文件，不用模糊的”源码里”
3. 每个新章节必须包含 <HtmlLab> 与 <ExerciseCard>
4. 互动实验必须明确区分”概念模拟”和”真实模型执行”
5. 性能数字必须记录硬件、模型、版本与工作负载

Important

本教程是社区学习项目，不是 GeeeekExplorer/nano-vllm 的官方文档。上游项目持续变化，请以源码主分支为最终依据。

---

🤝 贡献与社区

欢迎加入我们的社区，分享学习心得、提问和贡献内容！

💬 社区渠道

• GitHub Discussions：加入讨论
  • 💡 Ideas - 新实验建议、改进建议
  • ❓ Q&A - 学习问题和概念澄清
  • 🎨 Show and Tell - 分享你的学习成果
  • 📢 Announcements - 公告和更新

🐛 贡献方式

• 📖 修正源码解释或文档错误
• 🐛 报告学习过程中的困惑点
• ✨ 提议新实验或改进现有实验
• 📊 分享可复现的 benchmark 结果
• 🔄 更新上游版本差异说明

👉 查看贡献指南 · 提交 Issue

---

📜 License

本项目代码与内容采用 MIT License。

上游 nano-vLLM 同样采用 MIT License，版权归原作者所有。

---

用互动实验读懂大模型推理引擎 ⚡

开始学习 · 源码地图 · GitHub

Made with ❤️ by lora-sys