使用 Docker¶

预构建的镜像¶

NVIDIA CUDAAMD ROCmIntel XPUApple Silicon

vLLM 提供了一个用于部署的官方 Docker 镜像。该镜像可用于运行 OpenAI 兼容服务器，可在 Docker Hub 上找到，地址为 vllm/vllm-openai。

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model Qwen/Qwen3-0.6B

此镜像也可用于其他容器引擎，例如 Podman。

podman run --device nvidia.com/gpu=all \
-v ~/.cache/huggingface:/root/.cache/huggingface \
--env "HF_TOKEN=$HF_TOKEN" \
-p 8000:8000 \
--ipc=host \
docker.io/vllm/vllm-openai:latest \
--model Qwen/Qwen3-0.6B

您可以在镜像标签（vllm/vllm-openai:latest）后添加任何其他 engine-args。

注意

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

注意

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

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

FROM vllm/vllm-openai:v0.11.0

# 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.11.0

提示

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

要使用开发版本的 transformers，请在基础镜像之上创建一个自定义 Dockerfile，其中包含一个额外层，用于从源代码安装其代码

FROM vllm/vllm-openai:latest

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

在具有较旧 CUDA 驱动的系统上运行¶

vLLM 的 Docker 镜像预装了 CUDA 兼容性库。这允许您在 NVIDIA 驱动版本低于镜像中所用 CUDA Toolkit 版本的系统上运行 vLLM，但仅支持选定的专业和数据中心 NVIDIA GPU。

要启用此功能，请在运行容器时将 VLLM_ENABLE_CUDA_COMPATIBILITY 环境变量设置为 1 或 true。

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

这将自动配置 LD_LIBRARY_PATH，以便在加载 PyTorch 和其它依赖项之前指向兼容性库。

vLLM 提供官方 Docker 镜像用于部署。这些镜像可用于运行 OpenAI 兼容服务器，并在 Docker Hub 上提供，地址为 vllm/vllm-openai-rocm。

vllm/vllm-openai-rocm:latest — 稳定发布版
vllm/vllm-openai-rocm:nightly — 来自最新开发分支的预览版，如果您想要最新的功能和修复，请使用此版本。

docker run --rm \
    --group-add=video \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --device /dev/kfd \
    --device /dev/dri \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai-rocm:<tag> \
    --model Qwen/Qwen3-0.6B

要将 docker 镜像用作开发基础，可以通过覆盖入口点以交互会话方式启动它。

命令

docker run --rm -it \
    --group-add=video \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --device /dev/kfd \
    --device /dev/dri \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    --network=host \
    --ipc=host \
    --entrypoint /bin/bash \
    vllm/vllm-openai-rocm:<tag>

使用 AMD 的 Docker 镜像 (已弃用)¶

已弃用

AMD 的 Docker 镜像 (rocm/vllm 和 rocm/vllm-dev) 已被弃用，转而使用上述官方 vLLM Docker 镜像 (vllm/vllm-openai-rocm)。请迁移到官方镜像。

在 2026 年 1 月 20 日官方 docker 镜像在上游 vLLM docker hub 可用之前，vLLM AMD Infinity Hub 提供了一个预构建、经过优化的 docker 镜像，旨在验证 AMD Instinct MI300X™ 加速器上的推理性能。AMD 还从 Docker Hub 提供每日构建的预安装 docker 镜像，其中安装了 vLLM 及其所有依赖项。该 docker 镜像的入口点是 /bin/bash（与 vLLM 官方 Docker 镜像不同）。

提示

请查看 AMD Instinct MI300X 上的 LLM 推理性能验证以获取如何使用此预构建 docker 镜像的说明。

目前，我们在 docker hub 上发布基于 vLLM 发布版本的预构建 XPU 镜像。有关更多信息，请参阅发布说明。

以非 root 用户运行¶

出于向后兼容性的考虑，CUDA vllm/vllm-openai 镜像默认以 root 用户运行。它也已准备好以内置的 vllm 用户（UID 2000, GID 0）运行

docker run --rm --gpus all \
    --user 2000:0 \
    -p 8000:8000 \
    vllm/vllm-openai:latest \
    meta-llama/Llama-3.1-8B-Instruct

为非 root 容器挂载模型或缓存卷时，请将可写路径挂载到 /home/vllm 下而不是 /root 下。例如，将 Hugging Face 缓存挂载到 /home/vllm/.cache/huggingface，并确保挂载的目录对组 0 (group 0) 可写。

docker run --rm --gpus all \
    --user 2000:0 \
    -v ~/.cache/huggingface:/home/vllm/.cache/huggingface \
    -p 8000:8000 \
    vllm/vllm-openai:latest \
    meta-llama/Llama-3.1-8B-Instruct

要构建默认以非 root vllm 用户运行的镜像，请使用可选的 vllm-openai-nonroot 目标 (target)

docker build --target vllm-openai-nonroot \
    -t vllm-openai-nonroot:local \
    -f docker/Dockerfile .

docker run --rm --gpus all \
    -p 8000:8000 \
    vllm-openai-nonroot:local \
    meta-llama/Llama-3.1-8B-Instruct

当运行时 UID 是组 0 的成员时，vllm-openai-nonroot 目标还支持 OpenShift 风格的任意 UID。在 Kubernetes 清单中，请相应地设置容器安全上下文 (security context)，并保持挂载的缓存/模型路径对组 0 可写

securityContext:
  runAsNonRoot: true
  runAsUser: 1000540000
  runAsGroup: 0
  fsGroup: 0

组 0 之外的运行时 UID 不在文档支持范围内，因为它们可能无法写入 /home/vllm 或 /opt/uv/cache。

从源代码构建镜像¶

