安装#

vLLM 是一个 Python 库，其中还包含预编译的 C++ 和 CUDA (12.1) 二进制文件。

要求#

操作系统: Linux
Python: 3.8 – 3.12
GPU: 计算能力 7.0 或更高（例如，V100, T4, RTX20xx, A100, L4, H100 等）

安装已发布的版本#

你可以使用 pip 安装 vLLM：

$ # (Recommended) Create a new conda environment.
$ conda create -n myenv python=3.10 -y
$ conda activate myenv

$ # Install vLLM with CUDA 12.1.
$ pip install vllm

备注

虽然我们推荐使用 conda 来创建和管理 Python 环境，但强烈建议使用 pip 来安装 vLLM。这是因为 pip 可以安装带有独立库包（如 NCCL）的 torch，而 conda 安装的 torch 带有静态链接的 NCCL。这可能会在 vLLM 尝试使用 NCCL 时引起问题。更多详情请参见此问题。

备注

截至目前，vLLM 的二进制文件默认使用 CUDA 12.1 和公开的 PyTorch 发布版本进行编译。我们还提供使用 CUDA 11.8 和公开的 PyTorch 发布版本编译的 vLLM 二进制文件：

$ # Install vLLM with CUDA 11.8.
$ export VLLM_VERSION=0.6.1.post1
$ export PYTHON_VERSION=310
$ pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cu118-cp${PYTHON_VERSION}-cp${PYTHON_VERSION}-manylinux1_x86_64.whl --extra-index-url https://download.pytorch.org/whl/cu118

为了保持高性能，vLLM 需要编译许多 CUDA 内核。不幸的是，编译引入了与其他 CUDA 版本和 PyTorch 版本的二进制不兼容性，即使是相同 PyTorch 版本，但构建配置不同。

因此，建议在 全新的 conda 环境中安装 vLLM。如果你使用的是不同的 CUDA 版本，或者你想使用现有的 PyTorch 安装，你需要从源代码构建 vLLM。请参阅以下说明。

安装最新代码#

LLM 推理是一个快速发展的领域，最新的代码可能包含尚未发布的错误修复、性能改进和新功能。为了让用户无需等待下一次发布就能尝试最新代码，vLLM 为自 v0.5.3 以来的每个提交提供了在 x86 平台上运行 cuda 12 的 Linux 轮子。您可以使用以下命令下载并安装最新的轮子：

$ pip install https://vllm-wheels.s3.us-west-2.amazonaws.com/nightly/vllm-1.0.0.dev-cp38-abi3-manylinux1_x86_64.whl

如果你想访问之前提交的轮子，可以在URL中指定提交哈希：

$ export VLLM_COMMIT=33f460b17a54acb3b6cc0b03f4a17876cff5eafd # use full commit hash from the main branch
$ pip install https://vllm-wheels.s3.us-west-2.amazonaws.com/${VLLM_COMMIT}/vllm-1.0.0.dev-cp38-abi3-manylinux1_x86_64.whl

请注意，这些轮子是使用 Python 3.8 abi 构建的（有关 abi 的更多详细信息，请参阅 PEP 425），因此 它们与 Python 3.8 及更高版本兼容。轮子文件名中的版本字符串（1.0.0.dev）只是一个占位符，用于为轮子提供统一的 URL。轮子的实际版本包含在轮子元数据中。

另一种访问最新代码的方法是使用docker镜像：

$ export VLLM_COMMIT=33f460b17a54acb3b6cc0b03f4a17876cff5eafd # use full commit hash from the main branch
$ docker pull public.ecr.aws/q9t5s3a7/vllm-ci-test-repo:${VLLM_COMMIT}

这些Docker镜像仅用于CI和测试，不建议用于生产环境。它们将在几天后过期。

最新代码可能包含错误且可能不稳定。请谨慎使用。

从源码构建#

仅限 Python 的构建（无需编译）#

如果你只需要修改Python代码，你可以直接构建vLLM而不需要编译。

第一步是安装最新的 vLLM 轮子：

pip install https://vllm-wheels.s3.us-west-2.amazonaws.com/nightly/vllm-1.0.0.dev-cp38-abi3-manylinux1_x86_64.whl

你可以在上方找到更多关于 vLLM 轮子的信息。

在确认安装成功后，您可以使用以下脚本：

