From 9d7f3d7f87fc81cd6ee9043515f7c83e98012227 Mon Sep 17 00:00:00 2001 From: Quantong Qiu Date: Tue, 14 Jul 2026 10:59:15 +0000 Subject: [PATCH] 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 | 6 +- envs/UV_ENV_SETUP.md | 164 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 166 insertions(+), 4 deletions(-) create mode 100644 envs/UV_ENV_SETUP.md diff --git a/envs/README.md b/envs/README.md index 90c5a91..5ecd51f 100644 --- a/envs/README.md +++ b/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 上的代码修复记录 └── # 其他平台/环境的部署文档 ``` @@ -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） diff --git a/envs/UV_ENV_SETUP.md b/envs/UV_ENV_SETUP.md new file mode 100644 index 0000000..1f4719f --- /dev/null +++ b/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== --index-url https://download.pytorch.org/whl/cu +``` + +### 环境激活脚本路径 + +| 环境 | 激活命令 | +|---|---| +| vLLM | `source /data/yy/sskj/envs/vllm/bin/activate` | +| SGLang | `source /data/yy/sskj/envs/sglang/bin/activate` |