NVIDIA CUDAAMD ROCmIntel XPUApple Silicon

您可以通过提供的 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 命令时可能需要禁用 SELinux 标签，方法是添加 --security-opt label=disable，以避免某些现有问题。

注意

如果您没有更改任何 C++ 或 CUDA 内核代码，可以使用预编译的 wheel 显着减少 Docker 构建时间。

**启用功能**，添加构建参数：--build-arg VLLM_USE_PRECOMPILED="1"。
**工作原理**：默认情况下，vLLM 通过使用与上游 main 分支的合并基础提交，自动从我们的Nightly Builds中查找正确的 wheel。
**覆盖提交**：要使用来自特定提交的 wheel，请提供 --build-arg VLLM_PRECOMPILED_WHEEL_COMMIT=<commit_hash> 参数。

有关详细解释，请参阅从源代码构建 wheel中关于“使用仅 Python 构建（无需编译）进行设置”部分的文档，这些参数是相似的。

为 Arm64/aarch64 从源代码构建 vLLM 的 Docker 镜像¶

可以为 aarch64 系统（如 Nvidia Grace-Hopper 和 Grace-Blackwell）构建一个 docker 容器。使用标志 --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)
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 10.0+PTX" \
--build-arg RUN_WHEEL_CHECK=false

对于 (G)B300，我们建议使用 CUDA 13，如下命令所示。

命令

DOCKER_BUILDKIT=1 docker build \
--build-arg CUDA_VERSION=13.0.2 \
--build-arg BUILD_BASE_IMAGE=nvidia/cuda:13.0.2-devel-ubuntu22.04 \
--build-arg max_jobs=256 \
--build-arg nvcc_threads=2 \
--build-arg RUN_WHEEL_CHECK=false \
--build-arg torch_cuda_arch_list='9.0 10.0+PTX' \
--platform "linux/arm64" \
--tag vllm/vllm-gb300-openai:latest \
--target vllm-openai \
-f docker/Dockerfile \
.

注意

如果您在非 ARM 主机（例如 x86_64 机器）上构建 linux/arm64 镜像，则需要确保您的系统已使用 QEMU 设置为交叉编译。这允许您的主机模拟 ARM64 执行。

在您的主机上运行以下命令以注册 QEMU 用户静态处理程序

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

设置完 QEMU 后，您可以在 docker build 命令中使用 --platform "linux/arm64" 标志。

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

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

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --env "HF_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。

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

(可选) 构建一个带有 ROCm 软件栈的镜像

从 docker/Dockerfile.rocm_base 构建一个 docker 镜像，该镜像设置了 vLLM 所需的 ROCm 软件栈。**此步骤是可选的，因为此 rocm_base 镜像通常是预构建的并存储在 Docker Hub 上，标签为 rocm/vllm-dev:base，以加快用户体验。**如果您选择自己构建此 rocm_base 镜像，步骤如下。

用户使用 buildkit 启动 docker 构建非常重要。用户要么在调用 docker build 命令时将 DOCKER_BUILDKIT=1 作为环境变量，要么需要在 docker 守护进程配置 /etc/docker/daemon.json 中按如下方式设置 buildkit 并重新启动守护进程

{
    "features": {
        "buildkit": true
    }
}

要在 MI200 和 MI300 系列上使用 ROCm 7.0 构建 vllm，您可以使用默认设置

DOCKER_BUILDKIT=1 docker build \
    -f docker/Dockerfile.rocm_base \
    -t rocm/vllm-dev:base .

首先，从 docker/Dockerfile.rocm 构建一个 docker 镜像并从该镜像启动一个 docker 容器。用户使用 buildkit 启动 docker 构建非常重要。用户要么在调用 docker build 命令时将 DOCKER_BUILDKIT=1 作为环境变量，要么需要在 docker 守护进程配置 /etc/docker/daemon.json 中按如下方式设置 buildkit 并重新启动守护进程

{
    "features": {
        "buildkit": true
    }
}

docker/Dockerfile.rocm 默认使用 ROCm 7.0，但也支持旧版 vLLM 分支中的 ROCm 5.7、6.0、6.1、6.2、6.3 和 6.4。它提供了使用以下参数自定义构建 docker 镜像的灵活性

BASE_IMAGE：指定运行 docker build 时使用的基础镜像。默认值 rocm/vllm-dev:base 是 AMD 发布和维护的镜像。它使用 docker/Dockerfile.rocm_base 构建
ARG_PYTORCH_ROCM_ARCH：允许覆盖基础 docker 镜像中的 gfx 架构值

在运行 docker build 时，可以通过 --build-arg 选项传递它们的值。

要在 MI200 和 MI300 系列上使用 ROCm 7.0 构建 vllm，您可以使用默认设置（该设置构建一个以 vllm serve 为入口点的 docker 镜像）

DOCKER_BUILDKIT=1 docker build -f docker/Dockerfile.rocm -t vllm/vllm-openai-rocm .

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

docker run --rm \
    --group-add=video \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --device /dev/kfd \
    --device /dev/dri \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai-rocm <args...>

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

要将 docker 镜像用作开发基础，可以通过覆盖入口点以交互会话方式启动它。

命令

docker run --rm -it \
    --group-add=video \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --device /dev/kfd \
    --device /dev/dri \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    --network=host \
    --ipc=host \
    --entrypoint bash \
    vllm/vllm-openai-rocm

docker build -f docker/Dockerfile.xpu -t vllm-xpu-env --shm-size=4g .
docker run -it \
             --rm \
             --network=host \
             --device /dev/dri:/dev/dri \
             -v /dev/dri/by-path:/dev/dri/by-path \
             --ipc=host \
             --privileged \
             vllm-xpu-env