夜雨聆风学习资料网

ARTICLE · 1372130

Nano-vLLM源码学习(3):模型骨架与核心算子

Nano-vLLM源码学习(3):模型骨架与核心算子

📑 目录

  • 1. 从 Qwen3 的一层说起
  • 2. RMSNorm:更省的归一化
  • 3. RoPE:旋转位置编码
  • 4. SwiGLU:SiluAndMul
  • 5. 并行 Linear 族与张量并行
  • 6. 词表并行 Embedding 与 LMHead
  • 7. Attention:写 KV 与两条路径
  • 8. Qwen3 的组装
  • 9. Sampler:从 logits 到 token
  • 总结
  • 参考资料

1. 从 Qwen3 的一层说起

执行层最终要跑的是 models/qwen3.py里的 Transformer。先看一个 Qwen3DecoderLayer的结构,它决定了各个算子的调用顺序。

Qwen3 用的是 Pre-Norm + 残差结构:归一化放在子层之前,残差直接跨过子层。nano-vllm 把残差相加放进了 norm 内部:

●●●PythonclassQwen3DecoderLayer(nn.Module):defforward(self, positions, hidden_states, residual):if residual isNone:                       # 第一层:残差从输入初始化            hidden_states, residual = self.input_layernorm(hidden_states), hidden_stateselse:                                       # 后续层:norm 同时吐出新残差            hidden_states, residual = self.input_layernorm(hidden_states, residual)        hidden_states = self.self_attn(positions, hidden_states)        hidden_states, residual = self.post_attention_layernorm(hidden_states, residual)        hidden_states = self.mlp(hidden_states)return hidden_states, residual

每一层做两件事:先归一化 + 注意力,再归一化 + MLP。残差 residual从第一层一路传到最后一层。RMSNorm可以接收上一层的残差,先把它加进来再归一化,同时返回相加后的新残差,所以 DecoderLayer里不用反复写 x = x + sublayer(norm(x))。下面把这一层用到的算子逐个展开。

2. RMSNorm:更省的归一化

LLM 普遍用 RMSNorm 替代 LayerNorm。它去掉了减均值和偏置,只按均方根缩放,计算更少,效果相当:

nano-vllm 的 RMSNorm有两个入口,都带 @torch.compile。普通归一化:

●●●Python@torch.compiledefrms_forward(self, x):    orig_dtype = x.dtype    x = x.float()                                  # 升到 fp32 求方差    var = x.pow(2).mean(dim=-1, keepdim=True)    x.mul_(torch.rsqrt(var + self.eps))return x.to(orig_dtype).mul_(self.weight)      # 先转回原精度,再乘 γ

带残差相加的版本,先在 fp32 里把残差加进来,相加结果转回原精度作为新残差,再对和做归一化:

●●●Python@torch.compiledefadd_rms_forward(self, x, residual):    orig_dtype = x.dtype    x = x.float().add_(residual.float())           # 残差相加    residual = x.to(orig_dtype)                    # 新残差 = 相加后的值    var = x.pow(2).mean(dim=-1, keepdim=True)    x.mul_(torch.rsqrt(var + self.eps))return x.to(orig_dtype).mul_(self.weight), residual

💡 提示:上一节 hidden_states, residual = self.input_layernorm(hidden_states, residual)调用的就是这个版本。残差相加和归一化写在同一个 torch.compile函数里,编译器可以把它们融合成更少的 kernel。求方差在 fp32 里做,是为了避免 bf16 下平方求和损失精度。

3. RoPE:旋转位置编码

RoPE(Rotary Position Embedding)不往输入里加位置向量,而是按位置把 Q、K 的每一对维度旋转一个角度,这样 Q 和 K 的点积只和两者的相对位置有关。频率表在初始化时预计算,cos 和 sin 拼成一个 buffer:

●●●Pythoninv_freq = 1.0 / (base ** (torch.arange(0, rotary_dim, 2).float() / rotary_dim))t = torch.arange(max_position_embeddings).float()freqs = torch.einsum("i,j->ij", t, inv_freq)            # [位置, rotary_dim/2]cache = torch.cat((freqs.cos(), freqs.sin()), dim=-1)   # [位置, rotary_dim]self.register_buffer("cos_sin_cache", cache.unsqueeze_(1), persistent=False)  # 中间补一维对齐头维

