上游兼容性与源码锚点

本页说明 nano-vLLM Interactive Guide 的教学源码基线、可验证锚点与边界。它帮助读者区分“教程在解释什么”与“上游当前实现是什么”。

IMPORTANT

本教程是独立社区学习项目，并不自动跟随 GeeeekExplorer/nano-vllm 的每一次提交。互动实验与教学 Trace 是概念学习工件，不等同于真实 GPU trace、生产配置或 benchmark。若与上游代码冲突，请以上游主分支和可复现运行结果为准。

当前教学基线

项目	记录
上游仓库	GeeeekExplorer/nano-vllm
上游分支	main
已核验提交	bb823b3e06983d71485a8e1f23715ebd87d98ef8
该提交时间	2026-04-26 UTC
本次复核日期	2026-08-20
许可证	上游与本教程均采用 MIT 许可；请分别阅读各自的 LICENSE 文件。

教程章节与源码对应关系

教程主题	首选上游文件	读者应验证的状态变化	教学边界
请求入口与整体架构	llm.py、engine/llm_engine.py	generate 如何把请求交给引擎 step。	浏览器 trace 只展示教学顺序，不是 profiler 时间线。
Sequence 状态机	engine/sequence.py	prompt、输出 token 与缓存元数据如何随请求推进。	实验省略 tokenizer、错误恢复和并发细节。
Scheduler 与连续批处理	engine/scheduler.py	waiting/running 请求、Prefill/Decode 决策及 postprocess。	不把概念队列长度解释为生产吞吐或时延。
Paged KV Cache	engine/block_manager.py、engine/model_runner.py	block 分配、追加、引用计数和释放。	图中 block 数量为小规模教学参数，不代表实际显存容量。
Prefix Cache	engine/block_manager.py	block hashing、命中与可回收边界。	“命中”不等于端到端 latency 的固定百分比改善。
Prefill 与 Decode	engine/scheduler.py、engine/model_runner.py	输入准备在两阶段为何不同。	教程不推断任何硬件上的 token/s。
Attention 与缓存写入	layers/attention.py	attention kernel 的 KV 写入和读取位置。	可视化不替代 kernel profiler 或数值验证。
Sampling	sampling_params.py、layers/sampler.py	参数如何限制候选 token。	小样本分布用于解释，不是模型质量评估。
Tensor Parallel	layers/linear.py、layers/embed_head.py、models/qwen3.py	权重与张量如何按并行维度分片。	实验不等同于 NCCL 通信或多机性能测量。
CUDA Graph	engine/model_runner.py	stable shape、capture 与 replay 的控制边界。	任何性能结论都需要硬件、模型、版本和负载证据。

已知范围与复核规则

教程的 docs/reference/source-map.md 是快速导航页；本页是版本化的兼容性记录。两者应同步维护。当前基线包含 chunked prefill 相关重构后的上游实现；当上游修改 Scheduler、BlockManager、ModelRunner、Attention、Sampler 或并行层时，应重新复核受影响章节。

提交教程更新前，维护者应至少完成下列检查：确认上游文件路径仍存在；在相关章节更新源码链接；标明教学模型与真实运行环境的区别；如出现性能数字，记录硬件、模型、版本、工作负载和可复现命令。未复核的差异应保留为公开 Issue，而不应隐含为“教程已同步”。