vllm-xtu-moe

⚠️ 命名变更(2026-10-07,用户定案):本文件里出现的旧环境变量名已修改为下面的规范名 —— XIAOTU_MOE_W4A8 已修改为 XIAOTU_MOE_INT8(int8 激活路径总开关,默认由权重格式决定); XIAOTU_MOE_INT8_ALIGN 已修改为 XIAOTU_MOE_INT8_ALIGN(实现选择:ALIGN tile,默认档); XIAOTU_MOE_INT8_VNNI 已修改为 XIAOTU_MOE_INT8_VNNI(实现选择:旧 VNNI tile,默认 0); XIAOTU_MOE_I8_MIN_M 已修改为 XIAOTU_MOE_INT8_VNNI_MIN_TOKENS(⭐ M 阈值,默认 160,唯一设定处)。 旧名仍被识别:会告警一次并映射到新名(仍按旧值生效),绝不静默退回 fp32 ✓

XTU = X Transformers Unity(读音:汉语「小兔」)—— 一个高性能 MoE 推理加速层。

这是一个面向超大 MoE 模型的 vLLM 插件,核心思路是把计算拆开:

• GPU 负责注意力、KV cache、embedding 等非专家部分;
• CPU 负责专家权重与专家计算;
• 对长 prompt,还会把一部分专家计算流式搬到 GPU。

也就是说:在**"显存放不下专家权重"的情况下,仍然让大 MoE 模型跑起来, 而且尽量不改主线 vLLM**。

项目重点

• DeepSeek / GLM / MiMo 这类超大 MoE
• CPU + GPU 混合推理 · 低显存需求
• 高性能长上下文推理
• 兼容主线 vLLM,不需要 fork
• 主要面向大模型部署与工程优化

English · 中文(默认)

📌 当前版本：v0.2.7（2026-10-09） 主题：优化引擎，削减 CPU→GPU DMA 缓冲区，节省 11 GB 显存（总），性能无损失 ⭐ 微 ping/pong（XIAOTU_GPF_STAGE_TILE_E=96）：GPU 预填的 preflight staging 7.56 → 1.89 GiB/rank（省 5.67 GiB/rank）， 长 prompt TTFT −16.8%（同会话交错 A/B ×3 轮，两臂离散各 0.4%，输出 md5 逐位一致）✓ 口径：本模型官方量化 · TP=2 · MBT=8192 · MAXSEQS=2 · MAXLEN=524288 · 长 prompt ≈32K 字符 · 仅覆盖预填阶段（短请求走 CPU 预填，不受影响） ⚠️ 本版不宣称解码提升 —— 2026-10-08 那条"解码 +2.5~8%"已于 2026-10-09 更正并撤回 ✗；⚠️ 长稳（数小时级）未验 ✗ 发行说明：RELEASE_NOTES_v0.2.7.md 工作报告：docs/WORK_REPORT_2026-10-09.md

⚠️ 请勿开启 LMCache(已知恶性问题)

本项目已默认关闭 LMCache(LMCACHE=0,且不启动 lmcache_server)。原因:

• 🔴 长 prompt 会让整个引擎崩掉:一次大请求即可触发 KV connector reported block-level load failures (invalid_block_ids) ⇒ EngineDeadError ⇒ 所有会话一起断(我们实测:同一 78 万 token 请求,开 LMCache 两次都崩; 关掉后 20 万 token 请求 200 通过、GPU 预填从 0 次恢复到 686 次)。
• 🔴 与输出退化(重复、意图漂移、写错路径)高度相关,且与上游多条未修完的 issue 吻合。
• ✅ 关掉还有额外收益:GPU 省 0.85 GiB、宿主省 ~65 GiB RSS,且 GPU 预填恢复工作。

完整证据、上游 issue 清单、关闭/回滚方法见 docs/KNOWN_ISSUES_LMCACHE.md。 在上游修复前,请勿在生产启用 —— 下文凡提到 LMCache 的段落均仅作历史记录。

项目特色

