sskj/envs/SM120_DSV4_DEPLOYMENT_GUIDE.md

# SM120 (RTX 6000D) 部署 DeepSeek-V4-Flash 问题总结

## 环境信息

- **GPU**: NVIDIA RTX 6000D (SM120, 48GB x 8)
- **模型**: DeepSeek-V4-Flash (FP8 量化)
- **模型路径**: `/data/hf_models/DeepSeek-V4-Flash`
- **sglang 版本**: 0.5.15
- **vllm 版本**: 0.11.0+cu128 (with SM120 patches)
- **flashinfer**: 0.6.14
- **torch**: 2.8.0+cu128

---

## 问题概述

sglang 和 vllm 在 SM120 上部署 DSV4 时，都遇到了**算子不支持**的问题。根本原因是：

1. **flashinfer** 的某些算子尚未支持 SM120
2. **sgl_kernel** 的 `flash_mla_sparse_fwd` 只支持 SM90a 和 SM100f，不支持 SM120

---

## vllm 部署问题与修复

### 问题：flashinfer API 参数名不匹配

vllm 使用 flashinfer 的 `BatchDecodeWithPagedKVCacheWrapper` 时，调用参数名与 flashinfer 0.6.14 实际接口不一致。

**错误信息**:
```
TypeError: compute_kv_indptr() got an unexpected keyword argument 'page_size'
```

**根本原因**: vllm 代码中使用的参数名是 `page_size`，但 flashinfer 0.6.14 实际需要的是 `kv_layout` 或其他参数。

### 修复方法

修改文件：`/data/yy/sskj/envs/vllm/lib/python3.12/site-packages/vllm/attention/ops/flashinfer_sm120.py`

将 `page_size` 参数改为 `kv_layout`:

```python
# 修改前
indptr = flashinfer.compute_kv_indptr(
    num_pages,
    page_size=page_size,  # 错误
    ...
)

# 修改后
indptr = flashinfer.compute_kv_indptr(
    num_pages,
    kv_layout=page_size,  # 正确
    ...
)
```

### vllm 部署命令

```bash
source /data/yy/sskj/envs/vllm/bin/activate
python -m vllm.entrypoints.openai.api_server \
  --model /data/hf_models/DeepSeek-V4-Flash \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --max-model-len 65536 \
  --gpu-memory-utilization 0.85 \
  --port 8000
```

**状态**: ✅ 已修复，可成功部署

---

## sglang 部署问题与修复

### 问题1：flashinfer 版本过低

sglang 0.5.15 默认安装的 flashinfer 0.6.12 缺少 SM120 支持。需要升级到 0.6.14。

**修复**:
```bash
cp /data/yy/sskj/envs/vllm/lib/python3.12/site-packages/flashinfer* \
   /data/yy/sskj/envs/sglang/lib/python3.12/site-packages/
```

### 问题2：sgl_kernel flash_mla_sparse_fwd 不支持 SM120

sglang 的 DSV4 attention backend 在 prefill 阶段有两个路径：

1. **sparse prefill**: 使用 `sgl_kernel.flash_mla.flash_mla_sparse_fwd`，**只支持 SM90a 和 SM100f**
2. **非 sparse prefill**: 使用 `flash_mla_with_kvcache_sm120`，**支持 SM120**

**触发 sparse prefill 的条件** (`deepseek_v4_backend.py:1405`):
```python
if forward_batch.forward_mode.is_extend_without_speculative() and (
    q.shape[0] > _LARGE_INDEXER_QUERY_THRESHOLD  # 11673
    or envs.SGLANG_OPT_FLASHMLA_SPARSE_PREFILL.get()
):
    return self._forward_prefill_sparse(...)
```

warmup 阶段的 token 数超过 11673 阈值，导致触发 sparse prefill，然后报错：
```
RuntimeError: flash_mla_sparse_fwd only supports SM90a and SM100f
```

### 修复方法

修改文件：`/data/yy/sskj/envs/sglang/lib/python3.12/site-packages/sglang/srt/layers/attention/deepseek_v4_backend.py`

在 sparse prefill 条件判断中加入 `not _is_sm120`:

