document multi-step scheduler diagnostics

worklogs/decode_analysis_report_2026-07-14.md

@@ -297,3 +297,137 @@ GPU 利用率和功耗都偏低。虽然瞬时 GPU-Util 能到 100%，但平均
 4. 若没有提升，进入 qwen3_moe / fused_moe / attention 的代码级 profiling
 
 本轮最重要的事实是：GPU 平均利用率只有约 `29%`，所以先不要把问题简单归因为“卡算不动”。更像是当前 decode 执行路径没有把四张卡持续喂满。
+
+## 七、调度方向验证实验：multi-step decode
+
+追加日期：2026-07-14
+
+### 目标
+
+验证 `--num-scheduler-steps 4` 是否能作为 decode 吞吐提升方向。
+
+由于上一轮实验显示并发升高没有带来 aggregate TPS 增益，且平均 GPU 利用率只有约 `29%`，multi-step scheduling 是最直接的调度侧候选优化：它理论上可以减少每 token 调度往返和 Python/worker 协调开销，让 decode 连续执行多个 step。
+
+### 实验 1：关闭 chunked prefill，直接启用 multi-step
+
+启动变体：
+
+- `--num-scheduler-steps 4`
+- 不加 `--enable-chunked-prefill`
+- `--max-model-len 100000`
+- `--max-num-batched-tokens 8192`
+- 其它参数沿用完整 parser 服务配置
+
+结果：
+
+- 服务未启动。
+- 远端日志：`/root/work/logs/server_exp_sched4_nochunk_fullparser.log`
+- 本地归档：`worklogs/remote_results/2026-07-14-scheduler/server_exp_sched4_nochunk_fullparser.log`
+
+失败原因：
+
+```text
+ValueError: max_num_batched_tokens (8192) is smaller than max_model_len (100000).
+```
+
+解释：
+
+关闭 chunked prefill 后，vLLM 要求 `max_num_batched_tokens >= max_model_len`，否则实际最大可处理序列会被 `max_num_batched_tokens` 限制。这个配置不能用于官方长上下文，也无法进入 decode 压测。
+
+### 实验 2：decode-only 诊断配置
+
+为绕过实验 1 的限制，临时降低上下文长度，只用于短 prompt decode 诊断。
+
+启动变体：
+
+- `--max-model-len 4096`
+- `--max-seq-len-to-capture 4096`
+- `--max-num-batched-tokens 8192`
+- `--num-scheduler-steps 4`
+- 不加 `--enable-chunked-prefill`
+- attention backend 仍为自动选择
+
+结果：
+
+- 服务未启动。
+- 远端日志：`/root/work/logs/server_exp_sched4_nochunk_len4096_fullparser.log`
+- 本地归档：`worklogs/remote_results/2026-07-14-scheduler/server_exp_sched4_nochunk_len4096_fullparser.log`
+
+关键日志：
+
+```text
+Using XFormers backend.
+ValueError: Multi-Step not supported for attention backend: xformers.
+Set VLLM_ATTENTION_BACKEND to a value from ['flash-attn', 'rocm-flash-attn', 'flashinfer'].
+```
+
+解释：
+
+这说明当前环境不是“chunked prefill 与 multi-step 的组合不支持”这么简单，而是 `xformers` attention backend 本身不支持 multi-step worker。只要 attention backend 仍然落到 xFormers，multi-step 调度就无法启用。
+
+### 实验 3：强制 FlashInfer backend
+
+启动变体：
+
+- 环境变量：`VLLM_ATTENTION_BACKEND=FLASHINFER`
+- `--max-model-len 4096`
+- `--num-scheduler-steps 4`
+- 不加 `--enable-chunked-prefill`
+- 其它参数同实验 2
+
+结果：
+
+- 服务未启动。
+- 远端日志：`/root/work/logs/server_exp_sched4_nochunk_len4096_flashinfer.log`
+- 本地归档：`worklogs/remote_results/2026-07-14-scheduler/server_exp_sched4_nochunk_len4096_flashinfer.log`
+
+关键日志：
+
+```text
+TypeError: 'NoneType' object is not callable
+...
+self._decode_wrapper = BatchDecodeWithPagedKVCacheWrapper(...)
+```
+
+解释：
+
+`vllm/attention/backends/flashinfer.py` 会导入：
+
+- `flashinfer.BatchDecodeWithPagedKVCacheWrapper`
+- `flashinfer.decode.CUDAGraphBatchDecodeWithPagedKVCacheWrapper`
+- `flashinfer.prefill.BatchPrefillWithPagedKVCacheWrapper`
+- `ixformer.contrib.vllm_flash_attn.flash_attn_varlen_func`
+
+当前环境中至少有关键 FlashInfer wrapper 没导入成功，导致 wrapper 为 `None`，在 profiling 阶段调用时报错。
+
+### 实验结论
+
+本轮没有进入 c1/c2/c4 decode 曲线压测，因为 multi-step 服务在启动阶段就失败。
+
+结论不是“调度一定无效”，而是：
+
+1. 当前 xFormers backend 下，multi-step 调度不可用。
+2. 当前 FlashInfer backend 依赖不完整或与 CoreX 环境不兼容，不能直接替代 xFormers。
+3. 自动 FlashAttention 也不可用；此前日志已显示 `vllm_flash_attn` 包缺失，因此自动回落到 xFormers。
+
+因此，调度优化如果要继续推进，前置任务是 attention backend 适配：
+
+- 路线 A：补齐/修复 CoreX 环境里的 FlashAttention 或 FlashInfer backend。
+- 路线 B：改造 xFormers backend 或 MultiStepModelRunner，使其支持当前 xFormers 路径。
+- 路线 C：绕过 multi-step，直接 profile xFormers decode、paged attention、MoE 与 TP 通信开销。
+
+### 对下一步方向的影响
+
+短期内，继续调 `--num-scheduler-steps` 没意义；它被 backend 卡住了。
+
+下一步建议改为两条线并行：
+
+1. **backend 可用性线**
+   - 检查 `flashinfer` 和 `ixformer.contrib.vllm_flash_attn` 在服务器上的实际导入错误。
+   - 确认官方镜像/包中是否本应包含 `vllm_flash_attn`。
+   - 如果能补齐依赖，再重跑 multi-step decode 曲线。
+
+2. **代码 profiling 线**
+   - 直接在当前可用 xFormers 路径插桩。
+   - 重点记录每 token decode 中 attention、MoE、sampler、TP 同步的耗时。
+   - 当前平均 GPU 利用率低，profiling 比继续盲调参数更有价值。