前向时把最后一维按前后两半拆成 ,第 维和第 维组成一对,做二维旋转:

●●●Python@torch.compiledefforward(self, positions, query, key):    cos, sin = self.cos_sin_cache[positions].chunk(2, dim=-1)  # 按位置查表    query = apply_rotary_emb(query, cos, sin)    # 内部 chunk 成两半、按上式旋转    key = apply_rotary_emb(key, cos, sin)return query, key

需要注意的几点:

  • 🔑 RoPE 只作用于 Q 和 K,不碰 V。位置信息只需要体现在注意力分数上,V 是被加权求和的内容。
  • 🔑 forward带了 @torch.compile。RoPE 是逐元素的小算子,编译后可以融合成少量 kernel,减少显存读写。nano-vllm 在 RMSNorm、RoPE、SiluAndMul 和 Sampler 这几个逐元素算子上都用了 torch.compile。
  • get_rope带 @lru_cache(1),参数相同时返回同一个对象,所以 28 层共享一份 cos_sin_cache,不会每层各存一张表。
  • 即使配置里有 rope_scaling,代码也只从中读取 rope_theta,没有实现 NTK / YaRN 等长度外推逻辑。

4. SwiGLU:SiluAndMul

Qwen3 的 FFN 用的是 SwiGLU 激活。它把输入投影成两份:一份当「门控」过 SiLU,一份当「数据」,两份再逐元素相乘:

nano-vllm 把它拆成两部分:投影由一个 MergedColumnParallelLinear一次算出 gate和 up两段(输出维是中间维的 2 倍),激活是一个很短的 SiluAndMul:

●●●PythonclassSiluAndMul(nn.Module):@torch.compiledefforward(self, x):        gate, up = x.chunk(2, dim=-1)      # 前一半是 gate,后一半是 upreturn F.silu(gate) * up

💡 提示:gate 和 up 合并成一个 Linear 再切,是因为一次大矩阵乘比两次小矩阵乘更能用满 GPU:输入 x只读一次,kernel 启动次数也减半。QKV 合并成 qkv_proj是同样的考虑。

5. 并行 Linear 族与张量并行

张量并行(Tensor Parallelism, TP)把一个大矩阵乘切到多张卡上并行算。nano-vllm 的 linear.py把这套机制封装成一组 Linear 子类,模型代码选对类型就具备 TP 能力。关键是分清沿哪个维度切。下图以 TP=2 为例,蓝色和黄色分别是 rank0 和 rank1 负责的分片,红色是唯一需要通信的 all_reduce:

  • ColumnParallelLinear(tp_dim=0):按输出维切分,每张卡算出一部分输出列。权重加载时用 narrow沿 dim 0 取本 rank 的分片;前向是普通 F.linear,不需要通信。
  • RowParallelLinear(tp_dim=1):按输入维切分,每张卡拿输入的一部分、算出部分和。所以 TP>1 时前向末尾要 dist.all_reduce(y)把各卡结果加起来;偏置只在 rank 0 加,避免被累加 tp_size 次。
  • QKVParallelLinear(ColumnParallel 的子类):把 Q、K、V 三个投影合并成一个大矩阵,输出维是 `(num_heads + 2 num_kv_heads) head_dim`。它的权重加载按字符串shard_id("q"/"k"/"v")定位各段的偏移。
  • MergedColumnParallelLinear(ColumnParallel 的子类):把 gate、up 合并(上一节的 SwiGLU 用它),权重加载按整数shard_id(0=gate、1=up)索引 output_sizes。

把它们按 Transformer 的数据流排开,Column 和 Row 正好成对出现:

位置
用什么
为什么
QKV 投影
QKVParallelLinear
(Column)
按头切分,每卡算自己负责的那些注意力头
Attention 输出投影 o_proj
RowParallelLinear
把各卡的头拼回来,需要 all_reduce
FFN 第一层 gate_up
MergedColumnParallelLinear
(Column)
按中间维切
FFN 第二层 down
RowParallelLinear
收回中间维,需要 all_reduce

