执行摘要
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 通过添加警告消除了信息空白，防止用户在生产环境中盲目切换后端。
实现拆解
- 确定影响范围：对照
server_args.py 中 --dsa-topk-backend 默认值和 dsa_backend.py 的注意力后端注册表，筛选出 6 个使用 dsa 注意力后端且通过 --dsa-topk-backend 控制索引器 top-k 实现的模型页面。
- 逐页插入警告：在每个 cookbook 页面的部署面板组件（如
<GLM52Deployment />）之后立即插入 <Warning> 标签。警告内容统一为“所有配方运行在默认 sgl-kernel 上，其他 top-k 后端选择未在该模型上完全验证”。
- 措辞迭代优化：首个提交仅针对 GLM-5.2，随后扩展至全部 6 个页面。提交历史显示经历了三次措辞调整：最初提及具体替代后端（flashinfer、torch），后移除具体名称以免暗示支持，最后精简为当前简洁版本。
- 验证构建：通过
mint validate 确保文档无语法和组件引用错误。
以下为 GLM-5.2 页面添加的警告代码段，其他页面格式相同：
<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 注意力机制的稳定性加固。该文档改进是对内核功能完善的自然补充，确保用户了解已验证的配置边界。
参与讨论