1. 任意 MoE 模型:不绑死某一代架构。已跑通 DeepSeek-V4 / V4.1 系列、 GLM-5.3-Flash(含 A100 / SM80 的注意力后端)与 MiMo-V2.5。 MiMo-V2.6-Flash-RL 也已在 A100/SM80 上跑通:骨架 / 1M 上下文 / 真权重长文本端到端均已实测通过 多模态——图片 ✅（渲染 ZQ7K42 读对）、视频 ✅（红方块「出现又消失」，连时序都对）、音频 ✅（3 声提示音被正确描述为 "three short, high-pitched electronic beeps"）、组合（图 + 5,444 token 长文本 + MTP k=1）✅；音频需启动前装好 vllm[audio]+av+torchaudio（见 MODEL_GUIDES §0.1c），且数字计数类探针在合成音上不可靠（域限制）。它走的是与 V4.1 相同的 MXFP4 引擎路径，体积 161 GiB —— 见 docs/MODEL_GUIDES.md §3b 与 docs/EXPERIMENTS.md B92–B133。
2. 任意 x86 指令集:scalar → AVX2 → AVX-512(base/VNNI/BF16/VBMI), 运行时按 /proc/cpuinfo 自动选最高可用变体。
3. 显存优先级固定不变:KV 池 → GPU 预填充 staging → 投机解码 draft → 激活工作区(∝ MBT); 任何新功能都不得把这条顺序往后挤。

   2026-09-20 修订:①去掉"专家层常驻" —— 实测效果很差(每层 3.36 GiB, 换来的收益抵不上它对 32K 预填充的挤压,用户裁定不再列为优先级); ②补上"激活工作区" —— 它正比于 chunk(=MBT),是之前连续两次长 prompt OOM 的真凶, 却一直没被列进优先级。

4. 单服务器多 NUMA 节点也只占用一份内存:每个 NUMA 节点只存取本地内存, 在最大化性能的同时节省了内存占用。

实测平台

下文所有性能数字都在这台机器上取得:

性能

• 口径：聚合吞吐——prefill (tok/s) = 并发数 × prompt_tokens / TTFT、decode (tok/s) = 并发数 × 1000 / median(ITL)

  decode 取 median ITL(相邻 token 间隔中位数)而不是 median TPOT:median TPOT 是每请求平均,会把同一 step 里混进来的 prefill 工作算进解码时间,导致长上下文 C=2 时被严重低估(实测同一批数据:median TPOT 口径下 MiMo 长 C=2 = 9.8,而 median ITL 口径 = 39.6,真实争用只有 1.36×;GLM 更极端:2.9 vs 29.6)。详见 docs/EXPERIMENTS.md B126。 ⚠️ 勘误（2026-10-08，用户指出）：1/median(ITL) 不是速度 ✗ —— 速度的定义是 个数 ÷ 时间；而 median(1/x) != 1/median(x) ⇒ 中位间隔的倒数不等于速率。 本表该列只能当【典型 token 间隔】的延迟指标看，不能当吞吐 ✓。 ⭐ 真实 decode 吞吐 = (输出 token 数 - 1) / (末 token 时刻 - 首 token 时刻) ✓。均由同一次 vllm bench serve 换算； decode 取 median ITL（mean 会被极少数离群步拉高,median TPOT 会被混入的 prefill 拉低）。 ℹ️ decode 与 C 的关系:真实解码争用很小(倍率 1.13–1.77×,按 median ITL);早期表里曾出现「长 C=2 的 decode 明显低于 C=1」,那是 median TPOT 被混入的 prefill 步污染所致,另一部分来自把 --max-num-seqs 设成 1 导致 C=2 退化为串行。两者均已修正,判据见 docs/EXPERIMENTS.md B124/B126。

• 数据集：random 随机 token，--random-input-len 固定为短 128 / 长 16384，输出 128；前缀缓存开；每格 8 个请求、每格不同 seed。
• 表中「实际 token」= total_input_tokens / completed（含 chat template 的少量开销）。 配置细节、判据与 MBT 取舍见 docs/TUNING_GUIDE.md §8 与 docs/EXPERIMENTS.md。