📌 关键点:Column 切输出、Row 收输入,一前一后配对,中间的激活在卡内保持切分状态、不必通信,只在每个子层的末尾做一次 all_reduce。所以每个 Transformer 层恰好有 2 次 all_reduce(Attention 的 o_proj一次、FFN 的 down_proj一次)。这是 Megatron-LM 提出的 TP 切分方式,nano-vllm 的 linear.py用 156 行实现了它。

⚠️ 注意:QKV 按头切分,所以 Qwen3Attention断言注意力头数和 KV 头数都能被 tp_size 整除。Qwen3-0.6B 有 16 个 Q 头、8 个 KV 头,TP 度只能取 1、2、4、8。在 nano-vllm 里,KV 头数就是 GQA 模型 TP 度的上限(vLLM 会在 TP 度超过 KV 头数时复制 KV 头,nano-vllm 没有实现)。

6. 词表并行 Embedding 与 LMHead

Qwen3 的词表约 15 万行,Embedding 和 LMHead 的权重都很大,也要切。nano-vllm 把它们做成词表并行:每张卡只持有词表的一段。

VocabParallelEmbedding的 forward 要处理「某个 token 不属于本卡」的情况:

●●●Pythondefforward(self, x):ifself.tp_size > 1:        mask = (x >= self.vocab_start_idx) & (x < self.vocab_end_idx)  # 本卡负责的 token        x = mask * (x - self.vocab_start_idx)   # 平移到本地下标,越界的先置 0    y = F.embedding(x, self.weight)ifself.tp_size > 1:        y = mask.unsqueeze(1) * y               # 不属于本卡的行清零        dist.all_reduce(y)                      # 求和:每个 token 的向量只有一卡非零return y

每张卡都查一次表,但只有负责该 token 的卡查出非零向量,其余卡输出 0,all_reduce求和后就是完整结果。TP=1 时两段 if都跳过,退化成普通的 F.embedding。

ParallelLMHead是它的子类,负责把 hidden state 投影成词表 logits。两个细节:

●●●Pythondefforward(self, x):    context = get_context()if context.is_prefill:        last_indices = context.cu_seqlens_q[1:] - 1# 每条序列最后一个位置        x = x[last_indices].contiguous()               # 只取最后一个 token    logits = F.linear(x, self.weight)ifself.tp_size > 1:# 各卡算出词表的一段,gather 到 rank0 再拼接成完整 logits        all_logits = [...] ifself.tp_rank == 0elseNone        dist.gather(logits, all_logits, 0)        logits = torch.cat(all_logits, -1) ifself.tp_rank == 0elseNonereturn logits
  • 🔑 prefill 只取最后一个 token:生成下一个 token 只需要序列最后一个位置的 logits。`cu_seqlens_q[1:] - 1` 定位每条序列在拼接张量里的末位,避免把整段 prompt 都投影到词表维度。一条 1000 token 的 prompt,LMHead 只需投影 1 行,而不是 1000 行。
  • 🔑 LMHead 用 gather而非 all_reduce:词表按输出维切(每卡算不同的 logits 列),要的是拼接而不是求和,所以用 dist.gather收到 rank 0 再 cat,其他 rank 返回 None。Embedding 查表等价于 one-hot 向量乘权重矩阵,词表是这次乘法的输入维,所以用 all_reduce。切输入维就 reduce,切输出维就 gather,和第 5 节的 Column/Row 规律一致。

7. Attention:写 KV 与两条路径

attention.py做两件事:先把新算出的 K/V 写进 KV Cache,再做注意力计算。注意力计算在 prefill 和 decode 两个阶段调用的是不同的 FlashAttention 接口。

7.1 用 Triton 把 K/V 写进 Cache

每个 token 的 K/V 要存到 KV Cache 里对应的槽位(slot)。slot 编号由上层算好的 slot_mapping给出(见 3.6),这里只按编号写入。nano-vllm 用一个很短的 Triton kernel 完成:

