From 5d2f1b2d9a67afcf05d662ee51383e43ec69be00 Mon Sep 17 00:00:00 2001 From: Quantong Qiu Date: Tue, 14 Jul 2026 10:53:38 +0000 Subject: [PATCH] docs(envs): add envs README and track deployment guides - 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 --- .gitignore | 8 +- envs/README.md | 44 ++++++ envs/SM120_DSV4_DEPLOYMENT_GUIDE.md | 235 ++++++++++++++++++++++++++++ 3 files changed, 286 insertions(+), 1 deletion(-) create mode 100644 envs/README.md create mode 100644 envs/SM120_DSV4_DEPLOYMENT_GUIDE.md diff --git a/.gitignore b/.gitignore index 8173ad2..2d047ad 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,11 @@ # 环境/依赖/临时文件 -envs/ +# envs/ 目录下的虚拟环境子目录（具体环境文件不提交，但文档保留） +envs/modelscope-hub/ +envs/modelscope-upload/ +envs/sglang/ +envs/sglang-src/ +envs/vllm/ +# 其他通用忽略 deps/ tmp/ *.pid diff --git a/envs/README.md b/envs/README.md new file mode 100644 index 0000000..90c5a91 --- /dev/null +++ b/envs/README.md @@ -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 上的代码修复记录 +└── # 其他平台/环境的部署文档 +``` + +## 使用规范 + +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/` diff --git a/envs/SM120_DSV4_DEPLOYMENT_GUIDE.md b/envs/SM120_DSV4_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000..de7b1fc --- /dev/null +++ b/envs/SM120_DSV4_DEPLOYMENT_GUIDE.md @@ -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*