1. 项目概述
在Ubuntu 25系统上安装vLLM（Vectorized Low Latency Memory）是一个需要仔细处理的过程，特别是当涉及到GPU加速和Python环境配置时。作为一个长期在Linux环境下工作的开发者，我最近在Ubuntu 25上安装vLLM时遇到了不少坑，网上现有的教程要么不完整，要么在某些关键步骤上存在问题。经过多次尝试和调整，我终于找到了一套可靠的安装方法。
vLLM是一个高性能的向量化内存数据库，特别适合需要低延迟内存访问的应用场景。它通常用于机器学习、大数据处理和高性能计算领域。安装过程中最关键的环节包括：正确配置NVIDIA驱动和CUDA环境、设置Python 3.12虚拟环境，以及解决各种依赖关系问题。
2. 环境准备
2.1 系统更新与基础配置
在开始安装前，确保系统是最新的状态非常重要。这不仅能够避免潜在的兼容性问题，还能确保安全补丁都已安装。
bash复制sudo apt update && sudo apt upgrade -y
这个命令会更新软件包列表并升级所有已安装的包。在大型系统升级后，建议重启系统以确保所有更新完全生效。
2.2 临时目录配置
vLLM安装过程中会产生大量临时文件，默认的/tmp目录空间可能不足。我们可以通过以下方式解决这个问题：
bash复制sudo rm -rf /tmp/*
mkdir ~/tmp
export TMPDIR=~/tmp
这个配置将临时文件目录重定向到用户主目录下的tmp文件夹，避免了系统临时分区空间不足的问题。为了永久生效，可以将export命令添加到~/.bashrc文件中。
3. 驱动与CUDA安装
3.1 NVIDIA驱动安装
vLLM需要GPU加速，因此正确安装NVIDIA驱动是必不可少的。在Ubuntu 25上，推荐使用550版本的驱动：
bash复制sudo apt install -y nvidia-driver-550
sudo reboot
安装完成后必须重启系统。重启后，可以通过nvidia-smi命令验证驱动是否安装成功。这个命令会显示GPU的状态和驱动版本信息。
3.2 CUDA环境配置
虽然vLLM的官方文档没有明确要求特定版本的CUDA，但根据我的经验，使用与NVIDIA驱动兼容的CUDA版本非常重要。Ubuntu 25的仓库中通常已经包含了合适的CUDA版本：
bash复制sudo apt install -y nvidia-cuda-toolkit
安装完成后，可以通过nvcc --version命令检查CUDA版本。如果系统提示命令未找到，可能需要手动将CUDA路径添加到环境变量中。
4. 开发工具与依赖安装
4.1 基础开发工具
vLLM编译需要一些基础开发工具和库：
bash复制sudo apt install -y build-essential libuv1-dev curl
libuv1-dev是一个高性能的事件循环库，vLLM的某些组件依赖它。build-essential包含了GCC编译器等基础开发工具。
4.2 Node.js环境
虽然vLLM本身是用Python编写的，但它的某些工具链依赖Node.js环境：
bash复制curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install uv
这里我们安装了Node.js 14.x版本，这是一个长期支持版本，稳定性较好。安装完成后，可以通过node -v和npm -v命令验证安装是否成功。
5. Python环境配置
5.1 Python 3.12安装
vLLM推荐使用Python 3.12环境。在Ubuntu 25上，可以通过以下方式安装：
bash复制sudo apt install -y python3.12 python3.12-dev python3.12-venv
python3.12-dev包包含了Python开发头文件，编译某些Python扩展时需要。python3.12-venv包提供了创建虚拟环境的功能。
5.2 pip工具升级
系统自带的pip版本可能较旧，建议先升级：
bash复制sudo apt install -y python3-pip
pip3 install --upgrade pip
升级pip可以避免一些包安装时的兼容性问题。在某些系统上，可能需要使用python3.12 -m pip而不是简单的pip3命令。
6. 虚拟环境创建
6.1 使用uv创建虚拟环境
uv是一个新兴的Python虚拟环境管理工具，比传统的venv更快：
bash复制curl -Ls https://astral.sh/uv/install.sh | bash
uv venv vllm-env --python 3.12 --seed
source vllm-env/bin/activate
这个命令会下载并安装uv，然后用它创建一个名为vllm-env的Python 3.12虚拟环境。--seed参数会预先安装一些常用工具如pip和setuptools。
6.2 验证Python环境
激活虚拟环境后，应该验证Python版本是否正确：
bash复制python --version
这个命令应该显示Python 3.12.x。如果显示的是系统Python版本，说明虚拟环境没有正确激活。
7. vLLM安装
7.1 使用pip安装vLLM
在虚拟环境中，使用以下命令安装vLLM：
bash复制pip install --no-cache-dir vllm -i https://pypi.tuna.tsinghua.edu.cn/simple
--no-cache-dir选项可以避免pip使用缓存，确保安装的是最新版本。-i参数指定使用清华大学的镜像源，可以显著提高下载速度。
7.2 验证安装
安装完成后，可以通过以下命令验证：
bash复制pip show vllm
这个命令会显示vLLM的版本信息和安装路径。为了进一步验证，可以尝试导入vLLM模块：
bash复制python -c "import vllm; print(vllm.__version__)"
如果没有报错并显示了版本号，说明安装成功。
8. 常见问题与解决方案
8.1 驱动兼容性问题
如果遇到CUDA相关的错误，可能是驱动版本不兼容。可以尝试以下步骤：
- 卸载现有驱动：
bash复制sudo apt purge nvidia*
- 安装推荐版本的驱动：
bash复制sudo apt install nvidia-driver-550
- 重新安装CUDA工具包：
bash复制sudo apt install nvidia-cuda-toolkit
8.2 Python包冲突
如果在安装过程中遇到Python包冲突，可以尝试创建一个全新的虚拟环境，然后先安装vLLM，再安装其他依赖包。虚拟环境可以很好地隔离不同项目的依赖关系。
8.3 空间不足问题
如果安装过程中提示磁盘空间不足，可以尝试以下方法：
- 清理apt缓存：
bash复制sudo apt clean
- 删除不需要的软件包：
bash复制sudo apt autoremove
- 如前所述，将临时目录指向有足够空间的位置。
9. 性能优化建议
9.1 UV循环优化
vLLM的性能很大程度上依赖于事件循环的效率。可以安装uvloop来替代默认的事件循环：
bash复制pip install uvloop
然后在代码中尽早添加以下内容：
python复制import asyncio
import uvloop
asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
9.2 内存配置
根据系统内存大小，可以调整vLLM的内存分配策略。在内存较大的系统上，可以增加缓存大小来提高性能。具体的配置参数可以参考vLLM的官方文档。
9.3 GPU利用率监控
安装完成后，建议监控GPU的使用情况：
bash复制nvidia-smi -l 1
这个命令会每秒刷新一次GPU状态，帮助识别性能瓶颈。如果GPU利用率不高，可能需要调整批量大小或其他参数。