●●●Python@triton.jitdefstore_kvcache_kernel(key_ptr, key_stride, value_ptr, value_stride,                         k_cache_ptr, v_cache_ptr, slot_mapping_ptr, D: tl.constexpr):    idx = tl.program_id(0)                 # 每个 program 处理一个 token    slot = tl.load(slot_mapping_ptr + idx)if slot == -1:                         # -1 表示这个 token 不需要写(padding)return# 用传入的 stride 定位第 idx 个 token 的 D 个元素,写到 cache 的 slot 行    key = tl.load(key_ptr + idx * key_stride + tl.arange(0, D))    value = tl.load(value_ptr + idx * value_stride + tl.arange(0, D))    cache_offsets = slot * D + tl.arange(0, D)    tl.store(k_cache_ptr + cache_offsets, key)    tl.store(v_cache_ptr + cache_offsets, value)

包装函数 store_kvcache从 key.shape取出 (N, num_heads, head_dim),令 `D = num_heads * head_dim。传进来的 key是 KV 头的张量,所以这里的 num_heads实际是本 rank 的 KV 头数,D就是一个 token 在一层里的 K(或 V)向量长度。key_stride/value_stride由外层用 key.stride(0)传入;包装函数还断言 key.stride(-1) == 1、key.stride(1) == head_dim、k_cache.stride(1) == D`,确保每个 token 的 D 个元素在内存里连续,kernel 才能一次读写一整段。

💡 提示:用 PyTorch 写同样的逻辑,大致是 `k_cache.view(-1, D)[slot_mapping] = key.view(N, D)。问题出在 slot == -1` 的位置:CUDA Graph 回放时 decode batch 会补齐到固定大小,补出来的 token 的 slot 是 -1(3.6 会讲),这些位置不能写。PyTorch 里要先用掩码筛掉它们,筛选结果的长度随数据变化,不适合放进 CUDA Graph。Triton kernel 每个 program 处理一个 token,遇到 -1 直接返回,张量形状始终固定,可以被 Graph 捕获。

7.2 两条路径:prefill 用 varlen,decode 用 with_kvcache

Attention.forward先调用 store_kvcache写缓存,然后按 context.is_prefill分流:

●●●Pythondefforward(self, q, k, v):    context = get_context()    k_cache, v_cache = self.k_cache, self.v_cacheif k_cache.numel() and v_cache.numel():    # cache 已分配才写store_kvcache(k, v, k_cache, v_cache, context.slot_mapping)if context.is_prefill:if context.block_tables isnotNone:   # 有历史 KV:改从整块 cache 读            k, v = k_cache, v_cache        o = flash_attn_varlen_func(            q, k, v,            cu_seqlens_q=context.cu_seqlens_q, cu_seqlens_k=context.cu_seqlens_k,            max_seqlen_q=context.max_seqlen_q, max_seqlen_k=context.max_seqlen_k,            softmax_scale=self.scale, causal=True,            block_table=context.block_tables)else:                                       # decode        o = flash_attn_with_kvcache(            q.unsqueeze(1), k_cache, v_cache,            cache_seqlens=context.context_lens, block_table=context.block_tables,            softmax_scale=self.scale, causal=True)return o

两条路径分别对应两个阶段的特点:

  • 🔑 prefill 用 flash_attn_varlen_func:一次要算整段 prompt 的注意力,多条序列变长地拼在一起,靠 cu_seqlens_q/cu_seqlens_k两组累积长度切分;causal=True保证每个位置只看前文。如果本步的部分 K/V 已经在 Cache 里,ModelRunner会传入 block_tables,这时 k, v换成整块 k_cache/v_cache,kernel 按 block_table去物理块里读完整的历史 K/V。有两种情况会触发:命中了前缀缓存,或者 chunked prefill 的后续块(前面的块上一步已经写进 Cache)。两种情况下 Q 都比 K 短,判断条件统一是 `cu_seqlens_k[-1] > cu_seqlens_q[-1]`。
  • 🔑 decode 用 flash_attn_with_kvcache:每条序列只新增一个 token(q.unsqueeze(1)补出长度维 1),K/V 全部来自 Cache,cache_seqlens告诉 kernel 每条序列当前多长,block_table告诉它去哪些物理块里读。
  • 缩放因子 `scale = head_dim -0.5`,即标准的 。

