nano-vLLM 源码地图

本页对应上游 GeeeekExplorer/nano-vllm 主分支的核心结构。教程调研快照日期为 2026-08-02；上游持续演进，请始终查看最新源码。

nanovllm/
├── config.py                   # 运行参数与 Hugging Face 配置
├── llm.py                      # 公开 LLM 类型
├── sampling_params.py          # temperature / max_tokens / ignore_eos
├── engine/
│   ├── llm_engine.py           # 请求入口、主循环、多 GPU worker 启动
│   ├── scheduler.py            # waiting/running、Prefill/Decode 决策
│   ├── sequence.py             # 请求状态与 token/cache 元数据
│   ├── block_manager.py        # KV blocks、引用计数、Prefix Cache
│   └── model_runner.py         # GPU 输入、KV Cache、CUDA Graph、执行
├── layers/
│   ├── attention.py            # FlashAttention 与 Triton KV 写入
│   ├── linear.py               # Tensor Parallel 线性层
│   ├── embed_head.py           # 词表并行 Embedding / LM Head
│   ├── rotary_embedding.py     # RoPE
│   ├── layernorm.py            # RMSNorm
│   ├── activation.py           # SiLU-and-Mul
│   └── sampler.py              # temperature + 随机采样
├── models/
│   └── qwen3.py                # Qwen3 Transformer 组装
└── utils/
    ├── context.py              # 当前 Prefill/Decode 元数据上下文
    └── loader.py               # safetensors 权重加载与分片

按问题找文件

你想回答的问题	首先打开
API 怎样进入引擎？	llm.py → llm_engine.py
为什么某个请求没被执行？	scheduler.py
KV 显存为何不足？	block_manager.py、model_runner.py
前缀缓存为何没命中？	block_manager.py
token 写到哪个缓存位置？	model_runner.py、attention.py
多 GPU 如何切权重？	linear.py、embed_head.py、qwen3.py
Graph 模式为何报动态 shape？	model_runner.py
输出为什么更随机？	sampling_params.py、sampler.py

一次 step 的调用链

LLMEngine.step
  ├─ Scheduler.schedule
  │   ├─ BlockManager.can_allocate / allocate
  │   └─ BlockManager.can_append / may_append
  ├─ ModelRunner.call("run", seqs, is_prefill)
  │   ├─ prepare_prefill 或 prepare_decode
  │   ├─ Qwen3ForCausalLM.forward
  │   └─ Sampler.forward
  └─ Scheduler.postprocess
      ├─ hash_blocks
      ├─ append_token
      └─ finished → deallocate