⚠️ v0.2.7 行的 decode 比上一行低,是【数据集 × 投机】造成的,不是退化 ✗ —— 随机 token 下投机解码几乎不被接受,开投机反而更慢 ⇒ 本表 decode 不代表真实文本会话的水平 ✓。 本表的用途是同一口径内横向比较(并发 / 长度)✓; ⭐ 两行配置不同(投机开/关),不构成同口径对比 ⇒ 故此处不写提升百分比 ✓

⭐ 长 prompt 的 prefill 是硬天花板:三个并发档位均为 ~1005 tok/s(差 <0.7%)⇒ 加并发不提高预填吞吐,只把 TTFT 从 16.2 s 拉到 28.4 / 48.4 s ✓ (机理:预填受 PCIe 权重流式限制 —— 每层约 3.84 GB,实测 H2D 24.6 GB/s ≈ 链路 25.0)

GLM / DeepSeek-V4.1 未开投机解码（random 数据集对投机是最坏情况，且会挤占长上下文的显存）；MiMo-V2.6 开了 MTP k=1。MiMo 的 prefill 数字是 GPU 预填开启后的口径（VLLM_XIAOTU_GPU_PREFILL_MIN_TOKENS=4096；该变量不设或为 0 表示关闭，会让 prefill 掉到 ~310，见 docs/MODEL_GUIDES.md §0.1）。

⚠️ 口径提醒(2026-10-04 更正):上表"长 C=2 的 decode 9.8"用的是 median TPOT,它把预填步也算进分母 ⇒ 只要混进几个 chunk 就被严重污染 ✗;干净口径应看 median ITL,真实解码争用只有 1.13–1.77×(判据 B126)。同族的 MiMo 203.6 ms / GLM 700.8 ms 同理作废。 ⚠️ 单引擎混跑"长预填 + 解码"会饿死解码(实测,B277/B279):正在解码的请求,其 ITL 下界 = 相邻两次解码步之间排入的预填量 ÷ 预填吞吐。实测注入一个 32768-token 的 prompt 后,该解码请求的 ITL 从 中位 64.8 ms 暴涨到 ~8.4 s,并持续整个 57.6 s 预填窗口(它是每步只拿到 1 个 token,而每步被一个 MBT 大小的预填 chunk 撑满)。

• 压小 chunk(--long-prefill-token-threshold)会同时毁掉预填效率(每个 chunk 都要重新流式过 40 层权重:2048-token chunk 仅 ~410 tok/s,8192 的 ~1000)⇒ 净效果更差(解码吞吐 1.25 → 0.57 tok/s)⇒ 没有可用的调度旋钮 ✗
• 单流交付(1M × seqs=1 的口径):--max-num-seqs 1 ⇒ 请求串行、不存在混跑 ⇒ 单流 ITL 稳定在 ~65 ms ✓
  ⚠️ 这只是档位之一 —— 按场景选 1M×1 / 512K×2 / 256K×4,以及生产在用的 512K×4(高天花板 + 短任务多路;⚠️ 满载只有 ≈2 路满长,其余排队、不报错)。判据:seqs × maxlen ≤ 池容量 ⇒ 满载,超过 ⇒ 只排队不报错(⚠️ 是饱和阈值,不是硬不变量),见 docs/MODEL_GUIDES.md §0.1b ✓
• 多用户并发:应做 prefill/decode 分离(PD disaggregation),而不是调 max-num-seqs / max-num-batched-tokens / long-prefill-token-threshold ✓
• 根因:预填吞吐受 DMA/装配限制(每个 chunk、每卡、每层都要重流约 3.84 GB 权重;设备侧的 strided 转置实测仅 84 GB/s,而连续布局可达 1361 GB/s;装配步骤占 250 ms/层 = 85%,而该层的 MoE 计算只要 5–50 ms)⇒ 提高预填吞吐要靠消除 strided 转置 / 融合装配,不是调度 ✓ ⚠️ "--max-num-seqs 必须 ≥2"只对【基准口径】成立:早期用 seqs=1 跑 C=2 会串行、把短 C=2 的聚合 prefill 压到 54(那是配置问题,不是模型问题,判据 B124)⇒ 做并发基准时 seqs≥2;做单流交付时 seqs=1 才是对的 ✓

