# PR #30374 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[AMD] Fix DeepSeekV4 server cutlass error
- 合并时间：2026-07-08 05:43
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/30374

---

# 执行摘要

- 一句话：修复 AMD/ROCm 上 DSV4 启动时 cutlass 导入错误
- 推荐动作：建议精读，这是一个典型的跨平台兼容性修复案例，展示了如何在不影响主流程的前提下处理平台依赖的导入。关注 `__init__.py` 中的条件导入模式和 `dsa_indexer.py` 中的断言使用。

# 功能与动机

PR #25220 在 `sglang.jit_kernel.dsa` 包中引入了 `cutedsl_paged_mqa_logits` 模块的顶级导入，该模块依赖 NVIDIA-only cutlass 包。在 AMD/ROCm 环境中，由于缺少 cutlass 库，导入失败，导致 DSV4 模型注册时服务器无法启动，即使实际上不会使用 CuTeDSL 后端。

# 实现拆解

1. **在 `dsa_indexer.py` 中将 `pick_dsl_expand` 导入移至运行时条件检查**：在模块级别添加 `if not _is_hip: ... else: pick_dsl_expand = None` 分支，确保 AMD/ROCm 上不触发 cutlass 导入，同时保留 NVIDIA 的 eager 导入行为。
2. **在 `__init__.py` 中为 `CuteDSLPagedMQALogitsRunner` 添加类似保护**：使用 `if not is_hip(): from .cutedsl_paged_mqa_logits import ...` 避免在 AMD/ROCm 上加载 cutlass 依赖。
3. **在 `pick_dsl_expand` 使用点添加断言**：在 `_get_topk_paged` 方法中，当条件分支实际需要 `pick_dsl_expand` 时，增加 `assert pick_dsl_expand is not None, "Not supported on AMD/ROCm. "`，为未来误用提供明确的错误信息。

关键文件：
- `python/sglang/srt/layers/attention/dsa/dsa_indexer.py`（模块 注意力层；类别 source；类型 dependency-wiring）: 入口文件，包含条件导入和调用点的断言，是修复的核心。
- `python/sglang/jit_kernel/dsa/__init__.py`（模块 JIT 内核；类别 source；类型 dependency-wiring）: 包入口，对 CuteDSLPagedMQALogitsRunner 添加了条件导入保护。

关键符号：未识别

## 关键源码片段

### `python/sglang/srt/layers/attention/dsa/dsa_indexer.py`

入口文件，包含条件导入和调用点的断言，是修复的核心。

```python
# 文件 : python/sglang/srt/layers/attention/dsa/dsa_indexer.py
# ... 其他导入 ...

_is_hip = is_hip()

if not _is_hip:
    # Preserve the original eager import behavior on non-ROCm platforms.
    from sglang.jit_kernel.dsa import pick_dsl_expand
else:
    # 在 AMD/ROCm 上显式赋值为 None，避免静态分析警告
    pick_dsl_expand = None

# ... 后续代码 ...

# 在调用点（_get_topk_paged 方法中）
if use_cute_dsl \
    and forward_batch.forward_mode.is_target_verify() \
    and next_n >= 2:
    # 在 AMD/ROCm 上不应该进入此分支，如果进入则断言失败
    assert pick_dsl_expand is not None, "Not supported on AMD/ROCm. "
    dsl_expand_factor, dsl_atom = pick_dsl_expand(...)

```

### `python/sglang/jit_kernel/dsa/__init__.py`

包入口，对 CuteDSLPagedMQALogitsRunner 添加了条件导入保护。

```python
# 文件 : python/sglang/jit_kernel/dsa/__init__.py
from sglang.srt.utils import is_hip

from .paged_mqa_logits import (
    aiter_paged_mqa_logits,
    cutedsl_paged_mqa_logits,
    deepgemm_paged_mqa_logits_native,
    deepgemm_paged_mqa_logits_split,
)

if not is_hip():
    # 只在非 HIP 平台导入 CuTeDSL 相关符号，避免缺失 cutlass 报错
    from .cutedsl_paged_mqa_logits import CuteDSLPagedMQALogitsRunner, pick_dsl_expand

```

# 评论区精华

主要讨论围绕静态分析警告展开：gemini-code-assist[bot] 指出，当 `_is_hip` 为 True 时，`pick_dsl_expand` 在模块作用域中完全未定义，静态分析工具（如 Pyright、mypy）会标记为未定义名称。建议在 AMD/ROCm 上将 `pick_dsl_expand` 赋值为 `None`。kkHuang-amd 要求修复此问题，At1a8 已采纳建议并修复，在 else 分支中显式设置了 `pick_dsl_expand = None`。

- 静态分析警告：pick_dsl_expand 在 AMD/ROCm 上未定义 (style): At1a8 采纳建议，在 else 分支中添加了 `pick_dsl_expand = None`。

# 风险与影响

- 风险：变更仅影响导入路径，逻辑行为不变，风险低。主要风险在于：如果未来有人误在 AMD/ROCm 上调用 `pick_dsl_expand`，断言会触发，但提供了清晰错误信息。无运行时性能影响。
- 影响：直接影响：修复了 AMD/ROCm 上 DeepSeek-V4 服务器因 cutlass 缺失而无法启动的问题。间接影响：保持了 NVIDIA/CuTeDSL 路径的 eager 导入行为不变。对性能无显著影响。团队需确保未来引入新的 cutlass 依赖时遵循此条件导入模式。
- 风险标记：暂无

# 关联脉络

- PR #25220 引入 CuTeDSL MQA logits 模块的顶级导入 : 本 PR 正是为修复 #25220 引入的导入在 AMD/ROCm 上导致的启动失败。