```python
# 修改前 (第1405行)
if forward_batch.forward_mode.is_extend_without_speculative() and (
    q.shape[0] > _LARGE_INDEXER_QUERY_THRESHOLD
    or envs.SGLANG_OPT_FLASHMLA_SPARSE_PREFILL.get()
):

# 修改后
if forward_batch.forward_mode.is_extend_without_speculative() and not _is_sm120 and (
    q.shape[0] > _LARGE_INDEXER_QUERY_THRESHOLD
    or envs.SGLANG_OPT_FLASHMLA_SPARSE_PREFILL.get()
):
```

这样 SM120 上就会走下面的 `flash_mla_with_kvcache_sm120` 路径，而不是 `flash_mla_sparse_fwd`。

### sglang 部署命令

```bash
source /data/yy/sskj/envs/sglang/bin/activate
python -m sglang.launch_server \
  --model-path /data/hf_models/DeepSeek-V4-Flash \
  --tp 8 \
  --trust-remote-code \
  --mem-fraction-static 0.78 \
  --cuda-graph-backend-decode disabled \
  --host 0.0.0.0 \
  --port 30000
```

**状态**: ✅ 已修复，可成功部署

---

## prefill 阶段算子选项分析

| 算子 | 来源 | 支持架构 | 说明 |
|------|------|----------|------|
| `flash_mla_sparse_fwd` | `sgl_kernel.flash_mla` | SM90a, SM100f | sparse prefill，性能更优，**不支持 SM120** |
| `flash_mla_with_kvcache` | `sgl_kernel.flash_mla` | 非 SM120 GPU | 标准 prefill |
| `flash_mla_with_kvcache_sm120` | `sglang.srt.layers.attention.flash_mla_sm120` | SM120 | SM120 专用路径 |

**结论**: 对于 SM120，prefill 阶段目前只有一个可用选项：`flash_mla_with_kvcache_sm120`。

sparse prefill 的优化（`flash_mla_sparse_fwd`）目前不支持 SM120，需要等待 `sgl_kernel` 更新。

---

## 是否会出现在 B300/B200 上

- **B200**: SM100，应该支持 `flash_mla_sparse_fwd`（支持 SM100f）
- **B300**: 需要确认具体的 SM 版本。如果是 SM120 或更高，可能会遇到同样的问题

建议在这些 GPU 上部署前先检查：
```python
import torch
print(torch.cuda.get_device_capability())  # 查看 SM 版本
```

---

## 相关 GitHub Issue

### vllm
- [vllm-project/vllm#XXXX](https://github.com/vllm-project/vllm/issues) - flashinfer SM120 支持

### sglang
- [sgl-project/sglang#XXXX](https://github.com/sgl-project/sglang/issues) - sgl_kernel SM120 支持

建议关注以下 PR/Issue：
- flashinfer 官方 SM120 支持进度
- sgl_kernel 官方 SM120 支持进度

---

## 长期解决方案

1. **等待官方更新**: 等待 flashinfer 和 sgl_kernel 官方支持 SM120
2. **从源码编译**: 从 sglang 源码编译 sgl_kernel，添加 SM120 支持
   - 仓库: https://gitee.com/yy-fighting/sglang.git
   - 需要修改 CUDA 编译选项，添加 `sm120` 架构
3. **使用 triton 算子**: 如果 CUDA 算子不支持，可以尝试使用 triton 实现的替代算子

---

## 当前部署状态

| 框架 | 状态 | 修改文件 |
|------|------|----------|
| vllm | ✅ 可部署 | `vllm/attention/ops/flashinfer_sm120.py` |
| sglang | ✅ 可部署 | `sglang/srt/layers/attention/deepseek_v4_backend.py` |

---

## 测试验证

### vllm API 测试
```bash
curl -s -X POST http://127.0.0.1:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "DeepSeek-V4-Flash", "prompt": "Hello", "max_tokens": 10}'
```

### sglang API 测试
```bash
curl -s -X POST http://127.0.0.1:30000/generate \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, how are you?", "sampling_params": {"max_new_tokens": 10}}'
```

---

## 备注

- 以上修改都是临时 workaround，建议跟踪上游官方修复
- 如果升级 sglang 或 vllm 版本，可能需要重新应用这些修改
- 性能方面：SM120 上禁用 sparse prefill 可能会有轻微性能损失，但可以正常运行

---

*文档生成时间: 2026-07-14*