持久化输入缓存(LMCache,SSD)

🔴 【不推荐 / 已知恶性问题】本节仅作历史记录 —— 见上文警示与 docs/KNOWN_ISSUES_LMCACHE.md: LMCache 会导致长 prompt 崩溃与输出退化;本项目已默认 LMCACHE=0。 下列数字是当时测得的能力,不代表现在推荐这样部署。

服务重启后仍能复用巨大重复前缀(不再重新 prefill):

CHUNK_SIZE=256 bash scripts/serve_lmcache.sh &        # L1=内存 + L2=SSD
LMCACHE=1 PYTORCH_CUDA_ALLOC_CONF=expandable_segments:False bash scripts/serve_v41.sh

实测(V4.1-Flash,10K 前缀):冷 26.7 s ⇒ 重启后 1.27 s;连 LMCache 服务端也重启仍 1.27 s (⇒ 从 L2 磁盘命中 ✓)。三条前置条件与 V4.1 的必要补丁见 docs/MODEL_GUIDES.md §5 ✓。

性能观测:通过 DeepSeek Harness 进行本项目开发的典型性能统计

⭐ 本项目的开发方式是"自举(bootstrapping)"的:agent 自身充当开发者,而被开发的这个引擎 正是它的推理后端 —— 即每一次推进、每一次回归、每一轮 A/B 测量,都由被改造的引擎自己服务。 这同时验证了引擎在真实在线负载下的稳定性:v0.2.6 会话期间,该服务连续运行 16 小时以上无故障 ✓

agent 侧性能统计(该次会话;后端 = DeepSeek-V4.1-Flash,TP=2): 18 轮 / 718 步 · Token 232,529,485(agent 侧缓存命中 99.7%)· 输出 474,129 tok 模型用时 282 分 30 秒 · 工具调用用时 506 分 52 秒(合计 ≈ 13.2 h)· TTFT 6.6 s · 39 tok/s

⭐ 同口径序列（真实负载；取自 dsh 会话统计面板的输出速度）：

	输出速度	TTFT
0.2.6 历史基线（两例，投机开，真实会话）	38 ~ 40（38、39）	6.6 s / 9 s
0.2.7（本版配置，投机开）	41	9.3 s

=> ⛔ 更正（2026-10-09，用户）：这【不构成提升】 —— 41 是会话内速度衰减之后的读数；用户观察到的原话是 "当会话走到现在（都没多长）我就看到了生成速度掉到了41，果然没提高" ⇒ decode 侧目前没有可信的提升证据，38~40 与 41 不应被当作"旧 → 新"的对比 ✓ ⚠️ 另有一个【聚合吞吐】口径（全部输出 token ÷ 解码墙钟）：本次为 38 ~ 71 tok/s（见上表末列）。 ⭐ 该口径下暂不写百分比 —— 因为旧表没有这一列，我尚未用同一口径跑过 0.2.6 配置； 补测该基线后再定（这是本版发布后第一件要做的事）✓

• 同口径 A/B（同硬件 · 同 harness · 相邻时间 · 唯一变量 = MBT；decode 用仓库口径 c x 1000 / median(ITL)）

  c	L	0.2.6 decode	0.2.7 decode	decode 变化	prefill 变化	TTFT 变化
  1	128	16.3	15.3	-6.0%	+10.7%	-9.7%
  2	128	21.1	22.3	+5.8%	+0.5%	-0.5%
  4	128	25.6	26.2	+2.5%	-4.4%	-1.9%
  1	16384	13.3	13.2	-0.9%	+22.2%	-18.2%
  2	16384	20.2	19.4	-4.0%	+21.0%	-5.6%
  4	16384	28.4	27.9	-1.9%	+17.1%	-8.6%
  => 结论:预填长 prompt +1722%(稳)、解码在本口径下持平(-6%+6%)
  => ⛔ decode 目前【没有可信的提升证据】（2026-10-09 用户更正：41 是会话内衰减之后的读数，不是"新版更高"）✓
  => **另有【聚合吞吐】口径(总 token / 解码墙钟)为 38~71 tok/s,但实测 run-to-run 不复现(71.6 重测变 37.9)
  => 该列不作发布数字

