# 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

# vLLM nightly 环境
uv venv vllm-nightly --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 后端。

### Nightly 版

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

```bash
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）

```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/
│   └── ...
├── 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 占用过大

```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` |
| vLLM nightly | `source /data/yy/sskj/envs/vllm-nightly/bin/activate` |
| SGLang | `source /data/yy/sskj/envs/sglang/bin/activate` |