使用 Docker

使用 vLLM 官方 Docker 镜像¶

vLLM 提供了用于部署的官方 Docker 镜像。该镜像可用于运行与 OpenAI 兼容的服务器，并在 Docker Hub 上以 vllm/vllm-openai 提供。

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HUGGING_FACE_HUB_TOKEN=<secret>" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model mistralai/Mistral-7B-v0.1

此镜像也可与其他容器引擎（例如 Podman）一起使用。

podman run --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HUGGING_FACE_HUB_TOKEN=$HF_TOKEN" \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model mistralai/Mistral-7B-v0.1

您可以在镜像标签 (vllm/vllm-openai:latest) 之后添加您需要的任何其他引擎参数 (engine-args)。

注意

您可以使用 ipc=host 标志或 --shm-size 标志来允许容器访问主机的共享内存。vLLM 使用 PyTorch，它在底层使用共享内存来在进程之间共享数据，特别是对于张量并行推理。

注意

为了避免许可问题，未包含可选依赖项（例如 Issue #8030）。

如果您需要使用这些依赖项（并已接受许可条款），可以在基础镜像之上创建一个自定义 Dockerfile，增加一个额外的层来安装它们

FROM vllm/vllm-openai:v0.8.3

# e.g. install the `audio` optional dependencies
# NOTE: Make sure the version of vLLM matches the base image!
RUN uv pip install --system vllm[audio]==0.8.3

提示

一些新的模型可能只在 HF Transformers 的主分支上可用。

要使用 transformers 的开发版本，可以在基础镜像之上创建一个自定义 Dockerfile，增加一个额外的层来从源代码安装其代码

FROM vllm/vllm-openai:latest

RUN uv pip install --system git+https://github.com/huggingface/transformers.git

从源代码构建 vLLM Docker 镜像¶

您可以通过提供的 docker/Dockerfile 从源代码构建和运行 vLLM。要构建 vLLM

# optionally specifies: --build-arg max_jobs=8 --build-arg nvcc_threads=2
DOCKER_BUILDKIT=1 docker build . \
    --target vllm-openai \
    --tag vllm/vllm-openai \
    --file docker/Dockerfile

注意

默认情况下，vLLM 将构建适用于所有 GPU 类型的版本以实现最广泛的分发。如果您仅为机器当前运行的 GPU 类型构建，可以添加参数 --build-arg torch_cuda_arch_list=""，让 vLLM 找到当前 GPU 类型并为其构建。

如果您使用 Podman 而非 Docker，在运行 podman build 命令时可能需要添加 --security-opt label=disable 来禁用 SELinux 标签，以避免某些已知问题。

为 Arm64/aarch64 构建¶

可以为 aarch64 系统（如 Nvidia Grace-Hopper）构建 Docker 容器。截至本文撰写之时，这需要使用 PyTorch Nightly，并且应被视为实验性功能。使用标志 --platform "linux/arm64" 将尝试为 arm64 构建。

注意

必须编译多个模块，因此此过程可能需要一些时间。建议使用 --build-arg max_jobs= 和 --build-arg nvcc_threads= 标志来加快构建过程。但是，请确保您的 max_jobs 远大于 nvcc_threads，以获得最大效益。注意并行作业的内存使用情况，因为它可能相当大（参见下面的示例）。

# Example of building on Nvidia GH200 server. (Memory usage: ~15GB, Build time: ~1475s / ~25 min, Image size: 6.93GB)
python3 use_existing_torch.py
DOCKER_BUILDKIT=1 docker build . \
  --file docker/Dockerfile \
  --target vllm-openai \
  --platform "linux/arm64" \
  -t vllm/vllm-gh200-openai:latest \
  --build-arg max_jobs=66 \
  --build-arg nvcc_threads=2 \
  --build-arg torch_cuda_arch_list="9.0+PTX" \
  --build-arg vllm_fa_cmake_gpu_arches="90-real"

使用自定义构建的 vLLM Docker 镜像¶

使用自定义构建的 Docker 镜像运行 vLLM

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --env "HUGGING_FACE_HUB_TOKEN=<secret>" \
    vllm/vllm-openai <args...>

参数 vllm/vllm-openai 指定要运行的镜像，应替换为自定义构建的镜像名称（构建命令中的 -t 标签）。

注意

仅适用于版本 0.4.1 和 0.4.2 - 这些版本的 vLLM docker 镜像应以 root 用户身份运行，因为运行时需要加载 root 用户主目录下的库，即 /root/.config/vllm/nccl/cu12/libnccl.so.2.18.1。如果您在不同用户下运行容器，可能需要先更改库（以及所有父目录）的权限，以允许该用户访问，然后使用环境变量 VLLM_NCCL_SO_PATH=/root/.config/vllm/nccl/cu12/libnccl.so.2.18.1 运行 vLLM 。