nano-vllm-omni 自学手册：26 道一小时练习吃透 vLLM-Omni

October 22, 2026

读大型推理框架的源码，最难的往往不是看懂某一个函数，而是理解多个进程、线程和事件循环之间怎么配合。为了真正吃透 vLLM-Omni，我把它拆成了 26 道“一小时能写完”的核心实现题，配上验收测试、带注释的参考解和交互式提示，整理成一本自学手册。

手册分三部分

Part I 刷题（约 25 小时）：26 道题，每题一小时，目标是把一个核心机制写对。题目覆盖 Qwen-Omni 的模型实现，以及多阶段推理服务的前端、调度、数据面和启动流程。
Part II 大作业（约 8–10 周）：把 Part I 写出的零件组装成一个跑在单张 RTX 5090 上的 nano-vllm-omni。按 M0–M11 的里程碑推进，从金标准对拍、按 stage 加载权重，一直到 async_chunk 流式流水线、OpenAI 兼容服务和 CUDA graph 优化。
Part III 参考：vLLM-Omni 并发设计的深度解读。每处讲解都标注了对应 commit 下的 path:line，可以直接在本地 checkout 里打开源码对照。

三部分互相对应：Part I 的题对应 Part II 的里程碑，也对应 Part III 的章节。比如 orchestrator 的两道题（P02 / P03）对应里程碑 M6 / M8 和 Part III 第 6 节。

Track M · Qwen-Omni 模型实现（8 题）：RMSNorm 与多模态 RoPE、QK-norm + GQA + KV cache、Sparse MoE、DeepStack 多模态拼接、Talker MTP（一帧预测 15 个残差 codebook）、Code2Wav 流式因果卷积，最后串成 tiny thinker 的 KV-cache 解码。
Track A · 前端与 Orchestrator（5 题）：线性多 stage 路由、async_chunk 预热与终态守门、线程 → asyncio 的批量唤醒、两阶段 abort、共享通道上的 RPC 关联。
Track B · Stage 进程与调度（6 题）：EngineCore busy loop、continuous batching + chunked prefill + 抢占、paged KV + 前缀缓存、批不变的采样器、paged decode attention。
Track C · 数据面（2 题）：跨进程共享内存 connector、后台收发线程与顺序 / 清理语义。
Track D · 模型胶水（3 题）：Thinker → Talker 输入构造、codec 窗口规划、MRoPE 三维位置。
Track E · 启动与 GPU（2 题）：设备分组与并行初始化、CUDA graph bucket runner。

所有测试都在 CPU 上运行，不需要 GPU。Track M 的测试用 HF transformers 4.57.1 的 Qwen3-Omni 实现（tiny 随机权重）作为对拍的标准答案，几秒钟就能跑完。

读题 5 分钟：列出能想到的边界情况。
限时 45 分钟实现：写在 mine/<文件>.py 里，骨架已经给好。
15 分钟跑测试、修 bug：./check.sh m01。
卡住 15 分钟以上再看提示：交互式提示分 L1 → L2 → L3 三级，剧透程度逐级增加。每页还有可以一步步播放的状态图，以及题面中 ?? 处的答案。
做完再看参考解：solutions/ 里有完整的中文注释，容易写错的地方都用“易错：”标了出来。

Track A / B / C / E 的题本质上都是并发程序设计。手册里总结了一份写 asyncio / 多线程程序时按顺序走的清单：

T（Topology，执行拓扑）：先确定代码跑在哪些进程、线程和事件循环里，边界在哪里。
SBWC（State、Blocking、Workers、Channels）：再搭骨架：共享状态由谁写、会在哪里阻塞、需要哪些各司其职的 worker、它们之间用什么通道传消息。
LIFE（Lifecycle、Interface、Flow + invariants、Edges + errors）：最后让程序活起来：怎么启动和干净地停止、对外接口怎么保持精简、哪些不变量必须始终成立、迟到 / 乱序 / 重复的消息和异常怎么处理。

三条贯穿始终的法则：await 就是交出控制权；跨线程只能走专门的桥（call_soon_threadsafe）；能用“队列 + 单写者”就别用锁。