# PR #31124 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[docs] Note the default dsa-topk-backend on all DSA-model cookbook pages
- 合并时间：2026-07-14 15:04
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/31124

---

## 执行摘要

PR #31124 为 6 个使用 DSA 稀疏注意力的模型 cookbook 页面（GLM-5/5.1/5.2、DeepSeek-V3.2/Math-V2、LongCat-2.0）添加了 `<Warning>` 组件，明确告知用户所有部署配方均基于默认 `--dsa-topk-backend sgl-kernel` 验证，其他 top-k 后端未完全验证，以提升文档透明度和用户决策质量。

## 功能与动机

PR body 指出：DSA 模型的 cookbook 部署面板生成的启动命令均使用默认 `sgl-kernel` 后端验证，但页面上未说明其他 top-k 后端（如 flashinfer、torch）可能未完全验证，用户可能误以为所有后端均等效。该 PR 通过添加警告消除了信息空白，防止用户在生产环境中盲目切换后端。

## 实现拆解

1. **确定影响范围**：对照 `server_args.py` 中 `--dsa-topk-backend` 默认值和 `dsa_backend.py` 的注意力后端注册表，筛选出 6 个使用 `dsa` 注意力后端且通过 `--dsa-topk-backend` 控制索引器 top-k 实现的模型页面。
2. **逐页插入警告**：在每个 cookbook 页面的部署面板组件（如 `<GLM52Deployment />`）之后立即插入 `<Warning>` 标签。警告内容统一为“所有配方运行在默认 `sgl-kernel` 上，其他 top-k 后端选择未在该模型上完全验证”。
3. **措辞迭代优化**：首个提交仅针对 GLM-5.2，随后扩展至全部 6 个页面。提交历史显示经历了三次措辞调整：最初提及具体替代后端（flashinfer、torch），后移除具体名称以免暗示支持，最后精简为当前简洁版本。
4. **验证构建**：通过 `mint validate` 确保文档无语法和组件引用错误。

### 以下为 GLM-5.2 页面添加的警告代码段，其他页面格式相同：

```markdown
<Deployment config={config} benchmarks={benchmarks} />

<Warning>
  All recipes here run the DSA indexer top-k on the default
  `--dsa-topk-backend sgl-kernel`. Other top-k backend choices have not
  been fully validated on GLM-5.2.
</Warning>

```

## 评论区精华

本 PR 无 Review 讨论。提交历史提供了措辞演变的完整记录：
- 初始提交明确提及“flashinfer、torch 等替代”，后在扩展时删除，避免暗示这些后端已被测试。
- 最终版本仅陈述验证事实，不评价其他后端状态，保持客观中立。

## 风险与影响

- **风险极低**：纯文档变更，无代码行为修改。唯一的风险是用户可能忽视警告，但文档本身已清晰列出约束。
- **影响正面**：提升文档透明度，帮助用户理解 DSA top-k 后端的验证范围，避免在未验证后端上出现非预期行为。

## 关联脉络

本 PR 与近期多个 DSA/GLM 相关 PR（如 #30992 增加 GLM-5.2 MTP index sharing 支持、#30839 修复 GLM-5.2 IndexShare 跨 PD 稳定性）共同构成了 DSA 注意力机制的稳定性加固。该文档改进是对内核功能完善的自然补充，确保用户了解已验证的配置边界。