📌 关键点:「Prefill 算力密集、Decode 访存密集」在代码里体现为两个阶段调用不同的 FlashAttention 接口。KV Cache 的物理块怎么分、slot 怎么算留到 3.4 和 3.6,这里只需记住 Attention 既负责写 Cache,也负责读 Cache。

8. Qwen3 的组装

有了上面这些算子,models/qwen3.py按 Qwen3 的结构把它们拼起来。和 LLaMA 式实现相比,有两处不同。

① QKV 投影后对 Q、K 做 per-head RMSNorm。Qwen3 在每个注意力头的 Q、K 上各加了一个 RMSNorm(即 QK-Norm),用来稳定训练:

●●●Pythondefforward(self, positions, hidden_states):    qkv = self.qkv_proj(hidden_states)    q, k, v = qkv.split([self.q_size, self.kv_size, self.kv_size], dim=-1)    q = q.view(-1, self.num_heads, self.head_dim)     # reshape 成 [token, 头, head_dim]    k = k.view(-1, self.num_kv_heads, self.head_dim)    v = v.view(-1, self.num_kv_heads, self.head_dim)ifnotself.qkv_bias:                             # Qwen3 走这条分支        q = self.q_norm(q)                            # 在 head_dim 维上逐头归一化        k = self.k_norm(k)    q, k = self.rotary_emb(positions, q, k)           # 再加旋转位置    o = self.attn(q, k, v)returnself.o_proj(o.flatten(1, -1))              # 把头维摊平后投影回 hidden

🔑 核心概念:RMSNorm作用在最后一维 head_dim上,所以把张量 reshape 成 `[token, 头, head_dim]后直接送进去,就是逐头归一化。QK-Norm 只在 not self.qkv_bias时启用。qkv_bias取自 HF 配置的 attention_bias(缺省按 True处理),Qwen3 的配置里它是 false`,所以走 QK-Norm 分支;带 QKV bias 的 Qwen2 式结构则不做 QK-Norm。

② 权重映射 packed_modules_mapping。nano-vllm 把 q/k/v 合并成了 qkv_proj、gate/up 合并成了 gate_up_proj,而 HuggingFace 的 checkpoint 里它们是分开的五个权重。加载时 loader.py遍历 safetensors 里的权重名,按子串匹配这张映射表,把原始名字翻译成合并后的参数名和 shard_id:

