vLLM-MetaX MoE Triton 配置调优 —— 参赛文件包

参赛者：LindseyMei 目标仓库：MetaX-MACA/vLLM-metax（GitLink 主仓：metax-maca/vLLM-metax）贡献内容：为 MetaX C500（MXC500）补充 3 组缺失的 fused-MoE Triton tuned 配置 PR：MetaX-MACA/vLLM-metax#313 GPU：MetaX C500（sGPU 切片：16GB VRAM / 25% 算力）+ MACA 3.3.0.15 包生成/更新日期：2026-07-02

一句话概述

本文件包记录为 vLLM-MetaX（沐曦 MACA 后端） 做的 MoE（Mixture-of-Experts）Triton 内核配置调优 贡献：在真机 MetaX C500 上定位到 3 个热门 MoE 模型在 MXC500 上无 tuned 配置、回退默认 tile 的性能缺口，通过直接调优 MACA 实际运行的 vllm_metax fused-MoE 内核，给出针对性的两段式 Triton 配置，实现 kernel 级 1.17–2.20x 提速，并通过正确性与加载验证。

提交材料

贡献	PR	状态
MoE Triton 配置调优（3 个 MXC500 缺口 shape）	MetaX-MACA/vLLM-metax#313	OPEN（等待 review / merge）

1. 问题（真实缺口）

vllm_metax 的 fused-MoE 走 Triton 内核，其 tile 配置按 (H, E, N, device_name[, dtype]) 从 vllm_metax/model_executor/layers/fused_moe/configs/ 加载 tuned JSON；未命中则回退到通用 get_default_config，并打印 Using default MoE config. Performance might be sub-optimal!。

实测缺口：以下 3 个常见 MoE shape 在 MXC500 上没有对应的 tuned 配置文件：

Shape (H, E, N)	top_k	代表模型	架构
(2048, 60, 1408)	4	`Qwen/Qwen1.5-MoE-A2.7B`	`Qwen2MoeForCausalLM`
(2048, 64, 1408)	6	`deepseek-ai/DeepSeek-V2-Lite`	`DeepseekV2ForCausalLM`
(2048, 128, 768)	8	`Qwen/Qwen3-30B-A3B`	`Qwen3MoeForCausalLM`

2. 方法（调优的是真正的 MACA 内核）

关键点：上游 benchmarks/kernels/benchmark_moe.py 导入的是上游 fused_experts，而 MACA 运行时用的是 vllm_metax 自己的 fused_experts（经 OOT 注册，二者是不同对象，已核实）。因此上游 tuner 调的是错误的内核。

本方案自建微基准（moe_tuning/tools/moe_tune.py）直接调优 MACA 内核：

用 vllm.model_executor.layers.fused_moe.override_config 强制指定 tile，计时单次 vllm_metax ... fused_experts()（随机权重，因此无需下载模型）；
CUDA event + torch.cuda.synchronize()，warmup + 多次取中位数；
网格搜索 BLOCK_SIZE_M/N/K、GROUP_SIZE_M、num_warps、num_stages；
将胜出的扁平配置包装成 MetaX 两段式 schema（stage1/stage2 + ACCF32/SPLIT_K/pipeline/scenario），对称填充（低风险起点）。

正确性验证：moe_tuning/tools/moe_verify.py 使用 torch.allclose(rtol=2e-2, atol=2e-2) 比较「默认 tile」与「调优 tile」的 MoE 输出，并调用 get_moe_configs() 确认配置文件会被运行时正确加载。

3. 结果（kernel 级，真机 sGPU 切片）

Qwen1.5-MoE-A2.7B（H=2048, E=60, N=1408, top_k=4）

M	默认 (ms)	调优后 (ms)	加速
64	1.154	0.915	1.26x
256	1.291	1.025	1.26x
1024	2.340	1.567	1.49x
2048	4.559	2.589	1.76x

DeepSeek-V2-Lite（H=2048, E=64, N=1408, top_k=6）

M	默认 (ms)	调优后 (ms)	加速
128	1.260	1.046	1.21x
512	1.642	1.311	1.25x
1024	3.163	1.720	1.84x
2048	6.793	3.081	2.20x

