跳至内容

使用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=$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 "HUGGING_FACE_HUB_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.9.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.9.0

提示

某些新模型可能仅在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以获得最佳效果。请注意并行作业可能会占用大量内存（参见下方示例）。

Command 
# 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 10.0+PTX"

注意

如果您在非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 "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。

优云智算