9d7f3d7f87
- 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.
165 lines
3.5 KiB
Markdown
165 lines
3.5 KiB
Markdown
# 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` |
|