sskj/envs/UV_ENV_SETUP.md

UV 虚拟环境搭建规范

本文档说明如何使用 uv 在本项目下搭建 vLLM 和 SGLang 的虚拟环境。

前置要求

• Python 3.10+
• CUDA 驱动已正确安装

通用设置

1. 安装 uv

pip install --upgrade pip
pip install uv

2. 设置 uv cache 目录

将 uv 的缓存目录设置到 envs/ 下，避免占用用户主目录空间：

export UV_CACHE_DIR="/data/yy/sskj/envs/.uv_cache"
# 建议写入 ~/.bashrc 或 ~/.zshrc 持久化

注意：envs/.uv_cache/ 已加入 .gitignore，不会被提交。

3. 创建虚拟环境

cd /data/yy/sskj/envs

# vLLM 稳定版环境
uv venv vllm --python 3.12

# vLLM nightly 环境
uv venv vllm-nightly --python 3.12

# SGLang 环境
uv venv sglang --python 3.12

---

vLLM 环境安装

稳定版

source /data/yy/sskj/envs/vllm/bin/activate

# 安装 vLLM（自动匹配 PyTorch CUDA 后端）
uv pip install vllm --torch-backend=auto

--torch-backend=auto 让 uv 自动选择匹配当前 CUDA 版本的 PyTorch 后端。

Nightly 版

如果需要使用 vLLM 的 nightly 版本（包含最新修复但可能不稳定）：

source /data/yy/sskj/envs/vllm-nightly/bin/activate

# 安装 vLLM nightly（从 vLLM 官方 nightly wheels）
uv pip install -U vllm \
    --torch-backend=auto \
    --extra-index-url https://wheels.vllm.ai/nightly

如需特定 CUDA 变体（如 cu128），可在 URL 后添加子目录，例如 https://wheels.vllm.ai/nightly/cu128。

---

SGLang 环境安装

标准 CUDA 版本（如 cu128）

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 内核：

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

source /data/yy/sskj/envs/vllm/bin/activate
python -c "import vllm; print(vllm.__version__)"

SGLang

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/
│   └── ...
├── vllm-nightly/           # vLLM nightly 虚拟环境（已加入 .gitignore）
│   ├── bin/
│   ├── lib/
│   └── ...
├── sglang/                 # SGLang 虚拟环境（已加入 .gitignore）
│   ├── bin/
│   ├── lib/
│   └── ...
├── README.md               # 本目录说明
├── UV_ENV_SETUP.md         # 本文档
└── SM120_DSV4_DEPLOYMENT_GUIDE.md  # 平台特定部署指南

---

常见问题

uv cache 占用过大

# 清理 uv 缓存
uv cache clean

切换 CUDA 版本后 PyTorch 不匹配

# 先卸载再重新安装对应 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
vLLM nightly	source /data/yy/sskj/envs/vllm-nightly/bin/activate
SGLang	source /data/yy/sskj/envs/sglang/bin/activate