docs(envs): add uv environment setup guide

- Add envs/UV_ENV_SETUP.md with standard commands for creating
  vLLM and SGLang virtual environments using uv.
- Configure UV_CACHE_DIR under envs/ to avoid polluting home directory.
- Include cu129-specific reinstall steps for SGLang kernel packages.
- Update envs/README.md to reference the new guide.

envs/README.md

@@ -7,9 +7,8 @@
 ```
 envs/
 ├── README.md                          # 本说明文件
+├── UV_ENV_SETUP.md                    # uv 虚拟环境搭建规范
 ├── SM120_DSV4_DEPLOYMENT_GUIDE.md     # SM120 (RTX 6000D) 部署 DSV4 指南
-├── SM120_DSV4_DEPLOYMENT_ISSUES.md    # SM120 部署问题汇总与解决方案
-├── VLLM_DSV4_SM120_FIX.md             # vLLM 在 SM120 上的代码修复记录
 └── <future guides>                    # 其他平台/环境的部署文档
 ```
 
@@ -29,9 +28,8 @@ envs/
 
 | 文档 | 说明 |
 |---|---|
+| `UV_ENV_SETUP.md` | uv 虚拟环境搭建规范，含 vLLM 和 SGLang 的标准安装命令 |
 | `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）
 

envs/UV_ENV_SETUP.md

@@ -0,0 +1,164 @@
+# UV 虚拟环境搭建规范
+
+本文档说明如何使用 [uv](https://docs.astral.sh/uv/) 在本项目下搭建 vLLM 和 SGLang 的虚拟环境。
+
+## 前置要求
+
+- Python 3.10+
+- CUDA 驱动已正确安装
+
+## 通用设置
+
+### 1. 安装 uv
+
+```bash
+pip install --upgrade pip
+pip install uv
+```
+
+### 2. 设置 uv cache 目录
+
+将 uv 的缓存目录设置到 `envs/` 下，避免占用用户主目录空间：
+
+```bash
+export UV_CACHE_DIR="/data/yy/sskj/envs/.uv_cache"
+# 建议写入 ~/.bashrc 或 ~/.zshrc 持久化
+```
+
+> **注意**：`envs/.uv_cache/` 已加入 `.gitignore`，不会被提交。
+
+### 3. 创建虚拟环境
+
+```bash
+cd /data/yy/sskj/envs
+
+# vLLM 环境
+uv venv vllm --python 3.12
+
+# SGLang 环境
+uv venv sglang --python 3.12
+```
+
+---
+
+## vLLM 环境安装
+
+```bash
+source /data/yy/sskj/envs/vllm/bin/activate
+
+# 安装 vLLM（自动匹配 PyTorch CUDA 后端）
+uv pip install vllm --torch-backend=auto
+```
+
+> `--torch-backend=auto` 让 uv 自动选择匹配当前 CUDA 版本的 PyTorch 后端。
+
+---
+
+## SGLang 环境安装
+
+### 标准 CUDA 版本（如 cu128）
+
+```bash
+source /data/yy/sskj/envs/sglang/bin/activate
+
+pip install --upgrade pip
+pip install uv
+
+# 安装 SGLang（允许预发布版本）
+uv pip install --prerelease=allow sglang
+```
+
+### CUDA 12.9 (cu129) 特殊处理
+
+如果目标平台使用 CUDA 12.9，需要强制重新安装匹配 cu129 的 PyTorch 和 SGLang 内核：
+
+```bash
+source /data/yy/sskj/envs/sglang/bin/activate
+
+pip install --upgrade pip
+pip install uv
+
+# 1. 安装 SGLang
+uv pip install --prerelease=allow sglang
+
+# 2. 强制重新安装 cu129 版 PyTorch
+uv pip install --force-reinstall \
+  torch==2.11.0 torchaudio==2.11.0 torchvision \
+  --index-url https://download.pytorch.org/whl/cu129
+
+# 3. 强制重新安装 cu129 版 SGLang 内核
+uv pip install --force-reinstall sglang-kernel \
+  --index-url https://docs.sglang.ai/whl/cu129/
+
+# 4. 强制重新安装 cu129 版 deep gemm（无依赖）
+uv pip install --force-reinstall sgl-deep-gemm \
+  --index-url https://docs.sglang.ai/whl/cu129/ \
+  --no-deps
+```
+
+> `--force-reinstall` 确保覆盖默认安装的 CUDA 版本。
+> `--no-deps` 避免 `sgl-deep-gemm` 拉取不兼容的依赖。
+
+---
+
+## 验证安装
+
+### vLLM
+
+```bash
+source /data/yy/sskj/envs/vllm/bin/activate
+python -c "import vllm; print(vllm.__version__)"
+```
+
+### SGLang
+
+```bash
+source /data/yy/sskj/envs/sglang/bin/activate
+python -c "import sglang; print(sglang.__version__)"
+```
+
+---
+
+## 环境目录结构（参考）
+
+```
+envs/
+├── .uv_cache/              # uv 缓存（已加入 .gitignore）
+├── vllm/                   # vLLM 虚拟环境（已加入 .gitignore）
+│   ├── bin/
+│   ├── lib/
+│   └── ...
+├── sglang/                 # SGLang 虚拟环境（已加入 .gitignore）
+│   ├── bin/
+│   ├── lib/
+│   └── ...
+├── README.md               # 本目录说明
+├── UV_ENV_SETUP.md         # 本文档
+└── SM120_DSV4_DEPLOYMENT_GUIDE.md  # 平台特定部署指南
+```
+
+---
+
+## 常见问题
+
+### uv cache 占用过大
+
+```bash
+# 清理 uv 缓存
+uv cache clean
+```
+
+### 切换 CUDA 版本后 PyTorch 不匹配
+
+```bash
+# 先卸载再重新安装对应 CUDA 版本的 PyTorch
+uv pip uninstall torch torchaudio torchvision
+uv pip install torch==<version> --index-url https://download.pytorch.org/whl/cu<version>
+```
+
+### 环境激活脚本路径
+
+| 环境 | 激活命令 |
+|---|---|
+| vLLM | `source /data/yy/sskj/envs/vllm/bin/activate` |
+| SGLang | `source /data/yy/sskj/envs/sglang/bin/activate` |