●●●Pythonpacked_modules_mapping = {"q_proj":    ("qkv_proj", "q"),      # 字符串 shard_id"k_proj":    ("qkv_proj", "k"),"v_proj":    ("qkv_proj", "v"),"gate_proj": ("gate_up_proj", 0),    # 整数 shard_id"up_proj":   ("gate_up_proj", 1),}

第 5 节「QKV 用字符串 shard_id、Merged 用整数 shard_id」就来自这张表:两个类的 weight_loader分别处理表里的两种值类型。

此外还有两个工程细节:

  • tie_word_embeddings:Qwen3-0.6B 这类小模型的 Embedding 和 LMHead 共用同一张权重表。Qwen3ForCausalLM.__init__里执行 self.lm_head.weight.data = self.model.embed_tokens.weight.data,让两个参数指向同一块存储;之后加载 embed 权重,lm_head 自然也有了,只占一份显存。
  • compute_logits单独调用 LMHead:forward只算到 hidden state,logits 由 compute_logits单独计算。这样 CUDA Graph 只需要捕获到 hidden state 为止,LMHead 的「prefill 只取最后 token」逻辑和后面的采样都放在 Graph 之外。

9. Sampler:从 logits 到 token

rank 0 拿到 logits 后,Sampler按每条序列自己的温度采样出下一个 token。整个类只有一个带 @torch.compile的 forward:

●●●PythonclassSampler(nn.Module):@torch.compiledefforward(self, logits, temperatures):        logits = logits.float().div_(temperatures.unsqueeze(dim=1))  # 每行除以各自的温度        probs = torch.softmax(logits, dim=-1)        noise = torch.empty_like(probs).exponential_(1).clamp_min_(1e-10)  # E ~ Exp(1)return probs.div_(noise).argmax(dim=-1)                       # argmax(p / E)

最后一行没有调用 torch.multinomial,而是给每个概率除以一个独立的指数分布随机数,再取最大值。这是 Gumbel-max 技巧的等价写法,结论是:

简单的推导:的最大值对应的最小值,而服从参数为的指数分布。一组独立指数随机变量里,第个最先「到达」的概率是,正好是按概率抽样。

  • 🔑 效果和 multinomial一样,但都是逐元素运算加一次 argmax:除法、指数随机数、argmax 都能被 torch.compile融合,不需要 multinomial那样先做前缀和再二分查找。
  • 🔑 温度只缩放 logits:温度越高,softmax 越平,随机性越大。温度为 0 时第一行就会除以 0,这就是 SamplingParams在入口处断言 temperature > 1e-10的原因(见 3.2)。
  • 采样只在 rank 0 执行。ModelRunner.run里只有 rank 0 调用 prepare_sample和 sampler,其他 rank 的 compute_logits返回 None,run也返回 None。
  • nano-vllm 没有实现 top-k、top-p、重复惩罚等策略,SamplingParams也只有三个字段。

📝 总结

  • Qwen3DecoderLayer是 Pre-Norm + 残差结构,nano-vllm 把残差相加放进 RMSNorm,主干代码只传一个 residual。
  • RMSNorm 去掉减均值、只按均方根缩放,方差在 fp32 里算;RoPE 按前后两半配对旋转 Q/K,不碰 V,28 层共享一份 cos_sin_cache;SwiGLU 由 MergedColumnParallelLinear+ SiluAndMul实现。这些逐元素算子都用 @torch.compile融合。
  • 并行 Linear 族遵循「Column 切输出、Row 收输入」,每个 Transformer 层恰好 2 次 all_reduce(o_proj与 down_proj);TP 度必须能整除 Q 头数和 KV 头数。
  • 词表并行里,Embedding 用 all_reduce、LMHead 用 gather;LMHead 在 prefill 阶段只对每条序列最后一个 token 投影。
  • Attention 先用 Triton kernel 把 K/V 写进 Cache(跳过 slot = -1 的 padding),再按阶段分流:prefill 走 flash_attn_varlen_func,Cache 里已有历史 KV 时带上 block_table;decode 走 flash_attn_with_kvcache。
  • Qwen3 的特点是 per-head QK-Norm 与 packed_modules_mapping权重合并映射;tie_word_embeddings让 LMHead 与 Embedding 共享存储。
  • Sampler用 argmax(p / E)、E ~ Exp(1)实现按温度采样,等价于从 softmax(logits / T)中抽样,只在 rank 0 执行。

📚 参考资料

  • nano-vllm GitHub 仓库
  • Qwen3 Technical Report(Qwen Team, 2025)
  • Qwen3-0.6B 模型卡
  • RoFormer: Enhanced Transformer with Rotary Position Embedding(Su et al., 2021)
  • Root Mean Square Layer Normalization(Zhang & Sennrich, 2019)
  • GLU Variants Improve Transformer(Shazeer, 2020)
  • Megatron-LM: Training Multi-Billion Parameter Language Models Using Model Parallelism(Shoeybi et al., 2019)
  • FlashAttention: Fast and Memory-Efficient Exact Attention with IO-Awareness(Dao et al., 2022)
  • FlashAttention 接口文档(flash_attn_interface.py)
  • Triton 官方文档

📚 推荐阅读

AI Infra学习路线

AIInfraGuide : 开源全栈AI Infra 学习教程

推理优化系列:

AIInfra推理优化(1):LLM 推理基础

AIInfra推理优化(2):vLLM 快速入门

AIInfra推理优化(3):PagedAttention - 像操作系统管理内存一样管理 KV Cache

AIInfra推理优化(4):Continuous Batching - 让 GPU 不再空等的动态批处理

AIInfra推理优化(5):Prefix Cache 与 RadixAttention 复用共享前缀的 KV

AIInfra推理优化(6):Chunked Prefill 与统一 Token Budget 调度

AIInfra推理优化(7):Attention 后端与CUDA Graph

Nano-vLLM源码学习(1):项目全景与四层架构

Nano-vLLM源码学习(2):配置、入口与一次 generate 的全流程

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料