⚠️ 另外：上方合成基准表的旧行是投机【关】的 vllm bench 数据，与上表的 38~40 无关 ✗； 它与本版的合成行（投机开）配置不同 => 不构成同口径对比；其中 c=4 两档是新增信息（旧表没有该档）✓ ⚠️ prefill 是【恢复到 MBT=8192 水平】，不是新提升 ✓ ⚠️ 这是真实会话口径，与下方合成基准表是两个不同口径，不可互相推算 ✓

上图是本项目自建监控栈在一次典型开发会话中的读数(面板来自 vLLM + LMCache 业务指标与主机 NUMA/GPU/CPU 指标)。该次会话中:前缀命中率(vLLM) 97.1%、LMCache 命中率 97.0%、 投机解码接受率 51.0%、KV 使用率 15.1%、TTFT p50 ≈ 14 s(p99 ≈ 1.33 min,长预填阶段)。

复现这张图:见 docs/MODEL_GUIDES.md §5(启动监控栈与看板的完整步骤)。 图中涉及的 LMCache 修复对应上游 PR LMCache#5268(尚未合并 ⇒ 当前需本地补丁 ✓)。

快速开始

# 1) 主线 vLLM(本插件是插件,不需要 fork)
pip install vllm==2.5.0

# 2) 本插件(发行名 vllm-xtu-moe,**不发 PyPI**;二选一)
# (a) 从 GitHub Release 附件装:wheel 里已含 6 个 ISA 变体,无需本地编译器
pip install ./vllm_xtu_moe-0.2.3-cp312-cp312-manylinux_2_34_x86_64.whl
# (b) 源码安装(需要本地编译器):
# CXX=g++-16 PYTHON=$(which python) bash scripts/build_engine_variants.sh && pip install -e .

# 3) 跑一个专家权重放不进显存的 MoE 模型
VLLM_EXPERTS_LOAD_DEVICE=cpu \
vllm serve <MODEL_DIR> --tensor-parallel-size 2 --enable-expert-parallel \
  --max-model-len 65536 --max-num-batched-tokens 8192 --gpu-memory-utilization 0.95

逐模型配方、显存核算、自检与排错 → docs/RUNBOOK.md、 docs/MODEL_GUIDES.md。

版本变更(简)

改动清单、性能对照与运行参数变更: v0.2.6 · v0.2.5 · v0.2.4 · v0.2.3 · v0.2.2 · v0.2.1 · v0.2 · v0.1.0 (归档:v0.2pre)

文档

面向使用者 —— docs/

面向开发者 —— 架构与主线集成、GPU 预填充实现、上游漂移、调优记录与全部内部报告, 属于内部开发文档,不随本仓库发布(只保留在本地工作副本里)。

关于作者

独立研究者。曾担任一台 10 PFLOP/s(双精度)超级计算机的主要设计师和运营者,此前长期从事高性能计算方向的工作。

这正是本项目关注点的来源:NUMA 拓扑与内存布局、带宽受限内核、主机侧数据搬运 —— 也正是"把巨型 MoE 模型放到常规服务器上跑"这件事今天真正的战场。

致谢

本项目受到 KTransformers 和 Lvllm 项目启发,尤其是计算引擎 xiaotu-moe 深度借鉴了 lk-moe 思路, xiaotu-moe 全部代码均为独立编写,特此致谢。

• KTransformers —— https://github.com/kvcache-ai/ktransformers
• Lvllm(及其 CPU MoE 引擎 lk-moe;本项目对照的 lk_moe 2.4.2 即来自此仓库)—— https://github.com/guqiong96/Lvllmds4-x
• 同时感谢 vLLM(https://github.com/vllm-project/vllm)提供的插件式扩展点,使本项目无需 fork 即可接入。

许可

Apache-2.0。第三方组件与致谢清单见 THIRD_PARTY_NOTICES.md 与 NOTICE。