vllm 学习笔记

Appearance

混合专家模型，通过路由机制在每次 forward 仅激活部分专家网络，以较低计算成本实现超大参数量。

为什么需要 Mixture of Experts ​

模型容量（参数量）与性能正相关，但全量激活的计算成本随参数线性增长。MoE 将模型中的 FFN 层替换为多个并行的专家网络（Expert），每个 token 仅由路由器（Router/Gate）选出的 1-2 个专家处理。以 DeepSeek-V3 为例，总参数 671B 但每个 token 仅激活 37B，计算成本与 37B 稠密模型相当。

核心原理 ​

  • Router/Gate：线性层将 hidden state 映射为专家分数，取 Top-K 选择活跃专家。
  • Expert 网络：每个专家是一个独立的 FFN（或更复杂的网络），各自持有独立权重。
  • 负载均衡：为防止路由坍缩（多数 token 走同一专家），通常加入 auxiliary loss 鼓励均匀分布。
  • Expert Parallelism：专家按数量均匀分配到多个 GPU，每个 GPU 处理被路由到本地专家的 token。

在源码中的实现 ​

v0.23 对 Fused MoE 层做了控制反转重构（commit dc68bd8c4），FusedMoE 从单一 nn.Module 拆为三个可插拔组件：

  • vllm/model_executor/layers/fused_moe/layer.py — 薄协调层（FusedMoE），组合下面三件套。
  • vllm/model_executor/layers/fused_moe/router/ — FusedMoERouter，专家路由（grouped-topk、bias-topk 等变体，经 router_factory 创建）。
  • vllm/model_executor/layers/fused_moe/routed_experts.py — RoutedExperts，持有专家权重并委托 FusedMoEMethodBase.apply() 执行。
  • vllm/model_executor/layers/fused_moe/runner/ — MoERunner（实现 MoERunnerInterface 抽象契约），统一 forward / 共享专家 / 量化方法接口。
  • vllm/model_executor/layers/fused_moe/experts/ — 按后端拆分的实现（triton_moe.py、cutlass_moe.py、flashinfer_b12x_moe.py、fused_humming_moe.py、marlin_moe.py、rocm_aiter_moe.py、trtllm_nvfp4_moe.py、xpu_moe.py、cpu_moe.py 等）。其中 fused_humming_moe.py 是 Red Hat Humming 后端（16 种 W×A 组合），现已标准化为继承 FusedMoEExpertsModular 的一等后端，经 oracle 按 QuantKey 协商（详见 topics/model-layers/）；cpu_moe.py 现含 CPUExpertsInt8（INT8 W8A8 经 Intel VNNI 预打包）。
  • vllm/model_executor/layers/fused_moe/hpc_moe.py — 包装 Tencent HPC-Ops 库的融合 MoE kernel（SM90+，仅 FP8），经 --moe-backend hpc 启用（位于包顶层而非 experts/ 下）。
  • vllm/model_executor/layers/fused_moe/oracle/ — Oracle 框架统一后端选择，以 MoEKernelOracle 抽象基类（oracle/base.py）标准化六项契约（backend_enum_cls / get_priority_backends / backend_to_kernel_cls / map_backend / select_backend / make_kernel），按精度类型分散为 oracle/{fp8,int8,int_wna16,mxfp4,mxfp8,nvfp4,unquantized,w4a8,w4a8_int8}.py（commit 84b2a8a7e）。
  • vllm/model_executor/layers/fused_moe/runner/shared_experts.py — 共享专家融合（FSE）：把共享专家权重并入分组 GEMM（或独立 CUDA 流重叠），一次发射同时产出 routed + shared 专家输出。
  • vllm/distributed/eplb/ — EPLB（专家级负载均衡）；异步 EPLB 在 v0.23 已成为默认（commit 4aaba00f9），新增基于 NIXL 的零拷贝通信器 NixlEplbCommunicator，并支持 DeepSeek V4 的 Mega MoE。负载记录现对 padding token 做掩码（每 ubatch 一次 num_unpadded_tokens 张量，CUDA graph 安全），避免空 token 被路由后虚高 expert load；EPLB 也扩展到推测解码的草稿模型。
  • vllm/distributed/ — Expert Parallelism 的通信原语（All-to-All、NIXL EP、DeepEP V2），见 device_communicators/all2all.py 等。
  • vllm/distributed/elastic_ep/ — Elastic EP 的分阶段生命周期管理。

相关概念 ​

反向链接

出链