$ git clone https://github.com/vllm-project/vllm.git
$ cd vllm
$ python python_only_dev.py

该脚本将：

在当前环境中找到已安装的 vLLM 包。
将构建的文件复制到当前目录。
重命名已安装的 vLLM 包。
将当前目录符号链接到已安装的 vLLM 包。

现在，您可以编辑当前目录中的Python代码，并且在运行vLLM时，更改将会反映出来。

一旦你完成编辑或想要安装另一个 vLLM wheel，你应该使用相同的脚本并带上 --quit-dev``（或简写为 ``-q）标志退出开发环境：

$ python python_only_dev.py --quit-dev

带有 --quit-dev 标志的脚本将会：

从当前目录中移除指向 vLLM 包的符号链接。
从备份中恢复原始的 vLLM 包。

如果你更新了 vLLM 的 wheel 并希望从源代码重新构建并进行进一步编辑，你需要重新开始上述所有步骤。

备注

您的源代码可能与最新的 vLLM 轮子有不同的提交 ID，这可能会导致未知错误。建议使用与您安装的 vLLM 轮子相同的提交 ID 来编译源代码。请参阅上述部分以获取如何安装指定轮子的说明。

完整构建（包含编译）#

如果你想修改 C++ 或 CUDA 代码，你需要从源码构建 vLLM。这可能需要几分钟时间：

$ git clone https://github.com/vllm-project/vllm.git
$ cd vllm
$ pip install -e .

小技巧

从源代码构建需要大量的编译。如果你反复从源代码构建，缓存编译结果会更高效。例如，你可以通过 conda install ccache 或 apt install ccache 安装 ccache 。只要 which ccache 命令能找到 ccache 二进制文件，构建系统就会自动使用它。第一次构建后，后续的构建将会快得多。

使用现有的 PyTorch 安装#

在某些情况下，无法通过 pip 轻松安装 PyTorch 依赖，例如：

使用 PyTorch nightly 或自定义 PyTorch 构建 vLLM。
在 aarch64 和 CUDA (GH200) 上构建 vLLM，其中 PyTorch 轮子在 PyPI 上不可用。目前，只有 PyTorch nightly 为 aarch64 提供了 CUDA 轮子。你可以运行 pip3 install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu124 来安装 PyTorch nightly，然后在其基础上构建 vLLM。

要使用现有的 PyTorch 安装构建 vLLM：

$ git clone https://github.com/vllm-project/vllm.git
$ cd vllm
$ python use_existing_torch.py
$ pip install -r requirements-build.txt
$ pip install -e . --no-build-isolation

故障排除#

为了避免系统过载，您可以通过环境变量 MAX_JOBS 限制同时运行的编译作业数量。例如：

$ export MAX_JOBS=6
$ pip install -e .

这在您使用性能较弱的机器时特别有用。例如，当您使用 WSL 时，它默认仅分配总内存的 50%，因此使用 export MAX_JOBS=1 可以避免同时编译多个文件并耗尽内存。一个副作用是构建过程会慢得多。

此外，如果你在构建 vLLM 时遇到问题，我们建议使用 NVIDIA PyTorch Docker 镜像。

$ # Use `--ipc=host` to make sure the shared memory is large enough.
$ docker run --gpus all -it --rm --ipc=host nvcr.io/nvidia/pytorch:23.10-py3

如果你不想使用docker，建议安装完整的CUDA Toolkit。你可以从官方网站下载并安装。安装后，将环境变量 CUDA_HOME 设置为CUDA Toolkit的安装路径，并确保 nvcc 编译器在你的 PATH 中，例如：

$ export CUDA_HOME=/usr/local/cuda
$ export PATH="${CUDA_HOME}/bin:$PATH"

以下是一个健全性检查，以验证CUDA工具包是否正确安装：

$ nvcc --version # verify that nvcc is in your PATH
$ ${CUDA_HOME}/bin/nvcc --version # verify that nvcc is in your CUDA_HOME

不支持的操作系统构建#

vLLM 只能在 Linux 上完全运行，但对于开发目的，您仍然可以在其他系统（例如 macOS）上构建它，从而允许导入并提供更方便的开发环境。二进制文件将不会被编译，并且在非 Linux 系统上将无法工作。

在安装之前，只需禁用 VLLM_TARGET_DEVICE 环境变量：

$ export VLLM_TARGET_DEVICE=empty
$ pip install -e .