Qwen3-30B-A3B（H=2048, E=128, N=768, top_k=8）

M	默认 (ms)	调优后 (ms)	加速
256	1.505	1.189	1.27x
1024	2.650	1.850	1.43x
2048	4.424	2.755	1.61x

小 M（decode）保留默认 tile 或近似配置，避免延迟回退；大 M（prefill / 大 batch）获得显著加速。

原始数据：moe_tuning/results/moe_tune_result.json。

4. 正确性与加载验证

正确性：同输入下「默认 tile」与「调优 tile」的 MoE 输出 max|Δ|≈1e-3，torch.allclose(rtol/atol=2e-2)=True —— 调优只改 tile 选择，不改数学。
加载：对 3 个 shape 分别调用 get_moe_configs(E, N, None, 0, 0, H) 均能命中本配置（device_name=MXC500），返回全部 10 个 M-条目 → 运行时会被正确采用。

验证命令：

source /data/workspace/vLLM-metax-Project/env_vllm.sh
cp moe_tuning/tools/moe_verify.py /tmp/ && cd /tmp && python3 /tmp/moe_verify.py

5. 重要说明（诚实边界）

本次调优/验证在 C500 sGPU 切片（16GB/25% 算力） 上完成。tile 形状（BLOCK_SIZE/warps/stages）是每-SM 特性，预期可迁移到整卡 C500；grid 级参数（GROUP_SIZE_M=1, SPLIT_K=1）取值保守。整卡 C500 上的最优性未验证，欢迎维护者在整卡上复跑 moe_tuning/tools/moe_tune.py 复核。
因 16GB 限制，完整的 28GB Qwen1.5-MoE bf16 等模型无法做整模型 E2E；本贡献采用 kernel 级基准（与上游 benchmark_moe.py 同类证据，是 MoE 配置 PR 的标准依据）。
PR 仅新增 3 个 JSON 配置文件，无代码改动，风险极低。

6. 目录结构

vLLM-metax-Contributions/
├── README.md                 # 本文件
├── LINKS.md                  # PR / issue 链接汇总
├── docs/
│   └── PROGRESS_vLLM_metax.md   # 路线 A 全栈安装 + 恢复文档
└── moe_tuning/               # 主贡献：MoE Triton 配置调优
    ├── README.md
    ├── configs/
    │   ├── H=2048,E=60,N=1408,device_name=MXC500.json   # Qwen1.5-MoE
    │   ├── H=2048,E=64,N=1408,device_name=MXC500.json   # DeepSeek-V2-Lite
    │   └── H=2048,E=128,N=768,device_name=MXC500.json   # Qwen3-30B-A3B
    ├── tools/
    │   ├── moe_tune.py       # MACA 内核微基准调优器
    │   └── moe_verify.py     # 正确性 + 配置加载验证
    └── results/
        └── moe_tune_result.json  # 原始调优数据

7. 复现

source /data/workspace/vLLM-metax-Project/env_vllm.sh

# 调优（无需下载模型，随机权重）；注意从不含 vllm/ 子目录的 cwd 运行
cp moe_tuning/tools/moe_tune.py /tmp/ && cd /tmp
python3 /tmp/moe_tune.py --H 2048 --E 60 --N 1408 --top-k 4 --Ms 1 8 16 32 64 128 256 512 1024 2048

# 正确性 + 加载验证
cp moe_tuning/tools/moe_verify.py /tmp/ && python3 /tmp/moe_verify.py

# 部署到插件：把 configs/*.json 复制到
#   vllm_metax/model_executor/layers/fused_moe/configs/
# 或者用 VLLM_TUNED_CONFIG_FOLDER 覆盖测试

8. 后续可扩展方向

在整卡 C500 上复跑 moe_tuning/tools/moe_tune.py 复核 tile。
补全更多 MoE 配置缺口（如 DeepSeek-V2 / Qwen3-235B-A22B 的量化 shape）。
在验证过程中发现并修复 metax 后端的真实 bug。