qqtang/sskj
1
2
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(envs): add envs README and track deployment guides

Browse Source 
- Add envs/README.md explaining the directory purpose and usage rules.
- Update .gitignore to exclude only virtual env subdirectories under envs/,
  allowing deployment guide documents to be tracked.
- Track existing deployment docs:
  - SM120_DSV4_DEPLOYMENT_GUIDE.md
  - SM120_DSV4_DEPLOYMENT_ISSUES.md
  - VLLM_DSV4_SM120_FIX.md
This commit is contained in:
Quantong Qiu 2026-07-14 10:53:38 +00:00
parent 5405d002fc
commit 5d2f1b2d9a
3 changed files with 286 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.gitignore vendored
View File

@ -1,5 +1,11 @@
# 环境/依赖/临时文件 # 环境/依赖/临时文件
envs/ # envs/ 目录下的虚拟环境子目录（具体环境文件不提交，但文档保留）
envs/modelscope-hub/
envs/modelscope-upload/
envs/sglang/
envs/sglang-src/
envs/vllm/
# 其他通用忽略
deps/ deps/
tmp/ tmp/
*.pid *.pid

44
envs/README.md Normal file
View File

@ -0,0 +1,44 @@
# envs 目录说明
本目录用于存放**环境搭建相关的文档和指南**，不包括具体的虚拟环境或容器镜像文件。
## 目录结构
```
envs/
├── README.md # 本说明文件
├── SM120_DSV4_DEPLOYMENT_GUIDE.md # SM120 (RTX 6000D) 部署 DSV4 指南
├── SM120_DSV4_DEPLOYMENT_ISSUES.md # SM120 部署问题汇总与解决方案
├── VLLM_DSV4_SM120_FIX.md # vLLM 在 SM120 上的代码修复记录
└── <future guides> # 其他平台/环境的部署文档
```
## 使用规范
1. **文档放这里**：与建立环境、部署模型、修复平台兼容性相关的文档，应放到 `envs/` 目录下。
2. **环境不放这里**：具体的 uv venv、conda env、Docker 镜像构建产物等，**不应**提交到 git。请在对应环境的 `.gitignore` 中排除。
3. **命名规范**：`{平台}_{模型或框架}_DEPLOYMENT_GUIDE.md` 或 `{框架}_{平台}_FIX.md`。
4. **内容要求**：
- 环境信息（GPU、CUDA、驱动版本）
- 问题现象与错误日志
- 根因分析
- 解决步骤（含具体命令或代码修改）
- 验证结果
## 现有文档
| 文档 | 说明 |
|---|---|
| `SM120_DSV4_DEPLOYMENT_GUIDE.md` | RTX 6000D (SM120) 上部署 DeepSeek-V4-Flash 的完整指南，含 vLLM 和 SGLang 的适配步骤 |
| `SM120_DSV4_DEPLOYMENT_ISSUES.md` | SM120 部署过程中遇到的具体问题汇总，包括 flashinfer、sgl_kernel 等兼容性问题的解决方案 |
| `VLLM_DSV4_SM120_FIX.md` | vLLM 在 SM120 上的代码级修复记录，含参数名不匹配等具体修改 |
## 排除的环境目录（已加入 .gitignore）
以下子目录包含具体的虚拟环境文件，不应提交：
- `modelscope-hub/`
- `modelscope-upload/`
- `sglang/`
- `sglang-src/`
- `vllm/`

235
envs/SM120_DSV4_DEPLOYMENT_GUIDE.md Normal file
View File

@ -0,0 +1,235 @@
# 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*