# PR #22525 完整报告

- 仓库：`sgl-project/sglang`
- 标题：fix: EPLB dispatch OOB when shared experts fusion enabled under DeepEP
- 合并时间：2026-04-14 17:33
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/22525

---

# 执行摘要

修复了 DeepEP 后端下共享专家融合与 EPLB（专家位置负载均衡）同时启用时的索引越界问题。当两个功能同时启用时，MoE 层的 topk 后处理逻辑会将共享专家列错误地送入 EPLB 调度表，导致 CUDA 设备端断言错误。修复方案是在调度前分离共享专家列，仅对路由专家列进行重映射。该变更影响使用 DeepEP 后端且启用共享专家融合的场景，消除了崩溃风险，提升了系统稳定性。

# 功能与动机

根据 PR body 描述，问题出现在 DeepEP 后端同时启用两个特性时：
- `--enforce-shared-experts-fusion`：强制共享专家融合，将共享专家作为额外列附加到 topk_ids 中。
- `--init-expert-location`：初始化专家位置，启用 EPLB 调度。

`biased_grouped_topk_gpu` 会将共享专家列（值固定为 `n_routed_experts=256`）附加到 `topk_ids` 中。后续 EPLB 调度在 `_biased_grouped_topk_postprocess` 中使用 `topk_ids` 作为索引查询逻辑 - 物理调度表，但该表只有 256 个条目（索引 0-255），导致索引 256 越界，引发 CUDA 设备端断言错误。

# 实现拆解

修改文件：`python/sglang/srt/layers/moe/topk.py`

关键改动在 `_post_process_topk_ids` 函数中，新增条件分支处理共享专家融合与 EPLB 的冲突：

```python
if num_fused_shared_experts > 0 and is_deepep_class_backend():
    shared_cols = topk_ids[:, -num_fused_shared_experts:]
    routed_cols = topk_ids[:, :-num_fused_shared_experts]
    routed_cols = _biased_grouped_topk_postprocess(
        routed_cols, expert_location_dispatch_info, num_token_non_padded
    )
    topk_ids = torch.cat([routed_cols, shared_cols], dim=-1)
else:
    topk_ids = _biased_grouped_topk_postprocess(
        topk_ids, expert_location_dispatch_info, num_token_non_padded
    )
```

**逻辑解析**：
1. 当检测到共享专家融合且使用 DeepEP 后端时，将 `topk_ids` 分割为路由专家列和共享专家列。
2. 仅对路由专家列调用 `_biased_grouped_topk_postprocess` 进行 EPLB 调度重映射。
3. 将处理后的路由列与原始共享列重新拼接。
4. 其他情况（非 DeepEP 后端或无共享专家融合）走原有 else 分支。

# 评论区精华

review 中仅有一次实质性讨论：

> **gemini-code-assist[bot]**建议重构条件逻辑以提高可读性和减少代码重复，通过预先确定要处理的列来避免重复调用 `_biased_grouped_topk_postprocess`。

但作者未采纳该建议，最终代码保持了原有的 if/else 结构。ch-wan 直接批准了 PR，未提出进一步意见。

# 风险与影响

**风险**：
1. **回归风险**：修改了 MoE 层 topk 后处理的核心逻辑，可能影响所有使用 DeepEP 后端且启用共享专家融合的场景。
2. **性能风险**：新增了张量分割（`[:, -num_fused_shared_experts:]`）和拼接（`torch.cat`）操作，可能引入微小开销，但仅在特定条件（共享专家融合 +DeepEP）下触发。
3. **测试覆盖不足**：PR body 提到已测试 EP8 和 EP16，但未提供单元测试变更，依赖现有测试套件。

**影响**：
1. **对用户**：修复了 DeepEP 后端下共享专家融合与 EPLB 同时启用时的崩溃问题，使该配置可用。
2. **对系统**：消除了 CUDA 设备端断言错误，提升系统稳定性。
3. **对团队**：明确了共享专家融合与 EPLB 调度的交互边界，为后续类似功能开发提供参考。

# 关联脉络

从近期历史 PR 看，MoE 层持续优化是重点方向之一：
- **PR #22642**：优化 MoE 层 DP 注意力通信，将两阶段通信合并为 reduce_scatterv，提升吞吐量 7.7%。同属 MoE 层性能改进，但侧重通信模式而非调度逻辑。
- **PR #21259**：为 HiCache 添加 Mooncake 存储后端支持，兼容 DSA 和 Mamba 混合模型。同属 DeepEP 相关功能，可能涉及后端兼容性处理。

本 PR 揭示了 MoE 层中功能组合的边界问题：当多个优化特性（共享专家融合、EPLB 调度）叠加时，可能产生未预期的交互冲突。这种问题在复杂系统中具有典型性，值得后续开发中注意类似场景。